docs/Servers/Automation/Puppet/Deployment/Puppet Bolt.md

Purpose: Puppet Bolt can be leveraged in an Ansible-esque manner to connect to and enroll devices such as Windows Servers, Linux Servers, and various workstations. To this end, it could be used to run ad-hoc tasks or enroll devices into a centralized Puppet server. (e.g. LAB-PUPPET-01.bunny-lab.io)

!!! note "Assumptions" This deployment assumes you are deploying Puppet bolt onto the same server as Puppet. If you have not already, follow the Puppet Deployment documentation to do so before continuing with the Puppet Bolt deployment.

Initial Preparation

# Install Bolt Repository
sudo rpm -Uvh https://yum.puppet.com/puppet-tools-release-el-9.noarch.rpm
sudo yum install -y puppet-bolt

# Verify Installation
bolt --version

# Clone Puppet Bolt Repository into Bolt Directory
#sudo git clone https://git.bunny-lab.io/GitOps/Puppet-Bolt.git /etc/puppetlabs/bolt <-- Disabled for now
sudo mkdir -p /etc/puppetlabs/bolt
sudo chown -R $(whoami):$(whoami) /etc/puppetlabs/bolt
sudo chmod -R 644 /etc/puppetlabs/bolt
#sudo chmod -R u+rwx,g+rx,o+rx /etc/puppetlabs/bolt/modules/bolt <-- Disabled for now

# Initialize A New Bolt Project
cd /etc/puppetlabs/bolt
bolt project init bunny_lab

Configuring Inventory

At this point, you will want to create an inventory file that you can use for tracking devices. For now, this will have hard-coded credentials until a cleaner method is figured out.

# Inventory file for Puppet Bolt
groups:
  - name: linux_servers
    targets:
      - lab-auth-01.bunny-lab.io
      - lab-auth-02.bunny-lab.io
    config:
      transport: ssh
      ssh:
        host-key-check: false
        private-key: "/etc/puppetlabs/bolt/id_rsa_OpenSSH" # (1)
        user: nicole
        native-ssh: true

  - name: windows_servers
    config:
      transport: winrm
      winrm:
        realm: BUNNY-LAB.IO
        ssl: true
        user: "BUNNY-LAB\\nicole.rappe"
        password: DomainPassword # (2)
    groups:
      - name: domain_controllers
        targets:
          - lab-dc-01.bunny-lab.io
          - lab-dc-02.bunny-lab.io
      - name: dedicated_game_servers
        targets:
          - lab-games-01.bunny-lab.io
          - lab-games-02.bunny-lab.io
          - lab-games-03.bunny-lab.io
          - lab-games-04.bunny-lab.io
          - lab-games-05.bunny-lab.io
      - name: hyperv_hosts
        targets:
          - virt-node-01.bunny-lab.io
          - bunny-node-02.bunny-lab.io

1. Point the inventory file to the private key (if you use key-based authentication instead of password-based SSH authentication.)
2. Replace this with your actual domain admin / domain password.

Validate Bolt Inventory Works

If the inventory file is created correctly, you will see the hosts listed when you run the command below:

cd /etc/puppetlabs/bolt
bolt inventory show

??? example "Example Output of bolt inventory show" You should expect to see output similar to the following: ``` sh [root@lab-puppet-01 bolt-lab]# bolt inventory show Targets lab-auth-01.bunny-lab.io lab-auth-02.bunny-lab.io lab-dc-01.bunny-lab.io lab-dc-02.bunny-lab.io lab-games-01.bunny-lab.io lab-games-02.bunny-lab.io lab-games-03.bunny-lab.io lab-games-04.bunny-lab.io lab-games-05.bunny-lab.io virt-node-01.bunny-lab.io bunny-node-02.bunny-lab.io

Inventory source
/tmp/bolt-lab/inventory.yaml

Target count
11 total, 11 from inventory, 0 adhoc

Additional information
Use the '--targets', '--query', or '--rerun' option to view specific targets
Use the '--detail' option to view target configuration and data
```

Configuring Kerberos

If you work with Windows-based devices in a domain environment, you will need to set up Puppet so it can perform Kerberos authentication while interacting with Windows devices. This involves a little bit of setup, but nothing too crazy.

Install Krb5

