Red Hat Summit Red Hat SummitSupportConsoleDevelopersStart a trialContact

Configuring Capsules with a load balancer

Red Hat Satellite 6.18

Distribute load among Capsules

Red Hat Satellite Documentation Team

Abstract

This guide describes how to configure Red Hat Satellite to use a load balancer to distribute load among Capsule Servers.

Providing feedback on Red Hat documentation
Copy link

We appreciate your feedback on our documentation. Let us know how we can improve it.

Use the Create Issue form in Red Hat Jira to provide your feedback. The Jira issue is created in the Red Hat Satellite Jira project, where you can track its progress.

Prerequisites

Procedure

  1. Click the following link: Create Issue. If Jira displays a login error, log in and proceed after you are redirected to the form.
  2. Complete the Summary and Description fields. In the Description field, include the documentation URL, chapter or section number, and a detailed description of the issue. Do not modify any other fields in the form.
  3. Click Create.

You can configure your Satellite environment to use a load balancer to distribute host requests and network load across multiple Capsule Servers. This results in an improved performance on Capsule Servers and improved performance and stability for host connections to Satellite. In a load-balanced setup, Capsule functionality supported for load balancing continues to work as expected when one Capsule Server is down for planned or unplanned maintenance.

1.1. Components of a load-balanced setup
Copy link

When you configure your Satellite environment for load balancing, several components interact to provide the required functionality.

A load-balanced setup in a Satellite environment consists of the following components:

  • Satellite Server
  • Two or more Capsule Servers
  • A load balancer
  • Multiple hosts

A host sends a request to the TCP load balancer. The load balancer receives the request and determines which Capsule Server will handle the request to ensure optimal performance and availability.

Figure 1.1. Components of a load-balanced setup

Components of a load-balanced setup
View larger image
Components of a load-balanced setup

A load balancer in Satellite distributes load only for selected services and features.

The following services and features are supported for load balancing:

  • Registering hosts
  • Providing content to hosts
  • Configuring hosts by using Puppet

Other Satellite services, such as provisioning, virt-who, or remote execution, go directly through the individual Capsules on which these services are running.

Configuring Capsules to use a load balancer results in a more complex environment and requires additional maintenance.

The following additional steps are required for load balancing:

  • You must ensure that all Capsules have the same content. If you publish a content view version on Satellite, synchronize it to all Capsule Servers.
  • You must upgrade each Capsule in sequence.

Satellite does not support configuring existing Capsule Servers for load balancing. You must create a new Capsule Server for this purpose.

2.1. Registering to Satellite Server
Copy link

Register the base operating system on which you want to install Capsule Server to Satellite Server. This enables you to download the installation packages from your synchronized repositories.

Prerequisites

  • Prerequisites for Red Hat subscription manifest:

    • On Satellite Server, a manifest must be installed and it must contain the appropriate repositories for the organization you want Capsule to belong to.
    • The manifest must contain repositories for the base operating system on which you want to install Capsule, as well as any clients that you want to connect to Capsule.

    • The repositories must be synchronized.

      For more information on manifests and repositories, see Managing Red Hat Subscriptions in Managing content.

  • Prerequisites for HTTP proxy and network:

    • The Satellite Server base operating system must be able to resolve the host name of the Capsule base operating system and vice versa.
    • Ensure HTTPS connection using client certificate authentication is possible between Capsule Server and Satellite Server. HTTP proxies between Capsule Server and Satellite Server are not supported.
    • You must configure the host and network-based firewalls accordingly. For more information, see Opening required ports in Installing Capsule Server.

You can register hosts with Satellite using the host registration feature in the Satellite web UI, Hammer CLI, or the Satellite API. For more information, see Registering hosts and setting up host integration in Managing hosts.

Procedure

  1. In the Satellite web UI, navigate to Hosts > Register Host.
  2. From the Activation Keys list, select the activation keys to assign to your host.
  3. Click Generate to create the registration command.
  4. Click on the files icon to copy the command to your clipboard.
  5. Connect to your host using SSH and run the registration command.
  6. Check the /etc/yum.repos.d/redhat.repo file and ensure that the appropriate repositories have been enabled.

CLI procedure

  1. Generate the host registration command using the Hammer CLI: 

    $ hammer host-registration generate-command \
--activation-keys "My_Activation_Key"
    Copy to Clipboard Toggle word wrap

    If your hosts do not trust the SSL certificate of Satellite Server, you can disable SSL validation by adding the --insecure flag to the registration command. 

    $ hammer host-registration generate-command \
--activation-keys "My_Activation_Key" \
--insecure true
    Copy to Clipboard Toggle word wrap
  2. Connect to your host using SSH and run the registration command.
  3. Check the /etc/yum.repos.d/redhat.repo file and ensure that the appropriate repositories have been enabled.

API procedure

  1. Generate the host registration command using the Satellite API: 

    # curl -X POST https://satellite.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"] }}'
    Copy to Clipboard Toggle word wrap

    If your hosts do not trust the SSL certificate of Satellite Server, you can disable SSL validation by adding the --insecure flag to the registration command. 

    # curl -X POST https://satellite.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 }}'
    Copy to Clipboard Toggle word wrap

    Use an activation key to simplify specifying the environments. For more information, see Managing Activation Keys in Managing content.

    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 Satellite web UI, navigate to My Account > Personal Access Tokens.

  2. Connect to your host using SSH and run the registration command.
  3. Check the /etc/yum.repos.d/redhat.repo file and ensure that the appropriate repositories have been enabled.

2.2. Configuring repositories
Copy link

Configure repositories to install your Capsule Server.

Procedure

  1. Disable all repositories: 

    # subscription-manager repos --disable "*"
    Copy to Clipboard Toggle word wrap

  2. Enable the following repositories: 

    # subscription-manager repos \
