How to Configure Puppet Master and Agent on Linux
Puppet is a powerful configuration management tool that enables system administrators to automate the deployment, configuration, and management of servers and applications across Linux environments. This comprehensive guide will walk you through the complete process of setting up a Puppet master server and configuring Puppet agents, providing you with the knowledge to implement enterprise-grade infrastructure automation.
Table of Contents
1. [Introduction to Puppet Architecture](#introduction-to-puppet-architecture)
2. [Prerequisites and Requirements](#prerequisites-and-requirements)
3. [Installing Puppet Master](#installing-puppet-master)
4. [Configuring Puppet Master](#configuring-puppet-master)
5. [Installing Puppet Agent](#installing-puppet-agent)
6. [Configuring Puppet Agent](#configuring-puppet-agent)
7. [Certificate Management](#certificate-management)
8. [Creating and Managing Manifests](#creating-and-managing-manifests)
9. [Testing the Configuration](#testing-the-configuration)
10. [Troubleshooting Common Issues](#troubleshooting-common-issues)
11. [Best Practices and Security](#best-practices-and-security)
12. [Advanced Configuration Options](#advanced-configuration-options)
13. [Conclusion](#conclusion)
Introduction to Puppet Architecture
Puppet operates on a client-server architecture where the Puppet master serves as the central authority that manages configuration data, and Puppet agents are installed on managed nodes that retrieve and apply configurations. The master-agent communication occurs over HTTPS using SSL certificates for security.
The Puppet master stores configuration data in the form of manifests (written in Puppet's declarative language), modules, and other resources. Agents periodically contact the master to retrieve their catalog (compiled configuration) and apply any necessary changes to maintain the desired state.
Prerequisites and Requirements
Before beginning the installation process, ensure your environment meets the following requirements:
System Requirements
Puppet Master:
- Linux distribution: Ubuntu 18.04+, CentOS 7+, or RHEL 7+
- Minimum RAM: 4GB (8GB recommended for production)
- CPU: 2 cores minimum (4+ cores recommended)
- Disk space: 20GB minimum
- Network connectivity to all managed nodes
Puppet Agent:
- Linux distribution: Ubuntu 16.04+, CentOS 6+, or RHEL 6+
- Minimum RAM: 512MB
- Network connectivity to Puppet master
Network Configuration
- Ensure port 8140 is open between master and agents
- Configure proper DNS resolution or hosts file entries
- Synchronize time across all systems using NTP
User Permissions
- Root or sudo access on all systems
- Ability to modify system configurations and install packages
Installing Puppet Master
Step 1: Update System Packages
Begin by updating your system packages to ensure you have the latest security patches and dependencies:
```bash
For Ubuntu/Debian systems
sudo apt update && sudo apt upgrade -y
For CentOS/RHEL systems
sudo yum update -y
```
Step 2: Configure Hostname and DNS
Set a proper hostname for your Puppet master. This is crucial for certificate generation and agent communication:
```bash
Set hostname (replace 'puppet-master' with your desired hostname)
sudo hostnamectl set-hostname puppet-master.example.com
Verify hostname
hostname -f
```
Add entries to `/etc/hosts` for proper name resolution:
```bash
sudo vim /etc/hosts
```
Add the following lines:
```
192.168.1.10 puppet-master.example.com puppet-master
192.168.1.11 puppet-agent1.example.com puppet-agent1
192.168.1.12 puppet-agent2.example.com puppet-agent2
```
Step 3: Install Puppet Repository
For Ubuntu/Debian:
```bash
Download and install the Puppet repository package
wget https://apt.puppetlabs.com/puppet7-release-focal.deb
sudo dpkg -i puppet7-release-focal.deb
sudo apt update
```
For CentOS/RHEL:
```bash
Install Puppet repository
sudo rpm -Uvh https://yum.puppetlabs.com/puppet7-release-el-7.noarch.rpm
sudo yum update
```
Step 4: Install Puppet Server
For Ubuntu/Debian:
```bash
sudo apt install puppetserver -y
```
For CentOS/RHEL:
```bash
sudo yum install puppetserver -y
```
Step 5: Configure Memory Allocation
Puppet Server runs on the JVM and requires memory configuration. Edit the startup configuration:
```bash
sudo vim /etc/default/puppetserver
```
Modify the `JAVA_ARGS` line based on your available memory:
```bash
For systems with 4GB RAM
JAVA_ARGS="-Xms2g -Xmx2g -Djruby.logger.class=com.puppetlabs.jruby_utils.jruby.Slf4jLogger"
For systems with 8GB+ RAM
JAVA_ARGS="-Xms4g -Xmx4g -Djruby.logger.class=com.puppetlabs.jruby_utils.jruby.Slf4jLogger"
```
Configuring Puppet Master
Step 1: Configure Main Configuration File
Edit the main Puppet configuration file:
```bash
sudo vim /etc/puppetlabs/puppet/puppet.conf
```
Add or modify the following configuration:
```ini
[main]
certname = puppet-master.example.com
server = puppet-master.example.com
environment = production
runinterval = 30m
[master]
vardir = /opt/puppetlabs/server/data/puppetserver
logdir = /var/log/puppetlabs/puppetserver
rundir = /var/run/puppetlabs/puppetserver
pidfile = /var/run/puppetlabs/puppetserver/puppetserver.pid
codedir = /etc/puppetlabs/code
```
Step 2: Start and Enable Puppet Server
```bash
Start Puppet Server
sudo systemctl start puppetserver
Enable automatic startup
sudo systemctl enable puppetserver
Check status
sudo systemctl status puppetserver
```
Step 3: Configure Firewall
Open the required port for Puppet communication:
For Ubuntu (UFW):
```bash
sudo ufw allow 8140/tcp
sudo ufw reload
```
For CentOS/RHEL (firewalld):
```bash
sudo firewall-cmd --permanent --add-port=8140/tcp
sudo firewall-cmd --reload
```
Installing Puppet Agent
Step 1: Prepare Agent Systems
On each system that will be managed by Puppet, perform the following steps:
Update system packages:
```bash
For Ubuntu/Debian systems
sudo apt update && sudo apt upgrade -y
For CentOS/RHEL systems
sudo yum update -y
```
Configure hostname:
```bash
sudo hostnamectl set-hostname puppet-agent1.example.com
```
Update `/etc/hosts` file:
```bash
sudo vim /etc/hosts
```
Add the master and agent entries:
```
192.168.1.10 puppet-master.example.com puppet-master
192.168.1.11 puppet-agent1.example.com puppet-agent1
```
Step 2: Install Puppet Repository
Follow the same repository installation steps as for the master, but install the agent package instead.
For Ubuntu/Debian:
```bash
wget https://apt.puppetlabs.com/puppet7-release-focal.deb
sudo dpkg -i puppet7-release-focal.deb
sudo apt update
sudo apt install puppet-agent -y
```
For CentOS/RHEL:
```bash
sudo rpm -Uvh https://yum.puppetlabs.com/puppet7-release-el-7.noarch.rpm
sudo yum update
sudo yum install puppet-agent -y
```
Configuring Puppet Agent
Step 1: Configure Agent Settings
Edit the Puppet agent configuration:
```bash
sudo vim /etc/puppetlabs/puppet/puppet.conf
```
Add the following configuration:
```ini
[main]
certname = puppet-agent1.example.com
server = puppet-master.example.com
environment = production
runinterval = 30m
[agent]
report = true
pluginsync = true
```
Step 2: Add Puppet to PATH
For easier command execution, add Puppet binaries to your PATH:
```bash
echo 'export PATH="/opt/puppetlabs/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc
```
Step 3: Start and Enable Puppet Agent
```bash
Start Puppet Agent
sudo systemctl start puppet
Enable automatic startup
sudo systemctl enable puppet
Check status
sudo systemctl status puppet
```
Certificate Management
Puppet uses SSL certificates for secure communication between master and agents. Understanding certificate management is crucial for maintaining a secure Puppet infrastructure.
Step 1: Generate Agent Certificate Request
On the agent, run the following command to generate a certificate request:
```bash
sudo /opt/puppetlabs/bin/puppet agent --test --server puppet-master.example.com
```
This command will:
- Generate a private key and certificate request
- Submit the request to the Puppet master
- Wait for certificate approval
Step 2: List and Sign Certificates on Master
On the Puppet master, list pending certificate requests:
```bash
sudo /opt/puppetlabs/bin/puppetserver ca list
```
Sign the agent certificate:
```bash
sudo /opt/puppetlabs/bin/puppetserver ca sign --certname puppet-agent1.example.com
```
To sign all pending certificates at once:
```bash
sudo /opt/puppetlabs/bin/puppetserver ca sign --all
```
Step 3: Verify Certificate Installation
On the agent, run another test to verify the certificate was properly installed:
```bash
sudo /opt/puppetlabs/bin/puppet agent --test
```
You should see output indicating successful catalog retrieval and application.
Creating and Managing Manifests
Manifests are Puppet's configuration files written in Puppet's declarative language. They define the desired state of your systems.
Step 1: Create a Simple Manifest
Create a basic manifest to test functionality:
```bash
sudo mkdir -p /etc/puppetlabs/code/environments/production/manifests
sudo vim /etc/puppetlabs/code/environments/production/manifests/site.pp
```
Add the following content:
```puppet
Default node configuration
node default {
# Ensure NTP is installed and running
package { 'ntp':
ensure => installed,
}
service { 'ntp':
ensure => running,
enable => true,
require => Package['ntp'],
}
# Create a test file
file { '/tmp/puppet-test.txt':
ensure => present,
content => "This file was created by Puppet on ${::fqdn}\n",
owner => 'root',
group => 'root',
mode => '0644',
}
}
Specific node configuration
node 'puppet-agent1.example.com' {
include apache
file { '/var/www/html/index.html':
ensure => present,
content => "
Welcome to ${::fqdn}
\n
Managed by Puppet
\n",
owner => 'www-data',
group => 'www-data',
mode => '0644',
require => Package['apache2'],
}
}
```
Step 2: Create a Module
Modules provide a way to organize and reuse Puppet code. Create a simple Apache module:
```bash
sudo mkdir -p /etc/puppetlabs/code/environments/production/modules/apache/{manifests,files,templates}
sudo vim /etc/puppetlabs/code/environments/production/modules/apache/manifests/init.pp
```
Add the following content:
```puppet
class apache {
package { 'apache2':
ensure => installed,
}
service { 'apache2':
ensure => running,
enable => true,
require => Package['apache2'],
}
file { '/etc/apache2/sites-available/000-default.conf':
ensure => present,
source => 'puppet:///modules/apache/000-default.conf',
notify => Service['apache2'],
require => Package['apache2'],
}
}
```
Testing the Configuration
Step 1: Test Agent Connection
On the agent, perform a test run:
```bash
sudo /opt/puppetlabs/bin/puppet agent --test --verbose
```
This command will:
- Contact the master
- Retrieve the catalog
- Apply configurations
- Report results
Step 2: Verify Applied Configurations
Check that the configurations were applied correctly:
```bash
Check if test file was created
ls -la /tmp/puppet-test.txt
Check NTP service status
systemctl status ntp
Check Apache installation (if configured)
systemctl status apache2
```
Step 3: Review Puppet Logs
Monitor Puppet logs for troubleshooting:
Master logs:
```bash
sudo tail -f /var/log/puppetlabs/puppetserver/puppetserver.log
```
Agent logs:
```bash
sudo tail -f /var/log/puppetlabs/puppet/puppet.log
```
Troubleshooting Common Issues
Certificate Issues
Problem: Agent cannot connect due to certificate errors.
Solution:
```bash
On agent, clean certificates
sudo /opt/puppetlabs/bin/puppet ssl clean
On master, clean agent certificate
sudo /opt/puppetlabs/bin/puppetserver ca clean --certname puppet-agent1.example.com
Regenerate certificate request
sudo /opt/puppetlabs/bin/puppet agent --test
```
Time Synchronization Issues
Problem: Certificate validation fails due to time skew.
Solution:
```bash
Install and configure NTP
sudo apt install ntp -y
sudo systemctl start ntp
sudo systemctl enable ntp
Manually sync time
sudo ntpdate -s time.nist.gov
```
DNS Resolution Problems
Problem: Agent cannot resolve master hostname.
Solution:
```bash
Test DNS resolution
nslookup puppet-master.example.com
Add to /etc/hosts if DNS is not available
echo "192.168.1.10 puppet-master.example.com puppet-master" >> /etc/hosts
```
Memory Issues
Problem: Puppet Server fails to start due to insufficient memory.
Solution:
```bash
Reduce memory allocation in /etc/default/puppetserver
JAVA_ARGS="-Xms1g -Xmx1g"
Restart service
sudo systemctl restart puppetserver
```
Port Connectivity Issues
Problem: Agent cannot connect to master on port 8140.
Solution:
```bash
Test port connectivity
telnet puppet-master.example.com 8140
Check firewall rules
sudo iptables -L
sudo firewall-cmd --list-all
Verify Puppet Server is listening
sudo netstat -tlnp | grep 8140
```
Best Practices and Security
Security Hardening
1.
Use Strong SSL Certificates:
```bash
# Generate custom CA certificate with longer key length
sudo /opt/puppetlabs/bin/puppetserver ca setup --config /etc/puppetlabs/puppet/puppet.conf
```
2.
Implement Certificate Autosigning Policies:
```bash
sudo vim /etc/puppetlabs/puppet/autosign.conf
```
Add specific patterns:
```
*.internal.company.com
puppet-agent*.example.com
```
3.
Configure Firewall Rules:
```bash
# Restrict access to Puppet master
sudo ufw allow from 192.168.1.0/24 to any port 8140
```
Performance Optimization
1.
Tune JVM Settings:
```bash
# Optimize garbage collection
JAVA_ARGS="-Xms4g -Xmx4g -XX:+UseG1GC -XX:MaxGCPauseMillis=200"
```
2.
Configure Agent Run Intervals:
```ini
[agent]
runinterval = 30m
splay = true
splaylimit = 10m
```
3.
Use Environment Caching:
```ini
[master]
environment_timeout = 5m
```
Monitoring and Maintenance
1.
Set Up Log Rotation:
```bash
sudo vim /etc/logrotate.d/puppetserver
```
2.
Monitor Certificate Expiration:
```bash
# Check certificate expiry
sudo /opt/puppetlabs/bin/puppet ssl show puppet-master.example.com
```
3.
Regular Backup Procedures:
```bash
# Backup Puppet configuration
sudo tar -czf puppet-backup-$(date +%Y%m%d).tar.gz /etc/puppetlabs/
```
Advanced Configuration Options
Hiera Configuration
Hiera provides a way to separate data from Puppet code. Configure Hiera for better data management:
```bash
sudo vim /etc/puppetlabs/puppet/hiera.yaml
```
```yaml
---
version: 5
defaults:
datadir: data
data_hash: yaml_data
hierarchy:
- name: "Per-node data"
path: "nodes/%{::trusted.certname}.yaml"
- name: "Per-OS defaults"
path: "os/%{facts.os.family}.yaml"
- name: "Common data"
path: "common.yaml"
```
Environment Configuration
Set up multiple environments for development, testing, and production:
```bash
sudo mkdir -p /etc/puppetlabs/code/environments/{development,testing,production}
Configure environment.conf for each environment
sudo vim /etc/puppetlabs/code/environments/production/environment.conf
```
```ini
modulepath = modules:$basemodulepath
environment_timeout = 5m
```
PuppetDB Integration
For advanced reporting and exported resources, integrate PuppetDB:
```bash
Install PuppetDB
sudo apt install puppetdb puppetdb-termini -y
Configure connection
sudo vim /etc/puppetlabs/puppet/puppetdb.conf
```
```ini
[main]
server_urls = https://puppet-master.example.com:8081
```
Conclusion
Successfully configuring Puppet master and agent on Linux provides a robust foundation for infrastructure automation and configuration management. This guide has covered the complete setup process, from initial installation through advanced configuration options.
Key takeaways from this implementation include:
-
Proper planning is essential for certificate management and network configuration
-
Security considerations should be implemented from the beginning, not as an afterthought
-
Testing and validation at each step ensures a reliable deployment
-
Monitoring and maintenance procedures are crucial for long-term success
Next Steps
After successfully implementing your Puppet infrastructure, consider these advanced topics:
1.
Scaling Your Infrastructure: Implement Puppet Server clustering for high availability
2.
Advanced Module Development: Create custom modules and contribute to the Puppet Forge
3.
Integration with CI/CD: Implement automated testing and deployment pipelines
4.
Compliance Management: Use Puppet for security compliance and audit reporting
5.
Monitoring and Alerting: Integrate with monitoring solutions for proactive management
Additional Resources
-
Puppet Documentation: Official documentation and guides
-
Puppet Forge: Community modules and resources
-
Puppet Training: Professional certification and training programs
-
Community Support: Forums and user groups for ongoing support
By following this comprehensive guide, you now have a fully functional Puppet master-agent setup that can scale to manage hundreds or thousands of nodes efficiently and securely. Regular maintenance, monitoring, and continuous improvement will ensure your Puppet infrastructure remains reliable and effective for your organization's needs.