Skip to content

Commit 155d019

Browse files
chris1984claude
chris1984
and
claude
committed
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 <noreply@anthropic.com>
1 parent c0c86c4 commit 155d019

1 file changed

Lines changed: 141 additions & 51 deletions

File tree

‎README.md‎

Lines changed: 141 additions & 51 deletions
Original file line numberDiff line numberDiff line change
@@ -4,87 +4,177 @@
44

55
# ForemanRhCloud
66

7+
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:
8+
9+
- **Inventory Upload** — Generate and upload host inventory reports to Red Hat cloud
10+
- **Insights Recommendations** — Sync security, performance, and stability recommendations from Red Hat Insights
11+
- **Remediations** — Apply Insights remediation playbooks via Remote Execution (Ansible)
12+
- **Cloud Connector** — Enable cloud-initiated remediations through `rhcd`
13+
- **Client Tools Forwarding** — Proxy `insights-client` requests from managed hosts
14+
15+
## Requirements
16+
17+
- Foreman (with the following plugins):
18+
- [Katello](https://github.com/Katello/katello)
19+
- [foreman_ansible](https://github.com/theforeman/foreman_ansible)
20+
- [foreman-tasks](https://github.com/theforeman/foreman-tasks)
21+
- [foreman_remote_execution](https://github.com/theforeman/foreman_remote_execution)
22+
- Ruby >= 2.7, < 4
23+
724
## Installation
825

9-
See [How_to_Install_a_Plugin](http://projects.theforeman.org/projects/foreman/wiki/How_to_Install_a_Plugin)
10-
for how to install Foreman plugins
26+
See [How to Install a Plugin](https://projects.theforeman.org/projects/foreman/wiki/How_to_Install_a_Plugin) in the Foreman wiki.
27+
28+
## Operating Modes
29+
30+
The plugin operates in two modes:
31+
32+
### Regular Mode (Cloud)
33+
34+
The default mode. Communicates directly with Red Hat cloud services to upload inventory, download recommendations, and forward client requests.
35+
36+
### IoP Mode (On-Premise)
37+
38+
When an 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. Note: "IoP" is a technical abbreviation used internally but does not officially stand for anything.
39+
40+
Check the current mode: `ForemanRhCloud.with_iop_smart_proxy?`
41+
42+
## Usage
43+
44+
### Inventory Upload
45+
46+
**UI (cloud):** Insights → Inventory Upload → select the organization → Generate and upload report
47+
**UI (IoP):** Administer → Inventory Upload → select the organization → Generate and upload report
48+
49+
**CLI:**
50+
51+
```bash
52+
# Generate and upload report for all organizations
53+
foreman-rake rh_cloud_inventory:report:generate_upload
54+
55+
# Generate and upload report for specific organization
56+
foreman-rake rh_cloud_inventory:report:generate_upload organization_id=1
57+
58+
# Generate report without uploading
59+
foreman-rake rh_cloud_inventory:report:generate organization_id=1 target=/var/lib/foreman/red_hat_inventory/generated_reports/
60+
61+
# Upload a previously generated report
62+
foreman-rake rh_cloud_inventory:report:upload organization_id=1 target=/var/lib/foreman/red_hat_inventory/generated_reports/
63+
```
64+
65+
### Insights Recommendations
66+
67+
**UI:** Insights → Recommendations → Sync recommendations (under the vertical ellipsis menu)
68+
69+
**CLI:**
70+
71+
```bash
72+
foreman-rake rh_cloud_insights:sync
73+
```
74+
75+
### Inventory Status Sync
76+
77+
**UI:** Insights → Inventory Upload → Sync all inventory status
78+
79+
**CLI:**
80+
81+
```bash
82+
# All organizations
83+
foreman-rake rh_cloud_inventory:sync
1184

12-
## Project overview
13-
See our [wiki](https://deepwiki.com/theforeman/foreman_rh_cloud)
85+
# Specific organization
86+
foreman-rake rh_cloud_inventory:sync organization_id=1
87+
```
1488

15-
### In Satellite
89+
## Cloud Endpoints
1690

17-
#### Inventory upload
91+
| Purpose | Default URL | ENV Override |
92+
|---|---|---|
93+
| Inventory uploads | `https://cert.cloud.redhat.com/api/ingress/v1/upload` | `SATELLITE_INVENTORY_UPLOAD_URL` |
94+
| Query inventory hosts | `https://cloud.redhat.com/api/inventory/v1/hosts` | `SATELLITE_RH_CLOUD_URL` |
95+
| Query Insights hits | `https://cloud.redhat.com/api/insights/v1/export/hits/` | `SATELLITE_RH_CLOUD_URL` |
96+
| Query Insights rules | `https://cloud.redhat.com/api/insights/v1/rule/` | `SATELLITE_RH_CLOUD_URL` |
97+
| Query remediations | `https://cloud.redhat.com/api/remediations/v1/resolutions` | `SATELLITE_RH_CLOUD_URL` |
98+
| Forward `/platform` requests | `https://cert.cloud.redhat.com/api` | `SATELLITE_CERT_RH_CLOUD_URL` |
99+
| Forward `/lightspeed` requests | `https://cert.cloud.redhat.com/api/lightspeed` | `SATELLITE_CERT_RH_CLOUD_URL` |
100+
| Forward legacy `/redhat_access/r/insights` | `https://cert-api.access.redhat.com/r/insights` | `SATELLITE_LEGACY_INSIGHTS_URL` |
18101

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

21-
From command-line:
104+
> **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.
22105
23-
# generate and upload report for all organizations
24-
/usr/sbin/foreman-rake rh_cloud_inventory:report:generate_upload
106+
### Setup
25107

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

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

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

40-
#### Fetch hosts remediation data
120+
### Running Tests
41121

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

44-
From command-line:
124+
```bash
125+
cd /path/to/foreman
45126

46-
/usr/sbin/foreman-rake rh_cloud_insights:sync
127+
# Run all plugin tests
128+
bundle exec rake test:foreman_rh_cloud
47129

48-
#### Synchronize inventory status
130+
# Run a single test file
131+
bundle exec rake test TEST=/path/to/foreman_rh_cloud/test/path/to/test_file.rb
132+
```
49133

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

52-
From command-line:
136+
```bash
137+
cd /path/to/foreman_rh_cloud
53138

54-
# all organizations
55-
/usr/sbin/foreman-rake rh_cloud_inventory:sync
139+
npm test # All JS tests
140+
npm run test:watch # Watch mode
141+
npm run test:current # Current changes only
142+
```
56143

57-
# specific organization with id 1
58-
export organization_id=1
59-
/usr/sbin/foreman-rake rh_cloud_inventory:sync
144+
### Linting
60145

61-
## TODO
146+
```bash
147+
# Ruby (from Foreman directory)
148+
cd /path/to/foreman
149+
bundle exec rubocop --parallel
62150

63-
*Todo list here*
151+
# JavaScript (from plugin directory)
152+
cd /path/to/foreman_rh_cloud
153+
npm run lint
154+
```
64155

65-
## Design
156+
### Development Server
66157

67-
### Endpoints
158+
```bash
159+
cd /path/to/foreman
160+
bundle exec foreman start
161+
```
68162

69-
| purpose | url | ENV setting for the **bold** part
70-
| ------------------------------| -------| -----------
71-
| Inventory uploads | **https://cert.cloud.redhat.com/api/ingress/v1/upload** | SATELLITE_INVENTORY_UPLOAD_URL
72-
| Query inventory hosts list | **https://cloud.redhat.com** /api/inventory/v1/hosts?tags= | SATELLITE_RH_CLOUD_URL
73-
| Query insights hits | **https://cloud.redhat.com** /api/insights/v1/export/hits/ | SATELLITE_RH_CLOUD_URL
74-
| 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
75-
| Query insights resolutions | **https://cloud.redhat.com** /api/remediations/v1/resolutions| SATELLITE_RH_CLOUD_URL
76-
| Forward insights-client `/static` requests | **https://cloud.redhat.com** /api/static | SATELLITE_RH_CLOUD_URL
77-
| Forward insights-client legacy `/platform` requests | **https://cert.cloud.redhat.com** /api | SATELLITE_CERT_RH_CLOUD_URL
78-
| Forward insights-client legacy `/redhat_access/r/insights` requests | **https://cert-api.access.redhat.com** /r/insights | SATELLITE_LEGACY_INSIGHTS_URL
163+
## Architecture
79164

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

81167
## Contributing
82168

83-
Fork and send a Pull Request. Thanks!
169+
1. Fork the repository
170+
2. Create a feature branch
171+
3. Make your changes
172+
4. Run the full test suite and linter (see above)
173+
5. Submit a Pull Request
84174

85175
## Copyright
86176

87-
Copyright (c) 2013 - 2024 - The Foreman Team
177+
Copyright (c) 2013 - 2026 The Foreman Team
88178

89179
This program is free software: you can redistribute it and/or modify
90180
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
93183

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

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

0 commit comments

Comments
 (0)