BLOG POSTS

MangoHost Blog / Getting Started with Puppet Code, Manifests, and Modules

Getting Started with Puppet Code, Manifests, and Modules

Puppet is one of the most powerful configuration management tools in the DevOps ecosystem, allowing you to define and maintain your server infrastructure as code. Instead of manually configuring each server, Puppet lets you write declarative code that describes your desired system state, then automatically enforces that configuration across your infrastructure. This guide will walk you through the fundamentals of Puppet code structure, from basic manifests to reusable modules, complete with practical examples and real-world implementation strategies that you can start using immediately.

Understanding Puppet’s Architecture and Code Structure

Puppet operates on a declarative paradigm where you describe what you want rather than how to achieve it. The Puppet agent on each node compares the current system state against your desired configuration and makes necessary changes to bring the system into compliance.

The core components of Puppet code include:

Resources: The fundamental building blocks representing system components like files, packages, or services
Manifests: Files containing Puppet code with a .pp extension
Modules: Organized collections of manifests, templates, and files that manage specific applications or system components
Classes: Named groups of resources that can be applied to nodes

Here’s a basic resource example that ensures Apache is installed and running:

package { 'apache2':
  ensure => installed,
}

service { 'apache2':
  ensure  => running,
  enable  => true,
  require => Package['apache2'],
}

Creating Your First Puppet Manifest

Let’s start with a practical example by creating a manifest that sets up a basic web server environment. Create a file called webserver.pp:

# webserver.pp - Basic web server configuration
class webserver {
  # Install required packages
  package { ['apache2', 'php', 'mysql-server']:
    ensure => installed,
  }

  # Ensure Apache service is running
  service { 'apache2':
    ensure  => running,
    enable  => true,
    require => Package['apache2'],
  }

  # Create a custom index.html
  file { '/var/www/html/index.html':
    ensure  => file,
    content => 'Welcome to My Server',
    owner   => 'www-data',
    group   => 'www-data',
    mode    => '0644',
    require => Package['apache2'],
  }

  # Configure firewall
  exec { 'ufw-allow-http':
    command => '/usr/sbin/ufw allow 80',
    unless  => '/usr/sbin/ufw status | grep "80/tcp"',
  }
}

# Apply the class
include webserver

To apply this manifest locally, use:

sudo puppet apply webserver.pp

The require parameter creates dependencies between resources, ensuring packages are installed before services start or files are created.

Building Reusable Modules

Modules are the backbone of scalable Puppet infrastructure. They follow a specific directory structure that promotes reusability and organization. Here’s how to create a proper module structure:

nginx/
├── manifests/
│   ├── init.pp
│   ├── install.pp
│   ├── config.pp
│   └── service.pp
├── templates/
│   └── nginx.conf.erb
├── files/
│   └── default.conf
├── tests/
│   └── init.pp
└── metadata.json

Let’s build a complete nginx module. Start with nginx/manifests/init.pp:

# nginx/manifests/init.pp
class nginx (
  $package_name = 'nginx',
  $service_name = 'nginx',
  $config_dir   = '/etc/nginx',
  $enable_ssl   = false,
) {
  
  contain nginx::install
  contain nginx::config
  contain nginx::service

  Class['nginx::install']
  -> Class['nginx::config']
  ~> Class['nginx::service']
}

Create the installation class in nginx/manifests/install.pp:

# nginx/manifests/install.pp
class nginx::install {
  package { $nginx::package_name:
    ensure => installed,
  }
}

Add configuration management in nginx/manifests/config.pp:

# nginx/manifests/config.pp
class nginx::config {
  file { "${nginx::config_dir}/nginx.conf":
    ensure  => file,
    content => template('nginx/nginx.conf.erb'),
    owner   => 'root',
    group   => 'root',
    mode    => '0644',
    require => Class['nginx::install'],
    notify  => Class['nginx::service'],
  }

