Skip to content

Improve README with comprehensive project documentation #1168

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
chris1984 wants to merge 1 commit into
base: develop
Choose a base branch
from
+141 −51
Open

Improve README with comprehensive project documentation #1168

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
192 changes: 141 additions & 51 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,87 +4,177 @@

# ForemanRhCloud

A [Foreman](https://theforeman.org/) plugin that connects your Foreman or Red Hat Satellite instance to the [Red Hat Hybrid Cloud Console](https://cloud.redhat.com). It provides:

- **Inventory Upload** — Generate and upload host inventory reports to Red Hat cloud
- **Insights Recommendations** — Sync security, performance, and stability recommendations from Red Hat Insights
- **Remediations** — Apply Insights remediation playbooks via Remote Execution (Ansible)
- **Cloud Connector** — Enable cloud-initiated remediations through `rhcd`
- **Client Tools Forwarding** — Proxy `insights-client` requests from managed hosts that lack direct internet access
Copy link
Collaborator

@jeremylenz jeremylenz Mar 5, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It's for any hosts registered to Foreman, not just those that lack internet access.

Suggested change
- **Client Tools Forwarding** — Proxy `insights-client` requests from managed hosts that lack direct internet access
- **Client Tools Forwarding** — Proxy `insights-client` requests from managed hosts


## Requirements

- Foreman (with the following plugins):
- [Katello](https://github.com/Katello/katello) >= 4.18
- [foreman_ansible](https://github.com/theforeman/foreman_ansible) >= 15.0.0
- [foreman-tasks](https://github.com/theforeman/foreman-tasks) >= 10.0.0
Comment on lines +18 to +20
Copy link
Collaborator

@jeremylenz jeremylenz Mar 5, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I would leave the version numbers out here - just another thing to keep up to date.

- Ruby >= 2.7, < 4

## Installation

See [How_to_Install_a_Plugin](http://projects.theforeman.org/projects/foreman/wiki/How_to_Install_a_Plugin)
for how to install Foreman plugins
See [How to Install a Plugin](https://projects.theforeman.org/projects/foreman/wiki/How_to_Install_a_Plugin) in the Foreman wiki.

## Operating Modes

The plugin operates in two modes:

### Regular Mode (Cloud)

The default mode. Communicates directly with Red Hat cloud services to upload inventory, download recommendations, and forward client requests.

### IoP Mode (On-Premise)

When an Insights on Premise (IoP) Smart Proxy is configured, all cloud communication is routed through the local proxy instead. HTTP proxy settings are disabled, and scheduled sync tasks are skipped.
Comment on lines +35 to +37
Copy link

@sourcery-ai sourcery-ai bot Mar 5, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

suggestion (typo): Use the standard term "on-premises" instead of "on-premise/on Premise" for accuracy and consistency.

For example, update the heading to IoP Mode (On-Premises) and the sentence to When an Insights on-premises (IoP) Smart Proxy is configured, ... for consistent terminology.

Suggested change
### IoP Mode (On-Premise)
When an Insights on Premise (IoP) Smart Proxy is configured, all cloud communication is routed through the local proxy instead. HTTP proxy settings are disabled, and scheduled sync tasks are skipped.
### IoP Mode (On-Premises)
When an Insights on-premises (IoP) Smart Proxy is configured, all cloud communication is routed through the local proxy instead. HTTP proxy settings are disabled, and scheduled sync tasks are skipped.

Comment on lines +35 to +37
Copy link
Collaborator

@jeremylenz jeremylenz Mar 5, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Could highlight here that IoP is a technical abbreviation, but it doesn't officially stand for anything.


Check the current mode: `ForemanRhCloud.with_iop_smart_proxy?`

## Usage

### Inventory Upload

**UI:** Insights → Inventory Upload → select the organization → Generate and upload report
Copy link
Collaborator

@jeremylenz jeremylenz Mar 5, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
**UI:** Insights → Inventory Upload → select the organization → Generate and upload report
**UI (cloud):** Insights → Inventory Upload → select the organization → Generate and upload report
**UI (IoP):** Administer → Inventory Upload → select the organization → Generate and upload report


**CLI:**

```bash
# Generate and upload report for all organizations
foreman-rake rh_cloud_inventory:report:generate_upload

# Generate and upload report for specific organization
organization_id=1 foreman-rake rh_cloud_inventory:report:generate_upload
Copy link
Collaborator

@jeremylenz jeremylenz Mar 5, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

this will not work with env var in front


# Generate report without uploading
organization_id=1 target=/var/lib/foreman/red_hat_inventory/generated_reports/ \
Copy link
Collaborator

@jeremylenz jeremylenz Mar 5, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

same here

foreman-rake rh_cloud_inventory:report:generate

# Upload a previously generated report
organization_id=1 target=/var/lib/foreman/red_hat_inventory/generated_reports/ \
Copy link
Collaborator

@jeremylenz jeremylenz Mar 5, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

same here

foreman-rake rh_cloud_inventory:report:upload
```

### Insights Recommendations

**UI:** Insights → Recommendations → Sync recommendations (under the vertical ellipsis menu)

**CLI:**

```bash
foreman-rake rh_cloud_insights:sync
```

### Inventory Status Sync

**UI:** Insights → Inventory Upload → Sync all inventory status

**CLI:**

```bash
# All organizations
foreman-rake rh_cloud_inventory:sync

## Project overview
See our [wiki](https://deepwiki.com/theforeman/foreman_rh_cloud)
# Specific organization
organization_id=1 foreman-rake rh_cloud_inventory:sync
Copy link
Collaborator

@jeremylenz jeremylenz Mar 5, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

same here

```

### In Satellite
## Cloud Endpoints

#### Inventory upload
| Purpose | Default URL | ENV Override |
|---|---|---|
| Inventory uploads | `https://cert.cloud.redhat.com/api/ingress/v1/upload` | `SATELLITE_INVENTORY_UPLOAD_URL` |
| Query inventory hosts | `https://cloud.redhat.com/api/inventory/v1/hosts` | `SATELLITE_RH_CLOUD_URL` |
| Query Insights hits | `https://cloud.redhat.com/api/insights/v1/export/hits/` | `SATELLITE_RH_CLOUD_URL` |
| Query Insights rules | `https://cloud.redhat.com/api/insights/v1/rule/` | `SATELLITE_RH_CLOUD_URL` |
| Query remediations | `https://cloud.redhat.com/api/remediations/v1/resolutions` | `SATELLITE_RH_CLOUD_URL` |
| Forward `/static` requests | `https://cloud.redhat.com/api/static` | `SATELLITE_RH_CLOUD_URL` |
| Forward legacy `/platform` requests | `https://cert.cloud.redhat.com/api` | `SATELLITE_CERT_RH_CLOUD_URL` |
| Forward legacy `/redhat_access/r/insights` | `https://cert-api.access.redhat.com/r/insights` | `SATELLITE_LEGACY_INSIGHTS_URL` |

In UI: Insights -> Inventory Upload -> select the organization -> Generate and upload report
## Development

From command-line:
> **Important:** foreman_rh_cloud is a Foreman plugin, not a standalone app. Edit files in this directory but run all `rake`/`rails` commands from the **Foreman root** directory.

# generate and upload report for all organizations
/usr/sbin/foreman-rake rh_cloud_inventory:report:generate_upload
### Setup

# generate and upload report for specific organization
export organization_id=1
/usr/sbin/foreman-rake rh_cloud_inventory:report:generate_upload
```bash
# Clone Foreman and this plugin (if not already done)
cd /path/to/foreman

# generate report for specific organization (don't upload)
export organization_id=1
export target=/var/lib/foreman/red_hat_inventory/generated_reports/
/usr/sbin/foreman-rake rh_cloud_inventory:report:generate
# Install Ruby dependencies
bundle install

# upload previously generated report (needs to be named 'report_for_#{organization_id}.tar.gz')
export organization_id=1
export target=/var/lib/foreman/red_hat_inventory/generated_reports/
/usr/sbin/foreman-rake rh_cloud_inventory:report:upload
# Install JavaScript dependencies (from the plugin directory)
cd /path/to/foreman_rh_cloud
npm install
```

#### Fetch hosts remediation data
### Running Tests

In UI: Insights -> Recommendations -> Sync recommendations (under the vertical ellipsis)
**Ruby tests** (from the Foreman directory):

From command-line:
```bash
cd /path/to/foreman

/usr/sbin/foreman-rake rh_cloud_insights:sync
# Run all plugin tests
bundle exec rake test:foreman_rh_cloud

#### Synchronize inventory status
# Run a single test file
bundle exec rake test TEST=/path/to/foreman_rh_cloud/test/path/to/test_file.rb
```

In UI: Insights -> Inventory Upload -> Sync all inventory status
**JavaScript tests** (from the plugin directory):

From command-line:
```bash
cd /path/to/foreman_rh_cloud

# all organizations
/usr/sbin/foreman-rake rh_cloud_inventory:sync
npm test # All JS tests
npm run test:watch # Watch mode
npm run test:current # Current changes only
```

# specific organization with id 1
export organization_id=1
/usr/sbin/foreman-rake rh_cloud_inventory:sync
### Linting

## TODO
```bash
# Ruby (from Foreman directory)
cd /path/to/foreman
bundle exec rubocop --parallel

*Todo list here*
# JavaScript (from plugin directory)
cd /path/to/foreman_rh_cloud
npm run lint
```

## Design
### Development Server

### Endpoints
```bash
cd /path/to/foreman
bundle exec foreman start
```

| purpose | url | ENV setting for the **bold** part
| ------------------------------| -------| -----------
| Inventory uploads | **https://cert.cloud.redhat.com/api/ingress/v1/upload** | SATELLITE_INVENTORY_UPLOAD_URL
| Query inventory hosts list | **https://cloud.redhat.com** /api/inventory/v1/hosts?tags= | SATELLITE_RH_CLOUD_URL
| Query insights hits | **https://cloud.redhat.com** /api/insights/v1/export/hits/ | SATELLITE_RH_CLOUD_URL
| Query insights rules | **https://cloud.redhat.com** /api/insights/v1/rule/?impacting=true&rule_status=enabled&has_playbook=true&limit=&offset= | SATELLITE_RH_CLOUD_URL
| Query insights resolutions | **https://cloud.redhat.com** /api/remediations/v1/resolutions| SATELLITE_RH_CLOUD_URL
| Forward insights-client `/static` requests | **https://cloud.redhat.com** /api/static | SATELLITE_RH_CLOUD_URL
| Forward insights-client legacy `/platform` requests | **https://cert.cloud.redhat.com** /api | SATELLITE_CERT_RH_CLOUD_URL
| Forward insights-client legacy `/redhat_access/r/insights` requests | **https://cert-api.access.redhat.com** /r/insights | SATELLITE_LEGACY_INSIGHTS_URL
## Architecture

See [ARCHITECTURE.md](ARCHITECTURE.md) for detailed design documentation covering code organization, report generation flow, recommendations sync, Cloud Connector, and client tools forwarding.

## Contributing

Fork and send a Pull Request. Thanks!
1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Run the full test suite and linter (see above)
5. Submit a Pull Request

## Copyright

Copyright (c) 2013 - 2024 - The Foreman Team
Copyright (c) 2013 - 2026 The Foreman Team

This program is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
Expand All @@ -93,8 +183,8 @@ the Free Software Foundation, either version 3 of the License, or

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program. If not, see <http://www.gnu.org/licenses/>.
along with this program. If not, see <http://www.gnu.org/licenses/>.