--enable=rhel-9-for-x86_64-baseos-rpms \
--enable=rhel-9-for-x86_64-appstream-rpms \
--enable=satellite-capsule-6.18-for-rhel-9-x86_64-rpms \
--enable=satellite-maintenance-6.18-for-rhel-9-x86_64-rpms
    Copy to Clipboard Toggle word wrap

Verification

  • Verify that the required repositories are enabled: 

    # dnf repolist enabled
    Copy to Clipboard Toggle word wrap

2.3. Installing Capsule Server packages
Copy link

Before installing Capsule Server packages, you must upgrade all packages that are installed on the base operating system.

Procedure

  1. Upgrade all packages: 

    # dnf upgrade
    Copy to Clipboard Toggle word wrap

  2. Install the packages: 

    # dnf install satellite-capsule
    Copy to Clipboard Toggle word wrap

You can configure one or more Capsule Servers that use default SSL certificates for load balancing.

If you use Puppet in your Satellite deployment, the configuration steps are different. See Chapter 5, Configuring Capsule Servers with default SSL certificates for load balancing (with Puppet).

On each Capsule Server that you want to configure for load balancing, install Katello certificates.

Prerequisites

Procedure

  1. On Satellite Server, generate Katello certificates for Capsule Server: 

    # capsule-certs-generate \
--certs-tar "/root/capsule.example.com-certs.tar" \
--foreman-proxy-cname loadbalancer.example.com \
--foreman-proxy-fqdn capsule.example.com
    Copy to Clipboard Toggle word wrap

    Retain a copy of the example satellite-installer command that is output by the capsule-certs-generate command for installing Capsule Server certificate.

  2. Copy the certificate archive file from Satellite Server to Capsule Server. 

    # scp /root/capsule.example.com-certs.tar root@capsule.example.com:/root/capsule.example.com-certs.tar
    Copy to Clipboard Toggle word wrap

  3. Append the following options to the satellite-installer command that you obtain from the output of the capsule-certs-generate command: 

    --certs-cname "loadbalancer.example.com" \
--enable-foreman-proxy-plugin-remote-execution-script
    Copy to Clipboard Toggle word wrap

  4. On Capsule Server, enter the satellite-installer command: 

    # satellite-installer --scenario capsule \
--certs-cname "loadbalancer.example.com" \
--certs-tar-file "capsule.example.com-certs.tar" \
--enable-foreman-proxy-plugin-remote-execution-script \
--foreman-proxy-foreman-base-url "https://satellite.example.com" \
--foreman-proxy-oauth-consumer-key "oauth key" \
--foreman-proxy-oauth-consumer-secret "oauth secret" \
--foreman-proxy-trusted-hosts "satellite.example.com" \
--foreman-proxy-trusted-hosts "capsule.example.com"
    Copy to Clipboard Toggle word wrap

You can configure one or more Capsule Servers that use custom SSL certificates for load balancing. To do this, configure and install certificates on each Capsule Server you want to use for load balancing.

If you use Puppet in your Satellite deployment, the configuration steps are different. See Chapter 6, Configuring Capsule Servers with custom SSL certificates for load balancing (with Puppet).

On each Capsule Server you want to configure for load balancing, create a configuration file for the Certificate Signing Request and include the load balancer and Capsule Server as Subject Alternative Names (SAN).

Procedure

  1. To store all the source certificate files, create a directory that is accessible only to the root user: 

    # mkdir /root/capsule_cert
    Copy to Clipboard Toggle word wrap

  2. Create a private key with which to sign the certificate signing request (CSR).

    Note that the private key must be unencrypted. If you use a password-protected private key, remove the private key password.

    If you already have a private key for this Capsule Server, skip this step. 

    # openssl genrsa -out /root/capsule_cert/capsule_cert_key.pem 4096
    Copy to Clipboard Toggle word wrap

  3. Create the /root/capsule_cert/openssl.cnf configuration file for the CSR and include the following content: 

    [ req ]
req_extensions = v3_req
distinguished_name = req_distinguished_name
x509_extensions = usr_cert
prompt = no

[ req_distinguished_name ]
commonName = capsule.example.com

[ v3_req ]
basicConstraints = CA:FALSE
keyUsage = digitalSignature, keyEncipherment
extendedKeyUsage = serverAuth, clientAuth
subjectAltName = @alt_names

[alt_names]
DNS.1 = loadbalancer.example.com
DNS.2 = capsule.example.com
    Copy to Clipboard Toggle word wrap

    The options used in the configuration file include the following:

    commonName
    The certificate common name. It must match the FQDN of Capsule Server. Ensure to change this when running the command on each Capsule Server that you configure for load balancing. You can also set a wildcard value *.
    [alt_names]

    The alternative names for the load balancer and Capsule Server. Include the FQDN of the load balancer as DNS.1 and the FQDN of Capsule Server as DNS.2.

    For more information about the [ v3_req ] parameters and their purpose, see RFC 5280: Internet X.509 Public Key Infrastructure Certificate and Certificate Revocation List (CRL) Profile.

  4. Optional: If you want to add Distinguished Name (DN) details to the CSR, add the following information to the [ req_distinguished_name ] section: 

    [req_distinguished_name]
CN = capsule.example.com
countryName = My_Country_Name
stateOrProvinceName = My_State_Or_Province_Name
localityName = My_Locality_Name
organizationName = My_Organization_Or_Company_Name
organizationalUnitName = My_Organizational_Unit_Name
    Copy to Clipboard Toggle word wrap

    The options used in the configuration file include the following:

    countryName
    The country represented by a two-letter code
    stateOrProvinceName
    Full name of the state or province
    localityName
    Full name of the locality (example: New York)
    organizationalUnitName
    Division responsible for the certificate (example: IT department)

  5. Generate CSR: 

    # openssl req -new \
