**Purpose**:
Puppet is another declarative configuration management tool that excels in system configuration and enforcement. Like Ansible, it's designed to maintain the desired state of a system's configuration but uses a client-server (master-agent) architecture by default.

!!! note "Assumptions"
    This document assumes you are deploying Puppet server onto Rocky Linux 9.4.  Any version of RHEL/CentOS/Alma/Rocky should behave similarily.

## Deployment Steps:
You will need to perform a few steps outlined in the [official Puppet documentation](https://www.puppet.com/docs/puppet/7/install_puppet.html) to get a Puppet server operational.  A summarized workflow is seen below:

### Install Puppet Repository
**Installation Scope**: Puppet Server / Managed Devices
``` sh
# Add Puppet Repository / Enable Puppet on YUM
sudo rpm -Uvh https://yum.puppet.com/puppet7-release-el-9.noarch.rpm
```

### Install Puppet Server
**Installation Scope**: Puppet Server
``` sh
# Install the Puppet Server
yum install -y puppetserver
systemctl enable --now puppetserver

# Validate Successful Deployment
exec bash
puppetserver -v

# Open Necessary Firewall Port for Agent Communication
sudo firewall-cmd --add-port=8140/tcp --permanent
sudo firewall-cmd --reload
```

### Install Puppet Agent
**Installation Scope**: Puppet Server / Managed Devices
``` sh
# Install Puppet Agent
sudo yum install -y puppet-agent

# Enable the Puppet Agent
sudo /opt/puppetlabs/bin/puppet resource service puppet ensure=running enable=true

# Configure Puppet Server to Connect To
puppet config set server lab-puppet-01.bunny-lab.io --section main

# Establish Secure Connection to Puppet Server
puppet ssl bootstrap

# ((On the Puppet Server))
# You will see an error stating: "Couldn't fetch certificate from CA server; you might still need to sign this agent's certificate (fedora.bunny-lab.io)."
# Run the following command (as root) on the Puppet Server to generate a certificate
puppetserver ca sign --certname fedora.bunny-lab.io
```

#### Validate Agent Functionality
At this point, you want to ensure that the device being managed by the agent is able to pull down configurations from the Puppet Server.  You will know if it worked by getting a message similar to `Notice: Applied catalog in X.XX seconds` after running the following command:
``` sh
puppet agent --test
```

## Install r10k
At this point, we need to configure Gitea as the storage repository for the Puppet "Environments" (e.g. `Production` and `Development`).  We can do this by leveraging a tool called "r10k" which pulls a Git repository and configures it as the environment in Puppet.  
``` sh
# Install r10k Pre-Requisites
sudo dnf install -y ruby ruby-devel gcc make

# Install r10k Gem (The Software)
# Note: If you encounter any issues with permissions, you can install the gem with "sudo gem install r10k --no-document".
sudo gem install r10k

# Verify the Installation (Run this as a non-root user)
r10k version
```

### Configure r10k
``` sh
# Create the r10k Configuration Directory
sudo mkdir -p /etc/puppetlabs/r10k

# Create the r10k Configuration File
sudo nano /etc/puppetlabs/r10k/r10k.yaml
```

```yaml title="/etc/puppetlabs/r10k/r10k.yaml"
---
# Cache directory for r10k
cachedir: '/var/cache/r10k'

# Sources define which repositories contain environments (Be sure to use the SSH URL, not the Git URL)
sources:
  puppet:
    remote: 'https://git.bunny-lab.io/GitOps/Puppet.git'
    basedir: '/etc/puppetlabs/code/environments'
```

``` sh
# Lockdown the Permissions of the Configuration File
chmod 600 /etc/puppetlabs/r10k/r10k.yaml

# Create r10k Cache Directory
sudo mkdir -p /var/cache/r10k
sudo chown -R puppet:puppet /var/cache/r10k
```

### Configure Gitea
At this point, we need to set up the branches and file/folder structure of the Puppet repository on Gitea.
!!! warning "Incomplete"
    This section needs a copy of all of the folder structure explained, as well as the branch structure, and example files for things like `site.pp`, `environment.conf`, and `init.pp`.  That will be added at a later time soon.

### Storing Credentials to Gitea
We need to be able to pull down the data from Gitea's Puppet repository under the root user so that r10k can automatically pull down any changes made to the Puppet environments (e.g. `Production` and `Development`).  Each Git branch represents a different Puppet environment.  We will use an application token to do this.

Navigate to "**Gitea > User (Top-Right) > Settings > Applications
- Token Name: `Puppet r10k`
- Permissions: `Repository > Read Only`
- Click the "**Generate Token**" button to finish.

!!! warning "Securely Store the Application Token"
    It is critical that you store the token somewhere safe like a password manager as you will need to reference it later and might need it in the future if you re-build the r10k environment.

Now we want to configure Gitea to store the credentials for later use by r10k:
``` sh
# Enable Stored Credentials (We will address security concerns further down...)
git config --global credential.helper store

# Clone the Git Repository Once to Store the Credentials (Use the Application Token as the password)
# Username: nicole.rappe
# Password: <Application Token Value>
git clone https://git.bunny-lab.io/GitOps/Puppet.git /tmp/PuppetTest

# Verify the Credentials are Stored
cat /root/.git-credentials

# Lockdown Permissions
chmod 600 /root/.git-credentials

# Cleanup After Ourselves
rm -rf /tmp/PuppetTest
```

Finally we validate that everything is working by pulling down the Puppet environments using r10k on the Puppet Server:
``` sh
sudo /usr/local/bin/r10k deploy environment -p
```

!!! success "Successful Puppet Environment Deployment
    If you got no errors about Puppetfile formatting or Gitea permissions errors, then you are good to move onto the next step.

## External Node Classifier (ENC)
An ENC allows you to define node-specific data, including the environment, on the Puppet Server. The agent requests its configuration, and the Puppet Server provides the environment and classes to apply.

**Advantages**:

- **Centralized Control**: Environments and classifications are managed from the server.
- **Security**: Agents cannot override their assigned environment.
- **Scalability**: Suitable for managing environments for hundreds or thousands of nodes.

### Create an ENC Script
``` sh
sudo mkdir -p /opt/puppetlabs/server/data/puppetserver/scripts/
```

```ruby title="/opt/puppetlabs/server/data/puppetserver/scripts/enc.rb"
#!/usr/bin/env ruby
# enc.rb

require 'yaml'

node_name = ARGV[0]

# Define environment assignments
node_environments = {
  'fedora.bunny-lab.io' => 'development',
  # Add more nodes and their environments as needed
}

environment = node_environments[node_name] || 'production'

# Define classes to include per node (optional)
node_classes = {
  'fedora.bunny-lab.io' => ['neofetch'],
  # Add more nodes and their classes as needed
}

classes = node_classes[node_name] || []

# Output the YAML document
output = {
  'environment' => environment,
  'classes' => classes
}

puts output.to_yaml
```

``` sh
# Ensure the File is Executable
sudo chmod +x /opt/puppetlabs/server/data/puppetserver/scripts/enc.rb
```

### Configure Puppet Server to Use the ENC
Edit the Puppet Server's `puppet.conf` and set the `node_terminus` and `external_nodes` parameters:
```ini title="/etc/puppetlabs/puppet/puppet.conf"
[master]
node_terminus = exec
external_nodes = /opt/puppetlabs/server/data/puppetserver/scripts/enc.rb
```

Restart the Puppet Service
``` sh
sudo systemctl restart puppetserver
```

## Pull Puppet Environments from Gitea
At this point, we can tell r10k to pull down the Puppet environments (e.g. `Production` and `Development`) that we made in the Gitea repository in previous steps.  Run the following command on the Puppet Server to pull down the environments.  This will download / configure any Puppet Forge modules as well as any hand-made modules such as Neofetch.
``` sh
sudo /usr/local/bin/r10k deploy environment production -p
sudo /usr/local/bin/r10k deploy environment development -p
```