Configuring Hosts Using Puppet

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 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

How Puppet integrates with orcharhino

Puppet uses a server-agent architecture. The Puppet server is the central component that stores configuration definitions. orcharhino Server or any orcharhino Proxies are typically deployed with the Puppet server and orcharhino acts as an External Node Classifier (ENC) for such Puppet server. 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 orcharhino and orcharhino stores them for later use. Based on the facts and other definitions, orcharhino 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 orcharhino.

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 orcharhino 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 orcharhino involves the following high-level steps:

Import Puppet agent packages into orcharhino. Puppet agent packages can be managed like any other content with orcharhino by syncing repositories in custom products 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.

Supported Puppet versions and system requirements

Before you begin with the Puppet integration, review the supported Puppet versions and system requirements.

Supported Puppet Versions: orcharhino supports Puppet 7. Ensure that the Puppet modules used to configure your hosts are compatible with Puppet 7.
System Requirements: Before you begin integrating Puppet with your orcharhino, ensure that you meet the system requirements. For more information, see System Requirements for Puppet 7 in the Open Source Puppet documentation.

Enabling Puppet integration with orcharhino

By default, orcharhino 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 orcharhino to manage and deploy Puppet server on orcharhino Server or orcharhino Proxies. Additionally, you can deploy Puppet server to orcharhino externally and integrate it with orcharhino for reporting, facts, and external node classification (ENC).

Procedure

Enable Puppet integration and install Puppet server on orcharhino Server:

$ orcharhino-installer \
--enable-foreman-cli-puppet \
--enable-foreman-plugin-puppet \
--enable-puppet \
--foreman-proxy-puppet true \
--foreman-proxy-puppetca true \
--puppet-server true

If you want to use Puppet integration on orcharhino Proxies, enable Puppet integration and install Puppet server on orcharhino Proxies:
```
$ orcharhino-installer \
--enable-puppet \
--foreman-proxy-puppet true \
--foreman-proxy-puppetca true \
--puppet-server true
```

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 orcharhino.

Prerequisites

Puppet must be enabled in your orcharhino. For more information, see Enabling Puppet Integration.
You created a Product and repository containing the Puppet agent and synchronized the repository to orcharhino. For more information, see Importing Content in Managing Content.
You created an activation key that enables the Puppet agent repository for hosts. 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_setup snippet is included as follows:
```
<%= snippet 'puppet_setup' %>
```
Note that this snippet is already included in the templates shipped with orcharhino, such as Kickstart default or Preseed default.
Enable the Puppet agent using a host parameter in global parameters, a host group, or for a single host. Add a host parameter named enable-puppet7, select the boolean type, and set the value to true.
Set configuration for the Puppet agent.
- If you use an integrated Puppet server, ensure that you select a Puppet orcharhino Proxy, Puppet CA orcharhino Proxy, and Puppet environment when you create a host.
- If you use a non-integrated Puppet 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 Puppet server, such as puppet.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 as puppet-ca.example.com. If puppet_ca_server is not set, the Puppet agent will use the same server as puppet_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.
Ensure your host has access to the Puppet agent packages from orcharhino Server by using an appropriate activation key.

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 orcharhino. For more information about Puppet, see Configuring Hosts Using Puppet.

Prerequisites

Puppet must be enabled in your orcharhino. For more information, see Enabling Puppet Integration with orcharhino in Configuring Hosts Using Puppet.
You created a Product and repository containing the Puppet agent and synchronized the repository to orcharhino. For more information, see Importing Content in Managing Content.
You created an activation key that enables the Puppet agent repository for hosts. For more information, see Managing Activation Keys in Managing Content.

Procedure

In the orcharhino management 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 to true.
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 as puppet.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 as puppet-ca.example.com. If puppet_ca_server is not set, the Puppet agent will use the same server as puppet_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.