Managing configurations by using Puppet integration
Configure Puppet integration in Satellite and use Puppet classes to configure your hosts
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.
Procedure
- Log in to Content from id.atlassian.com is not included.Atlassian Jira.
- Click the following link: Content from redhat.atlassian.net is not included.Create Issue.
- Complete the Summary, Description, and Reporter 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. Introducing configuration management by using Puppet
You can use Puppet to manage and automate configurations of hosts. Puppet uses a declarative language to describe the desired state of 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
- Content from puppet.com is not included.Open Source Puppet documentation
- Content from forge.puppet.com is not included.Puppet Forge — a repository of pre-built Puppet modules
1.1. How Puppet integrates with Satellite
Puppet uses a server-agent architecture. OpenVox server communicates with OpenVox agents on hosts registered to Satellite to manage the Puppet configuration of these hosts.
Satellite components integrate with that architecture to provide configuration management capabilities in Satellite.
Puppet architecture in Satellite comprises the following components:
- OpenVox server
- OpenVox server is the central component that stores Puppet configuration definitions in Satellite. It runs on Satellite Server or Capsule Servers.
Puppet server is no longer supported for Puppet integration with Satellite. To integrate your Puppet infrastructure with Satellite, you need to use an OpenVox server instead. An OpenVox server is functionally equivalent to a Puppet server.
- OpenVox agent
- OpenVox agent is a service that communicates with an OpenVox server to manage the configuration of hosts. It runs on hosts registered to Satellite.
As a legacy alternative, Puppet agent also remains compatible with Satellite for Puppet integration. However, an OpenVox agent is the recommended agent for Puppet integration, and it is functionally equivalent to a Puppet agent. You cannot run both OpenVox agent and Puppet agent on the same host.
Puppet modules
A Puppet module is a collection of classes, manifests, resources, files, and templates. The Puppet modules work as components of host configuration definitions.
Puppet environments
Puppet environments are used to control versions of configuration definitions or to manage variants of the definitions, and to test the definitions before you deploy them on production. You can create multiple Puppet environments.
On each run, the OpenVox agent collects Puppet facts about the host and sends them to the OpenVox server. The OpenVox server forwards those facts to Satellite.
To list Puppet facts on a host, run the puppet facts command.
Satellite acts as an external node classifier (ENC) for the OpenVox server. Based on the facts and other definitions Satellite receives from the OpenVox server, Satellite constructs the ENC answer to the OpenVox server.
Based on the ENC answer, the OpenVox server compiles a catalog for the host and sends it to the agent.
The agent evaluates the system state on the host. If the agent finds differences between the desired state defined in the catalog and the actual state, known as drifts, it enforces correction of the state of the host.
The agent reports correction results back to the OpenVox server. The OpenVox server receives correction results from the agent and reports them to Satellite.
If the Puppet modules you are using support the use of parameters, you can override parameters of the module by using Smart Class parameters in Satellite. In Satellite, you define the parameters as key-value pairs, which behave similar to host parameters or Ansible variables.
1.2. OpenVox versions supported for integration with Satellite
Before you begin with the Puppet integration, review which versions of the OpenVox server and OpenVox agent are supported for integration with Satellite.
OpenVox Server 8 is supported on Satellite Server and Capsule Servers.
The Puppet modules you use must be compatible with the OpenVox Server version you run.
OpenVox Agent 8 is supported on hosts registered to Satellite.
Additionally, Puppet agent 7 remains compatible with OpenVox in Satellite as a legacy alternative. Hosts registered to Satellite that run Puppet agent 7 can still integrate with the OpenVox implementation in Satellite. However, Puppet agent 7 is end of life. Red Hat recommends to use OpenVox agent 8.
1.3. Installing OpenVox server on Satellite Server and Capsule Servers
Use the satellite-installer utility to install an OpenVox server on Satellite Server. Optionally, you can also install additional OpenVox servers on Capsule Servers.
Procedure
Install OpenVox server on Satellite Server:
# satellite-installer \ --enable-foreman-cli-puppet \ --enable-foreman-plugin-puppet \ --enable-puppet \ --foreman-proxy-puppet true \ --foreman-proxy-puppetca true \ --puppet-server true
Optional: If you want manage configuration with Puppet on Capsule Servers, install OpenVox server on Capsule Servers:
# satellite-installer \ --enable-puppet \ --foreman-proxy-puppet true \ --foreman-proxy-puppetca true \ --puppet-server true
1.4. Configuring OpenVox agent on a host during provisioning
You can install and configure the OpenVox agent on a host during the provisioning process. A configured OpenVox agent is required on the host for Puppet integration with your Satellite.
Prerequisites
Red Hat Satellite Client 6 OpenVox repository is synchronized on Satellite Server and enabled in the activation key you use. Choose from the following repositories, based on the operating system version and the architecture of the host you are registering:
- satellite-client-openvox-for-rhel-9-x86_64-rpms
- satellite-client-openvox-for-rhel-8-aarch64-rpms
- satellite-client-openvox-for-rhel-8-x86_64-rpms
- You have an activation key. For more information, see Managing Activation Keys in Managing content.
Procedure
- Navigate to Hosts > Templates > 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_setupsnippet is included as follows:<%= snippet 'puppet_setup' %>
Note that this snippet is already included in the templates shipped with Satellite, such as
Kickstart defaultorPreseed default.-
Enable the OpenVox agent using a host parameter in global parameters, a host group, or for a single host. Add a host parameter named
enable-puppet8, select the boolean type, and set the value totrue. Set configuration for the OpenVox agent.
- If you use an integrated OpenVox server, ensure that you select a Puppet Capsule, Puppet CA Capsule, and Puppet environment when you create a host.
If you use a non-integrated OpenVox server, either set the following host parameters in global parameters, or a host group, or when you create a host:
-
Add a host parameter named
puppet_server, select the string type, and set the value to the hostname of your OpenVox server, such asopenvox.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_serveris not set, the OpenVox 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.
-
Add a host parameter named
- Ensure your host has access to the OpenVox agent packages from Satellite Server by using an appropriate activation key.
1.5. Configuring OpenVox agent on a host during registration
You can install and configure the OpenVox agent on the host during registration. A configured OpenVox agent is required on the host for Puppet integration with your Satellite.
Prerequisites
Puppet is enabled in your Satellite. For more information, see Section 1.3, “Installing OpenVox server on Satellite Server and Capsule Servers”.
Choose from the following repositories, based on the operating system version and the architecture of the host you are registering:
- satellite-client-openvox-for-rhel-9-x86_64-rpms
- satellite-client-openvox-for-rhel-8-aarch64-rpms
- satellite-client-openvox-for-rhel-8-x86_64-rpms
- You have an activation key. 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 OpenVox agent using a host parameter in global parameters or a host group. Add a host parameter named
enable-puppet8, select the boolean type, and set the value totrue. Specify configuration for the OpenVox 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 OpenVox server, such asopenvox.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_serveris not set, the OpenVox 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 This content is not included.BZ2177730 is resolved, you must use host parameters to specify the Puppet agent configuration even in integrated setups where the OpenVox 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 by using global registration 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 OpenVox agent.
1.6. Configuring OpenVox agent on a host manually
On hosts that are already registered to Satellite, you can install and configure the OpenVox agent manually. A configured OpenVox agent is required on the host for Puppet integration with your Satellite.
Prerequisites
- Puppet is enabled in your Satellite. For more information, see Section 1.3, “Installing OpenVox server on Satellite Server and Capsule Servers”.
- The host must have a Puppet environment assigned to it.
Red Hat Satellite Client 6 OpenVox repository is synchronized on Satellite Server, available in the content view and the lifecycle environment of the host, and enabled for the host.
Choose from the following repositories, based on the operating system version and the architecture of the host you are registering:
- satellite-client-openvox-for-rhel-9-x86_64-rpms
- satellite-client-openvox-for-rhel-8-aarch64-rpms
- satellite-client-openvox-for-rhel-8-x86_64-rpms
Procedure
-
Log in to the host as the
rootuser. Install the OpenVox agent package:
On hosts running Red Hat Enterprise Linux 8 and above:
# dnf install openvox-agent
On hosts running Red Hat Enterprise Linux 7 and below:
# yum install openvox-agent
Add the OpenVox agent to
PATHin your current shell using the following script:. /etc/profile.d/puppet-agent.sh
Configure the Puppet agent. Set the
environmentparameter 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 OpenVox 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 OpenVox agent.
On the host, run the OpenVox agent again:
# puppet ssl bootstrap
1.7. Performing configuration management
After you deploy OpenVox agent on a host, you can start performing configuration management with Puppet. This involves the following high-level steps:
- Managing Puppet modules on the OpenVox 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 OpenVox agent on hosts and for configuration enforcement runs of the OpenVox 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 your 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 OpenVox 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 This content is not included.Bug 2087067.
Procedure
If you have used OpenVox server on any Capsules, disable OpenVox server on all Capsules:
# satellite-maintain plugin purge-puppet --remove-all-data
Disable OpenVox server on Satellite Server:
# satellite-maintain plugin purge-puppet --remove-all-data
Chapter 2. Managing Puppet modules
2.1. Installing a Puppet module on Satellite server
You can install a pre-built Puppet module from the Puppet Forge. The Puppet Forge is a repository that provides Puppet modules contributed by the community. Puppet modules flagged as supported are officially supported and tested by Puppet Inc.
This example shows how to add the ntp module to hosts.
Procedure
-
Navigate to Content from forge.puppet.com is not included.forge.puppet.com and search for
ntp. One of the first modules is puppetlabs/ntp. Connect to your Satellite Server using SSH and install the Puppet module:
# puppet module install puppetlabs-ntp -i /etc/puppetlabs/code/environments/production/modules
Use the
-iparameter to specify the path and Puppet environment, for exampleproduction.Once the installation is completed, the output looks as follows:
Notice: Preparing to install into /etc/puppetlabs/code/environments/production/modules ... Notice: Created target directory /etc/puppetlabs/code/environments/production/modules Notice: Downloading from https://forgeapi.puppet.com ... Notice: Installing -- do not interrupt ... /etc/puppetlabs/code/environments/production/modules |-| puppetlabs-ntp (v8.3.0) |-- puppetlabs-stdlib (v4.25.1) [/etc/puppetlabs/code/environments/production/modules]
An alternative way to install a Puppet module is to copy a folder containing the Puppet module to the module path as mentioned above. Ensure to resolve its dependencies manually.
2.2. Updating a Puppet module
You can update an existing Puppet module using the puppet command.
Procedure
Connect to your OpenVox server using SSH and find out where the Puppet modules are located:
# puppet config print modulepath
This returns output as follows:
/etc/puppetlabs/code/environments/production/modules:/etc/puppetlabs/code/environments/common:/etc/puppetlabs/code/modules:/opt/puppetlabs/puppet/modules:/usr/share/puppet/modules
If the module is located in the path as displayed above, the following command updates a module:
# puppet module upgrade module name
Chapter 3. Importing Puppet classes and environments into Satellite
Import Puppet classes and environments from the installed Puppet modules to Satellite Server or any attached Capsule Server before you assign any of the classes to hosts.
Prerequisites
- Ensure to select Any Organization and Any Location as context, otherwise the import might fail.
Procedure
- In the Satellite web UI, navigate to Configure > Puppet ENC > Classes or Configure > Puppet ENC > Environments.
- Click Import in the upper right corner and select which Capsule you want to import modules from. You may typically choose between your Satellite Server or any attached Capsule Server.
- Select the Puppet environments to import using checkboxes on the left.
- Click Update to import the Puppet environments and classes to Satellite.
The import should result in a notification as follows:
Successfully updated environments and Puppet classes from the on-disk Puppet installation
Chapter 4. Creating a custom Puppet environment
You can create a Puppet environment within your Satellite.
Procedure
- In the Satellite web UI, navigate to Configure > Puppet Environments.
- Click Create Puppet Environment to create a Puppet environment.
-
Enter a Name, alphanumeric characters and underscores are allowed, such as
example_environment. - Optional: Set a location context.
- Optional: Set an organization context.
- Click Submit to create the Puppet environment.
Note that before you run an import of Puppet modules into Satellite, the environment must already exist as the folder /etc/puppetlabs/code/environments/example_environment on the Puppet server and contain installed Puppet modules.
Chapter 5. Creating a Puppet config group
A Puppet config group is a named list of Puppet classes that allows you to combine their capabilities and assign them to hosts at a click. This is equivalent to the concept of profiles in pure Puppet.
Procedure
- In the Satellite web UI, navigate to Configure > Puppet ENC > Config Groups.
- Click Create Config Group.
Select the classes you want to add to the config group.
- Choose a meaningful Name for the Puppet config group.
- Add selected Puppet classes to the Included Classes field.
- Click Submit to save the changes.
Chapter 6. Configuring Puppet smart class parameters
6.1. Puppet parameter hierarchy
Puppet parameters are structured hierarchically. Parameters at a lower level override parameters of the higher levels:
- Global parameters
- Organization parameters
- Location parameters
- Host group parameters
- Host parameters
For example, host specific parameters override the parameter at any higher level, and location parameters only override parameters at the organization or global level. This feature is especially useful when you use locations or organizations to group hosts.
6.2. Overriding a smart class parameter globally
You can configure a Puppet class after you have imported it to Satellite Server. This example overrides the default list of ntp servers.
Procedure
- In the Satellite web UI, navigate to Configure > Puppet ENC > Classes.
- Select the ntp Puppet class to change its configuration.
- Select the Smart Class Parameter tab and search for servers.
- Ensure the Override checkbox is selected.
- Set the Parameter Type drop down menu to array.
Insert a list of ntp servers as Default Value:
["0.de.pool.ntp.org","1.de.pool.ntp.org","2.de.pool.ntp.org","3.de.pool.ntp.org"]
An alternative way to describe the array is the
yamlsyntax:- 0.de.pool.ntp.org - 1.de.pool.ntp.org - 2.de.pool.ntp.org - 3.de.pool.ntp.org
-
Click Submit to change the default configuration of the Puppet module
ntp.
6.3. Overriding a smart class parameter for an organization
You can use groups of hosts to override Puppet parameters for multiple hosts at once. The following example chooses the organization context to illustrate setting context based parameters.
Note that organization-level Puppet parameters are overridden by location-level Puppet parameters.
Procedure
- In the Satellite web UI, navigate to Configure > Puppet ENC > Classes.
- Click a class name to select a class.
- On the Smart Class Parameter tab, select a parameter.
-
Use the Order list to define the hierarchy of the Puppet parameters. The individual host (
fqdn) marks the most and the organization context (organization) the least relevant. - Check Merge Overrides if you want to add all further matched parameters after finding the first match.
- Check Merge Default if you want to also include the default value even if there are more specific values defined.
- Check Avoid Duplicates if you want to create a list of unique values for the selected parameter.
- The matcher field requires an attribute type from the order list.
- Optional: Click Add Matcher to add more matchers.
- Click Submit to save the changes.
6.4. Overriding a smart class parameter for a location
You can use groups of hosts to override Puppet parameters for multiple hosts at once. The following examples chooses the location context to illustrate setting context based parameters.
Procedure
- In the Satellite web UI, navigate to Configure > Puppet ENC > Classes.
- Click a class name to select a class.
- On the Smart Class Parameter tab, select a parameter.
-
Use the Order list to define the hierarchy of the Puppet parameters. The individual host (
fqdn) marks the most and the location context (location) the least relevant. - Check Merge Overrides if you want to add all further matched parameters after finding the first match.
- Check Merge Default if you want to also include the default value even if there are more specific values defined.
- Check Avoid Duplicates if you want to create a list of unique values for the selected parameter.
-
The matcher field requires an attribute type from the order list. For example, you can choose
Parisas location context and set the value to French ntp servers. - Optional: Click Add Matcher to add more matchers.
- Click Submit to save the changes.
6.5. Overriding a smart class parameter on an individual host
You can override parameters on individual hosts. This is recommended if you have multiple hosts and only want to make changes to a single one.
Procedure
- In the Satellite web UI, navigate to Hosts > All Hosts.
- Click a host name to select a host.
- Click Edit.
- On the Host tab, select a Puppet Environment.
- Select the Puppet ENC tab.
- Click Override to edit the Puppet parameter.
- Click Submit to save the changes.
Chapter 7. Assigning a Puppet class to a host group
Use a host group to assign the ntp Puppet class to multiple hosts at once. Every host you deploy based on this host group has this Puppet class installed.
Procedure
- In the Satellite web UI, navigate to Configure > Host Groups to create a host group or edit an existing one.
On the Host Group tab, set the following parameters:
- The Lifecycle Environment describes the stage in which certain versions of content are available to hosts.
- The Content View is comprised of products and allows for version control of content repositories.
- The Environment allows you to supply a group of hosts with their own dedicated configuration.
- Navigate to the Puppet ENC tab.
- Add the Puppet class to the Included Classes or to the Included Config Groups if a Puppet config group is configured.
- Click Submit to save the changes.
Chapter 8. Assigning a Puppet class to an individual host
Procedure
- In the Satellite web UI, navigate to Hosts > All Hosts.
-
Locate the host you want to add the
ntpPuppet class to and click Edit. - Select the Puppet ENC tab and look for the ntp class.
-
Click the + symbol next to
ntpto add the ntp submodule to the list of included classes. Click Submit to save your changes.
TipIf the Puppet classes tab of an individual host is empty, check if it is assigned to the proper Puppet environment.
Verify the Puppet configuration.
- Navigate to Hosts > All Hosts and select the host.
- From the top overflow menu, select Legacy UI.
Under Details, click Puppet YAML. This produces output similar as follows:
--- parameters: // shortened YAML output classes: ntp: servers: '["0.de.pool.ntp.org","1.de.pool.ntp.org","2.de.pool.ntp.org","3.de.pool.ntp.org"]' environment: production ...
Verify the ntp configuration.
Connect to your host using SSH and check the content of
/etc/ntp.conf.This example assumes your host is running CentOS 7. Other operating systems may store the ntp config file in a different path.
TipYou may need to run the OpenVox agent on your host by executing the following command:
# puppet agent -t
Running the following command on the host checks which ntp servers are used for clock synchronization:
# cat /etc/ntp.conf
This returns output similar as follows:
# ntp.conf: Managed by puppet. server 0.de.pool.ntp.org server 1.de.pool.ntp.org server 2.de.pool.ntp.org server 3.de.pool.ntp.org
You now have a working ntp module which you can add to a host or group of hosts to roll out your ntp configuration automatically.
Chapter 9. Enforcing Puppet configuration on hosts
You can enforce configuration from Satellite either manually on demand (run once) or automatically in configurable intervals.
9.1. Running Puppet once using SSH
Assign the proper job template to the Run Puppet Once feature to run Puppet on hosts.
Procedure
- In the Satellite web UI, navigate to Administer > Remote Execution Features.
-
Select the
puppet_run_hostremote execution feature. -
Assign the
Puppet Run Once – Script Defaultjob template.
Run Puppet on hosts by running a job and selecting category Puppet and template Puppet Run Once - Script Default. Alternatively, click Run Puppet Once in the Schedule Remote Job drop down menu on the host details page.
9.2. Understanding intervals of automatic enforcement
Satellite considers hosts to be out of sync if the last Puppet report is older than the combined values of outofsync_interval and puppet_interval set in minutes. By default, the Puppet agent on your hosts runs every 30 minutes, the puppet_interval is set to 35 minutes and the global outofsync_interval is set to 30 minutes.
The effective time after which hosts are considered out of sync is the sum of outofsync_interval and puppet_interval. For example, setting the global outofsync_interval to 30 and the puppet_interval to 60 results in a total of 90 minutes after which the host status changes to out of sync.
9.3. Setting the OpenVox agent run interval on a host
Set the interval when the OpenVox agent runs and sends reports to Satellite.
Procedure
- Connect to your host using SSH.
-
Add the OpenVox agent run interval to
/etc/puppetlabs/puppet/puppet.conf, for exampleruninterval = 1h.
9.4. Setting the global out-of-sync interval
Procedure
- In the Satellite web UI, navigate to Administer > Settings.
On the General tab, edit Out of sync interval. Set a duration, in minutes, after which hosts are considered to be out of sync.
You can also override this interval on host groups or individual hosts by adding the
outofsync_intervalparameter.
9.5. Setting the Puppet out-of-sync interval
Procedure
- In the Satellite web UI, navigate to Administer > Settings, and click the Config Management tab.
- In the Puppet interval field, set the value to the duration, in minutes, after which hosts reporting using Puppet are considered to be out of sync.
9.6. Overriding out-of-sync interval for a host group
Procedure
- In the Satellite web UI, navigate to Configure > Host Groups.
- Select a host group.
- On the Parameters tab, click Add Parameter.
-
In the Name field, enter
outofsync_interval. -
From the Type dropdown menu, select
integer. - In the Value field, enter the new interval in minutes.
- Click Submit.
9.7. Overriding out-of-sync interval for an individual host
Procedure
- In the Satellite web UI, navigate to Hosts > All Hosts.
- Click Edit for a selected host.
- On the Parameters tab, click Add Parameter.
-
In the Name field, enter
outofsync_interval. -
From the Type dropdown menu, select
integer. - In the Value field, enter the new interval in minutes.
- Click Submit.