Upstreamize VM subscriptions guide #3528

apinnick · 2024-12-15T14:40:25Z

What changes are you introducing?

Upstreamizing VM subscriptions guide.

Updated doc title because user story is configuring virt-who for VM subscriptions, not configuring the subscriptions themselves.
Updated UI procedure for creating virt-who configs for Nutanix and CNV
Removed troubleshooting sections that duplicated troubleshooting content in Subscription Central doc, Getting started with RHEL system registration, retaining only Satellite/Foreman procedures.

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

https://issues.redhat.com/browse/SAT-27789

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.13/Katello 4.15
Foreman 3.12/Katello 4.14 (Satellite 6.16)
Foreman 3.11/Katello 4.13 (orcharhino 6.11 on EL8 only)
Foreman 3.10/Katello 4.12
Foreman 3.9/Katello 4.11 (Satellite 6.15; orcharhino 6.8/6.9/6.10)
Foreman 3.8/Katello 4.10
Foreman 3.7/Katello 4.9 (Satellite 6.14)
We do not accept PRs for Foreman older than 3.7.

github-actions · 2024-12-15T14:43:11Z

The PR preview for f55acc9 is available at theforeman-foreman-documentation-preview-pr-3528.surge.sh

The following output files are affected by this PR:

show diff

show diff as HTML

apinnick · 2024-12-22T08:35:04Z

@chris1984 Please review.

guides/common/assembly_managing-virt-who-configurations.adoc

guides/common/modules/con_managing-virt-who-configurations.adoc

guides/common/modules/con_troubleshooting-virt-who.adoc

guides/common/modules/con_virtual-machine-subscriptions-overview.adoc

guides/common/modules/proc_enabling-rhsm-debug-logging.adoc

guides/common/modules/proc_removing-a-virt-who-configuration.adoc

guides/common/modules/proc_editing-a-virt-who-configuration.adoc

Lennonka

Generally looks good! I've taken a look at a couple of top-level formalities so far. Will give it another round afterwards.

guides/doc-Configuring_Virt-Who-VM-Subscriptions/master.adoc

guides/common/modules/snip_technology-preview.adoc

guides/common/attributes-titles.adoc

guides/upstream_filename_to_satellite_link.json

Lennonka

I tried to go more in depth with my review. This is what stood out.

Lennonka · 2025-01-09T15:43:27Z

guides/doc-Configuring_Virt-Who-VM-Subscriptions/docinfo.xml

@@ -0,0 +1,15 @@
+<title>Configuring virt-who for virtual machine subscriptions</title>


Suggested change

<title>Configuring virt-who for virtual machine subscriptions</title>

<title>{ConfiguringVMSubscriptionsDocTitle}</title>

You can use the DocTitle attribute here as well.

Lennonka · 2025-01-09T15:45:14Z

guides/doc-Configuring_Virt-Who-VM-Subscriptions/docinfo.xml

+<title>Configuring virt-who for virtual machine subscriptions</title>
+<productname>{ProjectName}</productname>
+<productnumber>{ProjectVersion}</productnumber>
+<subtitle>Tracking the usage of your host-based subscriptions</subtitle>


Suggested change

<subtitle>Tracking the usage of your host-based subscriptions</subtitle>

<subtitle>Track the usage of your host-based subscriptions</subtitle>

We use this verb form in other subtitles.

Lennonka · 2025-01-09T15:50:52Z

guides/common/modules/proc_deploying-a-virt-who-configuration-on-a-separate-rhel-server.adoc

+. On the {EL} server, install the {ProjectServer} CA certificate:
+
+[options="nowrap" subs="+quotes"]
+----
+$ rpm -ivh http://__{server.example.com}__/pub/katello-ca-consumer-latest.noarch.rpm
+----
+
+. Register the {EL} server to {ProjectServer}:
+
+[options="nowrap" subs="+quotes"]
+----
+$ subscription-manager register \
+--org=_organization_label_ \
+--auto-attach
+----


These two steps look like an outdated way to register a host because the Katello CA consumer package is deprecated. Perhaps we should link to global registration instead?

Lennonka · 2025-01-09T15:55:35Z

guides/common/modules/snip_technology-preview.adoc

+[IMPORTANT]
+====
+[subs="attributes+"]
+{FeatureName} is a Technology Preview feature only. Technology Preview features are not supported with Red Hat production service level agreements (SLAs) and might not be functionally complete. Red Hat does not recommend using them in production. These features provide early access to upcoming product features, enabling customers to test functionality and provide feedback during the development process.


One sentence per line.

guides/common/attributes-titles.adoc

Lennonka · 2025-01-09T16:07:31Z

guides/common/modules/ref_virt-who-configuration-examples.adoc

Could we make the example values a bit more descriptive and use a bit more formatting to distinguish values that are to be replaced by the user? For example:

hypervisor_id=_hypervisor.example.com_ server=_server.example.com_

Btw, what server is server.example.com? If it's supposed to be the Foreman/Satellite server, you can use the {foreman-example-com} attribute.

