Unfinished Development Web Development, Infrastructure & Testing

Using R10K with Foreman on CentOS 6.5

Over the last couple of days I've been setting up The Foreman and R10K to play nicely with each other. It's actually a very simple process with the latest version of The Foreman (1.9 at the time of writing) as it comes with built in support for directory environments.

What is The Foreman?

The Foreman is the open source version of RedHat's Sattelite tool, which amongst a number of other things works as a ENC (external node classifier) for Puppet. It is the ENC functionality that we will be combining with R10K.

The Foreman is much, much more than just an ENC, most of which is beyond the scope of both this post and my knowledge.

What is R10K?

R10K is a number of tools, packaged in a Ruby gem, to help deploy Puppet environments and modules.

Environments are managed through Git branches and dependencies and modules can be installed via a Puppetfile.


The purpose of this post is not how to install Puppet or The Foreman and as such I am going to assume you already have them both installed and running.

Configure Puppet

Before we can use R10K to manage our environments we need to ensure Puppet is configured to support directory environments. This is very simple, ensure /etc/puppet/puppet.conf has the following:


  environmentpath = $confdir/environments

Install R10K

The Foreman installtion will install Ruby 1.9.3 using the SCL repositories. The latest versions of R10K have dropped support for Ruby 1.8, so we need to install R10K with Ruby 1.9.3 enabled.

The easist way for us to do this and it will also help when configuring directory permissions and running R10K is to create a new, unprivileged user that will always have Ruby 1.9.3 enabled.

useradd r10k
sudo vi /home/r10k/.bashrc

Ensure the R10K users .bashrc file contains the following:

# ensure Ruby 1.9.3 is enabled
source /opt/rh/ruby193/enable

# ensure the path contains the directory for the r10k binary
export PATH

Next we need to enable Ruby 1.9.3 for the installation of the R10K gem

scl enable ruby193 bash

Finally, we can install the R10K gem

sudo gem install r10k --no-rdoc --no-ri

Configure R10K

R10K looks for it's configuration in /etc/puppetlabs/r10k/r10k.yaml so we will need to create the directory and file.

sudo mkdir -p /etc/puppetlabs/r10k
sudo vi /etc/puppetlabs/r10k/r10k.yaml

Ensure the file has the following contents:

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

# A list of git repositories to create
  # This will clone the git repository and instantiate an environment per
  # branch in /etc/puppet/environments
    basedir: '/etc/puppet/environments'

Configure Hiera

Configure you Hiera install by editing /etc/hiera.yaml and ensuring it looks similar to:

  - yaml
  - "nodes/%{fqdn}"
  - common

   :datadir: /etc/puppet/environments/%{environment}/hiera

Create a symlink to the Hiera config in the Puppet directory

sudo ln -s /etc/hiera.yaml /etc/puppet/hiera.yaml

Directory permissions

The last part of the configuration is to ensure the R10K user has permission to write to the various directories it requires

sudo mkdir -p /var/cache/r10k
sudo chgrp r10k /var/cache/r10k
sudo chmod 775 /var/cache/r10k
sudo chgrp r10k /etc/puppet/environments
sudo chmod 775 /etc/puppet/environments

Using R10K

Once you have configured your code repository you can run R10K simply by changing the the R10K user.

sudo su - r10k
r10k deploy environment --puppetfile

Repository Permissions

Your R10K user will need permission to clone the various module repositories. If you are using private Git repositories then you will need to generate an SSH key for the R10K user.

All Done

That's it. You should now be able to happily create, modify and remove you Puppet environments through R10K and then import those changes into Foreman.