Table of contents

• Background
• Legal Disclaimer
• Version Information
• Installing r10k
• Configuring r10k
• Setting up the repository
• Deploying the modules
• Importing into Satellite 6
• Assigning the environment
• Pros and cons of working with r10k

Background

From time to time, we get questions from customers already using Puppet, on whether it is possible to incorporate an existing Puppet workflow based on r10k into Satellite 6.

These customers are often well accustomed to the r10k workflow and do not have any desire to change it, but still want to migrate to Satellite 6 as their Puppet platform, for support and integration reasons.

It turns out that by itself, getting r10k to work with Satellite 6 is not very complicated, but there are a few caveats. If you work around those - by following the documentation below - you'll have a Satellite 6 server with r10k in no time!

Disclaimer

Red Hat does not officially support r10k or this workflow, but considering that r10k just manages Puppet modules that are served out by the embedded Puppet master in Satellite 6, we do not anticipate problems with this configuration.

Version information

This was tested most recently on a Satellite 6.1.6 server, running on Red Hat Enterprise Linux 7.2 with r10k 2.1.1.

Installing

You can install r10k on Red Hat Enterprise Linux 7 with the following command.

gem install r10k -v 2.1.1

This will install r10k into /usr/local/share/gems/gems/r10k-2.1.1 with the r10k binary in the /usr/local/bin directory. The command will also install a series of dependencies. You can find out which gems are pulled in as dependencies by running gem dependency r10k¹.

Configuring

r10k expects a global configuration file in either /etc/r10k.yaml or /etc/puppetlabs/r10k/r10k.yaml. The first location is deprecated, but neither location works really well for a Satellite 6 Puppet installation in /etc/puppet. To keep all Puppet related configuration together, I have put my configuration file in /etc/puppet/r10k.yaml.

Create an /etc/puppet/r10k.yaml file containing the following, adapted to your specific requirements:

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

# A list of git repositories to create
sources:
  # This will clone the git repository and instantiate an environment per
  # branch in /etc/puppet/environments
  someorg:
    remote: 'git@github.com:someorg/somerepo.git'
    basedir: '/etc/puppet/r10k/environments'

postrun: ['/usr/local/bin/fix_perms.sh']

The /usr/local/bin/fix_perms.sh script resets ownership and SELinux context on the files and directories r10k checks out. Otherwise, r10k will leave ownership at the user running the command and user_tmp_t as SELinux label, which will prevent Puppet from reading them.

Thus we'll create an executable /usr/local/bin/fix_perms.sh script with the following context:

#!/bin/bash

chown -R apache: /etc/puppet/r10k/environments
restorecon -Fr /etc/puppet/r10k/environments

Next, we'll create the /etc/puppet/r10k/environments directory:

mkdir -p /etc/puppet/r10k/environments

The /etc/puppet/puppet.conf configuration file specifies where Satellite 6 and Puppet will search for Puppet environments, in the environmentpath setting. If you use the default environmentpath, all Satellite 6 managed environments will be purged when executing r10k. As this breaks Satellite 6, we will instead create a second location to create and search for environments, and update our /etc/puppet/puppet.conf to reflect that fact. Hence, in /etc/puppet/puppet.conf, change:

environmentpath  = /etc/puppet/environments

to

environmentpath  = /etc/puppet/environments:/etc/puppet/r10k/environments

Setting up the repository

We need to create a git repository that contains the actual information r10k uses to create environments. This information includes what Puppet modules to download and from where, as well as information on where to look for modules on the local system. Create the base git repository by running:

mkdir ~/r10krepo
cd !$
git init .

Two files need to be present in that directory: Puppetfile and environment.conf. The Puppetfile contains a list of modules to be pulled from either git or the Puppet Forge. Below is an example Puppetfile, that installs a couple of modules from the Puppet Forge, and one from a Github repository.

forge 'forge.puppetlabs.com'