Lennonka · 2025-01-09T16:16:09Z

guides/doc-Configuring_Virt-Who-VM-Subscriptions/master.adoc

+:virt-who-vm-subs:
+:ProductName: {ProjectServer}
+
+= {ConfiguringVMSubscriptionsDocTitle}


For some reason, the build displays "Configuring virtual machine subscriptions" as the title. I don't understand why.

Lennonka · 2025-01-09T16:17:50Z

guides/upstream_filename_to_satellite_link.json

@@ -2,6 +2,7 @@
  "build/Administering_Project/index-satellite.html": "administering_red_hat_satellite",
  "build/Configuring_Load_Balancer/index-satellite.html": "configuring_capsules_with_a_load_balancer",
  "build/Configuring_User_Authentication/index-satellite.html": "configuring_authentication_for_red_hat_satellite_users",
+  "build/Configuring_Virtual_Machine_Subscriptions/index-satellite.html": "configuring_virt-who_for_virtual_machine_subscriptions",


Suggested change

"build/Configuring_Virtual_Machine_Subscriptions/index-satellite.html": "configuring_virt-who_for_virtual_machine_subscriptions",

"build/Configuring_Virt-Who-VM-Subscriptions/index-satellite.html": "configuring_virt-who_for_virtual_machine_subscriptions",

This path has to match the folder name after the doc- prefix.

Lennonka · 2025-01-09T16:20:39Z

guides/common/modules/ref_virt-who-troubleshooting-scenarios.adoc

I can't see this file included anywhere.

Lennonka · 2025-01-09T16:22:18Z

guides/common/modules/ref_troubleshooting-virt-who.adoc

I can't see this file included anywhere.

chris1984

Left a few comments around ovirt, debugging and hammer. Overall looks pretty good

chris1984 · 2025-01-09T16:14:54Z

guides/common/modules/con_deploying-virt-who-configurations.adoc

+After you create a virt-who configuration, you download a script from the {ProjectWebUI} to deploy the configuration.
+
+The script installs virt-who and creates the local and global virt-who configuration files.
+


Should we mention you can deploy the script on the {ProjectWebUI} with hammer as well?

chris1984 · 2025-01-09T16:17:23Z

guides/common/modules/con_virtual-machine-subscriptions-overview.adoc

+* VMware vSphere
+* {EL} Virtualization (KVM)
+* {OpenStack}
+* {oVirt}


Downstream we don't support {oVirt} anymore and the project upstream has been abandoned. We remove support for it here theforeman/foreman_virt_who_configure#136

chris1984 · 2025-01-09T16:19:03Z

guides/common/modules/proc_creating-a-virt-who-configuration.adoc

+* Microsoft Hyper-V:
+** You have enabled remote management on each hypervisor.
+** You have created a virt-who user with read-only access and a non-expiring password on each hypervisor.
+* {oVirt}, {EL} Virtualization (KVM), {OpenStack}:


Drop {oVirt}

chris1984 · 2025-01-09T16:19:31Z

guides/common/modules/proc_creating-a-virt-who-configuration.adoc

+* *Hypervisor Type*: Select one of the following types:
+** *VMware vSphere / vCenter (esx)*.
+** *Microsoft Hyper-V (hyperv)*.
+** *libvirt*: For {oVirt}, {EL} Virtualization (KVM), or {OpenStack}.


Drop {oVirt}

chris1984 · 2025-01-09T16:19:54Z

guides/common/modules/proc_creating-a-virt-who-configuration.adoc

+====
+
+<4> Specify the hypervisor type:
+* {EL} Virtualization (KVM), {oVirt}, or {OpenStack}: `libvirt`.


Drop {oVirt}

chris1984 · 2025-01-09T16:20:14Z

guides/common/modules/proc_deploying-a-virt-who-configuration-on-a-hypervisor.adoc

+.Prerequisites
+
+* You have registered the hypervisor to {ProjectServer}.
+* {oVirt}: You have updated {oVirt} to the latest version so that the minimum virt-who version is available.


Drop {oVirt}

chris1984 · 2025-01-09T16:20:17Z

guides/common/modules/proc_deploying-a-virt-who-configuration-on-a-hypervisor.adoc

+[id="deploying-a-virt-who-configuration-on-a-hypervisor_{context}"]
+= Deploying a virt-who configuration on a hypervisor or a {SmartProxyServer}
+
+For {oVirt}, {EL} Virtualization (KVM), and {OpenStack}, you deploy the configuration on the hypervisor specified in the file.


Drop {oVirt}

chris1984 · 2025-01-09T16:20:27Z

guides/common/modules/proc_deploying-a-virt-who-configuration-on-a-hypervisor.adoc

+
+* You have registered the hypervisor to {ProjectServer}.
+* {oVirt}: You have updated {oVirt} to the latest version so that the minimum virt-who version is available.
+virt-who is available by default on {oVirt}, but you cannot update virt-who by using the `rhel-7-server-rhvh-4-rpms` repository.


Drop {oVirt}

