Connecting standalone Puppet nodes to PuppetDB

This option is recommended. The Puppet team optimizes for this option when they're developing, and it is better tested.

When talking to PuppetDB, puppet apply can use the certificates issued by a Puppet Server's certificate authority. You can issue certificates to every node by setting up a Puppet Server server with dummy manifests, running puppet agent --test one time on every node, signing every certificate request on the Puppet Server, and running puppet agent --test again on every node.

Do the same on your PuppetDB node, then re-run the SSL setup script (which usually runs automatically during installation). PuppetDB will now trust connections from your Puppet nodes.

You will have to sign a certificate for every new node you add to your site.

Before you head down this path, please consider if signing certificates with Puppet Server will work for you. This option requires more work on your part to set up, and does not allow you to provide SSL to PuppetDB without a signed certificate, but it will allow you to provide SSL connections to PuppetDB using an existing CA. If you have an existing CA you would like to use, you can set up Puppet Server as an intermediate CA and then follow the instructions in Option A.

1. Edit the [jetty] section of the PuppetDB config files to remove all SSL-related settings.

2. Install a general-purpose web server (like Apache or NGINX) on the PuppetDB server.

3. Configure the web server to listen on port 8081 with SSL enabled and proxy all traffic to localhost:8080 (or whatever unencrypted hostname and port were set in jetty.ini). The cacert used will need to be signed.

If you use this option, you'll need to add these settings in addition to the general ones specified below. The cacert supplied to localcacert should be the one that signs the SSL proxy cert for PuppetDB.

Add this to your puppetdb.conf

[main]
verify_client_certificate = false

Add this to your puppet.conf

[main]
localcacert = /etc/path/to/cacert/ca.crt
certificate_revocation = false

If your Puppet Server isn't running Puppet from a supported package, you will need to install the plugins using file resources.

• Download the PuppetDB source code; unzip it, locate the puppet/lib/puppet directory, and put it in the files directory of the Puppet module you are using to enable PuppetDB integration.

• Identify the install location of Puppet on your nodes.

• Create a file resource in your manifest(s) for each of the plugin files, to move them into place on each node.

    # <modulepath>/puppetdb/manifests/terminus.pp
    class puppetdb::terminus {
      $puppetdir = "$rubysitedir/puppet"

      file { $puppetdir:
        ensure => directory,
        recurse => remote, # Copy these files without deleting the existing files
        source => "puppet:///modules/puppetdb/puppet",
        owner => root,
        group => root,
        mode => 0644,
      }
    }

You can specify the contents of puppetdb.conf directly in your manifests. It should contain the PuppetDB server's hostname and port:

[main]
server = puppetdb.example.com
port = 8081

PuppetDB's port for secure traffic defaults to 8081. Puppet requires use of PuppetDB's secure HTTPS port. You cannot use the unencrypted, plain HTTP port. If you are providing SSL via a proxy like nginx (Option B in Step 1) refer there for a few extra configuration options that you will need.

For availability reasons, there is a setting named soft_write_failure that will cause the PuppetDB-termini to fail in a soft manner if PuppetDB is not accessible for command submission. This means that users who are either not using storeconfigs or only exporting resources will still have their catalogs compile during a PuppetDB outage.

If no puppetdb.conf file exists, the following default values will be used:

server = puppetdb
port = 8081
soft_write_failure = false

You will need to create a template for puppet.conf based on your existing configuration. Then, modify the template by adding the following settings to the [main] block:

[main]
  storeconfigs = true
  storeconfigs_backend = puppetdb
  # Optional settings to submit reports to PuppetDB:
  report = true
  reports = puppetdb

Note: The thin_storeconfigs and async_storeconfigs settings should be absent or set to false.

Typically, you can specify the contents of routes.yaml directly in your manifests; if you are already using routes.yaml for some other purpose, you will need to manage it with a template based on your existing configuration. The path to this Puppet configuration file can be found with the command puppet config print route_file.

Ensure that the following keys are present:

---
apply:
  catalog:
    terminus: compiler
    cache: puppetdb
  resource:
    terminus: ral
    cache: puppetdb
  facts:
    terminus: facter
    cache: puppetdb_apply

This is necessary to keep Puppet from using stale facts and to keep the puppet resource subcommand from malfunctioning. Note that the puppetdb_apply terminus is specifically for puppet apply nodes, and differs from the configuration of Puppet Servers using PuppetDB.