Configuring Capsules with a load balancer
Distribute load among Capsules
Abstract
Providing feedback on Red Hat documentation
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
- Ensure you have registered a Red Hat account.
Procedure
- Click the following link: Create Issue. If Jira displays a login error, log in and proceed after you are redirected to the form.
- 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.
- Click Create.
Chapter 1. Overview of load balancing in Satellite
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
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
1.2. Services and features supported in a load-balanced setup
A load balancer in Satellite distributes load only for the following services and features:
- 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.
1.3. Additional maintenance required for load balancing
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.
Chapter 2. Preparing Capsule Servers for load balancing
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
Use this procedure to register the base operating system on which you want to install Capsule Server to Satellite Server.
Red Hat subscription manifest prerequisites
- 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.
Proxy and network prerequisites
- 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 Port and firewall requirements 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.
Prerequisites
- You have set the load balancer for host registration. For more information, see Chapter 8, Setting the load balancer for host registration.
Procedure
- In the Satellite web UI, navigate to Hosts > Register Host.
- From the Capsule dropdown list, select the load balancer.
- Select Force to register a host that has been previously registered to a Capsule Server.
- 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.
-
Check the
/etc/yum.repos.d/redhat.repo
file and ensure that the appropriate repositories have been enabled.
CLI procedure
Generate the host registration command using the Hammer CLI:
# hammer host-registration generate-command \ --activation-keys "My_Activation_Key"
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
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.- Connect to your host using SSH and run the registration command.
-
Check the
/etc/yum.repos.d/redhat.repo
file and ensure that the appropriate repositories have been enabled.
API procedure
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"] }}'
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 }}'
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.- Connect to your host using SSH and run the registration command.
-
Check the
/etc/yum.repos.d/redhat.repo
file and ensure that the appropriate repositories have been enabled.
2.2. Configuring repositories
Prerequisite
- If you are installing Capsule Server as a virtual machine hosted on Red Hat Virtualization, you must also enable the Red Hat Common repository and then install Red Hat Virtualization guest agents and drivers. For more information, see Installing the Guest Agents and Drivers on Red Hat Enterprise Linux in the Virtual Machine Management Guide.
Procedure
Select the operating system and version you are installing on:
2.2.1. Red Hat Enterprise Linux 9
Disable all repositories:
# subscription-manager repos --disable "*"
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.16-for-rhel-9-x86_64-rpms \ --enable=satellite-maintenance-6.16-for-rhel-9-x86_64-rpms
Verification
Verify that the required repositories are enabled:
# dnf repolist enabled
2.2.2. Red Hat Enterprise Linux 8
Disable all repositories:
# subscription-manager repos --disable "*"
Enable the following repositories:
# subscription-manager repos \ --enable=rhel-8-for-x86_64-baseos-rpms \ --enable=rhel-8-for-x86_64-appstream-rpms \ --enable=satellite-capsule-6.16-for-rhel-8-x86_64-rpms \ --enable=satellite-maintenance-6.16-for-rhel-8-x86_64-rpms
Enable the module:
# dnf module enable satellite-capsule:el8
Verification
Verify that the required repositories are enabled:
# dnf repolist enabled
Additional Resources
-
If there is any warning about conflicts with Ruby or PostgreSQL while enabling
satellite-capsule:el8
module, see Troubleshooting DNF modules. - For more information about modules and lifecycle streams on Red Hat Enterprise Linux 8, see Red Hat Enterprise Linux 8 Application Streams Lifecycle.
2.3. Installing Capsule Server packages
Before installing Capsule Server packages, you must update all packages that are installed on the base operating system.
Procedure
To install Capsule Server, complete the following steps:
Update all packages:
# dnf upgrade
Install the Satellite Server packages:
# dnf install satellite-capsule
2.4. Additional resources
- For more information about installing Capsule Servers, see Installing Capsule Server.
Chapter 3. Configuring Capsule Servers with default SSL certificates for load balancing
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).
3.1. Prerequisites
- Prepare a new Capsule Server to use for load balancing. See Chapter 2, Preparing Capsule Servers for load balancing.
- Review Section 1.2, “Services and features supported in a load-balanced setup”.
3.2. Configuring Capsule Server with default SSL certificates for load balancing without Puppet
On each Capsule Server that you want to configure for load balancing, install Katello certificates.
Procedure
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
Retain a copy of the example
satellite-installer
command that is output by thecapsule-certs-generate
command for installing Capsule Server certificate.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
Append the following options to the
satellite-installer
command that you obtain from the output of thecapsule-certs-generate
command:--certs-cname "loadbalancer.example.com" \ --enable-foreman-proxy-plugin-remote-execution-script
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-register-in-foreman "true" \ --foreman-proxy-trusted-hosts "satellite.example.com" \ --foreman-proxy-trusted-hosts "capsule.example.com"
Chapter 4. Configuring Capsule Servers with custom SSL certificates for load balancing
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).
4.1. Prerequisites
- Prepare a new Capsule Server to use for load balancing. See Chapter 2, Preparing Capsule Servers for load balancing.
- Review Section 1.2, “Services and features supported in a load-balanced setup”.
4.2. Creating a custom SSL certificate for Capsule Server
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
To store all the source certificate files, create a directory that is accessible only to the
root
user:# mkdir /root/capsule_cert
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
4096Create 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 1 [ v3_req ] basicConstraints = CA:FALSE keyUsage = digitalSignature, nonRepudiation, keyEncipherment, dataEncipherment extendedKeyUsage = serverAuth, clientAuth, codeSigning, emailProtection subjectAltName = @alt_names [alt_names] 2 DNS.1 = loadbalancer.example.com DNS.2 = capsule.example.com
- 1
- The certificate’s common name 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
*
. If you set a wildcard value, you must add the-t capsule
option when you use thekatello-certs-check
command. - 2
- Under
[alt_names]
, include the FQDN of the load balancer asDNS.1
and the FQDN of Capsule Server asDNS.2
.
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 1 stateOrProvinceName = My_State_Or_Province_Name 2 localityName = My_Locality_Name 3 organizationName = My_Organization_Or_Company_Name organizationalUnitName = My_Organizational_Unit_Name 4
Generate CSR:
# openssl req -new \ -key /root/capsule_cert/capsule_cert_key.pem \ 1 -config /root/capsule_cert/openssl.cnf \ 2 -out /root/capsule_cert/capsule_cert_csr.pem 3
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.
- 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 Satellite Server, validate Capsule Server certificate input files:
# katello-certs-check \ -c /root/capsule_cert/capsule_cert.pem \ 1 -k /root/capsule_cert/capsule_cert_key.pem \ 2 -b /root/capsule_cert/ca_cert_bundle.pem 3
If you set the
commonName=
to a wildcard value*
, you must add the-t capsule
option to thekatello-certs-check
command.Retain a copy of the example
capsule-certs-generate
command that is output by thekatello-certs-check
command for creating the Certificate Archive File for this Capsule Server.
4.3. Configuring Capsule Server with custom SSL certificates for load balancing without Puppet
On each Capsule Server you want to configure for load balancing, install Katello certificates.
Procedure
Append the following option to the
capsule-certs-generate
command that you obtain from the output of thekatello-certs-check
command:--foreman-proxy-cname loadbalancer.example.com
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
Retain a copy of the example
satellite-installer
command from the output for installing Capsule Server certificates.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
Append the following options to the
satellite-installer
command that you obtain from the output of thecapsule-certs-generate
command:--certs-cname "loadbalancer.example.com" \ --enable-foreman-proxy-plugin-remote-execution-script
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-register-in-foreman "true" \ --foreman-proxy-trusted-hosts "satellite.example.com" \ --foreman-proxy-trusted-hosts "capsule.example.com"
Chapter 5. Configuring Capsule Servers with default SSL certificates for load balancing (with Puppet)
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.
5.1. Prerequisites
- Prepare a new Capsule Server to use for load balancing. See Chapter 2, Preparing Capsule Servers for load balancing.
- Review Section 1.2, “Services and features supported in a load-balanced setup”.
5.2. Configuring Capsule Server with default SSL certificates to generate and sign Puppet certificates
On the Capsule Server that will generate Puppet certificates for all other load-balancing Capsule Servers, configure Puppet certificate generation and signing.
Procedure
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
Retain a copy of the example
satellite-installer
command that is output by thecapsule-certs-generate
command for installing Capsule Server certificate.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
Append the following options to the
satellite-installer
command that you obtain from the output of thecapsule-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"
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-register-in-foreman "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"
On Capsule Server that is the Puppetserver Certificate Authority, stop the Puppet server:
# systemctl stop puppetserver
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
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
-
Start the Puppet server:
# systemctl start puppetserver
5.3. Configuring remaining Capsule Servers with default SSL certificates for load balancing
On each load-balancing Capsule Server, excluding the Capsule Server configured to sign Puppet certificates, configure the system to use Puppet certificates.
Procedure
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
Retain a copy of the example
satellite-installer
command that is output by thecapsule-certs-generate
command for installing Capsule Server certificate.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
On Capsule Server, install the
puppetserver
package:# satellite-maintain packages install puppetserver
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/
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
On Capsule Server, change the
/etc/puppetlabs/puppet/ssl/
directory ownership to userpuppet
and grouppuppet
:# chown -R puppet:puppet /etc/puppetlabs/puppet/ssl/
On Capsule Server, set the SELinux context for the
/etc/puppetlabs/puppet/ssl/
directory:# restorecon -Rv /etc/puppetlabs/puppet/ssl/
Append the following options to the
satellite-installer
command that you obtain from the output of thecapsule-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"
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-register-in-foreman "true" \ --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"
5.4. Managing Puppet limitations with load balancing in Satellite
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:
- Configure Puppet certificate signing on one Capsule Server, typically the first system where you configure Capsule Server for load balancing.
- Configure the clients to send CA requests to port 8141 on a load balancer.
- 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.
Chapter 6. Configuring Capsule Servers with custom SSL certificates for load balancing (with Puppet)
You can configure one or more Capsule Servers that use custom SSL certificates for load balancing.
6.1. Prerequisites
- Prepare a new Capsule Server to use for load balancing. See Chapter 2, Preparing Capsule Servers for load balancing.
- Review Section 1.2, “Services and features supported in a load-balanced setup”.
6.2. Creating a custom SSL certificate for Capsule Server
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
To store all the source certificate files, create a directory that is accessible only to the
root
user:# mkdir /root/capsule_cert
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
4096Create 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 1 [ v3_req ] basicConstraints = CA:FALSE keyUsage = digitalSignature, nonRepudiation, keyEncipherment, dataEncipherment extendedKeyUsage = serverAuth, clientAuth, codeSigning, emailProtection subjectAltName = @alt_names [alt_names] 2 DNS.1 = loadbalancer.example.com DNS.2 = capsule.example.com
- 1
- The certificate’s common name 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
*
. If you set a wildcard value, you must add the-t capsule
option when you use thekatello-certs-check
command. - 2
- Under
[alt_names]
, include the FQDN of the load balancer asDNS.1
and the FQDN of Capsule Server asDNS.2
.
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 1 stateOrProvinceName = My_State_Or_Province_Name 2 localityName = My_Locality_Name 3 organizationName = My_Organization_Or_Company_Name organizationalUnitName = My_Organizational_Unit_Name 4
Generate CSR:
# openssl req -new \ -key /root/capsule_cert/capsule_cert_key.pem \ 1 -config /root/capsule_cert/openssl.cnf \ 2 -out /root/capsule_cert/capsule_cert_csr.pem 3
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.
- 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 Satellite Server, validate Capsule Server certificate input files:
# katello-certs-check \ -c /root/capsule_cert/capsule_cert.pem \ 1 -k /root/capsule_cert/capsule_cert_key.pem \ 2 -b /root/capsule_cert/ca_cert_bundle.pem 3
If you set the
commonName=
to a wildcard value*
, you must add the-t capsule
option to thekatello-certs-check
command.Retain a copy of the example
capsule-certs-generate
command that is output by thekatello-certs-check
command for creating the Certificate Archive File for this Capsule Server.
6.3. Configuring Capsule Server with custom SSL certificates to generate and sign Puppet certificates
On the Capsule Server that will generate Puppet certificates for all other load-balancing Capsule Servers, configure Puppet certificate generation and signing.
Procedure
Append the following option to the
capsule-certs-generate
command that you obtain from the output of thekatello-certs-check
command:--foreman-proxy-cname loadbalancer.example.com
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
Retain a copy of the example
satellite-installer
command from the output for installing Capsule Server certificates.- Copy the certificate archive file from Satellite Server to Capsule Server.
Append the following options to the
satellite-installer
command that you obtain from the output of thecapsule-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"
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-register-in-foreman "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"
On Capsule Server that is the Puppetserver Certificate Authority, stop the Puppet server:
# systemctl stop puppetserver
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
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
-
Start the Puppet server:
# systemctl start puppetserver
6.4. Configuring remaining Capsule Servers with custom SSL certificates for load balancing
On each load-balancing Capsule Server, excluding the Capsule Server configured to sign Puppet certificates, configure the system to use Puppet certificates.
Procedure
Append the following option to the
capsule-certs-generate
command that you obtain from the output of thekatello-certs-check
command:--foreman-proxy-cname loadbalancer.example.com
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
Retain a copy of the example
satellite-installer
command from the output for installing Capsule Server certificates.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
On Capsule Server, install the
puppetserver
package:# satellite-maintain packages install puppetserver
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/
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
On Capsule Server, change the
/etc/puppetlabs/puppet/ssl/
directory ownership to userpuppet
and grouppuppet
:# chown -R puppet:puppet /etc/puppetlabs/puppet/ssl/
On Capsule Server, set the SELinux context for the
/etc/puppetlabs/puppet/ssl/
directory:# restorecon -Rv /etc/puppetlabs/puppet/ssl/
Append the following options to the
satellite-installer
command that you obtain from the output of thecapsule-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"
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-register-in-foreman "true" \ --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"
6.5. Managing Puppet limitations with load balancing in Satellite
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:
- Configure Puppet certificate signing on one Capsule Server, typically the first system where you configure Capsule Server for load balancing.
- Configure the clients to send CA requests to port 8141 on a load balancer.
- 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.
Chapter 7. Upgrading Capsule Servers in a load-balancing setup
To upgrade Capsule Servers from 6.15 to 6.16, see Upgrading connected Red Hat Satellite to 6.16. There are no additional steps required for Capsule Servers in a load-balancing configuration.
Chapter 8. Setting the load balancer for host registration
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
You configured SSL certificates on all Capsule Servers. For more information, see the following sections:
- Chapter 3, Configuring Capsule Servers with default SSL certificates for load balancing.
- Chapter 4, Configuring Capsule Servers with custom SSL certificates for load balancing.
- Chapter 5, Configuring Capsule Servers with default SSL certificates for load balancing (with Puppet).
- Chapter 6, Configuring Capsule Servers with custom SSL certificates for load balancing (with Puppet).
You enabled Registration and Templates plugins on all Capsule Servers:
# satellite-installer \ --foreman-proxy-registration true \ --foreman-proxy-templates true
Procedure
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"
- In the Satellite web UI, navigate to Infrastructure > Capsules.
- For each Capsule, click the dropdown menu in the Actions column and select Refresh.
Chapter 9. Installing the load balancer
The following example provides general guidance for configuring an HAProxy load balancer using Red Hat Enterprise Linux 9 or Red Hat Enterprise Linux 8. However, you can install any suitable load balancing software solution that supports TCP forwarding.
Procedure
Install HAProxy:
# dnf install haproxy
Install the following package that includes the
semanage
tool:# dnf install policycoreutils-python-utils
Configure SELinux to allow HAProxy to bind any port:
# semanage boolean --modify --on haproxy_connect_any
Configure the load balancer to balance the network load for the ports as described in Table 9.1, “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. For more information, see Configuration example for haproxy.cfg for HAProxy load balancer with Satellite 6 in the Red Hat Knowledgebase.Table 9.1. Ports configuration for the load balancer Service Port Mode Balance Mode Destination 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
- 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.
Start and enable the HAProxy service:
# systemctl enable --now haproxy
Chapter 10. Verifying the load balancing configuration
Use this procedure to verify the load balancing configuration for each Capsule Server.
Procedure
- Shut down the base operating system for your Capsule Server.
-
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. - Restart the base operating system for your Capsule Server.
Chapter 11. Registering clients to the load balancer
To balance the load of network traffic from clients, you must register the clients to the load balancer.
To register clients, proceed with one of the following procedures:
11.1. Registering clients using host registration
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.
Prerequisites
- You have set the load balancer for host registration. For more information, see Chapter 8, Setting the load balancer for host registration.
Procedure
- In the Satellite web UI, navigate to Hosts > Register Host.
- From the Capsule dropdown list, select the load balancer.
- Select Force to register a host that has been previously registered to a Capsule Server.
- 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.
-
Check the
/etc/yum.repos.d/redhat.repo
file and ensure that the appropriate repositories have been enabled.
CLI procedure
Generate the host registration command using the Hammer CLI:
# hammer host-registration generate-command \ --activation-keys "My_Activation_Key"
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
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.- Connect to your host using SSH and run the registration command.
-
Check the
/etc/yum.repos.d/redhat.repo
file and ensure that the appropriate repositories have been enabled.
API procedure
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"] }}'
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 }}'
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.- Connect to your host using SSH and run the registration command.
-
Check the
/etc/yum.repos.d/redhat.repo
file and ensure that the appropriate repositories have been enabled.
11.2. (Deprecated) Registering clients using the bootstrap script
To register clients, enter the following command on the client. You must complete the registration procedure for each client.
Prerequisites
- Ensure that you install the bootstrap script on the client and change file permissions of the script to executable. For more information, see Registering Hosts to Red Hat Satellite Using The Bootstrap Script in Managing hosts.
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 \ 1 --force \ 2 --hostgroup="My_Host_Group" \ --location="My_Location" \ --login=admin \ --organization="My_Organization" \ --puppet-ca-port 8141 \ 3 --server loadbalancer.example.com
On Red Hat Enterprise Linux 7 or 6, enter the following command:
# python bootstrap.py --login=admin \ --activationkey="My_Activation_Key" \ --enablerepos=rhel-7-server-satellite-client-6-rpms \ --force \ 1 --hostgroup="My_Host_Group" \ --location="My_Location" \ --organization="My_Organization" \ --puppet-ca-port 8141 \ 2 --server loadbalancer.example.com
The script prompts for the password corresponding to the Satellite user name you entered with the --login
option.
Chapter 12. Propagating SCAP content through the load balancer
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.
12.1. Propagating SCAP content using Ansible deployment
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
- Ensure that you have configured Satellite for Ansible deployment of compliance policies. For more information, see Configuring Compliance Policy Deployment Methods in Managing security compliance.
Procedure
- In the Satellite web UI, navigate to Configure > Ansible > Variables.
-
Search for the
foreman_scap_client_port
variable and click its name. - In the Default Behavior area, ensure that the Override checkbox is selected.
-
In the Parameter Type list, ensure that
integer
is selected. -
In the Default Value field, enter
9090
. - In the Specify Matchers area, remove all matchers that override the default value.
- Click Submit.
-
Search for the
foreman_scap_client_server
variable and click its name. - In the Default Behavior area, ensure that the Override checkbox is selected.
-
In the Parameter Type list, ensure that
string
is selected. -
In the Default Value field, enter the FQDN of your load balancer, such as
loadbalancer.example.com
. - In the Specify Matchers area, remove all matchers that override the default value.
- Click Submit.
Continue with deploying a compliance policy using Ansible. For more information, see:
- Deploying a Policy in a Host Group Using Ansible in Managing security compliance
- Deploying a Policy on a Host Using Ansible in Managing security compliance
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
12.2. Propagating SCAP content using Puppet deployment
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
- Ensure that you have configured Satellite for Puppet deployment of compliance policies. For more information, see Configuring Compliance Policy Deployment Methods in Managing security compliance.
Procedure
- In the Satellite web UI, navigate to Configure > Puppet ENC > Classes.
-
Click
foreman_scap_client
. - Click the Smart Class Parameter tab.
-
In the pane to the left of the Smart Class Parameter window, click
port
. - In the Default Behavior area, select the Override checkbox.
-
From the Key Type list, select
integer
. -
In the Default Value field, enter
9090
. -
In the pane to the left of the Smart Class Parameter window, click
server
. - In the Default Behavior area, select the Override checkbox.
-
From the Key Type list, select
string
. -
In the Default Value field, enter the FQDN of your load balancer, such as
loadbalancer.example.com
. - In the lower left of the Smart Class Parameter window, click Submit.
Continue with deploying a compliance policy using Puppet. For more information, see:
- Deploying a Policy in a Host Group Using Puppet in Managing security compliance
- Deploying a Policy on a Host Using Puppet in Managing security compliance
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
Appendix A. Troubleshooting DNF modules
If DNF modules fails to enable, it can mean an incorrect module is enabled. In that case, you have to resolve dependencies manually as follows. List the enabled modules:
# dnf module list --enabled
A.1. Ruby
If Ruby module fails to enable, it can mean an incorrect module is enabled. In that case, you have to resolve dependencies manually as follows:
List the enabled modules:
# dnf module list --enabled
If the Ruby 2.5 module has already been enabled, perform a module reset:
# dnf module reset ruby
A.2. PostgreSQL
If PostgreSQL module fails to enable, it can mean an incorrect module is enabled. In that case, you have to resolve dependencies manually as follows:
List the enabled modules:
# dnf module list --enabled
If the PostgreSQL 10 module has already been enabled, perform a module reset:
# dnf module reset postgresql
If you created a PostgreSQL 10 database, perform an upgrade:
Enable the DNF modules:
# dnf module enable satellite-capsule:el8
Install the PostgreSQL upgrade package:
# dnf install postgresql-upgrade
Perform the upgrade:
# postgresql-setup --upgrade