Chapter 1. Introducing Configuration Management Using Puppet
You can use Puppet to manage and automate configurations of hosts. Puppet uses a declarative language to describe the desired state of managed hosts.
Puppet increases your productivity as you can administer multiple hosts simultaneously. At the same time, it decreases your configuration effort as Puppet makes it easy to verify and possibly correct the state of the hosts.
Additional resources
- Open Source Puppet documentation
- Puppet Forge — a repository of pre-built Puppet modules
1.1. How Puppet Integrates with Satellite
Puppet uses a server-agent architecture. The Puppet server is the central component that stores configuration definitions. Satellite Server or any Capsules are typically deployed with the Puppet server and Satellite acts as an External Node Classifier (ENC) for such Puppet server. Managed hosts run the Puppet agent that communicates with the Puppet server.
The Puppet agent collects facts about a host and reports them to the Puppet server on each run. You can display the Puppet facts in JSON format by running puppet facts
on a host.
The Puppet server forwards facts to Satellite and Satellite stores them for later use. Based on the facts and other definitions, Satellite constructs the ENC answer to the Puppet server. The Puppet server compiles a catalog based on the ENC answer and sends the catalog to the Puppet agent.
The Puppet agent evaluates the system state on the host. If the Puppet agent finds differences, known as drifts, between the desired state defined in the catalog and the actual state, it enforces correction of the state of the host. The Puppet agent then reports correction results back to the Puppet server, which reports them to Satellite.
Puppet modules
The desired state of a host is defined in a catalog. The catalog is compiled from Puppet manifests of one or more Puppet modules assigned to the host. A Puppet module is a collection of classes, manifests, resources, files, and templates. The Puppet modules work as components of host configuration definitions.
Smart Class parameters
You can override parameters of a Puppet module using Smart Class parameters if the module supports the use of parameters. You can define the parameters in your Satellite as key-value pairs, which behave similar to host parameters or Ansible variables.
Puppet environments
You can also create multiple Puppet environments to control versions of configuration definitions or to manage variants of the definitions, and to test the definitions before you deploy them on production.
High-Level Integration Steps
Puppet integration with Satellite involves the following high-level steps:
- Enable Puppet integration.
- Import Puppet agent packages into Satellite. Puppet agent packages can be managed like any other content with Satellite by enabling Red Hat Repositories and by using Activation Keys and Content Views.
- Install Puppet agent on hosts during provisioning, registration, manually, or by remote job execution.
Additional resources
- Managing Content
- Registering Hosts in the Managing Hosts Guide
- Configuring and Setting Up Remote Jobs in the Managing Hosts Guide
The following procedures outline how to use a Puppet module to install, configure, and manage the ntp service to provide examples.
1.2. Supported Puppet Versions And System Requirements
Before you begin with the Puppet integration, review the supported Puppet versions and system requirements.
- Supported Puppet Versions
Satellite supports the following Puppet versions:
- Puppet 7
- System Requirements
- Before you begin integrating Puppet with your Satellite, ensure that you meet the system requirements. For details, see System Requirements for Puppet 7 in the Open Source Puppet documentation.
1.3. Enabling Puppet Integration with Satellite
By default, Satellite does not have any Puppet integration configured. You need to enable the integration as is appropriate for your situation. This means that you can configure Satellite to manage and deploy Puppet server on Satellite Server or on Capsule. Additionally, you can deploy Puppet server to Satellite externally and integrate it with Satellite for reporting, facts, and external node classification (ENC).
Procedure
Enable Puppet integration and install Puppet server on Satellite Server:
# satellite-installer --enable-foreman-plugin-puppet \ --enable-foreman-cli-puppet \ --foreman-proxy-puppet true \ --foreman-proxy-puppetca true \ --foreman-proxy-content-puppet true \ --enable-puppet \ --puppet-server true \ --puppet-server-foreman-ssl-ca /etc/pki/katello/puppet/puppet_client_ca.crt \ --puppet-server-foreman-ssl-cert /etc/pki/katello/puppet/puppet_client.crt \ --puppet-server-foreman-ssl-key /etc/pki/katello/puppet/puppet_client.key
If you want to use Puppet integration on Capsules, enable Puppet integration and install Puppet server on Capsules:
# satellite-installer --foreman-proxy-puppet true \ --foreman-proxy-puppetca true \ --foreman-proxy-content-puppet true \ --enable-puppet \ --puppet-server true \ --puppet-server-foreman-ssl-ca /etc/pki/katello/puppet/puppet_client_ca.crt \ --puppet-server-foreman-ssl-cert /etc/pki/katello/puppet/puppet_client.crt \ --puppet-server-foreman-ssl-key /etc/pki/katello/puppet/puppet_client.key \ --puppet-server-foreman-url "https://satellite.example.com"
Enter the URL of your Satellite Server as the value of the
--puppet-server-foreman-url
argument.
1.4. Installing and Configuring Puppet Agent during Host Provisioning
You can install and configure the Puppet agent on a host during the provisioning process. A configured Puppet agent is required on the host for Puppet integration with your Satellite.
Prerequisites
- Puppet must be enabled in your Satellite. For more information, see Section 1.3, “Enabling Puppet Integration with Satellite”.
- You enabled and synchronized the Satellite Client 6 repository to Satellite. For more information, see Importing Content in Managing Content.
- You created an activation key that enables the Satellite Client 6 repository for hosts. For more information, see Managing Activation Keys in Managing Content.
Procedure
- Navigate to Hosts > Provisioning Templates.
- Select a provisioning template depending on your host provisioning method. For more information, see Kinds of Provisioning Templates in Provisioning Hosts.
Ensure the
puppet_setup
snippet is included as follows:<%= snippet 'puppet_setup' %>
Enable Puppet using a host parameter for a single host or host group:
Add a host parameter named
enable-puppet7
for Puppet 7 as type boolean set totrue
.-
Optional: To install the Puppet agent directly from yum.puppet.com, add a host parameter named
enable-puppetlabs-puppet7-repo
for Puppet 7 as type boolean set totrue
. Only use this if you don’t provide Puppet agent to the host using its activation key.
1.5. Installing and Configuring Puppet Agent during Host Registration
You can install and configure the Puppet agent on the host during registration. A configured Puppet agent is required on the host for Puppet integration with your Satellite.
Prerequisites
- Puppet must be enabled in your Satellite. For more information, see Section 1.3, “Enabling Puppet Integration with Satellite”.
- You enabled and synchronized the Satellite Client 6 repository to Satellite. For more information, see Importing Content in Managing Content.
- You created an activation key that enables the Satellite Client 6 repository for hosts. For more information, see Managing Activation Keys in Managing Content.
Procedure
- In the Satellite web UI, navigate to Configure > Global Parameters to add host parameters globally. Alternatively, you can navigate to Configure > Host Groups and edit or create a host group to add host parameters only to a host group.
-
Enable the Puppet agent using a host parameter in global parameters or a host group. Add a host parameter named
enable-puppet7
, select the boolean type, and set the value totrue
. Specify configuration for the Puppet agent using the following host parameters in global parameters or a host group:
-
Add a host parameter named
puppet_server
, select the string type, and set the value to the hostname of your Puppet server, such aspuppet.example.com
. -
Optional: Add a host parameter named
puppet_ca_server
, select the string type, and set the value to the hostname of your Puppet CA server, such aspuppet-ca.example.com
. Ifpuppet_ca_server
is not set, the Puppet agent will use the same server aspuppet_server
. -
Optional: Add a host parameter named
puppet_environment
, select the string type, and set the value to the Puppet environment you want the host to use.
Until the BZ2177730 is resolved, you must use host parameters to specify the Puppet agent configuration even in integrated setups where the Puppet server is a Capsule Server.
-
Add a host parameter named
- Navigate to Hosts > Register Host and register your host using an appropriate activation key. For more information, see Registering Hosts in Managing Hosts.
- Navigate to Infrastructure > Capsules.
- From the list in the Actions column for the required Capsule Server, select Certificates.
- Click Sign to the right of the required host to sign the SSL certificate for the Puppet agent.
1.6. Installing and Configuring Puppet Agent Manually
You can install and configure the Puppet agent on a host manually. A configured Puppet agent is required on the host for Puppet integration with your Satellite.
Prerequisites
- Puppet must be enabled in your Satellite. For more information, see Section 1.3, “Enabling Puppet Integration with Satellite”.
- The host must have a Puppet environment assigned to it.
- The Satellite Client 6 repository must be enabled and synchronized to Satellite Server, and enabled on the host. For more information, see Importing Content in Managing Content.
Procedure
-
Log in to the host as the
root
user. Install the Puppet agent package.
On hosts running Red Hat Enterprise Linux 8 and above:
# dnf install puppet-agent
On hosts running Red Hat Enterprise Linux 7 and below:
# yum install puppet-agent
Add the Puppet agent to
PATH
in your current shell using the following script:. /etc/profile.d/puppet-agent.sh
Configure the Puppet agent. Set the
environment
parameter to the name of the Puppet environment to which the host belongs:# puppet config set server satellite.example.com --section agent # puppet config set environment My_Puppet_Environment --section agent
Start the Puppet agent service:
# puppet resource service puppet ensure=running enable=true
Create a certificate for the host:
# puppet ssl bootstrap
- In the Satellite web UI, navigate to Infrastructure > Capsules.
- From the list in the Actions column for the required Capsule Server, select Certificates.
- Click Sign to the right of the required host to sign the SSL certificate for the Puppet agent.
On the host, run the Puppet agent again:
# puppet ssl bootstrap
1.7. Performing Configuration Management
After you deploy Puppet agent on a host, you can start performing configuration management with Puppet. This involves the following high-level steps:
- Managing Puppet modules on the Puppet server, that is installing and updating them.
- Importing Puppet classes and environments from Puppet modules into Satellite.
- Optional: Creating config groups from Puppet classes.
- Configuring overrides of Smart Class parameters on various levels.
- Assigning Puppet classes or config groups to host groups or individual hosts.
- Configuring intervals for runs of the Puppet agent on hosts and for configuration enforcement runs of the Puppet server.
- Monitoring configuration management using reports in the Satellite web UI. For more information, see Monitoring Resources in Administering Red Hat Satellite.
- Configuring email notifications. For more information, see Configuring Email Notification Preferences in Administering Red Hat Satellite.
After assigning Puppet classes or config groups, Satellite runs configuration management automatically in the configured intervals to enforce Puppet configuration on the managed hosts, or you can initiate it manually on demand with the Run Puppet Once feature. For more information, see Section 9.1, “Running Puppet Once Using SSH”.
1.8. Disabling Puppet Integration with Satellite
To discontinue using Puppet in your Satellite, follow this procedure.
Note that the command without the --remove-all-data
argument removes all Puppet-related data in Satellite database. With the --remove-all-data
argument, the command additionally removes Puppet server data files, including Puppet environments.
If you disable Puppet with the --remove-all-data
argument, you will not be able to re-enable Puppet afterwards. This is a known issue, see the Bug 2087067.
Prerequisite
- Puppet is enabled on Satellite.
Procedure
If you have used Puppet server on any Capsules, disable Puppet server on all Capsules:
# satellite-maintain plugin purge-puppet --remove-all-data
Disable Puppet server on Satellite Server:
# satellite-maintain plugin purge-puppet --remove-all-data