Overview

Relevant source files

• .github/workflows/ruby_tests.yml
• .rubocop.yml
• .rubocop_todo.yml
• README.md
• app/models/foreman_rh_cloud/ping.rb
• config/package-lock.json.plugin
• config/routes.rb
• lib/foreman_rh_cloud.rb
• lib/foreman_rh_cloud/engine.rb
• lib/foreman_rh_cloud/plugin.rb
• lib/foreman_rh_cloud/version.rb
• package.json
• test/unit/foreman_rh_cloud_iop_metadata_test.rb
• test/unit/foreman_rh_cloud_self_host_test.rb
• webpack/CVEsHostDetailsTab/index.js
• webpack/ForemanRhCloudPages.js
• webpack/InsightsCloudSync/Components/InsightsTable/InsightsLabel.js
• webpack/InsightsCloudSync/Components/InsightsTable/InsightsSection.js
• webpack/InsightsCloudSync/Components/InsightsTable/InsightsSection.scss
• webpack/common/styles.scss

Purpose and Scope: This document provides a high-level introduction to the foreman_rh_cloud plugin, explaining its purpose, architecture, and major subsystems. It covers how the plugin integrates Foreman/Katello with Red Hat Cloud services and the two deployment modes it supports. For detailed information on specific subsystems, refer to the child pages: plugin structure (1.1), deployment modes (1.2), and configuration (1.3).

---

What is foreman_rh_cloud?

The foreman_rh_cloud plugin is a Foreman extension implemented as a Rails Engine (lib/foreman_rh_cloud/engine.rb5) that bridges Foreman/Katello installations with Red Hat Cloud services. It provides four core capabilities:

1. Inventory Reporting - Generates and uploads host inventory data to Red Hat Cloud Inventory API

   • Components: ForemanInventoryUpload::Generators::Slice, HostInventoryReportJob, UploadReportDirectJob
   • Endpoint: https://cert.cloud.redhat.com/api/ingress/v1/upload

2. Insights Integration - Synchronizes security recommendations, vulnerabilities, and remediation playbooks

   • Components: InsightsCloud::Async::InsightsFullSync, InsightsHit, InsightsRule, InsightsResolution
   • Data Models: InsightsFacet (per-host), InsightsHit (recommendations), InsightsRule (rule definitions)

