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.
  • ProxyRequests Off
    ProxyPreserveHost On
        Order deny,allow
        Allow from all
            AuthType Basic
            AuthName "Gerrit Code Review"
            Require valid-user
            AuthUserFile "/etc/httpd/htpasswd_gerrit"
    ProxyPass /
    ProxyPassreverse /
  • Add users to the htpasswd file
  • Use the following command:

      htpasswd /etc/httpd/htpasswd_gerrit [username]

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

mkdir /root/gitrepos
cd /root/gitrepos
git clone --recursive
cd gitflow
make install

Setting up git bash completion

yum -y install bash-completion git-review
cd /etc/bash_completion.d/

Usage documentation

Setup R10K and environments


Install R10K

  # gem install r10k

Configure R10K


# The location to use for storing cached Git repos
:cachedir: '/var/cache/r10k'

# A list of git repositories to create
    remote: 'ssh://[user]@[gerrit-server]:29418/Puppet-Main'
    basedir: '/etc/puppet/environments'

Change Puppet settings to enable dynamic environments

  • Change the following lines in the [main] section:
    environmentpath = /etc/puppet/environments:/etc/puppet/dev_environments
    basemodulepath  = /usr/share/puppet/modules

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/

alias evim='eyaml edit --pkcs7-public-key /etc/puppet/secure/keys/public_key.pkcs7.pem --pkcs7-private-key /etc/puppet/secure/keys/private_key.pkcs7.pem '

Setup /etc/puppet/hiera.yaml config file

  - eyaml

  :datadir: /etc/puppet/hieradata/
  :extension: 'yaml'
  :pkcs7_private_key: /etc/puppet/secure/keys/private_key.pkcs7.pem
  :pkcs7_public_key:  /etc/puppet/secure/keys/public_key.pkcs7.pem

  - "hosts/%{clientcert}"        # Host-specific settings
  - "environment/%{environment}" # Environment specific settings
  - "osfamily/%{osfamily}"       # Settings based on OS
  - common                       # Common settings for all nodes.

Clone git repository and populate hieradata

  cd /etc/puppet
  git clone ssh://[user]@[gerritserver]:29418/Puppet-Hiera 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:

git branch develop
git branch testing
git branch production
git flow init -f  # Make sure to mark the 'testing' branch as 'production'
git checkout develop

You can download the modules from Puppetfile using the command

r10k puppetfile install

Add public modules to the Puppetfile

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


mod 'saz/ssh', '1.2.0'
mod 'saz/sudo', '2.2.0'
mod 'stahnma/puppetlabs_yum', '0.1.4'
mod 'puppetlabs/puppetdb', '3.0.0'
mod 'puppetlabs/inifile', '1.0.0'
mod 'puppetlabs/postgresql', '3.2.0'
mod 'puppetlabs/firewall', '0.4.2'
mod 'puppetlabs/stdlib', '4.1.0'
mod 'puppetlabs/concat', '1.0.0'
mod 'puppetlabs/ntp', '3.0.0-rc1'
mod 'metcalfc/rpmrepos', '0.0.1'
mod 'puppetlabs/dism', '0.1.0'
mod 'simondean/iis', '0.1.3'
mod 'saz-resolv_conf', '1.0.3'
mod 'saz-dnsmasq', '1.0.1'

mod "role",
  :git => "http://[gerritserver]/puppet-role"
  :ref => '0.1.0' #tag (or branch) to use

mod "companyname",
  :git => "http://[gerritserver]/puppet-[companyname]"
  :ref => '0.1.0' #tag (or branch) to use

Populate modules directory

echo modules/ > .gitignore #ignore modules subdir
mkdir modules
r10k puppetfile install

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!)

puppet agent -t --environment=[devname]

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

  r10k deploy environment develop -p