How Do I Add Puppet Agent to Foreman?

Adding a Puppet agent to Foreman involves installing the agent software on your client machine, configuring it to communicate with your Foreman server (acting as the Puppet master and certificate authority), and then signing its SSL certificate within the Foreman web interface to establish trust. This process integrates the host into Foreman's centralized management system, allowing you to deploy configurations, manage services, and ensure compliance across your infrastructure.

Understanding the Integration

Foreman provides a comprehensive platform for managing the lifecycle of physical and virtual servers. When integrated with Puppet, it acts as an intelligent front-end, simplifying Puppet's robust configuration management capabilities. The Puppet agent runs on client machines, applying configurations defined on the Foreman server. For secure communication, each agent requires an SSL certificate signed by the Foreman's internal Certificate Authority (CA).

Prerequisites for Seamless Integration

Before you begin, ensure the following foundational elements are in place:

Foreman & Smart Proxy Setup

Functional Foreman Instance: Your Foreman server should be fully installed and operational, with its Puppet components (Puppet master, CA, and Puppet agent proxy) configured.
Smart Proxy Role: The Foreman Smart Proxy handling Puppet services must be correctly configured and accessible to the agent. This Smart Proxy typically serves as the Puppet master and CA for your agents.

Network Connectivity

Port 8140: Ensure that the Puppet agent host can communicate with the Foreman Smart Proxy (Puppet master) on TCP port 8140.
DNS Resolution: The agent host must be able to resolve the hostname of your Foreman Smart Proxy (e.g., foreman.example.com).

Step-by-Step Guide to Adding a Puppet Agent

Follow these steps to successfully integrate a new Puppet agent with your Foreman deployment:

1. Install the Puppet Agent Package

The first step is to install the Puppet agent software on the client host you wish to manage. The installation process typically involves adding the Puppet repository and then installing the package using your operating system's package manager.

For Red Hat Enterprise Linux (RHEL), CentOS, Fedora:
1. Add the Puppet repository (replace el-7 or el-8 with your OS version, and 6 with the desired Puppet agent version):
```
sudo rpm -Uvh https://yum.puppet.com/puppet6-release-el-7.noarch.rpm
```
2. Install the Puppet agent:
```
sudo yum install -y puppet-agent
```

For Debian, Ubuntu:

Add the Puppet repository (replace bionic with your OS version, and 6 with the desired Puppet agent version):

sudo apt install -y curl
curl -LO https://apt.puppet.com/puppet6-release-bionic.deb
sudo dpkg -i puppet6-release-bionic.deb
sudo apt update

Install the Puppet agent:
```
sudo apt install -y puppet-agent
```

2. Configure the Puppet Agent

After installation, configure the Puppet agent to point to your Foreman server (acting as the Puppet master). This is done by editing the puppet.conf file.

Open the puppet.conf file, usually located at /etc/puppetlabs/puppet/puppet.conf:
```
sudo vim /etc/puppetlabs/puppet/puppet.conf
```
In the [main] section, add or modify the server and certname parameters:
```
[main]
    certname = <FQDN_OF_AGENT_HOST>
    server = <FOREMAN_SMART_PROXY_FQDN>
    environment = production # Or your desired environment
```
- Replace <FQDN_OF_AGENT_HOST> with the fully qualified domain name (FQDN) of your agent host (e.g., client1.example.com).
- Replace <FOREMAN_SMART_PROXY_FQDN> with the FQDN of your Foreman Smart Proxy that handles Puppet (e.g., foreman.example.com).
Save and close the file.

3. Initiate Certificate Signing Request (CSR)

For secure communication, the Puppet agent needs an SSL certificate. On its first run, the agent will generate a Certificate Signing Request (CSR) and send it to the Foreman's Puppet CA.

Start the Puppet agent service (optional, but good for ensuring it's running):
```
sudo systemctl start puppet
sudo systemctl enable puppet
```
Perform an initial Puppet agent run. This action will generate and submit the CSR to the Foreman CA:
```
sudo /opt/puppetlabs/bin/puppet agent -t --server <FOREMAN_SMART_PROXY_FQDN>
```
You will likely see a message indicating that the certificate request has been submitted and is awaiting signing.

4. Sign the SSL Certificate in Foreman

Once the CSR is submitted, you need to approve and sign it within the Foreman web UI. This step establishes trust between the agent and the Puppet master.

Open your web browser and log in to the Foreman web UI.
In the Foreman web UI, navigate to Infrastructure > Smart Proxies.
From the list, locate the required Smart Proxy server that serves as your Puppet CA. In the Actions column for that Smart Proxy, select Certificates.
You will see a list of pending certificate signing requests. Click Sign to the right of the host's name for which you want to sign the SSL certificate for the Puppet agent.

5. Final Puppet Agent Run and Verification

After the certificate is signed, the agent can retrieve its valid certificate and proceed with applying configurations.

On the Puppet agent host, run the Puppet agent again to fetch the signed certificate and apply any initial configurations:
```
sudo /opt/puppetlabs/bin/puppet agent -t
```
This time, the agent should successfully retrieve its certificate and connect to the Puppet master.
Verify the agent's status:
```
sudo /opt/puppetlabs/bin/puppet agent --status
```
It should report Running or Applied.

6. Manage the Host in Foreman

With the agent successfully integrated, the host will appear in your Foreman UI, and you can begin managing it.

Navigate to Hosts > All Hosts in the Foreman UI. Your newly added host should appear in the list.
Click on the host's name to view its details.
From here, you can:
- Assign Host Groups to apply pre-defined configurations.
- Add Puppet Classes to manage specific services or software.
- Set Parameters to customize class behaviors.
- View Reports of Puppet runs to track configuration changes and compliance.

For more detailed information, refer to the Foreman Documentation and Puppet Documentation.

Troubleshooting Common Issues

Certificate Errors: If you encounter certificate verify failed or similar errors, ensure the certificate was signed in Foreman and that puppet agent -t was run again.
Network Connectivity: Verify that the agent can ping the Foreman Smart Proxy and that port 8140 is open through any firewalls.
DNS Resolution: Confirm that both forward and reverse DNS resolution work correctly for the agent and Foreman server.
Time Synchronization: Ensure that both the agent and Foreman server have synchronized clocks to prevent certificate validation issues.

By following these steps, your Puppet agent will be fully integrated with Foreman, ready for comprehensive configuration management.