We need to install the necessary software on the puppet server to allow Kerberos authentication to occur. === "Rocky, CentOS, RHEL, Fedora"

``` sh
sudo yum install krb5-workstation
```

=== "Debian, Ubuntu"

``` sh
sudo apt-get install krb5-user
```

=== "SUSE"

``` sh
sudo zypper install krb5-client
```

Prepare /etc/krb5.conf Configuration

We need to configure Kerberos to know how to reach the domain, this is achieved by editing /etc/krb5.conf to look similar to the following, with your own domain substituting the example values.

[libdefaults]
    default_realm = BUNNY-LAB.IO
    dns_lookup_realm = false
    dns_lookup_kdc = false
    ticket_lifetime = 7d
    forwardable = true

[realms]
    BUNNY-LAB.IO = {
        kdc = LAB-DC-01.bunny-lab.io # (1)
        kdc = LAB-DC-02.bunny-lab.io # (2)
        admin_server = LAB-DC-01.bunny-lab.io # (3)
    }

[domain_realm]
    .bunny-lab.io = BUNNY-LAB.IO
    bunny-lab.io = BUNNY-LAB.IO

1. Your primary domain controller
2. Your secondary domain controller (if applicable)
3. This is your Primary Domain Controller (PDC)

Initialize Kerberos Connection

Now we need to log into the domain using (preferrably) domain administrator credentials, such as the example below. You will be prompted to enter your domain password.

kinit nicole.rappe@BUNNY-LAB.IO
klist

??? example "Example Output of klist" You should expect to see output similar to the following. Finding a way to ensure the Kerberos tickets live longer is still under research, as 7 days is not exactly practical for long-term deployments. ``` sh [root@lab-puppet-01 bolt-lab]# klist Ticket cache: FILE:/tmp/krb5cc_0 Default principal: nicole.rappe@BUNNY-LAB.IO

Valid starting       Expires              Service principal
11/14/2024 21:57:03  11/15/2024 07:57:03  krbtgt/BUNNY-LAB.IO@BUNNY-LAB.IO
        renew until 11/21/2024 21:57:03
```

Prepare Windows Devices

Windows devices need to be prepared ahead-of-time in order for WinRM functionality to work as-expected. I have prepared a powershell script that you can run on each device that needs remote management functionality. You can port this script based on your needs, and deploy it via whatever methods you have available to you. (e.g. Ansible, Group Policies, existing RMM software, manually via remote desktop, etc).

You can find the WinRM Enablement Script in the Bunny Lab documentation.

Ad-Hoc Command Examples

At this point, you should finally be ready to connect to Windows and Linux devices and run commands on them ad-hoc. Puppet Bolt Modules and Plans will be discussed further down the road.

??? example "Example Output of bolt command run whoami -t domain_controllers --no-ssl-verify" You should expect to see output similar to the following. This is what you will see when leveraging WinRM via Kerberos on Windows devices. sh [root@lab-puppet-01 bolt-lab]# bolt command run whoami -t domain_controllers --no-ssl-verify CLI arguments ["ssl-verify"] might be overridden by Inventory: /tmp/bolt-lab/inventory.yaml [ID: cli_overrides] Started on lab-dc-01.bunny-lab.io... Started on lab-dc-02.bunny-lab.io... Finished on lab-dc-02.bunny-lab.io: bunny-lab\nicole.rappe Finished on lab-dc-01.bunny-lab.io: bunny-lab\nicole.rappe Successful on 2 targets: lab-dc-01.bunny-lab.io,lab-dc-02.bunny-lab.io Ran on 2 targets in 1.91 sec

??? example "Example Output of bolt command run whoami -t linux_servers" You should expect to see output similar to the following. This is what you will see when leveraging native SSH on Linux devices. sh [root@lab-puppet-01 bolt-lab]# bolt command run whoami -t linux_servers CLI arguments ["ssl-verify"] might be overridden by Inventory: /tmp/bolt-lab/inventory.yaml [ID: cli_overrides] Started on lab-auth-01.bunny-lab.io... Started on lab-auth-02.bunny-lab.io... Finished on lab-auth-02.bunny-lab.io: nicole Finished on lab-auth-01.bunny-lab.io: nicole Successful on 2 targets: lab-auth-01.bunny-lab.io,lab-auth-02.bunny-lab.io Ran on 2 targets in 0.68 sec