  file { "${nginx::config_dir}/sites-available/default":
    ensure => file,
    source => 'puppet:///modules/nginx/default.conf',
    owner  => 'root',
    group  => 'root',
    mode   => '0644',
  }
}

Complete the module with nginx/manifests/service.pp:

# nginx/manifests/service.pp
class nginx::service {
  service { $nginx::service_name:
    ensure     => running,
    enable     => true,
    hasrestart => true,
    hasstatus  => true,
    require    => Class['nginx::config'],
  }
}

Advanced Puppet Techniques and Best Practices

When working with larger infrastructures, you’ll need more sophisticated approaches. Here are essential techniques:

Using Hiera for Data Separation

Hiera allows you to separate configuration data from Puppet code. Create a hiera.yaml file:

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

Store environment-specific data in data/common.yaml:

---
nginx::package_name: 'nginx'
nginx::enable_ssl: true
mysql::root_password: 'secure_password_here'
app_servers:
  - 'web01.example.com'
  - 'web02.example.com'

Resource Ordering and Relationships

Puppet provides several ways to manage resource dependencies:

# Method 1: Using require
file { '/etc/myapp/config.conf':
  ensure  => file,
  content => template('myapp/config.conf.erb'),
  require => Package['myapp'],
}

# Method 2: Using before
package { 'myapp':
  ensure => installed,
  before => File['/etc/myapp/config.conf'],
}

# Method 3: Using chaining arrows
Package['myapp'] -> File['/etc/myapp/config.conf'] ~> Service['myapp']

# Method 4: Using notify for restart triggers
file { '/etc/nginx/nginx.conf':
  ensure  => file,
  content => template('nginx/nginx.conf.erb'),
  notify  => Service['nginx'],
}

Real-World Implementation Examples

Here’s a comprehensive example that demonstrates a multi-tier web application setup suitable for VPS or dedicated server environments:

# site.pp - Main site manifest
node 'web01.company.com' {
  include role::webserver
}

node 'db01.company.com' {
  include role::database
}

# roles/manifests/webserver.pp
class role::webserver {
  include profile::base
  include profile::nginx
  include profile::php
  include profile::monitoring
}

# profiles/manifests/base.pp
class profile::base {
  # Common packages
  package { ['htop', 'vim', 'curl', 'wget', 'unzip']:
    ensure => installed,
  }

  # NTP configuration
  class { 'ntp':
    servers => ['pool.ntp.org'],
  }

  # SSH hardening
  class { 'ssh':
    permit_root_login => 'no',
    password_authentication => 'no',
    port => 2222,
  }

  # User management
  user { 'deploy':
    ensure     => present,
    home       => '/home/deploy',
    shell      => '/bin/bash',
    managehome => true,
    groups     => ['sudo'],
  }

  # Sudo configuration
  file { '/etc/sudoers.d/deploy':
    ensure  => file,
    content => 'deploy ALL=(ALL) NOPASSWD:ALL',
    mode    => '0440',
  }
}

# profiles/manifests/php.pp
class profile::php {
  package { ['php8.1-fpm', 'php8.1-mysql', 'php8.1-curl', 'php8.1-json']:
    ensure => installed,
  }

  service { 'php8.1-fpm':
    ensure  => running,
    enable  => true,
    require => Package['php8.1-fpm'],
  }

  # PHP configuration optimizations
  file { '/etc/php/8.1/fpm/conf.d/99-custom.ini':
    ensure  => file,
    content => template('profile/php-custom.ini.erb'),
    notify  => Service['php8.1-fpm'],
  }
}

Comparison with Alternative Configuration Management Tools

Feature	Puppet	Ansible	Chef	SaltStack
Architecture	Pull-based (agent)	Push-based (agentless)	Pull-based (agent)	Both push/pull
Language	Ruby DSL	YAML	Ruby DSL	YAML/Python
Learning Curve	Steep	Gentle	Steep	Moderate
Scalability	Excellent (1000+ nodes)	Good (500+ nodes)	Excellent (1000+ nodes)	Excellent (1000+ nodes)
Community Modules	5000+	3000+	4000+	1000+

