Fix issues reported by asciidoctor-dita-vale (Configuring Load Balancer) (#4178)

aneta-petrova · Lennonka · maximiliankolb · web-flow · commit 368411f9d0a0 · 2025-08-27T16:54:53.000+02:00
* Address asciidoctor-dita-vale issues
* Convert xrefs
* Turn installing LB into an assembly
* Move Verification heading out of the snippet

---------

Co-authored-by: Lena Ansorgová &lt;zuansorg@redhat.com&gt;
Co-authored-by: Maximilian Kolb &lt;mail@maximilian-kolb.de&gt;
diff --git a/guides/common/assembly_installing-the-load-balancer.adoc b/guides/common/assembly_installing-the-load-balancer.adoc
@@ -0,0 +1,7 @@
+:_mod-docs-content-type: ASSEMBLY
+
+include::modules/con_installing-and-configuring-the-load-balancer.adoc[]
+
+include::modules/proc_installing-the-load-balancer.adoc[leveloffset=+1]
+
+include::modules/ref_ports-configuration-for-the-load-balancer.adoc[leveloffset=+1]
diff --git a/guides/common/assembly_registering-clients-to-the-load-balancer.adoc b/guides/common/assembly_registering-clients-to-the-load-balancer.adoc
@@ -0,0 +1,15 @@
+:_mod-docs-content-type: ASSEMBLY
+
+include::modules/con_registering-clients-to-the-load-balancer.adoc[]
+
+include::modules/proc_setting-the-load-balancer-for-host-registration.adoc[leveloffset=+1]
+
+include::modules/proc_registering-a-host-to-the-load-balancer-using-web-ui.adoc[leveloffset=+1]
+
+include::modules/proc_registering-a-host-to-the-load-balancer-using-cli.adoc[leveloffset=+1]
+
+include::modules/proc_registering-a-host-to-the-load-balancer-using-api.adoc[leveloffset=+1]
+
+ifdef::satellite[]
+include::modules/proc_registering-clients-using-the-bootstrap-script.adoc[leveloffset=+1]
+endif::[]
diff --git a/guides/common/modules/con_configuring-smartproxyservers-with-custom-ssl-certificates-for-load-balancing-without-puppet.adoc b/guides/common/modules/con_configuring-smartproxyservers-with-custom-ssl-certificates-for-load-balancing-without-puppet.adoc
@@ -7,4 +7,4 @@ You can configure one or more {SmartProxyServers} that use custom SSL certificat
 To do this, configure and install certificates on each {SmartProxyServer} you want to use for load balancing.
 
 If you use Puppet in your {Project} deployment, the configuration steps are different.
-See xref:configuring-{smart-proxy-context}-servers-with-custom-ssl-certificates-for-load-balancing-with-puppet_{context}[].
+See xref:common/modules/con_configuring-smartproxyservers-with-custom-ssl-certificates-for-load-balancing-with-puppet.adoc#configuring-{smart-proxy-context}-servers-with-custom-ssl-certificates-for-load-balancing-with-puppet_{context}[].
diff --git a/guides/common/modules/con_configuring-smartproxyservers-with-default-ssl-certificates-for-load-balancing-without-puppet.adoc b/guides/common/modules/con_configuring-smartproxyservers-with-default-ssl-certificates-for-load-balancing-without-puppet.adoc
@@ -6,4 +6,4 @@
 You can configure one or more {SmartProxyServers} that use default SSL certificates for load balancing.
 
 If you use Puppet in your {Project} deployment, the configuration steps are different.
-See xref:configuring-{smart-proxy-context}-servers-with-default-ssl-certificates-for-load-balancing-with-puppet_{context}[].
+See xref:common/modules/con_configuring-smartproxyservers-with-default-ssl-certificates-for-load-balancing-with-puppet.adoc#configuring-{smart-proxy-context}-servers-with-default-ssl-certificates-for-load-balancing-with-puppet_{context}[].
diff --git a/guides/common/modules/con_installing-and-configuring-the-load-balancer.adoc b/guides/common/modules/con_installing-and-configuring-the-load-balancer.adoc
@@ -0,0 +1,7 @@
+:_mod-docs-content-type: CONCEPT
+
+[id="installing-and-configuring-the-load-balancer"]
+= Installing and configuring the load balancer
+
+{Team} provides general guidance for configuring an HAProxy load balancer using {EL} 9.
+However, you can install any suitable load balancing software solution that supports TCP forwarding.
diff --git a/guides/common/modules/con_registering-clients-to-the-load-balancer.adoc b/guides/common/modules/con_registering-clients-to-the-load-balancer.adoc
@@ -7,15 +7,3 @@ To balance the load of network traffic from clients, you must register the clien
 
 To consume container content from a load balancer regardless of client registration, use the load balancer hostname with the container client of choice.
 For example, use `podman login {loadbalancer-example-com}` to log in.
-
-ifdef::orcharhino,satellite[]
-.Next steps
-* xref:Registering_Clients_Using_Host_Registration_{context}[]
-endif::[]
-ifdef::satellite[]
-* xref:Registering_Clients_Using_the_Bootstrap_Script_{context}[]
-endif::[]
-
-ifndef::orcharhino,satellite[]
-include::snip_host-registration-steps.adoc[]
-endif::[]
diff --git a/guides/common/modules/proc_configuring-repositories-foreman-el.adoc b/guides/common/modules/proc_configuring-repositories-foreman-el.adoc
@@ -4,4 +4,5 @@
 
 include::proc_configuring-repositories-el.adoc[]
 
+.Verification
 include::snip_verification-enabled-repolist.adoc[]
diff --git a/guides/common/modules/proc_configuring-repositories-proxy.adoc b/guides/common/modules/proc_configuring-repositories-proxy.adoc
@@ -24,4 +24,5 @@ Configure repositories to install your {SmartProxyServer}.
 --enable={RepoRHEL9ServerSatelliteMaintenanceProjectVersion}
 ----
 
+.Verification
 include::snip_verification-enabled-repolist.adoc[]
diff --git a/guides/common/modules/proc_configuring-repositories-satellite.adoc b/guides/common/modules/proc_configuring-repositories-satellite.adoc
@@ -18,4 +18,5 @@
 --enable={RepoRHEL9ServerSatelliteMaintenanceProjectVersion}
 ----
 
+.Verification
 include::snip_verification-enabled-repolist.adoc[]
diff --git a/guides/common/modules/proc_installing-the-load-balancer.adoc b/guides/common/modules/proc_installing-the-load-balancer.adoc
@@ -1,6 +1,6 @@
 :_mod-docs-content-type: PROCEDURE
 
-[id="Installing_the_Load_Balancer_{context}"]
+[id="installing-the-load-balancer"]
 = Installing the load balancer
 
 The following example provides general guidance for configuring an HAProxy load balancer using {EL} 9.
@@ -24,24 +24,7 @@ However, you can install any suitable load balancing software solution that supp
 ----
 # semanage boolean --modify --on haproxy_connect_any
 ----
-. Configure the load balancer to balance the network load for the ports as described in xref:ports-configuration-for-the-load-balancer[].
-For example, to configure ports for HAProxy, edit the `/etc/haproxy/haproxy.cfg` file to correspond with the table.
-ifdef::satellite[]
-For more information, see https://access.redhat.com/solutions/4062981[Configuration example for haproxy.cfg for HAProxy load balancer with Satellite 6] in the _Red{nbsp}Hat Knowledgebase_.
-endif::[]
-+
-[id="ports-configuration-for-the-load-balancer"]
-.Ports configuration for the load balancer
-[cols="3,1,1,2,3",options="header"]
-|====
-| Service | Port | Mode | Balance Mode | Destination
-| HTTP | 80 | TCP | roundrobin | port 80 on all {SmartProxyServers}
-| HTTPS and RHSM | 443 | TCP | source | port 443 on all {SmartProxyServers}
-| Anaconda for template retrieval | 8000 | TCP | roundrobin | port 8000 on all {SmartProxyServers}
-| Puppet (_Optional_)| 8140 | TCP | roundrobin | port 8140 on all {SmartProxyServers}
-| PuppetCA (_Optional_)| 8141 | TCP | roundrobin | port 8140 only on the system where you configure {SmartProxyServer} to sign Puppet certificates
-| {SmartProxy} HTTPS for Host Registration and optionally OpenSCAP| {smartproxy_port} | TCP | roundrobin | port {smartproxy_port} on all {SmartProxyServers}
-|====
+. Configure the load balancer to balance the network load for the ports as described in xref:common/modules/ref_ports-configuration-for-the-load-balancer.adoc#ports-configuration-for-the-load-balancer[].
 . Configure the load balancer to disable SSL offloading and allow client-side SSL certificates to pass through to back end servers.
 This is required because communication from clients to {SmartProxyServers} depends on client-side SSL certificates.
 . Start and enable the HAProxy service:
diff --git a/guides/common/modules/proc_registering-a-host-to-the-load-balancer-using-api.adoc b/guides/common/modules/proc_registering-a-host-to-the-load-balancer-using-api.adoc
@@ -0,0 +1,58 @@
+:_mod-docs-content-type: PROCEDURE
+
+[id="registering-a-host-to-the-load-balancer-using-api"]
+= Registering a host to the load balancer using API
+
+After setting the load balancer for host registration, you can register a host to a load-balanced {SmartProxy}.
+
+.Procedure
+. Generate the host registration command using the {Project} API:
++
+[options="nowrap" subs="+quotes,attributes"]
+----
+# curl -X POST https://{foreman-example-com}/api/registration_commands \
+--user "_My_User_Name_" \
+-H 'Content-Type: application/json' \
+-d '{ "registration_command": { "activation_keys": ["_My_Activation_Key_1_, _My_Activation_Key_2_"] }}'
+----
++
+If your hosts do not trust the SSL certificate of {ProjectServer}, you can disable SSL validation by adding the `--insecure` flag to the registration command.
++
+[options="nowrap" subs="+quotes,attributes"]
+----
+# curl -X POST https://{foreman-example-com}/api/registration_commands \
+--user "_My_User_Name_" \
+-H 'Content-Type: application/json' \
+-d '{ "registration_command": { "activation_keys": ["_My_Activation_Key_1_, _My_Activation_Key_2_"], "insecure": true }}'
+----
++
+Use an activation key to simplify specifying the environments.
+For more information, see {ContentManagementDocURL}Managing_Activation_Keys_content-management[Managing Activation Keys] in _{ContentManagementDocTitle}_.
++
+Include `{ "smart_proxy_id": __My_{smart-proxy-context-titlecase}_ID__ }`.
+You can use the ID of any {SmartProxyServer} that you configured for host registration load balancing.
+{Project} will apply the load balancer to the registration command automatically.
++
+Include `{ "force": true }` to register a host that has been previously registered to a {SmartProxyServer}.
++
+To enter a password as a command line argument, use `username:password` syntax.
+Keep in mind this can save the password in the shell history.
+Alternatively, you can use a temporary personal access token instead of a password.
+To generate a token in the {ProjectWebUI}, navigate to *My Account* > *Personal Access Tokens*.
+. Connect to your host using SSH and run the registration command.
+ifdef::satellite[]
+. Check the `/etc/yum.repos.d/redhat.repo` file and ensure that the appropriate repositories have been enabled.
+endif::[]
+ifndef::satellite[]
+. Ensure that the appropriate repositories have been enabled:
++
+ifdef::client-content-dnf[]
+* On {EL}: Check the `/etc/yum.repos.d/redhat.repo` file and ensure that the appropriate repositories have been enabled.
+endif::[]
+ifdef::client-content-apt[]
+* On Debian: Check the `/etc/apt/sources.list` file and ensure that the appropriate repositories have been enabled.
+endif::[]
+* On {DL}: Check the `/etc/apt/sources.list` file and ensure that the appropriate repositories have been enabled.
+* On {EL}: Check the `/etc/yum.repos.d/redhat.repo` file and ensure that the appropriate repositories have been enabled.
+* On {SLES}: Check the `/etc/zypp/repos.d/` directory and ensure that the appropriate repositories have been enabled.
+endif::[]
diff --git a/guides/common/modules/proc_registering-a-host-to-the-load-balancer-using-cli.adoc b/guides/common/modules/proc_registering-a-host-to-the-load-balancer-using-cli.adoc
@@ -0,0 +1,49 @@
+:_mod-docs-content-type: PROCEDURE
+
+[id="registering-a-host-to-the-load-balancer-using-cli"]
+= Registering a host to the load balancer using CLI
+
+After setting the load balancer for host registration, you can register a host to the load balancer.
+
+.Procedure
+. Generate the host registration command using the Hammer CLI:
++
+[options="nowrap" subs="+quotes,attributes"]
+----
+$ hammer host-registration generate-command \
+--activation-keys "_My_Activation_Key_"
+----
++
+If your hosts do not trust the SSL certificate of {ProjectServer}, you can disable SSL validation by adding the `--insecure` flag to the registration command.
++
+[options="nowrap" subs="+quotes,attributes"]
+----
+$ hammer host-registration generate-command \
+--activation-keys "_My_Activation_Key_" \
+--insecure true
+----
++
+Include the `--smart-proxy-id __My_{smart-proxy-context-titlecase}_ID__` option.
+You can use the ID of any {SmartProxyServer} that you configured for host registration load balancing.
+{Project} will apply the load balancer to the registration command automatically.
++
+Include the `--force` option to register a host that has been previously registered to a {SmartProxyServer}.
+. Connect to your host using SSH and run the registration command.
+ifdef::satellite[]
+. Check the `/etc/yum.repos.d/redhat.repo` file and ensure that the appropriate repositories have been enabled.
+endif::[]
+ifndef::satellite[]
+. Ensure that the appropriate repositories have been enabled:
++
+ifdef::client-content-dnf[]
+* On {EL}: Check the `/etc/yum.repos.d/redhat.repo` file and ensure that the appropriate repositories have been enabled.
+endif::[]
+ifdef::client-content-apt[]
+* On Debian: Check the `/etc/apt/sources.list` file and ensure that the appropriate repositories have been enabled.
+endif::[]
+ifdef::load-balancing[]
+* On {DL}: Check the `/etc/apt/sources.list` file and ensure that the appropriate repositories have been enabled.
+* On {EL}: Check the `/etc/yum.repos.d/redhat.repo` file and ensure that the appropriate repositories have been enabled.
+* On {SLES}: Check the `/etc/zypp/repos.d/` directory and ensure that the appropriate repositories have been enabled.
+endif::[]
+endif::[]
diff --git a/guides/common/modules/proc_registering-a-host-to-the-load-balancer-using-web-ui.adoc b/guides/common/modules/proc_registering-a-host-to-the-load-balancer-using-web-ui.adoc
@@ -0,0 +1,33 @@
+:_mod-docs-content-type: PROCEDURE
+
+[id="registering-a-host-to-the-load-balancer-using-web-ui"]
+= Registering a host to the load balancer using {ProjectWebUI}
+
+After setting the load balancer for host registration, you can register a host to the load balancer.
+
+.Procedure
+. In the {ProjectWebUI}, navigate to *Hosts* > *Register Host*.
+. From the *{SmartProxy}* dropdown list, select your {SmartProxyServer} configured for load balancing.
+. Select *Force* to register a host that has been previously registered to a {SmartProxyServer}.
+. From the *Activation Keys* list, select the activation keys to assign to your host.
+. Click *Generate* to create the registration command.
+. Click on the _files_ icon to copy the command to your clipboard.
+. Connect to your host using SSH and run the registration command.
+ifdef::satellite[]
+. Check the `/etc/yum.repos.d/redhat.repo` file and ensure that the appropriate repositories have been enabled.
+endif::[]
+ifndef::satellite[]
+. Ensure that the appropriate repositories have been enabled:
++
+ifdef::client-content-dnf[]
+* On {EL}: Check the `/etc/yum.repos.d/redhat.repo` file and ensure that the appropriate repositories have been enabled.
+endif::[]
+ifdef::client-content-apt[]
+* On Debian: Check the `/etc/apt/sources.list` file and ensure that the appropriate repositories have been enabled.
+endif::[]
+ifdef::load-balancing[]
+* On {DL}: Check the `/etc/apt/sources.list` file and ensure that the appropriate repositories have been enabled.
+* On {EL}: Check the `/etc/yum.repos.d/redhat.repo` file and ensure that the appropriate repositories have been enabled.
+* On {SLES}: Check the `/etc/zypp/repos.d/` directory and ensure that the appropriate repositories have been enabled.
+endif::[]
+endif::[]
diff --git a/guides/common/modules/proc_registering-capsule-to-satellite-server.adoc b/guides/common/modules/proc_registering-capsule-to-satellite-server.adoc
@@ -6,17 +6,17 @@
 Register the base operating system on which you want to install {SmartProxyServer} to {ProjectServer}.
 This enables you to download the installation packages from your synchronized repositories.
 
-.Red{nbsp}Hat subscription manifest prerequisites
-* On {ProjectServer}, a manifest must be installed and it must contain the appropriate repositories for the organization you want {SmartProxy} to belong to.
-* The manifest must contain repositories for the base operating system on which you want to install {SmartProxy}, as well as any clients that you want to connect to {SmartProxy}.
-* The repositories must be synchronized.
-
+.Prerequisites
+* Prerequisites for Red{nbsp}Hat subscription manifest:
+** On {ProjectServer}, a manifest must be installed and it must contain the appropriate repositories for the organization you want {SmartProxy} to belong to.
+** The manifest must contain repositories for the base operating system on which you want to install {SmartProxy}, as well as any clients that you want to connect to {SmartProxy}.
+** The repositories must be synchronized.
++
 For more information on manifests and repositories, see {ContentManagementDocURL}Managing_Red_Hat_Subscriptions_content-management[Managing Red Hat Subscriptions] in _{ContentManagementDocTitle}_.
-
-.Proxy and network prerequisites
-* The {ProjectServer} base operating system must be able to resolve the host name of the {SmartProxy} base operating system and vice versa.
-* Ensure HTTPS connection using client certificate authentication is possible between {SmartProxyServer} and {ProjectServer}.
+* Prerequisites for HTTP proxy and network:
+** The {ProjectServer} base operating system must be able to resolve the host name of the {SmartProxy} base operating system and vice versa.
+** Ensure HTTPS connection using client certificate authentication is possible between {SmartProxyServer} and {ProjectServer}.
 HTTP proxies between {SmartProxyServer} and {ProjectServer} are not supported.
-* You must configure the host and network-based firewalls accordingly.
+** You must configure the host and network-based firewalls accordingly.
 For more information, see {InstallingSmartProxyDocURL}{smart-proxy-context}-port-and-firewall-requirements_{smart-proxy-context}[Port and firewall requirements] in _{InstallingSmartProxyDocTitle}_.
 include::snip_host-registration-steps.adoc[]
diff --git a/guides/common/modules/proc_registering-clients-using-host-registration.adoc b/guides/common/modules/proc_registering-clients-using-host-registration.adoc
diff --git a/guides/common/modules/proc_registering-clients-using-the-bootstrap-script.adoc b/guides/common/modules/proc_registering-clients-using-the-bootstrap-script.adoc
@@ -46,5 +46,5 @@ For more information, see {ManagingHostsDocURL}Registering_Hosts_by_Using_the_Bo
 ----
 <1> Include the `--force` option to register the client that has been previously registered to a standalone {SmartProxy}.
 <2> Include the `--puppet-ca-port 8141` option if you use Puppet.
-
++
 The script prompts for the password corresponding to the {Project} user name you entered with the `--login` option.
diff --git a/guides/common/modules/proc_setting-the-load-balancer-for-host-registration.adoc b/guides/common/modules/proc_setting-the-load-balancer-for-host-registration.adoc
@@ -12,10 +12,10 @@ Upon registration, the subscription manager on the host will be configured to ma
 .Prerequisites
 * You configured SSL certificates on all {SmartProxyServers}.
 For more information, see the following sections:
-** xref:configuring-{smart-proxy-context}-servers-with-default-ssl-certificates-for-load-balancing-without-puppet_{context}[].
-** xref:configuring-{smart-proxy-context}-servers-with-custom-ssl-certificates-for-load-balancing-without-puppet_{context}[].
-** xref:configuring-{smart-proxy-context}-servers-with-default-ssl-certificates-for-load-balancing-with-puppet_{context}[].
-** xref:configuring-{smart-proxy-context}-servers-with-custom-ssl-certificates-for-load-balancing-with-puppet_{context}[].
+** xref:common/modules/con_configuring-smartproxyservers-with-default-ssl-certificates-for-load-balancing-without-puppet.adoc#configuring-{smart-proxy-context}-servers-with-default-ssl-certificates-for-load-balancing-without-puppet_{context}[].
+** xref:common/modules/con_configuring-smartproxyservers-with-custom-ssl-certificates-for-load-balancing-without-puppet.adoc#configuring-{smart-proxy-context}-servers-with-custom-ssl-certificates-for-load-balancing-without-puppet_{context}[].
+** xref:common/modules/con_configuring-smartproxyservers-with-default-ssl-certificates-for-load-balancing-with-puppet.adoc#configuring-{smart-proxy-context}-servers-with-default-ssl-certificates-for-load-balancing-with-puppet_{context}[].
+** xref:common/modules/con_configuring-smartproxyservers-with-custom-ssl-certificates-for-load-balancing-with-puppet.adoc#configuring-{smart-proxy-context}-servers-with-custom-ssl-certificates-for-load-balancing-with-puppet_{context}[].
 * You enabled Registration and Templates plugins on all {SmartProxyServers}:
 +
 [options="nowrap" subs="+quotes,attributes"]
diff --git a/guides/common/modules/ref_ports-configuration-for-the-load-balancer.adoc b/guides/common/modules/ref_ports-configuration-for-the-load-balancer.adoc
@@ -0,0 +1,24 @@
+:_mod-docs-content-type: REFERENCE
+
+[id="ports-configuration-for-the-load-balancer"]
+= Ports configuration for the load balancer
+
+The load balancer must be configured to balance the network load for the ports.
+For example, to configure ports for HAProxy, edit the `/etc/haproxy/haproxy.cfg` file to correspond with the table.
+
+.Ports configuration for the load balancer
+[cols="3,1,1,2,3",options="header"]
+|====
+| Service | Port | Mode | Balance Mode | Destination
+| HTTP | 80 | TCP | roundrobin | port 80 on all {SmartProxyServers}
+| HTTPS and RHSM | 443 | TCP | source | port 443 on all {SmartProxyServers}
+| Anaconda for template retrieval | 8000 | TCP | roundrobin | port 8000 on all {SmartProxyServers}
+| Puppet (_Optional_)| 8140 | TCP | roundrobin | port 8140 on all {SmartProxyServers}
+| PuppetCA (_Optional_)| 8141 | TCP | roundrobin | port 8140 only on the system where you configure {SmartProxyServer} to sign Puppet certificates
+| {SmartProxy} HTTPS for Host Registration and optionally OpenSCAP| {smartproxy_port} | TCP | roundrobin | port {smartproxy_port} on all {SmartProxyServers}
+|====
+
+ifdef::satellite[]
+.Additional resources
+* https://access.redhat.com/solutions/4062981[Configuration example for haproxy.cfg for HAProxy load balancer with Satellite 6 in the _Red{nbsp}Hat Knowledgebase_]
+endif::[]
diff --git a/guides/common/modules/ref_prerequisites-configuring-smartproxyservers-for-load-balancing.adoc b/guides/common/modules/ref_prerequisites-configuring-smartproxyservers-for-load-balancing.adoc
@@ -4,5 +4,5 @@
 = Prerequisites
 
 * Prepare a new {SmartProxyServer} to use for load balancing.
-See xref:preparing-{smart-proxy-context}-servers-for-load-balancing_load-balancing[].
-* Review xref:services-and-features-supported-in-a-load-balanced-setup_load-balancing[].
+See xref:common/modules/con_preparing-smartproxyservers-for-load-balancing.adoc#preparing-{smart-proxy-context}-servers-for-load-balancing_load-balancing[].
+* Review xref:common/modules/con_services-and-features-supported-in-a-load-balanced-setup.adoc#services-and-features-supported-in-a-load-balanced-setup_load-balancing[].
diff --git a/guides/common/modules/snip_host-registration-steps.adoc b/guides/common/modules/snip_host-registration-steps.adoc
diff --git a/guides/common/modules/snip_verification-enabled-repolist.adoc b/guides/common/modules/snip_verification-enabled-repolist.adoc
diff --git a/guides/doc-Configuring_Load_Balancer/master.adoc b/guides/doc-Configuring_Load_Balancer/master.adoc

Original file line number	Diff line number	Diff line change
`@@ -4,4 +4,5 @@`
`4`	`4`
`5`	`5`	`include::proc_configuring-repositories-el.adoc[]`
`6`	`6`
	`7`	`+.Verification`
`7`	`8`	`include::snip_verification-enabled-repolist.adoc[]`