How To Install Puppet on AlmaLinux 10

Puppet stands as one of the most powerful configuration management tools in modern infrastructure automation. For system administrators and DevOps engineers working with AlmaLinux 10, implementing Puppet provides unparalleled control over server configurations, application deployments, and infrastructure consistency across multiple environments.

AlmaLinux 10, being a community-driven, enterprise-grade Linux distribution, offers exceptional stability and security features that make it an ideal platform for Puppet deployment. The combination of AlmaLinux’s robust foundation and Puppet’s declarative configuration management creates a powerful infrastructure automation solution.

This comprehensive guide will walk you through every step of installing and configuring Puppet on AlmaLinux 10. You’ll learn how to set up both Puppet Server and Puppet Agent components, configure secure communications, create your first manifests, and implement best practices for production environments. Whether you’re managing a handful of servers or thousands of nodes, this tutorial provides the foundation for scalable infrastructure automation.

Understanding Puppet Architecture

Core Components

Puppet operates on a client-server architecture that revolutionizes how system administrators manage infrastructure. The Puppet Server acts as the central authority, storing configuration data and serving compiled catalogs to connected nodes. This master component runs on a dedicated server and handles certificate management, catalog compilation, and reporting functions.

The Puppet Agent runs on managed nodes, regularly communicating with the Puppet Server to retrieve configuration updates. Agents execute these configurations locally, ensuring system state matches desired specifications. Communication between server and agents occurs over SSL/TLS encrypted channels using port 8140, providing secure data transmission across networks.

Certificate-based authentication ensures only authorized agents can communicate with the server. Each agent generates a unique SSL certificate that requires server approval before establishing trusted connections. This security model prevents unauthorized access while enabling scalable infrastructure management.

Domain Specific Language (DSL)

Puppet uses a Ruby-like Domain Specific Language that simplifies infrastructure code creation. The DSL enables administrators to describe desired system states rather than procedural steps. This declarative approach means you specify what you want, and Puppet determines how to achieve it.

Configuration catalogs represent compiled versions of Puppet code tailored for specific nodes. The server compiles these catalogs by evaluating manifests, applying conditional logic, and resolving dependencies. Agents then apply these catalogs to achieve desired system configurations.

Infrastructure Requirements

Successful Puppet deployment requires careful consideration of server resources and network architecture. The Puppet Server demands adequate memory allocation, typically 2GB minimum for small environments and 4-8GB for production deployments. CPU requirements scale with the number of managed nodes and catalog complexity.

Network architecture must accommodate regular agent-server communications. Agents typically contact the server every 30 minutes by default, though this interval is configurable based on your environment’s needs. Proper DNS resolution and time synchronization across all nodes ensure reliable operations.

Prerequisites and System Preparation

System Requirements

Before installing Puppet on AlmaLinux 10, verify your system meets minimum hardware specifications. The Puppet Server requires at least 2GB RAM for basic operations, though 4GB provides better performance for production environments. CPU requirements depend on the number of managed nodes, with modern multi-core processors recommended for larger deployments.

Storage considerations include space for Puppet code, SSL certificates, logs, and reports. Allocate at least 20GB for the Puppet Server installation, with additional space for growing configurations and historical data. Network connectivity between server and agents is crucial, with reliable bandwidth for configuration transfers.

Initial Server Setup

Start by ensuring your AlmaLinux 10 system is fully updated and properly configured. Log in as root or a user with sudo privileges to perform installation tasks. Update the system packages to the latest versions:

sudo dnf update -y

Configure the system hostname with a fully qualified domain name (FQDN). This step is critical for Puppet’s SSL certificate generation and proper communication between components. Set the hostname using:

sudo hostnamectl set-hostname puppet.example.com

Verify time synchronization is properly configured, as SSL certificate validation depends on accurate system time. Install and configure chrony if not already present:

sudo dnf install chrony -y
sudo systemctl enable chronyd
sudo systemctl start chronyd

Hostname and DNS Configuration

Proper DNS configuration ensures reliable communication between Puppet components. Configure your DNS server to resolve the Puppet Server’s FQDN, or modify the /etc/hosts file on all nodes for smaller environments:

echo "192.168.1.100 puppet.example.com puppet" | sudo tee -a /etc/hosts

Replace the IP address with your Puppet Server’s actual address. This configuration enables agents to locate the server using the default puppet hostname or your custom FQDN.