-key /root/capsule_cert/capsule_cert_key.pem \
-config /root/capsule_cert/openssl.cnf \
-out /root/capsule_cert/capsule_cert_csr.pem
    Copy to Clipboard Toggle word wrap

    The options used in the configuration file include the following:

    -key
    Path to the private key
    -config
    Path to the configuration file
    -out
    Path to the CSR to generate

  6. Send the certificate signing request to the certificate authority (CA). The same CA must sign certificates for Satellite Server and Capsule Server.

    When you submit the request, specify the lifespan of the certificate. The method for sending the certificate request varies, so consult the CA for the preferred method. In response to the request, you can expect to receive a CA bundle and a signed certificate, in separate files.

  7. Copy the Certificate Authority bundle and Capsule Server certificate file that you receive from the Certificate Authority, and Capsule Server private key to your Satellite Server.

On each Capsule Server you want to configure for load balancing, install Katello certificates.

Prerequisites

Procedure

  1. On Satellite Server, enter the capsule-certs-generate command to generate Capsule certificates: 

    # capsule-certs-generate \
--certs-tar /root/capsule_cert/capsule.tar \
--foreman-proxy-cname loadbalancer.example.com \
--foreman-proxy-fqdn capsule.example.com \
--server-ca-cert /root/capsule_cert/ca_cert_bundle.pem \
--server-cert /root/capsule_cert/capsule.pem \
--server-key /root/capsule_cert/capsule.pem
    Copy to Clipboard Toggle word wrap

    Retain a copy of the example satellite-installer command from the output for installing Capsule Server certificates.

  2. Copy the certificate archive file from Satellite Server to Capsule Server: 

    # scp /root/capsule.example.com-certs.tar root@capsule.example.com:capsule.example.com-certs.tar
    Copy to Clipboard Toggle word wrap

  3. Append the following options to the satellite-installer command that you obtain from the output of the capsule-certs-generate command: 

    --certs-cname "loadbalancer.example.com" \
--enable-foreman-proxy-plugin-remote-execution-script
    Copy to Clipboard Toggle word wrap

  4. On Capsule Server, enter the satellite-installer command: 

    # satellite-installer --scenario capsule \
--certs-cname "loadbalancer.example.com" \
--certs-tar-file "capsule.example.com-certs.tar" \
--enable-foreman-proxy-plugin-remote-execution-script \
--foreman-proxy-foreman-base-url "https://satellite.example.com" \
--foreman-proxy-oauth-consumer-key "oauth key" \
--foreman-proxy-oauth-consumer-secret "oauth secret" \
--foreman-proxy-trusted-hosts "satellite.example.com" \
--foreman-proxy-trusted-hosts "capsule.example.com"
    Copy to Clipboard Toggle word wrap

If you use Puppet in your Satellite setup, you can configure one or more Capsule Servers that use default SSL certificates for load balancing.

To do this, you configure Puppet certificate signing on one of your Capsule Servers. Then, you configure each remaining Puppet Capsule used for load balancing to use the certificates. The first Capsule Server will generate and sign Puppet certificates for the remaining Capsules configured for load balancing.

On the Capsule Server that will generate Puppet certificates for all other load-balancing Capsule Servers, configure Puppet certificate generation and signing.

Prerequisites

Procedure

  1. On Satellite Server, generate Katello certificates for the system where you configure Capsule Server to generate and sign Puppet certificates: 

    # capsule-certs-generate \
--certs-tar "/root/capsule-ca.example.com-certs.tar" \
--foreman-proxy-cname loadbalancer.example.com \
--foreman-proxy-fqdn capsule-ca.example.com
    Copy to Clipboard Toggle word wrap

    Retain a copy of the example satellite-installer command that is output by the capsule-certs-generate command for installing Capsule Server certificate.

  2. Copy the certificate archive file from Satellite Server to Capsule Server: 

    # scp /root/capsule-ca.example.com-certs.tar root@capsule-ca.example.com:capsule-ca.example.com-certs.tar
    Copy to Clipboard Toggle word wrap

  3. Append the following options to the satellite-installer command that you obtain from the output of the capsule-certs-generate command: 

    --certs-cname "loadbalancer.example.com" \
--enable-foreman-proxy-plugin-remote-execution-script \
--foreman-proxy-puppetca "true" \
--puppet-ca-server "capsule-ca.example.com" \
--puppet-dns-alt-names "loadbalancer.example.com" \
--puppet-server-ca "true"
    Copy to Clipboard Toggle word wrap

  4. On Capsule Server, enter the satellite-installer command: 

    # satellite-installer --scenario capsule \
--certs-cname "loadbalancer.example.com" \
--certs-tar-file "capsule-ca.example.com-certs.tar" \
--enable-foreman-proxy-plugin-remote-execution-script \
--enable-puppet \
--foreman-proxy-foreman-base-url "https://satellite.example.com" \
--foreman-proxy-oauth-consumer-key "oauth key" \
--foreman-proxy-oauth-consumer-secret "oauth secret" \
--foreman-proxy-puppetca "true" \
--foreman-proxy-trusted-hosts "satellite.example.com" \
--foreman-proxy-trusted-hosts "capsule-ca.example.com" \
--puppet-ca-server "capsule-ca.example.com" \
--puppet-dns-alt-names "loadbalancer.example.com" \
--puppet-server true \
--puppet-server-ca "true"
    Copy to Clipboard Toggle word wrap

  5. On Capsule Server that is the Puppetserver Certificate Authority, stop the Puppet server: 

    # systemctl stop puppetserver
    Copy to Clipboard Toggle word wrap

  6. Generate Puppet certificates for all other Capsule Servers that you configure for load balancing, except the system where you first configured Puppet certificate signing: 

    # puppetserver ca generate \
--ca-client \
--certname capsule.example.com \
--subject-alt-names loadbalancer.example.com
    Copy to Clipboard Toggle word wrap

    This command creates the following files:

    • /etc/puppetlabs/puppet/ssl/certs/capsule.example.com.pem
    • /etc/puppetlabs/puppet/ssl/private_keys/capsule.example.com.pem
    • /etc/puppetlabs/puppet/ssl/public_keys/capsule.example.com.pem
    • /etc/puppetlabs/puppetserver/ca/signed/capsule.example.com.pem

  7. Start the Puppet server: 

    # systemctl start puppetserver
    Copy to Clipboard Toggle word wrap

