Skip to content

Conversation

@Lennonka
Copy link
Contributor

@Lennonka Lennonka commented Dec 9, 2025

What changes are you introducing?

Splitting the Monitoring hosts by using Insights (=Lightspeed) chapter

Why are you introducing these changes? (Explanation, links to references, issues, etc.)

  • Formely mixed together Insights in RH Cloud and Insights in project
  • Difficult to understand
  • 3.16 introduced a new parameter host_registration_insights_inventory

Anything else to add? (Considerations, potential downsides, alternative solutions you have explored, etc.)

Contributor checklists

  • I am okay with my commits getting squashed when you merge this PR.
  • I am familiar with the contributing guidelines.

Please cherry-pick my commits into:

  • Foreman 3.17/Katello 4.19
  • Foreman 3.16/Katello 4.18 (Satellite 6.18)
  • Foreman 3.15/Katello 4.17
  • Foreman 3.14/Katello 4.16 (Satellite 6.17; orcharhino 7.4)
  • Foreman 3.13/Katello 4.15 (EL9 only)
  • Foreman 3.12/Katello 4.14 (Satellite 6.16; orcharhino 7.2 on EL9 only; orcharhino 7.3)
  • We do not accept PRs for Foreman older than 3.12.

Summary by Sourcery

Restructure and split the Lightspeed/Insights host monitoring documentation into separate cloud and project-focused assemblies and modules.

Documentation:

  • Introduce separate assemblies for monitoring hosts with Insights in Red Hat Cloud and in projects, with corresponding conceptual and procedural modules.
  • Rename and reorganize existing Insights-related procedures and concepts to focus terminology on hosts and clarify remediation, deployment, vulnerability, and recommendations workflows.
  • Remove the previous combined Insights monitoring assembly and outdated RH Cloud + Insights reporting modules in favor of the new split structure.

Summary by Sourcery

Restructure the Lightspeed/Insights host monitoring documentation by splitting cloud-based and project-based workflows into separate assemblies and updating related terminology.

Documentation:

  • Add new assemblies and conceptual/procedural modules for monitoring hosts with Insights in Red Hat Cloud and in projects, including configuration, analytics, recommendations, remediation, and data control topics.
  • Rename and reframe existing Insights procedures to focus on hosts (deployment, vulnerability assessment, data minimization, and inventory cleanup) for clearer guidance.
  • Remove the previous combined Insights monitoring assembly and outdated RH Cloud reporting modules in favor of the new split structure.

@sourcery-ai
Copy link

sourcery-ai bot commented Dec 9, 2025

Reviewer's guide (collapsed on small PRs)

Reviewer's Guide

Reworks the Lightspeed/Insights documentation by splitting the previously combined host monitoring assembly into separate cloud-focused and project-focused docs, renaming modules and procedures to emphasize hosts terminology, and adding new guidance around Insights analytics, project/cloud configuration, data control, and the new host_registration_insights_inventory parameter while removing superseded content.

File-Level Changes

Change Details Files
Split the monolithic Lightspeed/Insights host monitoring guide into separate assemblies for monitoring via Red Hat Cloud vs in-project workflows.
  • Add assembly_monitoring-hosts-by-using-insights-in-cloud.adoc focused on connecting a project server to Red Hat Cloud and using Insights analytics from the cloud side.
  • Add assembly_monitoring-hosts-by-using-insights-in-project.adoc focused on Insights usage and workflows within a project context.
  • Remove the previous combined assembly_monitoring-hosts-by-using-insights.adoc and its umbrella conceptual module in favor of the two new assemblies.
guides/common/assembly_monitoring-hosts-by-using-insights-in-cloud.adoc
guides/common/assembly_monitoring-hosts-by-using-insights-in-project.adoc
guides/common/assembly_monitoring-hosts-by-using-insights.adoc
guides/common/modules/con_monitoring-hosts-by-using-insights.adoc
Introduce new conceptual and procedural modules that clarify host-centric Insights workflows and configuration, including data control and analytics exclusions.
  • Add conceptual modules for monitoring-hosts-by-using-insights-in-cloud and in-project that describe architecture, flows, and prerequisites.
  • Add con_data-control-settings.adoc and related procedures for minimizing collected data, obfuscating hostnames/IPs, and controlling Insights analytics behavior.
  • Add ref_exclusion-of-hosts-from-insights-analytics.adoc and related procedures for excluding hosts and managing analytics participation.
  • Add new procedures for enabling Insights analytics for hosts, examining recommendations, and remediating issues based on recommendations, replacing older RH Cloud + Insights report procedures.
