From 9be242aba5f4b489884e35daa7b4d93d98f0c28f Mon Sep 17 00:00:00 2001 From: Chris Roberts Date: Thu, 5 Mar 2026 14:25:30 -0500 Subject: [PATCH] Improve README with comprehensive project documentation Add proper project description, requirements, operating modes, development setup, testing instructions, and contributing guidelines. Co-Authored-By: Claude Opus 4.6 --- README.md | 192 +++++++++++++++++++++++++++++++++++++++--------------- 1 file changed, 141 insertions(+), 51 deletions(-) diff --git a/README.md b/README.md index 67659997b..32b3534b7 100644 --- a/README.md +++ b/README.md @@ -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 + +## 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 +- 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. + +Check the current mode: `ForemanRhCloud.with_iop_smart_proxy?` + +## Usage + +### Inventory Upload + +**UI:** Insights → 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 + +# Generate report without uploading +organization_id=1 target=/var/lib/foreman/red_hat_inventory/generated_reports/ \ + foreman-rake rh_cloud_inventory:report:generate + +# Upload a previously generated report +organization_id=1 target=/var/lib/foreman/red_hat_inventory/generated_reports/ \ + 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 +``` -### 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 @@ -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 . +along with this program. If not, see .