Introduction

PuppetDB^1 allows you to retrieve data collected by Puppet such as facts and to use exported resources among other things. This data can then be used by other programs, such as the dashboard, or your own tools through an API. You can install the PuppetDB server on your PuppetMaster or on a separate server.^2

Today it is possible to use 2 backends to store this data:

• HSQLDB: in-memory database, with quite a few limitations including the 100 nodes maximum, but extremely fast (as it's loaded in RAM)
• PostgreSQL: classic database, with less performance (on disk), but with more flexibility and a greater possibility of extension over time (more than 100 Puppet nodes).

We will proceed with the PostgreSQL-based solution.

If you want more information, check out the different bottlenecks. In summary: if you have more than 100 clients, you'll need a PostgreSQL database, increase your JVM, and increase the number of CPUs/cores.

Installation

PuppetDB

Let's start by setting up what we need to install PuppetDB:

1
2

wget http://apt.puppetlabs.com/puppetlabs-release-stable.deb
dpkg -i puppetlabs-release-stable.deb

And then update:

1

aptitude update

Then you need to have puppet installed on the same machine where PuppetDB will be installed.

It doesn't matter whether it's the same machine as the master or not. For simplicity, we'll install it on the Puppet Master.

1

aptitude install puppetdb puppet

PostgreSQL

Since we plan to have more than 100 clients (or even if it's less, we don't want to change the configuration in the future), we'll install PostgreSQL:

1

aptitude install postgresql

Terminus

On the Puppet Master server, install this package:

1

aptitude install puppetdb-terminus

Configuration

PostgreSQL

We'll create a user and a database:

1
2
3
4

su - postgres
createuser -DRSP puppetdb
createdb -O puppetdb puppetdb
exit

PuppetDB

First, configure the database information:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28

[database]
# For the embedded DB: org.hsqldb.jdbcDriver
# For PostgreSQL: org.postgresql.Driver
# Defaults to embedded DB
classname = org.postgresql.Driver

# For the embedded DB: hsqldb
# For PostgreSQL: postgresql
# Defaults to embedded DB
subprotocol = postgresql

# For the embedded DB: file:/path/to/database;hsqldb.tx=mvcc;sql.syntax_pgs=true
# For PostgreSQL: //host:port/databaseName
# Defaults to embedded DB located in <vardir>/db
subname = //localhost:5432/puppetdb

# Connect as a specific user
username = puppetdb

# Use a specific password
password = puppetdb

# How often (in minutes) to compact the database
# gc-interval = 60

# Number of seconds before any SQL query is considered 'slow'; offending
# queries will not be interrupted, but will be logged at the WARN log level.
log-slow-statements = 10

Here we define the database connection properties, as well as the credentials we created earlier.

Now let's configure the number of threads:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

# See README.md for more thorough explanations of each section and
# option.

[global]
# Store mq/db data in a custom directory
vardir = /var/lib/puppetdb
# Use an external log4j config file
logging-config = /etc/puppetdb/conf.d/../log4j.properties

# Maximum number of results that a resource query may return
resource-query-limit = 20000

[command-processing]
# How many command-processing threads to use, defaults to (CPUs / 2)
threads = 4

Adjust the number of threads to your processor count divided by 2.

Then, we tackle the Jetty configuration:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

[jetty]
# Hostname to list for clear-text HTTP.  Default is localhost
host = 0.0.0.0
# Port to listen on for clear-text HTTP.
port = 8080

ssl-host = 0.0.0.0
ssl-port = 8081
keystore = /etc/puppetdb/ssl/keystore.jks
truststore = /etc/puppetdb/ssl/truststore.jks

key-password = CoaRwY6IL8KQd8H6SfZ7O9hHC
trust-password = CoaRwY6IL8KQd8H6SfZ7O9hHC

For the host, add the interface that will listen on ports 8080 and 8081. This notably allows the dashboard to connect to it.

Then restart PuppetDB:

1

/etc/init.d/puppetdb restart

After a few seconds/minutes, you should be able to connect to port 8081 (ssl) or 8080 (non-ssl) (http://:8080|https://:8081), where you'll have access to a nice interface:

Puppet Master

On the master, you need to modify its configuration:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20

[main]
logdir=/var/log/puppet
vardir=/var/lib/puppet
ssldir=/var/lib/puppet/ssl
rundir=/var/run/puppet
factpath=$vardir/lib/facter
templatedir=$confdir/templates
pluginsync = true

[master]
# These are needed when the puppetmaster is run by passenger
# and can safely be removed if webrick is used.
ssl_client_header = SSL_CLIENT_S_DN
ssl_client_verify_header = SSL_CLIENT_VERIFY
storeconfigs = true
storeconfigs_backend = puppetdb
report = true

[agent]
server=puppet-prd.deimos.fr

Then we'll set up a file for Puppet's configuration to tell it how to connect to PuppetDB:

1
2
3

[main]
server = puppet-prd.deimos.fr
port = 8081

And finally, a file to define the location of facts:

1
2
3
4
5

---
master:
  facts:
    terminus: puppetdb
    cache: yaml

That's it, your Puppet server now has a working PuppetDB backend! :-)

FAQ

I have OutOfMemoryError errors in my logs and PuppetDB responds slowly

To confirm that the problem is indeed due to insufficient memory, check that the file /var/log/puppetdb/puppetdb-oom.hprof exists, and make sure the content mentions OOM.

You'll need to increase the Java Heap size (Xmx value) of your PuppetDB which requires more RAM. Increase this value:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

###########################################
# Init settings for puppetdb
###########################################

# Location of your Java binary (version 6 or higher)
JAVA_BIN="/usr/bin/java"

# Modify this if you'd like to change the memory allocation, enable JMX, etc
JAVA_ARGS="-Xmx192m -XX:+HeapDumpOnOutOfMemoryError -XX:HeapDumpPath=/var/log/puppetdb/puppetdb-oom.hprof "

# These normally shouldn't need to be edited if using OS packages
USER="puppetdb"
INSTALL_DIR="/usr/share/puppetdb"
CONFIG="/etc/puppetdb/conf.d"

For an idea of the value to set (where n represents the number of nodes):

128M + (1M * n)

References