Written by Ger Apeldoorn on. Posted in Manageable Puppet Infrastructure, Sysadmin


This design has evolved in my Puppet consultancy. It enables better collaboration, manageability, flexibility etc. In this document, you’ll find how it is set up.

There is loads of documentation/talks available on the individual parts, but hardly any that forges all the parts together in a succesful setup.

  • Docs about maintainable module-structure is here: Todo
  • Detailed docs about the workflow can be found here: HERE

Wherever possible, I will refer to the docs of the tools used. No excuses, that’s just laziness. 🙂

Lets get started!

Setup Puppet Enterprise OR Foreman

Puppet Enterprise

  • Substitute all /etc/puppet directories for /etc/puppetlabs/puppet
  • When you install gems, use /opt/puppet/bin/gem to install them!


Make sure that you enable the PL repositories first! Click here
Foreman has some excellent documentation, use this to install it:

Setup of Gerrit Code Review (Git repository)

It is recommended to set this up on a seperate server. If you don’t, you will get a conflict on port 8080. (You can change the port in the config of Gerrit)

  • Main site
  • You can use htpasswd authentication for accessing the web-interface, add this to httpd.conf or your virtualhost.
  • Add users to the htpasswd file
  • Use the following command:

Create 5 repositories

We initially need 5 repositories:

  • Puppet-Main (Main puppet repo where Puppetfile (more info later) and site.pp reside)
  • Puppet-Hiera (This stores our Hiera data)
  • Puppet-Role (Roles)
  • Puppet-Profile (Profiles)
  • puppet-[companyname] (Company-specific (wrapper) modules)

You can easily create repositories (projects) with the web-interface.

Further setup:

  • Set Fast Forward only on all the projects preferences

git-flow (adapted for Gerrit)


Documentation: GitFlow

Setting up git bash completion

Usage documentation

Setup R10K and environments


Install R10K

Configure R10K


Change Puppet settings to enable dynamic environments

  • Change the following lines in the [main] section:

Setup Hiera & related

Install & init eyaml

The eyaml backend enables you to encrypt values in Hiera.

(Follow setup instructions)

Create alias to use eyaml

vim /etc/profile.d/

Setup /etc/puppet/hiera.yaml config file

Clone git repository and populate hieradata

Create unmanaged environments for development

I prefer to develop modules on the Puppet master, in a seperate environment. This way, I do not have to do a commit for each iteration. For this, I need an environment that is NOT managed with R10K. One can be created for each developer.

The location needs to be OUTSIDE the /etc/puppet/environments directory to prevent removal by R10K, but must be accessible to the Puppet Master.

You can use the script on this page to automate setting up new dev-environments.

Setup git-flow

In your main git directory and in the dir of every custom module:

You can download the modules from Puppetfile using the command

Add public modules to the Puppetfile

Note that dependencies need to be added too, use the unauthenticated git urls for your own repos!


Populate modules directory

Note that if you want to edit your own modules in-place, you should change the repository URL inside the modules/[modulename]/.git/config files to the authenticated SSH format.


You can do a testrun with: (If there is some code there!)

Deploying environments

R10K will create an environment for each branch it will find in the Puppet-Main git repo, using the Puppetfile found in that branch.

Documentation: R10K docs