On each load-balancing Capsule Server, excluding the Capsule Server configured to sign Puppet certificates, configure the system to use Puppet certificates.

Procedure

  1. On Satellite Server, generate Katello certificates for Capsule Server: 

    # capsule-certs-generate \
--certs-tar "/root/capsule.example.com-certs.tar" \
--foreman-proxy-cname loadbalancer.example.com \
--foreman-proxy-fqdn capsule.example.com
    Copy to Clipboard Toggle word wrap

    Retain a copy of the example satellite-installer command that is output by the capsule-certs-generate command for installing Capsule Server certificate.

  2. Copy the certificate archive file from Satellite Server to Capsule Server: 

    # scp /root/capsule.example.com-certs.tar root@capsule.example.com:/root/capsule.example.com-certs.tar
    Copy to Clipboard Toggle word wrap

  3. On Capsule Server, install the puppetserver package: 

    # satellite-maintain packages install puppetserver
    Copy to Clipboard Toggle word wrap

  4. On Capsule Server, create directories for puppet certificates: 

    # mkdir -p /etc/puppetlabs/puppet/ssl/certs/ \
/etc/puppetlabs/puppet/ssl/private_keys/ \
/etc/puppetlabs/puppet/ssl/public_keys/
    Copy to Clipboard Toggle word wrap

  5. On Capsule Server, copy the Puppet certificates for this Capsule Server from the system where you configure Capsule Server to sign Puppet certificates: 

    # scp root@capsule-ca.example.com:/etc/puppetlabs/puppet/ssl/certs/capsule.example.com.pem /etc/puppetlabs/puppet/ssl/certs/capsule.example.com.pem
# scp root@capsule-ca.example.com:/etc/puppetlabs/puppet/ssl/certs/ca.pem /etc/puppetlabs/puppet/ssl/certs/ca.pem
# scp root@capsule-ca.example.com:/etc/puppetlabs/puppet/ssl/private_keys/capsule.example.com.pem /etc/puppetlabs/puppet/ssl/private_keys/capsule.example.com.pem
# scp root@capsule-ca.example.com:/etc/puppetlabs/puppet/ssl/public_keys/capsule.example.com.pem /etc/puppetlabs/puppet/ssl/public_keys/capsule.example.com.pem
    Copy to Clipboard Toggle word wrap

  6. On Capsule Server, change the /etc/puppetlabs/puppet/ssl/ directory ownership to user puppet and group puppet: 

    # chown -R puppet:puppet /etc/puppetlabs/puppet/ssl/
    Copy to Clipboard Toggle word wrap

  7. On Capsule Server, set the SELinux context for the /etc/puppetlabs/puppet/ssl/ directory: 

    # restorecon -Rv /etc/puppetlabs/puppet/ssl/
    Copy to Clipboard Toggle word wrap

  8. Append the following options to the satellite-installer command that you obtain from the output of the capsule-certs-generate command: 

    --certs-cname "loadbalancer.example.com" \
--enable-foreman-proxy-plugin-remote-execution-script \
--foreman-proxy-puppetca "false" \
--puppet-ca-server "capsule-ca.example.com" \
--puppet-dns-alt-names "loadbalancer.example.com" \
--puppet-server-ca "false"
    Copy to Clipboard Toggle word wrap

  9. On Capsule Server, enter the satellite-installer command: 

    # satellite-installer --scenario capsule \
--certs-cname "loadbalancer.example.com" \
--certs-tar-file "capsule.example.com-certs.tar" \
--enable-foreman-proxy-plugin-remote-execution-script \
--foreman-proxy-foreman-base-url "https://satellite.example.com" \
--foreman-proxy-oauth-consumer-key "oauth key" \
--foreman-proxy-oauth-consumer-secret "oauth secret" \
--foreman-proxy-puppetca "false" \
--foreman-proxy-trusted-hosts "satellite.example.com" \
--foreman-proxy-trusted-hosts "capsule.example.com" \
--puppet-ca-server "capsule-ca.example.com" \
--puppet-dns-alt-names "loadbalancer.example.com" \
--puppet-server-ca "false"
    Copy to Clipboard Toggle word wrap

If you use Puppet, Puppet certificate signing is assigned to the first Capsule that you configure. If the first Capsule is down, hosts cannot obtain Puppet content.

Puppet Certificate Authority (CA) management does not support certificate signing in a load-balanced setup. Puppet CA stores certificate information, such as the serial number counter and CRL, on the file system. Multiple writer processes that attempt to use the same data can corrupt it.

To manage this Puppet limitation, complete the following steps:

  1. Configure Puppet certificate signing on one Capsule Server, typically the first system where you configure Capsule Server for load balancing.
  2. Configure the clients to send CA requests to port 8141 on a load balancer.
  3. Configure a load balancer to redirect CA requests from port 8141 to port 8140 on the system where you configure Capsule Server to sign Puppet certificates.

To troubleshoot issues, reproduce the issue on each Capsule, bypassing the load balancer. This solution does not use Pacemaker or other similar HA tools to maintain one state across all Capsules.

You can configure one or more Capsule Servers that use custom SSL certificates for load balancing.

On each Capsule Server you want to configure for load balancing, create a configuration file for the Certificate Signing Request and include the load balancer and Capsule Server as Subject Alternative Names (SAN).

Procedure

  1. To store all the source certificate files, create a directory that is accessible only to the root user: 

    # mkdir /root/capsule_cert
    Copy to Clipboard Toggle word wrap

  2. Create a private key with which to sign the certificate signing request (CSR).

    Note that the private key must be unencrypted. If you use a password-protected private key, remove the private key password.

    If you already have a private key for this Capsule Server, skip this step. 

    # openssl genrsa -out /root/capsule_cert/capsule_cert_key.pem 4096
    Copy to Clipboard Toggle word wrap

  3. Create the /root/capsule_cert/openssl.cnf configuration file for the CSR and include the following content: 

    [ req ]