guides/common/modules/con_data-control-settings.adoc
guides/common/modules/con_monitoring-hosts-by-using-insights-in-cloud.adoc
guides/common/modules/con_monitoring-hosts-by-using-insights-in-project.adoc
guides/common/modules/proc_enabling-insights-analytics-for-hosts.adoc
guides/common/modules/proc_examining-recommendations-for-hosts.adoc
guides/common/modules/proc_remediating-issues-based-on-insights-recommendations.adoc
guides/common/modules/ref_exclusion-of-hosts-from-insights-analytics.adoc
guides/common/modules/proc_enabling-rh-cloud-and-insights-client-reports-on-hosts.adoc
guides/common/modules/proc_excluding-hosts-from-rh-cloud-and-insights-client-reports.adoc
Align existing Insights-related procedures and references with host-centric terminology and the new split structure.
  • Rename and update the deployment procedure from using an Ansible role to deploying the Insights client on registered hosts, reflecting current workflows and parameters.
  • Rename vulnerability analysis, minimal data collection, and automatic Insights inventory cleanup procedures to focus on hosts, with content tweaks to point to new assemblies and the host_registration_insights_inventory parameter.
  • Adjust registration methods and managing-hosts master assembly to link to the new cloud vs project monitoring assemblies instead of the previous combined guide.
guides/common/modules/proc_deploying-insights-client-on-registered-hosts.adoc
guides/common/modules/proc_examining-vulnerability-of-hosts.adoc
guides/common/modules/proc_minimizing-collected-data.adoc
guides/common/modules/proc_removing-hosts-from-insights-inventory.adoc
guides/common/modules/proc_synchronizing-insights-recommendations-for-hosts.adoc
guides/common/modules/proc_setting-minimal-data-collection.adoc
guides/common/modules/proc_deploying-insights-by-using-the-ansible-role.adoc
guides/common/modules/proc_configuring-automatic-removal-of-hosts-from-the-insights-inventory.adoc
guides/common/modules/proc_examining-vulnerability-of-systems.adoc
guides/common/modules/proc_obfuscating-hostnames-and-ip-addresses.adoc
guides/common/modules/ref_registration-methods.adoc
guides/doc-Managing_Hosts/master.adoc
Add project-server and cloud-connection setup procedures that clarify SSH key and connection configuration steps.
  • Add proc_adding-project-server-ssh-key-to-authorized-keys.adoc to document how to configure SSH trust for the project server.
  • Add proc_configuring-project-server-for-cloud-connection.adoc to walk through connecting the project server to Red Hat Cloud for Insights usage.
guides/common/modules/proc_adding-project-server-ssh-key-to-authorized-keys.adoc
guides/common/modules/proc_configuring-project-server-for-cloud-connection.adoc
Remove outdated or redundant modules superseded by the new structure and terminology.
  • Delete the remediation-plan procedure that is no longer referenced in the reworked flows.
  • Remove the RH Cloud + Insights reporting access/reference module that duplicated information now covered by the new assemblies.
guides/common/modules/proc_creating-an-insights-remediation-plan-for-hosts.adoc
guides/common/modules/ref_access-to-information-from-insights-in-project.adoc

Tips and commands