# Forge Modules
mod 'puppetlabs/ntp', '4.0.0'
mod 'puppetlabs/stdlib', '4.6.0'
mod 'puppetlabs/postgresql', '4.3.0'
mod 'puppetlabs/mysql', '3.3.0'
mod 'puppetlabs/concat', '1.2.1'
mod 'apache',
  :git  => 'https://github.com/puppetlabs/puppetlabs-apache',
  :tag => '1.4.0'

The environment.conf configuration file could look like this example below. The $basemodulepath variable in the default configuration of Satellite 6's Puppet expands to the directory we install the OpenSCAP and Red Hat Insights Puppet modules in. Leave this as is, if you want to use those:

modulepath = modules:$basemodulepath

Now, we'll add the newly created Puppetfile and environment.conf files to the git repository. Run:

git checkout -b qa
git add .
git commit -v

In order to allow r10k to pull from this repository, we push² it to the central location you configured in /etc/puppet/r10k.yaml:

git remote add origin git@github.com:someorg/somerepo.git
git push origin qa

As you can see, we push the contents of the local qa branch to a remote qa branch. r10k uses the branches in the remote git repository to setup environments with the same name. In this example, the qa branch will result in a local Puppet environment with the same name.

Deploying the modules

We can now deploy all modules referenced in our Puppetfile into the qa Puppet environment, by running:

r10k deploy environment qa -p -v -c /etc/puppet/r10k.yaml

This command will first check out the git repository mentioned in the /etc/puppet/r10k.yaml file. It will read the Puppetfile that we stored in there in the qa branch, and deploy all modules mentioned in there into the qa environment. This environment will be created under /etc/puppet/r10k/environments. The /usr/local/bin/fix_perms.sh script we created earlier, will take care of ownership and SELinux labeling.

If you run the command above without qa, r10k will deploy all environments at once. r10k will iterate over all branches in your git repository and deploy an environment for each branch it finds.

Import into Satellite 6

The final step is to import the newly created environment into Satellite 6. The first phase of that is to check whether the environment already exists in Satellite 6. To figure that out, we run:

hammer environment list | awk ' /^[0-9]/ { print $3 }' | grep qa

If you don't see any output, you'll need to create the environment first. An environment needs to be created within the scope of an organization and location. Below, the 'qa' environment is created within the Primary_DC location for the ACME_Corp organization.

hammer environment create --name qa --location Primary_DC --organization ACME_Corp

The above command will make your qa environment show up in Satellite 6. Now you'll need to import the classes from this environment. You can do this through the web interface, but it's not easy to automate that (and relatively slow, as it iterates over all environments), so we'll do it through Hammer instead, and import our specific new qa environment only:

hammer proxy import-classes --id 1 --environment qa

The id above is the identifier of our Capsule server; in my case this was my Satellite server itself, hence the 1. You can find a list of your Capsule servers with hammer proxy list.

If you want to deploy r10k managed Puppet modules onto more than one Capsule, you will need to execute the above procedure on every one of them. You will also need to keep the modules on your Capsules in sync with each other by running the r10k deploy commands on all Capsules with little time in between.

Executing these steps on all Capsules in the infrastructure will create identical environments on all Capsules, that you can then easily assign through Satellite.

Assigning the environment

Now that the environment is known in Satellite, you can go edit a system or host group and assign the environment to it through the Puppet environment drop-down menu when editing the host or host group. Smart parameter assignment will work in the same way as with Puppet modules in content views.

As an example on how to do this with Hammer, you can assign the production environment to a host with id 40 by running:

hammer host update --id 40 --environment production

Or, similarly, to assign the production environment to a complete host group (with id 12), run:

hammer hostgroup update --id 12 --environment production

The pros and cons of working with r10k

The primary benefit of working with r10k is not having to change an existing workflow. Apart from that, using r10k, you can iterate rapidly without having to publish and promote content views, while still being able to easily use Satellite features like OpenSCAP, that rely on Puppet for client-side deployment.

On the downside is, however, that with r10k you will need to deploy your modules on each and every Capsule by hand. It also becomes a bit more complicated to define a 'build' for a specific group of hosts, since the build is now defined in two places: r10k for the configuration, Satellite for provisioning and software management.