Puppet

---
name: puppet
description: "Covers Puppet (8.x): Puppet DSL manifests, modules, Facter, Hiera, PuppetDB, Bolt, r10k, environments, and compliance automation. WHEN: \"Puppet\", \"manifest\", \"Puppet module\", \"Facter\", \"Hiera\", \"PuppetDB\", \"Bolt\", \"r10k\", \"puppet apply\", \"puppet agent\", \"Puppet Forge\", \"Puppet Enterprise\"."
license: MIT
---

# Puppet Expert

This skill covers Puppet 8.x, a declarative configuration management platform. Puppet uses its own DSL to declare the desired state of systems. Agents run on managed nodes and periodically enforce the declared state.

## Core Architecture

```
┌──────────────────┐
│  Puppet Server    │  Compiles catalogs from manifests
│  (puppetserver)   │
└────────┬─────────┘
         │ (HTTPS, every 30 min)
    ┌────┼────┐
    │    │    │
┌───▼┐ ┌▼──┐ ┌▼──┐
│Node│ │Node│ │Node│  puppet-agent requests catalog,
│ A  │ │ B │ │ C │  applies resources, reports back
└────┘ └───┘ └───┘
```

### Key Concepts

| Concept | Description |
|---|---|
| **Manifest** | `.pp` file containing Puppet DSL resource declarations |
| **Module** | Reusable unit containing manifests, templates, files, facts, types |
| **Class** | Named block of Puppet code that can be included/declared |
| **Resource** | Fundamental unit: package, file, service, user, exec |
| **Facter** | System fact collector (like Ohai in Chef) |
| **Hiera** | Hierarchical data lookup for separating data from code |
| **PuppetDB** | Database storing node facts, catalogs, reports |
| **Catalog** | Compiled graph of resources for a specific node |
| **Environment** | Isolated set of modules and manifests (production, staging) |
| **Bolt** | Agentless task runner for ad-hoc commands and plans |

### Manifest Example

```puppet
# modules/webserver/manifests/init.pp
class webserver (
  String  $server_name    = $facts['fqdn'],
  Integer $listen_port    = 80,
  Boolean $enable_ssl     = true,
  String  $document_root  = '/var/www/html',
) {
  package { 'nginx':
    ensure => installed,
  }

  file { '/etc/nginx/sites-available/default':
    ensure  => file,
    content => epp('webserver/vhost.epp', {
      server_name   => $server_name,
      listen_port   => $listen_port,
      document_root => $document_root,
    }),
    require => Package['nginx'],
    notify  => Service['nginx'],
  }

  file { $document_root:
    ensure => directory,
    owner  => 'www-data',
    group  => 'www-data',
    mode   => '0755',
  }

  service { 'nginx':
    ensure    => running,
    enable    => true,
    subscribe => File['/etc/nginx/sites-available/default'],
  }
}
```

### Hiera (Data Separation)

```yaml
# hiera.yaml (hierarchy configuration)
---
version: 5
defaults:
  datadir: data
  data_hash: yaml_data
hierarchy:
  - name: "Per-node"
    path: "nodes/%{facts.fqdn}.yaml"
  - name: "Per-environment"
    path: "environments/%{environment}.yaml"
  - name: "Per-OS"
    path: "os/%{facts.os.family}.yaml"
  - name: "Common"
    path: "common.yaml"
```

```yaml
# data/environments/production.yaml
webserver::listen_port: 443
webserver::enable_ssl: true
webserver::server_name: www.example.com

# data/common.yaml
webserver::document_root: /var/www/html
```

### Resource Types

```puppet
# Package management
package { 'nginx': ensure => '1.24.0' }

# File management
file { '/etc/motd':
  ensure  => file,
  content => "Managed by Puppet\n",
  owner   => 'root',
  mode    => '0644',
}

# Service management
service { 'nginx':
  ensure => running,
  enable => true,
}

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

# Exec (escape hatch — use sparingly)
exec { 'apt-update':
  command     => '/usr/bin/apt-get update',
  refreshonly => true,    # Only runs when notified
}
```

### Bolt (Agentless Tasks)

```bash
# Run a command on multiple nodes
bolt command run 'uptime' --targets webservers

# Run a task
bolt task run package action=install name=nginx --targets web1.example.com

# Run a plan
bolt plan run mymodule::deploy version=2.0 --targets webservers
```

```yaml
# plans/deploy.yaml
parameters:
  version:
    type: String
  targets:
    type: TargetSpec

steps:
  - command: "apt-get update"
    targets: $targets
  - task: package
    targets: $targets
    parameters:
      action: install
      name: myapp
      version: $version
  - command: "systemctl restart myapp"
    targets: $targets
```

### CLI Reference

```bash
# Agent operations
puppet agent --test              # Manual run (verbose)
puppet agent --noop              # Dry run
puppet agent --enable            # Enable scheduled runs
puppet agent --disable "reason"  # Disable with message

# Apply locally (masterless)
puppet apply manifest.pp
puppet apply --noop manifest.pp

# Module management
puppet module install puppetlabs-apache
puppet module list

# Facts
facter                           # All facts
facter os.family                 # Specific fact

# r10k (environment management)
r10k deploy environment production
r10k deploy environment --puppetfile
```

## Reference Files

- `references/architecture.md` — Puppet Server internals, catalog compilation, PuppetDB, r10k workflow, environment isolation
- `references/best-practices.md` — Module design, Hiera patterns, role/profile pattern, testing with PDK and Litmus
- `references/diagnostics.md` — Catalog compilation errors, resource failures, certificate issues, PuppetDB connectivity