req_extensions = v3_req
distinguished_name = req_distinguished_name
x509_extensions = usr_cert
prompt = no

[ req_distinguished_name ]
commonName = capsule.example.com

[ v3_req ]
basicConstraints = CA:FALSE
keyUsage = digitalSignature, keyEncipherment
extendedKeyUsage = serverAuth, clientAuth
subjectAltName = @alt_names

[alt_names]
DNS.1 = loadbalancer.example.com
DNS.2 = capsule.example.com
    Copy to Clipboard Toggle word wrap

    The options used in the configuration file include the following:

    commonName
    The certificate common name. It must match the FQDN of Capsule Server. Ensure to change this when running the command on each Capsule Server that you configure for load balancing. You can also set a wildcard value *.
    [alt_names]

    The alternative names for the load balancer and Capsule Server. Include the FQDN of the load balancer as DNS.1 and the FQDN of Capsule Server as DNS.2.

    For more information about the [ v3_req ] parameters and their purpose, see RFC 5280: Internet X.509 Public Key Infrastructure Certificate and Certificate Revocation List (CRL) Profile.

  4. Optional: If you want to add Distinguished Name (DN) details to the CSR, add the following information to the [ req_distinguished_name ] section: 

    [req_distinguished_name]
CN = capsule.example.com
countryName = My_Country_Name
stateOrProvinceName = My_State_Or_Province_Name
localityName = My_Locality_Name
organizationName = My_Organization_Or_Company_Name
organizationalUnitName = My_Organizational_Unit_Name
    Copy to Clipboard Toggle word wrap

    The options used in the configuration file include the following:

    countryName
    The country represented by a two-letter code
    stateOrProvinceName
    Full name of the state or province
    localityName
    Full name of the locality (example: New York)
    organizationalUnitName
    Division responsible for the certificate (example: IT department)

  5. Generate CSR: 

    # openssl req -new \
-key /root/capsule_cert/capsule_cert_key.pem \
-config /root/capsule_cert/openssl.cnf \
-out /root/capsule_cert/capsule_cert_csr.pem
    Copy to Clipboard Toggle word wrap

    The options used in the configuration file include the following:

    -key
    Path to the private key
    -config
    Path to the configuration file
    -out
    Path to the CSR to generate

  6. Send the certificate signing request to the certificate authority (CA). The same CA must sign certificates for Satellite Server and Capsule Server.

    When you submit the request, specify the lifespan of the certificate. The method for sending the certificate request varies, so consult the CA for the preferred method. In response to the request, you can expect to receive a CA bundle and a signed certificate, in separate files.

  7. Copy the Certificate Authority bundle and Capsule Server certificate file that you receive from the Certificate Authority, and Capsule Server private key to your Satellite Server.

On the Capsule Server that will generate Puppet certificates for all other load-balancing Capsule Servers, configure Puppet certificate generation and signing.

Prerequisites

Procedure

  1. On Satellite Server, enter the capsule-certs-generate command to generate Capsule certificates: 

    # capsule-certs-generate \
--certs-tar /root/capsule_cert/capsule-ca.tar \
--foreman-proxy-cname loadbalancer.example.com \
--foreman-proxy-fqdn capsule-ca.example.com \
--server-ca-cert /root/capsule_cert/ca_cert_bundle.pem \
--server-cert /root/capsule_cert/capsule-ca.pem \
--server-key /root/capsule_cert/capsule-ca.pem
    Copy to Clipboard Toggle word wrap

    Retain a copy of the example satellite-installer command from the output for installing Capsule Server certificates.

  2. Copy the certificate archive file from Satellite Server to Capsule Server.

  3. Append the following options to the satellite-installer command that you obtain from the output of the capsule-certs-generate command: 

    --enable-foreman-proxy-plugin-remote-execution-script \
--foreman-proxy-puppetca "true" \
--puppet-ca-server "capsule-ca.example.com" \
--puppet-dns-alt-names "loadbalancer.example.com" \
--puppet-server-ca "true"
    Copy to Clipboard Toggle word wrap

  4. On Capsule Server, enter the satellite-installer command: 

    # satellite-installer --scenario capsule \
--certs-cname "loadbalancer.example.com" \
--certs-tar-file "certs.tgz" \
--enable-foreman-proxy-plugin-remote-execution-script \
--enable-puppet \
--foreman-proxy-foreman-base-url "https://satellite.example.com" \
--foreman-proxy-oauth-consumer-key "oauth key" \
--foreman-proxy-oauth-consumer-secret "oauth secret" \
--foreman-proxy-puppetca "true" \
--foreman-proxy-trusted-hosts "satellite.example.com" \
--foreman-proxy-trusted-hosts "capsule-ca.example.com" \
--puppet-ca-server "capsule-ca.example.com" \
--puppet-dns-alt-names "loadbalancer.example.com" \
--puppet-server true \
--puppet-server-ca "true"
    Copy to Clipboard Toggle word wrap

  5. On Capsule Server that is the Puppetserver Certificate Authority, stop the Puppet server: 

    # systemctl stop puppetserver
    Copy to Clipboard Toggle word wrap

  6. Generate Puppet certificates for all other Capsule Servers that you configure for load balancing, except the system where you first configured Puppet certificate signing: 

    # puppetserver ca generate \