Troubleshooting Common Issues

Here are the most frequent problems you’ll encounter and their solutions:

Resource Dependency Cycles

When Puppet reports circular dependencies, use this debugging approach:

# Run with detailed dependency information
puppet apply --debug --trace manifest.pp

# Check for cycles in your dependency chain
puppet parser validate manifest.pp

Template and Variable Scope Issues

Always fully qualify variables in templates and manifests:

# Bad - may not work in all scopes
$package_name = 'nginx'

# Good - explicit scope
class nginx (
  String $package_name = 'nginx',
) {
  package { $nginx::package_name:
    ensure => installed,
  }
}

File Resource Conflicts

When multiple modules try to manage the same file, use resource defaults or defined types:

# Create a defined type for shared configuration
define config_file (
  $content,
  $path = $title,
) {
  file { $path:
    ensure  => file,
    content => $content,
    mode    => '0644',
  }
}

# Usage
config_file { '/etc/shared.conf':
  content => template('mymodule/shared.conf.erb'),
}

Performance Optimization and Monitoring

Monitor Puppet performance using these techniques:

# Enable reporting
puppet config set reports 'store,http'
puppet config set reporturl 'http://puppetdb:8080/reports'

# Performance profiling
puppet apply --evaltrace --summarize manifest.pp

# Resource timing analysis
puppet apply --profile manifest.pp

Typical performance benchmarks for Puppet runs:

Infrastructure Size	Average Run Time	Resources per Run	Memory Usage
Small (10-50 nodes)	30-90 seconds	50-200	100-300 MB
Medium (50-200 nodes)	60-180 seconds	200-500	300-800 MB
Large (200+ nodes)	120-300 seconds	500-1000+	800-2000 MB

Integration with External Tools and Services

Puppet integrates well with modern DevOps toolchains. Here’s how to connect it with popular services:

Git Integration for Code Management

# r10k Puppetfile for managing modules
forge "https://forgeapi.puppetlabs.com"

mod 'puppetlabs-stdlib', '8.5.0'
mod 'puppetlabs-apache', '9.1.2'
mod 'puppetlabs-mysql', '13.0.1'

# Custom modules from Git
mod 'company_nginx',
  :git => 'https://github.com/company/puppet-nginx.git',
  :tag => 'v1.2.3'

Docker and Container Integration

# Managing Docker with Puppet
class profile::docker {
  class { 'docker':
    use_upstream_package_source => false,
    package_name => 'docker.io',
  }

  docker::image { 'nginx':
    image_tag => 'latest',
  }

  docker::run { 'nginx-container':
    image   => 'nginx:latest',
    ports   => ['80:80', '443:443'],
    volumes => ['/etc/nginx:/etc/nginx:ro'],
    require => Docker::Image['nginx'],
  }
}

For comprehensive documentation and advanced features, check the official Puppet documentation and explore community modules on the Puppet Forge.

The modular approach demonstrated here scales effectively whether you’re managing a handful of development servers or thousands of production nodes across multiple data centers. Start small with basic manifests, then gradually adopt modules and advanced features as your infrastructure grows.

This article incorporates information and material from various online sources. We acknowledge and appreciate the work of all original authors, publishers, and websites. While every effort has been made to appropriately credit the source material, any unintentional oversight or omission does not constitute a copyright infringement. All trademarks, logos, and images mentioned are the property of their respective owners. If you believe that any content used in this article infringes upon your copyright, please contact us immediately for review and prompt action.

This article is intended for informational and educational purposes only and does not infringe on the rights of the copyright owners. If any copyrighted material has been used without proper credit or in violation of copyright laws, it is unintentional and we will rectify it promptly upon notification. Please note that the republishing, redistribution, or reproduction of part or all of the contents in any form is prohibited without express written permission from the author and website owner. For permissions or further inquiries, please contact us.