Skip to content

Puppet Bolt

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)

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.

/etc/puppetlabs/bolt/inventory.yaml
# 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 Output of bolt inventory show

You should expect to see output similar to the following: 

[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.

sudo yum install krb5-workstation

sudo apt-get install krb5-user

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 [email protected]
klist

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. 

[root@lab-puppet-01 bolt-lab]# klist
Ticket cache: FILE:/tmp/krb5cc_0
Default principal: [email protected]

Valid starting       Expires              Service principal
11/14/2024 21:57:03  11/15/2024 07:57:03  krbtgt/[email protected]
        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 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. 

[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 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. 

[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