--ca-client \
--certname capsule.example.com \
--subject-alt-names loadbalancer.example.com
    Copy to Clipboard Toggle word wrap

    This command creates the following files:

    • /etc/puppetlabs/puppet/ssl/certs/capsule.example.com.pem
    • /etc/puppetlabs/puppet/ssl/private_keys/capsule.example.com.pem
    • /etc/puppetlabs/puppet/ssl/public_keys/capsule.example.com.pem
    • /etc/puppetlabs/puppetserver/ca/signed/capsule.example.com.pem

  7. Start the Puppet server: 

    # systemctl start puppetserver
    Copy to Clipboard Toggle word wrap

On each load-balancing Capsule Server, excluding the Capsule Server configured to sign Puppet certificates, configure the system to use Puppet certificates.

Procedure

  1. On Satellite Server, enter the capsule-certs-generate command to generate Capsule certificates: 

    # capsule-certs-generate \
--certs-tar /root/capsule_cert/capsule.tar \
--foreman-proxy-cname loadbalancer.example.com \
--foreman-proxy-fqdn capsule.example.com \
--server-ca-cert /root/capsule_cert/ca_cert_bundle.pem \
--server-cert /root/capsule_cert/capsule.pem \
--server-key /root/capsule_cert/capsule.pem
    Copy to Clipboard Toggle word wrap

    Retain a copy of the example satellite-installer command from the output for installing Capsule Server certificates.

  2. Copy the certificate archive file from Satellite Server to Capsule Server. 

    # scp /root/capsule.example.com-certs.tar root@capsule.example.com:capsule.example.com-certs.tar
    Copy to Clipboard Toggle word wrap

  3. On Capsule Server, install the puppetserver package: 

    # satellite-maintain packages install puppetserver
    Copy to Clipboard Toggle word wrap

  4. On Capsule Server, create directories for puppet certificates: 

    # mkdir -p /etc/puppetlabs/puppet/ssl/certs/ \
/etc/puppetlabs/puppet/ssl/private_keys/ \
/etc/puppetlabs/puppet/ssl/public_keys/
    Copy to Clipboard Toggle word wrap

  5. On Capsule Server, copy the Puppet certificates for this Capsule Server from the system where you configure Capsule Server to sign Puppet certificates: 

    # scp root@capsule-ca.example.com:/etc/puppetlabs/puppet/ssl/certs/capsule.example.com.pem /etc/puppetlabs/puppet/ssl/certs/capsule.example.com.pem
# scp root@capsule-ca.example.com:/etc/puppetlabs/puppet/ssl/certs/ca.pem /etc/puppetlabs/puppet/ssl/certs/ca.pem
# scp root@capsule-ca.example.com:/etc/puppetlabs/puppet/ssl/private_keys/capsule.example.com.pem /etc/puppetlabs/puppet/ssl/private_keys/capsule.example.com.pem
# scp root@capsule-ca.example.com:/etc/puppetlabs/puppet/ssl/public_keys/capsule.example.com.pem /etc/puppetlabs/puppet/ssl/public_keys/capsule.example.com.pem
    Copy to Clipboard Toggle word wrap

  6. On Capsule Server, change the /etc/puppetlabs/puppet/ssl/ directory ownership to user puppet and group puppet: 

    # chown -R puppet:puppet /etc/puppetlabs/puppet/ssl/
    Copy to Clipboard Toggle word wrap

  7. On Capsule Server, set the SELinux context for the /etc/puppetlabs/puppet/ssl/ directory: 

    # restorecon -Rv /etc/puppetlabs/puppet/ssl/
    Copy to Clipboard Toggle word wrap

  8. Append the following options to the satellite-installer command that you obtain from the output of the capsule-certs-generate command: 

    --certs-cname "loadbalancer.example.com" \
--enable-foreman-proxy-plugin-remote-execution-script \
--foreman-proxy-puppetca "false" \
--puppet-ca-server "capsule-ca.example.com" \
--puppet-dns-alt-names "loadbalancer.example.com" \
--puppet-server-ca "false"
    Copy to Clipboard Toggle word wrap

  9. On Capsule Server, enter the satellite-installer command: 

    # satellite-installer --scenario capsule \
--certs-cname "loadbalancer.example.com" \
--certs-tar-file "capsule.example.com-certs.tar" \
--enable-foreman-proxy-plugin-remote-execution-script \
--foreman-proxy-foreman-base-url "https://satellite.example.com" \
--foreman-proxy-oauth-consumer-key "oauth key" \
--foreman-proxy-oauth-consumer-secret "oauth secret" \
--foreman-proxy-puppetca "false" \
--foreman-proxy-trusted-hosts "satellite.example.com" \
--foreman-proxy-trusted-hosts "capsule.example.com" \
--puppet-ca-server "capsule-ca.example.com" \
--puppet-dns-alt-names "loadbalancer.example.com" \
--puppet-server-ca "false"
    Copy to Clipboard Toggle word wrap

If you use Puppet, Puppet certificate signing is assigned to the first Capsule that you configure. If the first Capsule is down, hosts cannot obtain Puppet content.

Puppet Certificate Authority (CA) management does not support certificate signing in a load-balanced setup. Puppet CA stores certificate information, such as the serial number counter and CRL, on the file system. Multiple writer processes that attempt to use the same data can corrupt it.

To manage this Puppet limitation, complete the following steps:

  1. Configure Puppet certificate signing on one Capsule Server, typically the first system where you configure Capsule Server for load balancing.
  2. Configure the clients to send CA requests to port 8141 on a load balancer.
  3. Configure a load balancer to redirect CA requests from port 8141 to port 8140 on the system where you configure Capsule Server to sign Puppet certificates.

To troubleshoot issues, reproduce the issue on each Capsule, bypassing the load balancer. This solution does not use Pacemaker or other similar HA tools to maintain one state across all Capsules.

Red Hat provides general guidance for configuring an HAProxy load balancer using Red Hat Enterprise Linux 9. However, you can install any suitable load balancing software solution that supports TCP forwarding.

7.1. Installing the load balancer
Copy link

The following example provides general guidance for configuring an HAProxy load balancer using Red Hat Enterprise Linux 9. However, you can install any suitable load balancing software solution that supports TCP forwarding.