Interacting with Sourcery

  • Trigger a new review: Comment @sourcery-ai review on the pull request.
  • Continue discussions: Reply directly to Sourcery's review comments.
  • Generate a GitHub issue from a review comment: Ask Sourcery to create an
    issue from a review comment by replying to it. You can also reply to a
    review comment with @sourcery-ai issue to create an issue from it.
  • Generate a pull request title: Write @sourcery-ai anywhere in the pull
    request title to generate a title at any time. You can also comment
    @sourcery-ai title on the pull request to (re-)generate the title at any time.
  • Generate a pull request summary: Write @sourcery-ai summary anywhere in
    the pull request body to generate a PR summary at any time exactly where you
    want it. You can also comment @sourcery-ai summary on the pull request to
    (re-)generate the summary at any time.
  • Generate reviewer's guide: Comment @sourcery-ai guide on the pull
    request to (re-)generate the reviewer's guide at any time.
  • Resolve all Sourcery comments: Comment @sourcery-ai resolve on the
    pull request to resolve all Sourcery comments. Useful if you've already
    addressed all the comments and don't want to see them anymore.
  • Dismiss all Sourcery reviews: Comment @sourcery-ai dismiss on the pull
    request to dismiss all existing Sourcery reviews. Especially useful if you
    want to start fresh with a new review - don't forget to comment
    @sourcery-ai review to trigger a new review!

Customizing Your Experience

Access your dashboard to:

  • Enable or disable review features such as the Sourcery-generated pull request
    summary, the reviewer's guide, and others.
  • Change the review language.
  • Add, remove or edit custom review instructions.
  • Adjust other review settings.

Getting Help

@github-actions github-actions bot added Needs tech review Requires a review from the technical perspective Needs style review Requires a review from docs style/grammar perspective Needs testing Requires functional testing labels Dec 9, 2025
@github-actions
Copy link

github-actions bot commented Dec 9, 2025

The PR preview for b39e58b is available at theforeman-foreman-documentation-preview-pr-4524.surge.sh

The following output files are affected by this PR:

show diff

show diff as HTML

Copy link
Contributor

@jeremylenz jeremylenz left a comment

Choose a reason for hiding this comment

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

Thanks @Lennonka

Some inline comments

Copy link
Contributor

@jeremylenz jeremylenz left a comment

Choose a reason for hiding this comment

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

A few more I found while reading the preview

@Lennonka Lennonka changed the title Restructure Lightspeed docs Rework Lightspeed docs Dec 15, 2025
@Lennonka Lennonka requested a review from jeremylenz December 16, 2025 17:53
@Lennonka
Copy link
Contributor Author

Relevant preview links:

I'm not sure why the preview build produces so many links.

@Lennonka Lennonka marked this pull request as ready for review December 16, 2025 20:55
Copy link

@sourcery-ai sourcery-ai bot left a comment

Choose a reason for hiding this comment

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

Hey there - I've reviewed your changes - here's some feedback:

  • Since several modules and assemblies were renamed or split (for example, systemshosts and the new cloud vs project assemblies), double-check that all cross-references and includes in doc-Managing_Hosts/master.adoc and related guides point to the new file names and IDs to avoid broken links.
  • There is now some conceptual overlap between the cloud and project monitoring assemblies; consider factoring shared explanations (such as what Insights data is collected and how Lightspeed fits in) into a single reusable conceptual module to avoid divergence over time.
  • The terminology around Lightspeed vs Insights (and RH Cloud vs project) is central to this restructure; verify that the wording is consistent across the new modules (for example, consistently using ‘hosts’ and a single term for the inventory parameter) so users don’t have to infer that different phrases refer to the same feature.
Prompt for AI Agents
Please address the comments from this code review:

## Overall Comments
- Since several modules and assemblies were renamed or split (for example, `systems``hosts` and the new cloud vs project assemblies), double-check that all cross-references and includes in `doc-Managing_Hosts/master.adoc` and related guides point to the new file names and IDs to avoid broken links.
- There is now some conceptual overlap between the cloud and project monitoring assemblies; consider factoring shared explanations (such as what Insights data is collected and how Lightspeed fits in) into a single reusable conceptual module to avoid divergence over time.
- The terminology around Lightspeed vs Insights (and RH Cloud vs project) is central to this restructure; verify that the wording is consistent across the new modules (for example, consistently using ‘hosts’ and a single term for the inventory parameter) so users don’t have to infer that different phrases refer to the same feature.

## Individual Comments