chris1984 · 2025-01-09T16:25:57Z

guides/common/modules/ref_troubleshooting-virt-who.adoc

+# virt-who -op >/tmp/virt-who.json
+# systemctl start virt-who
+# cat /tmp/virt-who.json | json_reformat | grep "guestId" | sort | uniq -c | wc -l
+----


Looks really good, sent you a link on Slack to some of the debugging steps support uses, that maybe we can include here as well?

pr-processor bot added the Not yet reviewed label Dec 15, 2024

apinnick force-pushed the upstreamize-vm-subscription-guide branch 7 times, most recently from 4eba9e6 to 0cdf087 Compare December 16, 2024 15:11

apinnick marked this pull request as draft December 17, 2024 11:54

apinnick force-pushed the upstreamize-vm-subscription-guide branch 7 times, most recently from f0529d6 to 7905ee8 Compare December 18, 2024 15:42

apinnick marked this pull request as ready for review December 18, 2024 15:46

apinnick changed the title ~~Upstreamize VM subscriptions guide (WIP)~~ Upstreamize VM subscriptions guide Dec 18, 2024

apinnick added Needs tech review Requires a review from the technical perspective Needs style review Requires a review from docs style/grammar perspective labels Dec 18, 2024

apinnick force-pushed the upstreamize-vm-subscription-guide branch from 7905ee8 to 2c90793 Compare December 18, 2024 16:04

maximiliankolb reviewed Jan 3, 2025

View reviewed changes

pr-processor bot removed the Not yet reviewed label Jan 3, 2025

apinnick force-pushed the upstreamize-vm-subscription-guide branch from 37f3007 to f16c7f4 Compare January 5, 2025 13:08

Lennonka requested changes Jan 7, 2025

View reviewed changes

pr-processor bot added the Waiting on contributor Requires an action from the author label Jan 7, 2025

Upstreamize VM subscriptions guide

7a0b08a

apinnick force-pushed the upstreamize-vm-subscription-guide branch from f16c7f4 to f0321f9 Compare January 9, 2025 12:13

pr-processor bot added Needs re-review and removed Waiting on contributor Requires an action from the author Needs re-review labels Jan 9, 2025

peer review changes

f55acc9

apinnick force-pushed the upstreamize-vm-subscription-guide branch from f0321f9 to f55acc9 Compare January 9, 2025 14:18

Lennonka reviewed Jan 9, 2025

View reviewed changes

chris1984 reviewed Jan 9, 2025

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Upstreamize VM subscriptions guide #3528

Upstreamize VM subscriptions guide #3528

apinnick commented Dec 15, 2024 •

edited

Loading

github-actions bot commented Dec 15, 2024 •

edited

Loading

apinnick commented Dec 22, 2024

Lennonka left a comment

Lennonka left a comment

Lennonka Jan 9, 2025

Lennonka Jan 9, 2025

Lennonka Jan 9, 2025 •

edited

Loading

Lennonka Jan 9, 2025

Lennonka Jan 9, 2025

Lennonka Jan 9, 2025

Lennonka Jan 9, 2025

Lennonka Jan 9, 2025

Lennonka Jan 9, 2025

chris1984 left a comment

chris1984 Jan 9, 2025

chris1984 Jan 9, 2025

chris1984 Jan 9, 2025

chris1984 Jan 9, 2025

chris1984 Jan 9, 2025

chris1984 Jan 9, 2025

chris1984 Jan 9, 2025

chris1984 Jan 9, 2025

chris1984 Jan 9, 2025

		@@ -0,0 +1,15 @@
		<title>Configuring virt-who for virtual machine subscriptions</title>

	<title>Configuring virt-who for virtual machine subscriptions</title>
	<title>{ConfiguringVMSubscriptionsDocTitle}</title>

	<subtitle>Tracking the usage of your host-based subscriptions</subtitle>
	<subtitle>Track the usage of your host-based subscriptions</subtitle>

	"build/Configuring_Virtual_Machine_Subscriptions/index-satellite.html": "configuring_virt-who_for_virtual_machine_subscriptions",
	"build/Configuring_Virt-Who-VM-Subscriptions/index-satellite.html": "configuring_virt-who_for_virtual_machine_subscriptions",

		After you create a virt-who configuration, you download a script from the {ProjectWebUI} to deploy the configuration.

		The script installs virt-who and creates the local and global virt-who configuration files.

Upstreamize VM subscriptions guide #3528

Are you sure you want to change the base?

Upstreamize VM subscriptions guide #3528

Conversation

apinnick commented Dec 15, 2024 • edited Loading

What changes are you introducing?

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

Checklists

github-actions bot commented Dec 15, 2024 • edited Loading

apinnick commented Dec 22, 2024

Lennonka left a comment

Choose a reason for hiding this comment

Lennonka left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Lennonka Jan 9, 2025 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

chris1984 left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

apinnick commented Dec 15, 2024 •

edited

Loading

github-actions bot commented Dec 15, 2024 •

edited

Loading

Lennonka Jan 9, 2025 •

edited

Loading