3. Cloud Request Forwarding - Proxies HTTP requests from insights-client agents to Red Hat Cloud APIs

   • Components: ForemanRhCloud::CloudRequestForwarder, InsightsCloud::Api::MachineTelemetriesController
   • Routes: /redhat_access/r/insights/*, /api/lightspeed/*

4. Vulnerability Management - Integrates with Red Hat Insights Vulnerability service for CVE tracking

   • Components: Scalprum micro-frontend loader, CveDetailsPage, InsightsVulnerabilityListPage
   • UI Extensions: CVE count column in host tables, host details CVE tab

The plugin version is managed in parallel across Ruby (lib/foreman_rh_cloud/version.rb2) and JavaScript (package.json3) packages.

Sources: README.md5-13 lib/foreman_rh_cloud/engine.rb5-6 lib/foreman_rh_cloud/plugin.rb8-9 package.json2-3 lib/foreman_rh_cloud/version.rb2

---

Deployment Architecture

The plugin supports two distinct deployment modes that fundamentally change how data flows and where services execute:

Mode	Description	Service Location	Certificate Type
Hosted (Standard)	Direct connection to Red Hat Cloud	cloud.redhat.com	Manifest certificates
IoP (Insights on Platform)	Local Insights services on Smart Proxy	Smart Proxy with iop feature	Foreman SSL certificates

Mode detection occurs automatically by checking for the presence of a Smart Proxy with the iop feature using ForemanRhCloud.with_iop_smart_proxy?. When an IoP proxy exists, all cloud URLs are automatically redirected to the proxy's URL.

Key URL Resolution Methods:

URL Resolution Priority: IoP Smart Proxy URL → ENV variable → default cloud URL

Environment	base_url	cert_base_url	legacy_insights_url
Hosted (no IoP)	https://cloud.redhat.com	https://cert.cloud.redhat.com	https://cert-api.access.redhat.com
IoP (proxy at https://iop.example.com)	https://iop.example.com	https://iop.example.com	https://iop.example.com
ENV override (SATELLITE_RH_CLOUD_URL=https://test.com)	https://test.com	(default or ENV)	(default or ENV)

For detailed information on deployment modes, configuration differences, and conditional behavior, see Deployment Modes: Hosted vs. IoP.

Sources: lib/foreman_rh_cloud.rb6-26 lib/foreman_rh_cloud/engine.rb122-128 test/unit/foreman_rh_cloud_iop_metadata_test.rb79-199

---

Plugin Registration and Integration Points

Rails Engine Registration

Plugin Registration Flow

The plugin registers with Foreman through Foreman::Plugin.register :foreman_rh_cloud in lib/foreman_rh_cloud/plugin.rb8 The registration is idempotent - it checks if the plugin is already registered and returns early to prevent re-registration during code reloads (lib/foreman_rh_cloud/plugin.rb6).

Key Registration Components:

• Settings: Nine configuration options under :rh_cloud category (lib/foreman_rh_cloud/plugin.rb14-26)

  • allow_auto_inventory_upload, allow_auto_insights_sync, allow_auto_insights_mismatch_delete
  • obfuscate_inventory_hostnames, obfuscate_inventory_ips, exclude_installed_packages
  • include_parameter_tags, rhc_instance_id, insights_minimal_data_collection

• Permissions: Six permission types (lib/foreman_rh_cloud/plugin.rb29-96)

  • Core: generate_foreman_rh_cloud, view_foreman_rh_cloud, view_insights_hits, dispatch_cloud_requests, control_organization_insights
  • Insights Apps: view_vulnerability, edit_vulnerability, view_advisor, edit_advisor

• Roles: Two predefined roles (lib/foreman_rh_cloud/plugin.rb108-113)

  • ForemanRhCloud - Full access to all plugin features
  • ForemanRhCloud Read Only - View-only access

• Menu Items: Conditional menu structure based on deployment mode (lib/foreman_rh_cloud/plugin.rb120-146)

  • Hosted: Inventory Upload under Insights menu
  • IoP: Inventory Upload under Admin menu, Vulnerability under Insights menu

• Facets: InsightsFacet for per-host Insights data (lib/foreman_rh_cloud/plugin.rb148-153)

• Custom Status: Host status indicators (lib/foreman_rh_cloud/plugin.rb162-163)

  • InventorySync::InventoryStatus - Inventory upload/sync status
  • InsightsClientReportStatus - Client check-in status

• Remote Execution Features: Three REX features registered in config.to_prepare block (lib/foreman_rh_cloud/engine.rb68-86)

  • rh_cloud_remediate_hosts - Apply Insights recommendations
  • rh_cloud_connector_run_playbook - Run RH Cloud playbook
  • ansible_configure_cloud_connector - Configure Cloud Connector

Sources: lib/foreman_rh_cloud/plugin.rb3-196 lib/foreman_rh_cloud/engine.rb34-45 lib/foreman_rh_cloud/engine.rb68-87

---

Major Subsystems

System Component Mapping

The plugin is organized into several major subsystems with clear file organization:

Major Subsystem Overview by Directory Structure

Key File Organization Patterns:

• Async Jobs: All background jobs follow lib/*/async/*.rb pattern, inherit from ForemanTasks::Task
• Generators: Inventory generation logic in lib/foreman_inventory_upload/generators/*.rb
• Models: ActiveRecord models in app/models/*.rb, concerns in app/models/concerns/*.rb
• Services: Business logic in app/services/foreman_rh_cloud/*.rb
• API Controllers: REST endpoints in app/controllers/api/v2/rh_cloud/*.rb and app/controllers/insights_cloud/api/*.rb
• Frontend: React components in webpack/*/ directories, registered in webpack/ForemanRhCloudPages.js
• Routes: All HTTP routes defined in config/routes.rb with namespace organization

Sources: lib/foreman_rh_cloud/plugin.rb1-196 config/routes.rb1-89 webpack/ForemanRhCloudPages.js1-59 README.md17-60

---

Subsystem Responsibilities

1. Inventory Report Generation

Purpose: Collect host data from Foreman and transform it into structured JSON reports for Red Hat Cloud.

Key Components:

• ForemanInventoryUpload::Generators::Slice - Queries hosts in batches and generates JSON slices
• ForemanInventoryUpload::Generators::Tags - Extracts metadata (locations, hostgroups, content views)
• ForemanInventoryUpload::Generators::Metadata - Creates report metadata (organization, dates)
• ForemanInventoryUpload::Generators::FactHelpers - Transforms Foreman facts to cloud format

Settings Influence:

• insights_minimal_data_collection - Controls data scope (minimal vs. full)
• obfuscate_inventory_hostnames / obfuscate_inventory_ips - Privacy controls
• exclude_installed_packages - Package inclusion/exclusion

For details on report generation, see Inventory Report Generation.

Sources: Inferred from Diagram 2 in high-level architecture

---

2. Inventory Upload and Synchronization

Purpose: Upload generated reports to Red Hat Cloud and sync inventory status back to Foreman.

Key Components:

• ForemanInventoryUpload::Async::GenerateReportJob - Asynchronous report generation
• ForemanInventoryUpload::Async::QueueForUploadJob - Manages upload queue
• ForemanInventoryUpload::Async::UploadReportJob - Performs HTTPS upload with certificate auth
• InventorySync::Async::InventoryFullSync - Orchestrates status synchronization
• InventorySync::InventoryStatus - Stores per-host sync status

Upload Endpoint: https://cert.cloud.redhat.com/api/ingress/v1/upload (configurable via SATELLITE_INVENTORY_UPLOAD_URL)

For details on upload pipeline and sync, see Inventory Management.

Sources: README.md69-78 Diagram 2 and Diagram 3 in high-level architecture

---

3. Insights Integration

Purpose: Synchronize security recommendations, rules, and remediation playbooks from Red Hat Insights.

Key Components:

• InsightsCloud::Async::InsightsFullSync - Orchestrates multi-step sync process
• InsightsCloud::Async::InsightsRulesSync - Fetches Insights rules
• InsightsCloud::Async::InsightsResolutionsSync - Fetches remediation resolutions
• InsightsHit - Model representing individual recommendations/vulnerabilities
• InsightsRule - Model representing Insights rules with metadata
• InsightsFacet - Per-host facet tracking UUID and hit counts

API Endpoints:

• Export hits: /api/insights/v1/export/hits/
• Rules: /api/insights/v1/rule/?impacting=true&rule_status=enabled&has_playbook=true
• Resolutions: /api/remediations/v1/resolutions

For details on Insights synchronization, see Insights Integration.

Sources: README.md73-75 lib/foreman_rh_cloud/plugin.rb148-153

---

4. Cloud Request Forwarding

Purpose: Proxy HTTP requests from insights-client agents to Red Hat Cloud APIs, handling authentication and path transformation.

Key Components:

• ForemanRhCloud::CloudRequestForwarder - Main request forwarding service
• InsightsCloud::Api::MachineTelemetriesController - Controller for telemetry requests
• Api::V2::RhCloud::CloudRequestController - RESTful API for cloud requests

Request Path Transformations:

• /api/static/*path → https://cloud.redhat.com/api/static/*path
• /api/platform/*path → https://cert.cloud.redhat.com/api/*path (legacy)
• /r/insights/*path → https://cert-api.access.redhat.com/r/insights/*path (legacy)

For details on request forwarding, see Cloud Communication.

Sources: README.md76-78

---

5. Frontend UI Components

Purpose: Provide React-based user interfaces for Insights features, with conditional rendering based on deployment mode.

Key Components:

• Standard Mode: Locally rendered React components (InsightsCloudSync, InsightsTable, RemediationModal)
• IoP Mode: Scalprum-loaded micro-frontends from Smart Proxy (ScalprumComponent, ScalprumProvider)
• Host Extensions: Additional columns and actions in host tables (RecommendationsCell, CVECountCell)
• Component Registry: Webpack bundles registering columns, actions, and routes (global.js, ForemanRhCloudPages.js)

Conditional Rendering Pattern:

For details on frontend architecture, see User Interface.

Sources: lib/foreman_rh_cloud/plugin.rb160 Diagram 5 in high-level architecture

---

6. Background Job System

Purpose: Execute long-running operations asynchronously using ForemanTasks (Dynflow).

Key Components:

• ForemanInventoryUpload::Async::* - Inventory-related jobs
• InsightsCloud::Async::* - Insights sync jobs
• InventorySync::Async::* - Inventory status sync jobs
• ExponentialBackoff - Retry logic mixin for failed jobs

Scheduled Jobs (daily at midnight):

• GenerateAllReportsJob - Generate inventory reports for all organizations
• InventoryScheduledSync - Sync inventory status
• InsightsScheduledSync - Sync Insights recommendations
• InsightsClientStatusAging - Age out stale client status records

For details on background processing, see Background Processing.

Sources: Diagram 3 in high-level architecture

---

Permission Model

The plugin defines six permission types organized into two categories:

Core RH Cloud Permissions

Permission	Purpose	Key Actions
generate_foreman_rh_cloud	Generate and upload reports	Report generation, cloud connector enablement, task creation
view_foreman_rh_cloud	View reports and status	View accounts, reports, upload status, task history
view_insights_hits	View recommendations	Access Insights recommendations, rules, resolutions
dispatch_cloud_requests	Forward cloud requests	Proxy client requests to cloud
control_organization_insights	Manage org settings	Set organization-specific Insights parameters

Insights Application Permissions

Permission	Purpose	Applies To
view_vulnerability	View vulnerability data	CVE information, vulnerability service access
edit_vulnerability	Modify vulnerability settings	Host vulnerability opt-out/opt-in
view_advisor	View Advisor recommendations	Advisor service recommendations
edit_advisor	Modify Advisor settings	Disable/enable recommendations

Predefined Roles

• ForemanRhCloud: Full access to all plugin features (all six permissions)
• ForemanRhCloud Read Only: View-only access (view_foreman_rh_cloud, view_insights_hits, view_vulnerability, view_advisor)

Permissions are automatically assigned to ORG_ADMIN, MANAGER, and SYSTEM_ADMIN roles.

For details on permissions and security, see Permissions and Security.

Sources: lib/foreman_rh_cloud/plugin.rb28-117

---

Key Architectural Patterns

1. Conditional Behavior Based on Deployment Mode

Throughout the codebase, behavior changes based on the presence of an IoP Smart Proxy:

Sources: lib/foreman_rh_cloud.rb6-18

2. Certificate-Based Authentication

The plugin supports two authentication mechanisms:

• User sessions: Standard Foreman authentication for UI/API access
• Client certificates: UUID-based authentication for insights-client host agents

Client certificate authentication uses ClientAuthentication concern to lookup hosts by subscription UUID and set User.current to a CpConsumerUser.

Sources: Diagram 6 in high-level architecture, lib/foreman_rh_cloud/plugin.rb29-96

3. Job Orchestration with ForemanTasks

All asynchronous operations use ForemanTasks (Dynflow) for:

• Status tracking and progress reporting
• Error handling and retry logic (exponential backoff)
• Job chaining for multi-step operations (e.g., InsightsFullSync chains rules, hits, and resolution syncs)

Sources: Diagram 3 in high-level architecture

4. Component Registry Pattern

Frontend extensions use Foreman's component registry to inject functionality:

• registerColumns - Add columns to host tables
• registerGetActions - Add bulk actions to kebab menus
• registerRoutes - Define new page routes

Sources: lib/foreman_rh_cloud/plugin.rb160 Diagram 5 in high-level architecture

---

Configuration Settings

The plugin exposes nine configuration settings under the :rh_cloud category in Foreman's Settings UI. All settings are ignored when operating in IoP mode, as the Smart Proxy controls data collection:

Setting	Type	Default	Description
allow_auto_inventory_upload	boolean	true	Enable automatic daily inventory uploads
allow_auto_insights_sync	boolean	true	Enable automatic daily Insights sync
allow_auto_insights_mismatch_delete	boolean	false	Automatically delete mismatched hosts from cloud
obfuscate_inventory_hostnames	boolean	false	Obfuscate hostnames in reports
obfuscate_inventory_ips	boolean	false	Obfuscate IPv4 addresses in reports
exclude_installed_packages	boolean	false	Exclude package lists from reports
include_parameter_tags	boolean	false	Include host parameters as tags
rhc_instance_id	string	nil	RHC (Yggdrasil) daemon identifier
insights_minimal_data_collection	boolean	false	Minimal data collection mode

Note: When insights_minimal_data_collection is enabled, it overrides obfuscation settings - hostnames, IPs, and packages are excluded regardless of other settings.

For detailed configuration information, see Configuration and Settings.

Sources: lib/foreman_rh_cloud/plugin.rb14-26

---

Health Monitoring and Plugin Metadata

The plugin registers health check extensions and exposes deployment mode metadata:

Ping Extension (IoP Mode Only)

Provides service availability status for IoP deployments through ForemanRhCloud::Ping:

Service check implementation:

• Iterates through ForemanRhCloud::Ping.services (app/models/foreman_rh_cloud/ping.rb21)
• Executes execute_cloud_request for each service URL (app/models/foreman_rh_cloud/ping.rb71-82)
• Parses JSON response or captures raw response body (app/models/foreman_rh_cloud/ping.rb76-80)
• Overall status is 'ok' if all services return OK, else 'FAIL' (app/models/foreman_rh_cloud/ping.rb62)

Status Extension

Provides deployment mode metadata:

Plugin Metadata Registry

The plugin registers metadata accessible to the frontend via Foreman::Plugin.app_metadata_registry:

This metadata is used by frontend components to determine deployment mode and conditionally render UI elements (standard vs. Scalprum-based).

Sources: app/models/foreman_rh_cloud/ping.rb1-91 lib/foreman_rh_cloud/plugin.rb164-165 lib/foreman_rh_cloud/plugin.rb187-189

---

Next Steps

• For plugin structure and build system details, see Plugin Structure and Packaging
• For deployment mode differences and configuration, see Deployment Modes: Hosted vs. IoP
• For configuration settings and their effects, see Configuration and Settings
• For architectural details, see Plugin Architecture
• For inventory report generation, see Inventory Report Generation