Verify DNS resolution works correctly from all nodes that will run Puppet agents. Use nslookup or dig commands to confirm proper name resolution before proceeding with the installation.

Installing Puppet Repository

Adding Official Puppet Repository

AlmaLinux 10 requires the official Puppet repository to access current Puppet packages. Download and install the Puppet 8 repository package, which provides access to the latest stable versions:

sudo dnf install -y https://yum.puppet.com/puppet8-release-el-9.noarch.rpm

This command adds the Puppet repository configuration and imports the necessary GPG keys for package verification. The repository package automatically configures DNF to access Puppet’s official package sources.

Verify the repository installation by listing available Puppet packages:

sudo dnf list available | grep puppet

Repository Management

After adding the repository, update the package cache to ensure access to the latest package information:

sudo dnf makecache

The repository provides multiple Puppet components including puppetserver, puppet-agent, and various additional modules. Verify repository configuration by checking the enabled repositories:

sudo dnf repolist | grep puppet

This output confirms the Puppet repository is properly configured and accessible for package installation.

Installing Puppet Server

Package Installation

Install the Puppet Server package using DNF package manager. The installation process automatically handles dependencies and service configuration:

sudo dnf install puppetserver -y

This command installs the complete Puppet Server stack, including the Java runtime environment, server binaries, and default configurations. The installation creates the puppet user account and establishes necessary directory structures.

Verify the installation by checking the installed package version:

rpm -qa | grep puppetserver

Memory and JVM Configuration

Puppet Server runs on the Java Virtual Machine and requires proper memory allocation for optimal performance. The default configuration allocates 2GB heap space, which may need adjustment based on your environment size.

Edit the Puppet Server configuration file to modify JVM settings:

sudo nano /etc/sysconfig/puppetserver

Locate the JAVA_ARGS line and adjust memory allocation:

JAVA_ARGS="-Xms2g -Xmx2g -Djruby.logger.class=com.puppetlabs.jruby_utils.jruby.Slf4jLogger"

For larger environments managing hundreds of nodes, increase memory allocation to 4GB or more:

JAVA_ARGS="-Xms4g -Xmx4g -Djruby.logger.class=com.puppetlabs.jruby_utils.jruby.Slf4jLogger"

Service Management

Start the Puppet Server service and enable automatic startup at boot time:

sudo systemctl start puppetserver
sudo systemctl enable puppetserver

Verify the service is running correctly:

sudo systemctl status puppetserver

The output should show “active (running)” status. If the service fails to start, check the system logs for error messages:

sudo journalctl -u puppetserver -f

Initial Configuration

Configure basic Puppet Server settings by editing the main configuration file:

sudo nano /etc/puppetlabs/puppet/puppet.conf

Add essential configuration parameters:

