The Open Source Puppet Configuration Manager

The Puppet configuration manager integrates CloudBolt with your Open Source Puppet Master, enabling the addition and removal of Puppet classes from servers and the display of a servers’s facts and latest Puppet run report.

This page describes how to create a Puppet configuration manager and configure your Puppet master.

Puppet Version Support Matrix

Functionality Pre - 4.4 4.4+
Bootstrap agent NO NO
Sign agent cert YES YES
Set classes during prov YES YES
Remove node from Puppet YES YES
Import classes YES YES
Sync servers YES YES
Node facts YES NO
Reports YES YES
Un/Install applications YES YES

Prerequisites

For integration to work correctly, your Puppet environment must meet these prerequisites:

  • Puppet master…
    • autosign CSRs (certificate signing requests) [1]
    • can be configured to use CloudBolt as its ENC (external node classifier) [2]
  • Agent…
    • run interval (splay) of 30-minutes or less
    • agents must be pre-installed and configured in the image

Note

A remote script can be created to auto-install the agent

[1]future versions of CloudBolt may not require this configuration
[2]Puppet does not support multiple ENCs. This prevents managing Puppet agents with more than one external tool (such as Forman, Puppet console, or CloudBolt) at a time.

Configuring CloudBolt

Create a Puppet configuration manager:

  1. Navigate to the Configuration Managers admin page.
  2. Click the Add a configuration manager button, then click Puppet Open Source in the resulting dialog.
  3. Fill out the form, then click the Create button to create your configuration manager and show its detail page.
  4. CloudBolt will submit a CSR to the Puppet master (just like your agents do!) so that CloudBolt and Puppet can communicate with each other. The CSR will be automatically signed. Click the Fetch signed certificate button to complete the process.

Configuring Puppet

Your Puppet master needs to know how to ask CloudBolt which classes should be installed on a given server and be set to tell CloudBolt when Puppet runs occur.

Edit puppet.conf

Locate puppet.conf to add/modify the following settings. The known paths for this file are /etc/puppet/ and /etc/puppetlabs/puppet/:

[master]
    autosign = true

    reports = http
    reporturl = http://{CLOUDBOLT-DOMAIN}/providers/puppet/{PUPPET_CONF_ID}/reports/

    node_terminus = exec
    external_nodes = /root/enc-script.sh

[agent]
    report = true

Replace {CLOUDBOLT-DOMAIN} with the domain used to access your CloudBolt web interface and replace {PUPPET_CONF_ID} with the ID of the Puppet configuration manager you created. The numeric ID is visible in the URL of your configuration manager’s detail page (e.g. the ID ‘1’ in /providers/1).

Note

The reports and reporturl properties make the Puppet master forward agent’s Puppet reports to CloudBolt. (Puppet docs on reporting) If you need to maintain a pre-existing http-type report destination, read how to configure multiple http report destinations.

To submit reports over HTTPS, install a CA on the Puppet master that validates the SSL cert that has been installed on your CloudBolt instance and then update the report_url to use the https protocol.

The node_terminus and external_nodes properties make the Puppet master ask CloudBolt (via an ENC) what classes belong in an agent’s catalog so that CloudBolt can be used to install/remove applications. (Puppet docs on ENCs)

Install the ENC script

Copy the following script into a file called /root/enc-script.sh:

#!/bin/sh

SITE_URL="https://{your-CloudBolt-domain}/"
PUPPET_CONF_ID=1
NODE_NAME=$1

curl -fk ${SITE_URL}providers/puppet/${PUPPET_CONF_ID}/enc/${NODE_NAME}/

Modify the script by setting the value of the SITE_URL variable to the root URL used to access your CloudBolt web UI (include the trailing slash!). If needed, set the value of PUPPET_CONF_ID to the ID of your Puppet configuration manager that you created in CloudBolt. The numeric ID is visible in the URL of your configuration manager’s detail page (e.g. /providers/1).

Finally, make it executable by the Puppet master process by running:

chmod +x /root
chmod +x /root/enc-script.sh

Edit auth.conf

Note

Determine if your Puppet Master is using the (HOCON) or (LEGACY) auth configuration.

Add auth lines to the top of the config file, before any clauses that enforce deny-all behavior

If you are unable to determine which auth type you are using, consult the administrator of your Puppet infrastrcuture.

LEGACY: Example

# let CloudBolt manage certificates
path /certificate_
auth any
method find, search, save, destroy
allow_ip {your-CloudBolt-IP-address}

# let CloudBolt discover node facts
path /facts
auth any
method find, search
allow_ip {your-CloudBolt-IP-address}

# let CloudBolt enumerate class names
path /resource_type
auth any
method find, search
allow_ip {your-CloudBolt-IP-address}

Replace {your-CloudBolt-IP-address} with the IP address of your CloudBolt server.

If adding these rules to a customized auth.conf, be mindful of Puppet’s ACL matching behavior and interleave or combine the above rules with existing rules so that the paths are ordered in most-to-least specific.

HOCON: Example

# Allow CloudBolt to manage certificates
{
    match-request: {
        path: "/puppet-ca/v1/certificate_status"
        type: path
    }
    allow: "/cloudbolt.*$/"
    sort-order: 100
    name: "cloudbolt cert status"
},
{
    match-request: {
        path: "/puppet-ca/v1/certificate_statuses/"
        type: path
        method: [get, post]
    }
    allow: "/cloudbolt.*$/"
    sort-order: 100
    name: "cloudbolt cert statuses"
},
# Allow CloudBolt to enumerate class names
{
    match-request: {
        path: "/puppet/v3/environment_classes"
        type: path
        method: get
    }
    allow: "/cloudbolt.*$/"
    sort-order: 100
    name: "cloudbolt classes"
},

Restart Puppet

To make the above configuration changes take effect, restart Puppet. Use one of the following examples based on your configuration / platform.

service puppetmaster restart
service puppetserver restart
service httpd restart

The above commands may not be correct if using a custom web-server configuration.

Multiple Report Destinations

Puppet’s built in http report processor only supports a single destination. If you want to have a service receive reports over HTTP (in addition to CloudBolt), you can use the third-party Puppet plugin, ianunruh-multi_http, which provides a multi_http report processor that can send reports to multiple destinations.