Procedure

  1. Install HAProxy: 

    # dnf install haproxy
    Copy to Clipboard Toggle word wrap

  2. Install the following package that includes the semanage tool: 

    # dnf install policycoreutils-python-utils
    Copy to Clipboard Toggle word wrap

  3. Configure SELinux to allow HAProxy to bind any port: 

    # semanage boolean --modify --on haproxy_connect_any
    Copy to Clipboard Toggle word wrap
  4. Configure the load balancer to balance the network load for the ports as described in Section 7.2, “Ports configuration for the load balancer”.
  5. 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 Capsule Servers depends on client-side SSL certificates.

  6. Start and enable the HAProxy service: 

    # systemctl enable --now haproxy
    Copy to Clipboard Toggle word wrap

7.2. Ports configuration for the load balancer
Copy link

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.

Expand
Table 7.1. Ports configuration for the load balancer
ServicePortModeBalance ModeDestination

HTTP

80

TCP

roundrobin

port 80 on all Capsule Servers

HTTPS and RHSM

443

TCP

source

port 443 on all Capsule Servers

Anaconda for template retrieval

8000

TCP

roundrobin

port 8000 on all Capsule Servers

Puppet (Optional)

8140

TCP

roundrobin

port 8140 on all Capsule Servers

PuppetCA (Optional)

8141

TCP

roundrobin

port 8140 only on the system where you configure Capsule Server to sign Puppet certificates

Capsule HTTPS for Host Registration and optionally OpenSCAP

9090

TCP

roundrobin

port 9090 on all Capsule Servers

Additional resources

Use this procedure to verify the load balancing configuration for each Capsule Server.

Procedure

  1. Shut down the base operating system for your Capsule Server.
  2. Verify that content or subscription management features are available on clients registered to this Capsule. For example, enter the subscription-manager refresh command on a client.
  3. Restart the base operating system for your Capsule Server.

To balance the load of network traffic from clients, you must register the clients to the load balancer.

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.

You can configure Satellite to register clients through a load balancer when using the host registration feature.

You will be able to register hosts to the load balancer instead of Capsule. The load balancer will decide through which Capsule to register the host at the time of request. Upon registration, the subscription manager on the host will be configured to manage content through the load balancer.

Prerequisites

Procedure

  1. On all Capsule Servers, set the registration and template URLs using satellite-installer: 

    # satellite-installer \
--foreman-proxy-registration-url "https://loadbalancer.example.com:9090" \
--foreman-proxy-template-url "http://loadbalancer.example.com:8000"
    Copy to Clipboard Toggle word wrap
  2. In the Satellite web UI, navigate to Infrastructure > Capsules.
  3. For each Capsule, click the dropdown menu in the Actions column and select Refresh.

After setting the load balancer for host registration, you can register a host to the load balancer.

Procedure

  1. In the Satellite web UI, navigate to Hosts > Register Host.
  2. From the Capsule dropdown list, select your Capsule Server configured for load balancing.
  3. Select Force to register a host that has been previously registered to a Capsule Server.
  4. From the Activation Keys list, select the activation keys to assign to your host.
  5. Click Generate to create the registration command.
  6. Click on the files icon to copy the command to your clipboard.
  7. Connect to your host using SSH and run the registration command.
  8. Check the /etc/yum.repos.d/redhat.repo file and ensure that the appropriate repositories have been enabled.

After setting the load balancer for host registration, you can register a host to the load balancer.

Procedure

  1. Generate the host registration command using the Hammer CLI: 

    $ hammer host-registration generate-command \
--activation-keys "My_Activation_Key"
    Copy to Clipboard Toggle word wrap

    If your hosts do not trust the SSL certificate of Satellite Server, you can disable SSL validation by adding the --insecure flag to the registration command. 

    $ hammer host-registration generate-command \
--activation-keys "My_Activation_Key" \
--insecure true
    Copy to Clipboard Toggle word wrap

    Include the --smart-proxy-id My_Capsule_ID option. You can use the ID of any Capsule Server that you configured for host registration load balancing. Satellite 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 Capsule Server.

  2. Connect to your host using SSH and run the registration command.
  3. Check the /etc/yum.repos.d/redhat.repo file and ensure that the appropriate repositories have been enabled.

After setting the load balancer for host registration, you can register a host to a load-balanced Capsule.

Procedure

  1. Generate the host registration command using the Satellite API: 

    # curl -X POST https://satellite.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"] }}'
    Copy to Clipboard Toggle word wrap

    If your hosts do not trust the SSL certificate of Satellite Server, you can disable SSL validation by adding the --insecure flag to the registration command. 

    # curl -X POST https://satellite.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 }}'
    Copy to Clipboard Toggle word wrap

    Use an activation key to simplify specifying the environments. For more information, see Managing Activation Keys in Managing content.

    Include { "smart_proxy_id": My_Capsule_ID }. You can use the ID of any Capsule Server that you configured for host registration load balancing. Satellite will apply the load balancer to the registration command automatically.

    Include { "force": true } to register a host that has been previously registered to a Capsule Server.

    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 Satellite web UI, navigate to My Account > Personal Access Tokens.

  2. Connect to your host using SSH and run the registration command.
  3. Check the /etc/yum.repos.d/redhat.repo file and ensure that the appropriate repositories have been enabled.

To register clients, enter the following command on the client. You must complete the registration procedure for each client.

Prerequisites

Procedure

  • On Red Hat Enterprise Linux 8, enter the following command: 

    # /usr/libexec/platform-python bootstrap.py \