[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

These settings establish proper directory locations for Puppet Server operations and ensure consistent file organization.

Installing Puppet Agent

Agent Package Installation

Install the Puppet Agent on nodes you want to manage. The agent package provides the client-side components necessary for communication with the Puppet Server:

sudo dnf install puppet-agent -y

The installation creates the /opt/puppetlabs/bin directory containing Puppet executables. Add this directory to your system PATH for convenient command access:

echo 'export PATH="/opt/puppetlabs/bin:$PATH"' | sudo tee -a /etc/profile
source /etc/profile

Agent Configuration

Configure the Puppet Agent to communicate with your Puppet Server. Edit the agent configuration file:

sudo nano /etc/puppetlabs/puppet/puppet.conf

Add server connection parameters:

[main]
certname = client.example.com
server = puppet.example.com
environment = production
runinterval = 1800

The certname should be unique for each agent, typically using the node’s FQDN. The server parameter specifies your Puppet Server’s hostname or IP address.

Service Management

Enable and start the Puppet Agent service:

sudo systemctl enable puppet
sudo systemctl start puppet

Verify the agent service is running:

sudo systemctl status puppet

Test the agent’s ability to communicate with the server:

sudo /opt/puppetlabs/bin/puppet agent --test

This command performs a test run, attempting to contact the server and apply any available configurations.

Firewall Configuration

Firewalld Setup

Configure the firewall to allow Puppet communications. AlmaLinux 10 uses firewalld by default, requiring specific rules for Puppet traffic:

sudo firewall-cmd --permanent --add-port=8140/tcp
sudo firewall-cmd --reload

Verify the firewall rule is active:

sudo firewall-cmd --list-ports

For environments using custom ports, adjust the firewall rules accordingly. The standard Puppet port 8140 handles all agent-server communications.

Security Considerations

Implement additional security measures by restricting access to specific IP ranges. Create a custom firewall zone for Puppet communications:

sudo firewall-cmd --permanent --new-zone=puppet
sudo firewall-cmd --permanent --zone=puppet --add-port=8140/tcp
sudo firewall-cmd --permanent --zone=puppet --add-source=192.168.1.0/24
sudo firewall-cmd --reload

This configuration limits Puppet access to the specified network range, enhancing security by preventing unauthorized connection attempts.

Agent Registration and Certificate Management

Certificate Signing Process

When an agent first contacts the Puppet Server, it generates and submits a certificate signing request (CSR). The server administrator must approve these requests before agents can receive configurations.

List pending certificate requests on the Puppet Server:

sudo /opt/puppetlabs/bin/puppetserver ca list

Sign individual certificates using the certificate name:

sudo /opt/puppetlabs/bin/puppetserver ca sign --certname client.example.com

For bulk certificate signing in trusted environments, sign all pending requests:

sudo /opt/puppetlabs/bin/puppetserver ca sign --all

Troubleshooting Certificate Issues

Certificate problems commonly occur due to hostname mismatches or clock synchronization issues. If an agent cannot connect, check certificate status:

sudo /opt/puppetlabs/bin/puppet agent --test --debug

Remove and regenerate problematic certificates:

sudo /opt/puppetlabs/bin/puppetserver ca clean --certname client.example.com

On the agent side, remove the existing certificate:

sudo rm -rf /etc/puppetlabs/puppet/ssl/

Restart the agent service to generate a new certificate request:

sudo systemctl restart puppet

Security Best Practices

Implement certificate lifecycle management policies including regular renewal and monitoring. Set up automated alerts for certificate expiration to prevent service interruptions.

Configure certificate autosigning for trusted networks while maintaining manual approval for external connections. Create autosign policies in /etc/puppetlabs/puppet/autosign.conf:

*.internal.example.com
192.168.1.0/24

This configuration automatically signs certificates from specified domains or IP ranges while requiring manual approval for others.

Creating Your First Puppet Manifest

Understanding Puppet Manifests

Puppet manifests contain the code that describes desired system configurations. These files use the .pp extension and reside in the Puppet code directory structure. Create your first manifest in the default environment:

sudo mkdir -p /etc/puppetlabs/code/environments/production/manifests
sudo nano /etc/puppetlabs/code/environments/production/manifests/site.pp

Basic Manifest Examples

Start with simple resource declarations that demonstrate Puppet’s capabilities. Create a manifest that installs a package and ensures a service is running:

node default {
  package { 'httpd':
    ensure => present,
  }
  
  service { 'httpd':
    ensure  => running,
    enable  => true,
    require => Package['httpd'],
  }
  
  file { '/var/www/html/index.html':
    ensure  => present,
    content => '<h1>Welcome to Puppet-managed Apache</h1>',
    require => Package['httpd'],
  }
}

This manifest installs Apache HTTP server, ensures it starts automatically, and creates a basic index page. The require parameters establish dependencies between resources.

Testing Manifests

Validate manifest syntax before applying configurations:

sudo /opt/puppetlabs/bin/puppet parser validate /etc/puppetlabs/code/environments/production/manifests/site.pp

Perform dry-run testing to preview changes without applying them:

sudo /opt/puppetlabs/bin/puppet agent --test --noop

The --noop flag shows what changes would occur without actually modifying the system. This testing approach prevents unintended modifications while validating configurations.

Advanced Configuration and Management

Environment Setup

Puppet environments enable separation of development, testing, and production configurations. Create additional environments by establishing directory structures:

sudo mkdir -p /etc/puppetlabs/code/environments/development/{manifests,modules}
sudo mkdir -p /etc/puppetlabs/code/environments/testing/{manifests,modules}

Configure environment-specific settings in environment.conf files:

sudo nano /etc/puppetlabs/code/environments/development/environment.conf

modulepath = modules:$basemodulepath
manifest = manifests/site.pp
environment_timeout = 0

Puppet Modules

Modules provide reusable code components for common system configurations. Install modules from Puppet Forge:

sudo /opt/puppetlabs/bin/puppet module install puppetlabs-apache

Create custom modules for organization-specific requirements:

sudo /opt/puppetlabs/bin/puppet module generate mycompany-webserver

This command creates a module skeleton with proper directory structure and template files for developing custom configurations.

Hiera Data Management

Hiera provides hierarchical data lookup capabilities for managing variables across different environments and node types. Configure Hiera by creating a configuration file:

sudo nano /etc/puppetlabs/code/hiera.yaml

version: 5
defaults:
  datadir: data
  data_hash: yaml_data
hierarchy:
  - name: "Per-node data"
    path: "nodes/%{::trusted.certname}.yaml"
  - name: "Per-environment data"
    path: "environments/%{::environment}.yaml"
  - name: "Common data"
    path: "common.yaml"

Monitoring and Maintenance

Log Management

Monitor Puppet operations through comprehensive logging systems. Server logs provide insights into catalog compilation, agent communications, and system performance:

sudo tail -f /var/log/puppetlabs/puppetserver/puppetserver.log

Agent logs on client nodes show configuration application results and any errors:

sudo tail -f /var/log/puppetlabs/puppet/puppet.log

Configure log rotation to manage disk space usage and maintain historical records for troubleshooting purposes.

Performance Monitoring

Monitor Puppet Server performance metrics including catalog compilation times, memory usage, and agent check-in frequency. Use built-in reporting capabilities to track configuration changes and compliance status.

Implement monitoring solutions like Prometheus or Nagios to alert on service failures, certificate expirations, and performance degradation.

Backup and Recovery

Establish regular backup procedures for Puppet configurations, SSL certificates, and Hiera data. Critical backup components include:

• /etc/puppetlabs/code/ – Puppet code and modules
• /etc/puppetlabs/puppet/ssl/ – SSL certificates
• /etc/puppetlabs/puppet/puppet.conf – Configuration files

Automate backups using cron jobs or backup management systems to ensure consistent protection of Puppet infrastructure.

Troubleshooting Common Issues

Installation Problems

Repository access issues may occur due to network connectivity or proxy configurations. Verify repository accessibility:

sudo dnf repolist all | grep puppet

Package dependency conflicts sometimes arise with existing system packages. Resolve conflicts by updating the entire system before installing Puppet components.

Service startup failures often result from insufficient memory allocation or port conflicts. Check system resources and verify port 8140 availability.

Communication Issues

SSL certificate problems frequently cause agent-server communication failures. Verify certificate validity and proper hostname configuration:

sudo /opt/puppetlabs/bin/puppet ssl show

Network connectivity issues may prevent agent communication. Test connectivity using telnet or nc commands:

telnet puppet.example.com 8140

Performance Issues

Memory configuration problems can cause server instability or slow response times. Monitor JVM memory usage and adjust heap sizes based on actual requirements.

Catalog compilation delays may indicate complex manifests or resource conflicts. Profile catalog compilation times and optimize code efficiency.

Security Best Practices

Access Control

Implement role-based access control for Puppet infrastructure management. Create dedicated service accounts with minimal required privileges rather than using root access.

Configure sudo rules for Puppet administrators to limit command execution scope while maintaining necessary functionality.

SSL/TLS Security

Regularly update SSL certificates before expiration to maintain secure communications. Implement certificate monitoring and automated renewal processes.

Use strong encryption ciphers and disable legacy protocols to maintain security compliance standards.

Audit and Compliance

Enable comprehensive logging for all Puppet operations to support security auditing and compliance requirements. Configure centralized log management systems for efficient monitoring and analysis.

Track configuration changes through version control integration and automated reporting systems.

Updating and Maintenance

System Updates

Maintain current Puppet versions by regularly updating packages:

sudo dnf update puppetserver puppet-agent

Test updates in development environments before applying to production systems to ensure compatibility and functionality.

Version Management

Plan major version upgrades carefully, testing compatibility with existing manifests and modules. Review changelog documentation for breaking changes and required migration steps.

Maintain staging environments that mirror production configurations for thorough testing of upgrades and changes.

Congratulations! You have successfully installed Puppet. Thanks for using this tutorial for installing Puppet on your AlmaLinux OS 10 system. For additional help or useful information, we recommend you check the official Puppet website.