### Comment 1
<location> `guides/common/modules/proc_adding-project-server-ssh-key-to-authorized-keys.adoc:19` </location>
<code_context>
-To remove existing data of a system, navigate to *Inventory* > *Systems* in the {RHCloud}, select the system, and click *Delete*.
-* You have selected an organization and location.       
-
-.Procedure
-. In the {ProjectWebUI}, navigate to *{Insights}* > *Inventory Upload*.
-. Select the *Minimal data collection* setting from the dropdown menu under *Settings*.
</code_context>

<issue_to_address>
**suggestion (review_instructions):** This SSH key configuration procedure does not provide a verification step to ensure remote execution from {ProjectServer} will work.

Given that the goal is to enable remote execution on {ProjectServer}, it would be helpful to add a verification section describing how to confirm that the key setup works (for example, testing SSH from the `foreman-proxy` user to root on {ProjectServer} or running a simple remote execution job targeting {ProjectServer}).

<details>
<summary>Review instructions:</summary>

**Path patterns:** `guides/common/modules/proc*.adoc`

**Instructions:**
Verification steps are included where appropriate.

</details>
</issue_to_address>

### Comment 2
<location> `guides/common/modules/proc_enabling-insights-analytics-for-hosts.adoc:31` </location>
<code_context>
-To remove existing data of a system, navigate to *Inventory* > *Systems* in the {RHCloud}, select the system, and click *Delete*.
-* You have selected an organization and location.       
-
-.Procedure
-. In the {ProjectWebUI}, navigate to *{Insights}* > *Inventory Upload*.
-. Select the *Minimal data collection* setting from the dropdown menu under *Settings*.
</code_context>

<issue_to_address>
**suggestion (review_instructions):** The procedure for enabling {Insights} analytics and related parameters does not include guidance on verifying that analytics and reporting are actually enabled for the selected hosts.

Because this procedure controls analytics enablement and inventory uploads, it should have a verification section—for example, how to check that the parameters are in effect on a host, that the Insights client runs as expected, and, where applicable, that hosts appear in the {RHCloud} inventory/analytics views.

<details>
<summary>Review instructions:</summary>

**Path patterns:** `guides/common/modules/proc*.adoc`

**Instructions:**
Verification steps are included where appropriate.

</details>
</issue_to_address>

### Comment 3
<location> `guides/common/modules/ref_exclusion-of-hosts-from-insights-analytics.adoc:21` </location>
<code_context>
+
+ifdef::insights-in-cloud[]
+`host_registration_insights_inventory`::
+Setting this parameter to `false` will exclude the host from the {Project} host inventory that is uploaded to the {RHCloud}.
++
+If you exclude a host that is already reported on the https://console.redhat.com/[{RHCloud}], it will be still removed automatically from the inventory.
</code_context>

<issue_to_address>
**suggestion (review_instructions):** The phrase "that is uploaded to the {RHCloud}" uses passive voice and can be rephrased to active voice.

Consider rephrasing to active voice, for example: "from the {Project} host inventory that {Project} uploads to the {RHCloud}" or "from the {Project} host inventory uploaded to the {RHCloud}."

<details>
<summary>Review instructions:</summary>

**Path patterns:** `guides/common/*.adoc,guides/common/modules/*.adoc`

**Instructions:**
Avoid passive voice in verbs.

</details>
</issue_to_address>

### Comment 4
<location> `guides/common/modules/ref_exclusion-of-hosts-from-insights-analytics.adoc:23` </location>
<code_context>
+`host_registration_insights_inventory`::
+Setting this parameter to `false` will exclude the host from the {Project} host inventory that is uploaded to the {RHCloud}.
++
+If you exclude a host that is already reported on the https://console.redhat.com/[{RHCloud}], it will be still removed automatically from the inventory.
+However, this process can take some time to complete.
+endif::[]
</code_context>

<issue_to_address>
**suggestion (review_instructions):** The clause "it will be still removed automatically" is in passive voice and should be rewritten in active voice.

You could rephrase this to something like: "{Project} still removes the host automatically from the inventory" or "the host still gets removed automatically from the inventory" to avoid passive voice.

<details>
<summary>Review instructions:</summary>

**Path patterns:** `guides/common/*.adoc,guides/common/modules/*.adoc`