--activationkey="My_Activation_Key" \
--enablerepos=satellite-client-6-for-rhel-8-<arch>-rpms \
--force \
--hostgroup="My_Host_Group" \
--location="My_Location" \
--login=admin \
--organization="My_Organization" \
--puppet-ca-port 8141 \
--server loadbalancer.example.com
    Copy to Clipboard Toggle word wrap

    The options used in the command include the following:

    enablerepos
    Replace <arch> with the client architecture, for example x86.
    --force
    Include the --force option to register the client that has been previously registered to a standalone Capsule.
    --puppet-ca-port
    Include the --puppet-ca-port 8141 option if you use Puppet.

  • On Red Hat Enterprise Linux 7, enter the following command: 

    # python bootstrap.py --login=admin \
--activationkey="My_Activation_Key" \
--enablerepos=rhel-7-server-satellite-client-6-rpms \
--force \
--hostgroup="My_Host_Group" \
--location="My_Location" \
--organization="My_Organization" \
--puppet-ca-port 8141 \
--server loadbalancer.example.com
    Copy to Clipboard Toggle word wrap

    The options used in the command include the following:

    --force
    Include the --force option to register the client that has been previously registered to a standalone Capsule.
    --puppet-ca-port

    Include the --puppet-ca-port 8141 option if you use Puppet.

    The script prompts for the password corresponding to the Satellite user name you entered with the --login option.

If you use OpenSCAP to manage security compliance on your clients, you must configure the SCAP client to send ARF reports to the load balancer instead of Capsule. The configuration procedure depends on the method you have selected to deploy compliance policies.

Using this procedure, you can promote Security Content Automation Protocol (SCAP) content through the load balancer in the scope of the Ansible deployment method.

Prerequisites

Procedure

  1. In the Satellite web UI, navigate to Configure > Ansible > Variables.
  2. Search for the foreman_scap_client_port variable and click its name.
  3. In the Default Behavior area, ensure that the Override checkbox is selected.
  4. In the Parameter Type list, ensure that integer is selected.
  5. In the Default Value field, enter 9090.
  6. In the Specify Matchers area, remove all matchers that override the default value.
  7. Click Submit.
  8. Search for the foreman_scap_client_server variable and click its name.
  9. In the Default Behavior area, ensure that the Override checkbox is selected.
  10. In the Parameter Type list, ensure that string is selected.
  11. In the Default Value field, enter the FQDN of your load balancer, such as loadbalancer.example.com.
  12. In the Specify Matchers area, remove all matchers that override the default value.
  13. Click Submit.

  14. Continue with deploying a compliance policy using Ansible. For more information, see:

Verification

  • On the client, verify that the /etc/foreman_scap_client/config.yaml file contains the following lines: 

    # Foreman proxy to which reports should be uploaded
:server: 'loadbalancer.example.com'
:port: 9090
    Copy to Clipboard Toggle word wrap

Using this procedure, you can promote Security Content Automation Protocol (SCAP) content through the load balancer in the scope of the Puppet deployment method.

Prerequisites

Procedure

  1. In the Satellite web UI, navigate to Configure > Puppet ENC > Classes.
  2. Click foreman_scap_client.
  3. Click the Smart Class Parameter tab.
  4. In the pane to the left of the Smart Class Parameter window, click port.
  5. In the Default Behavior area, select the Override checkbox.
  6. From the Key Type list, select integer.
  7. In the Default Value field, enter 9090.
  8. In the pane to the left of the Smart Class Parameter window, click server.
  9. In the Default Behavior area, select the Override checkbox.
  10. From the Key Type list, select string.
  11. In the Default Value field, enter the FQDN of your load balancer, such as loadbalancer.example.com.
  12. In the lower left of the Smart Class Parameter window, click Submit.

  13. Continue with deploying a compliance policy using Puppet. For more information, see:

Verification

  • On the client, verify that the /etc/foreman_scap_client/config.yaml file contains the following lines: 

    # Foreman proxy to which reports should be uploaded
:server: 'loadbalancer.example.com'
:port: 9090
    Copy to Clipboard Toggle word wrap

Legal Notice
Copy link

Copyright © 2025 Red Hat, Inc.
The text of and illustrations in this document are licensed by Red Hat under a Creative Commons Attribution–Share Alike 3.0 Unported license ("CC-BY-SA"). An explanation of CC-BY-SA is available at http://creativecommons.org/licenses/by-sa/3.0/. In accordance with CC-BY-SA, if you distribute this document or an adaptation of it, you must provide the URL for the original version.
Red Hat, as the licensor of this document, waives the right to enforce, and agrees not to assert, Section 4d of CC-BY-SA to the fullest extent permitted by applicable law.
Red Hat, Red Hat Enterprise Linux, the Shadowman logo, the Red Hat logo, JBoss, OpenShift, Fedora, the Infinity logo, and RHCE are trademarks of Red Hat, Inc., registered in the United States and other countries.
Linux® is the registered trademark of Linus Torvalds in the United States and other countries.
Java® is a registered trademark of Oracle and/or its affiliates.
XFS® is a trademark of Silicon Graphics International Corp. or its subsidiaries in the United States and/or other countries.
MySQL® is a registered trademark of MySQL AB in the United States, the European Union and other countries.
Node.js® is an official trademark of Joyent. Red Hat is not formally related to or endorsed by the official Joyent Node.js open source or commercial project.
The OpenStack® Word Mark and OpenStack logo are either registered trademarks/service marks or trademarks/service marks of the OpenStack Foundation, in the United States and other countries and are used with the OpenStack Foundation's permission. We are not affiliated with, endorsed or sponsored by the OpenStack Foundation, or the OpenStack community.
All other trademarks are the property of their respective owners.
Back to top
Red Hat logoGithubredditYoutubeTwitter

Learn

Try, buy, & sell

Communities

About Red Hat Documentation

We help Red Hat users innovate and achieve their goals with our products and services with content they can trust. Explore our recent updates.

Making open source more inclusive

Red Hat is committed to replacing problematic language in our code, documentation, and web properties. For more details, see the Red Hat Blog.

About Red Hat

We deliver hardened solutions that make it easier for enterprises to work across platforms and environments, from the core datacenter to the network edge.

Theme

© 2025 Red Hat