**Instructions:**
Avoid passive voice in verbs.

</details>
</issue_to_address>

Sourcery is free for open source - if you like our reviews please consider sharing them ✨
Help me be more useful! Please click 👍 or 👎 on each comment and I'll use the feedback to improve your reviews.


ifdef::insights-in-cloud[]
`host_registration_insights_inventory`::
Setting this parameter to `false` will exclude the host from the {Project} host inventory that is uploaded to the {RHCloud}.
Copy link

Choose a reason for hiding this comment

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

suggestion (review_instructions): The phrase "that is uploaded to the {RHCloud}" uses passive voice and can be rephrased to active voice.

Consider rephrasing to active voice, for example: "from the {Project} host inventory that {Project} uploads to the {RHCloud}" or "from the {Project} host inventory uploaded to the {RHCloud}."

Review instructions:

Path patterns: guides/common/*.adoc,guides/common/modules/*.adoc

Instructions:
Avoid passive voice in verbs.

`host_registration_insights_inventory`::
Setting this parameter to `false` will exclude the host from the {Project} host inventory that is uploaded to the {RHCloud}.
+
If you exclude a host that is already reported on the https://console.redhat.com/[{RHCloud}], it will be still removed automatically from the inventory.
Copy link

Choose a reason for hiding this comment

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

suggestion (review_instructions): The clause "it will be still removed automatically" is in passive voice and should be rewritten in active voice.

You could rephrase this to something like: "{Project} still removes the host automatically from the inventory" or "the host still gets removed automatically from the inventory" to avoid passive voice.

Review instructions:

Path patterns: guides/common/*.adoc,guides/common/modules/*.adoc

Instructions:
Avoid passive voice in verbs.

@Lennonka
Copy link
Contributor Author

Lennonka commented Dec 16, 2025

I've vamped it up a bit. This is good enough for now or I could improve it indefinitely!

@jeremylenz Can I please get a formal tech ack on these changes? Please, also check if the order of the sections in those chapters makes sense.

Using preview is recommended.

Copy link
Contributor

@jeremylenz jeremylenz left a comment

Choose a reason for hiding this comment

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

Ordering of the preview looks good to me and all comments are addressed. One optional note below, but consider this a dev ACK from my side. 👍

@Lennonka Lennonka removed the Needs tech review Requires a review from the technical perspective label Dec 16, 2025
@Lennonka Lennonka added tech review done No issues from the technical perspective and removed Needs testing Requires functional testing labels Dec 16, 2025
Comment on lines +35 to +36
* If you have problems connecting to {Insights}, ensure that your certificates are up-to-date.
Refresh your subscription manifest to update your certificates.
Copy link
Contributor

Choose a reason for hiding this comment

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

I do not understand which certificates this refers to: Red Hat manifest on Foreman+Katello (aka https://docs.theforeman.org/nightly/Managing_Content/index-katello.html#Updating_and_Refreshing_Red_Hat_Subscription_Manifests_content-management)? certificates on clients (aka subscription-manager refresh)?

@jeremylenz Could you please weigh in?

Copy link
Contributor

Choose a reason for hiding this comment

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

Refreshing a manifest updates the upstream consumer identity certificate in the Candlepin owner, which is used by foreman_rh_cloud as credentials to communicate with console dot.

@Lennonka
Copy link
Contributor Author

Anything else? 👀

Copy link
Contributor

@maximiliankolb maximiliankolb left a comment

Choose a reason for hiding this comment

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

style-wise LGTM. #4524 (comment) is still unclear to me but this could also be a follow-up.

@maximiliankolb maximiliankolb added style review done No issues from docs style/grammar perspective and removed Needs style review Requires a review from docs style/grammar perspective labels Dec 19, 2025
@Lennonka Lennonka merged commit 61a0ae7 into theforeman:master Dec 19, 2025
10 checks passed
Lennonka added a commit that referenced this pull request Dec 19, 2025
Lennonka added a commit that referenced this pull request Dec 19, 2025
@Lennonka
Copy link
Contributor Author

Cherry picked:

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

style review done No issues from docs style/grammar perspective tech review done No issues from the technical perspective

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants