Getting To Know r10k

A newer version is available; see the version menu above for details.

R10k does two simple but valuable things. First, it installs Puppet modules using an authoritative, standalone list (Puppetfile) that you create for it. Second, r10k creates and manages directory environments based on the branches in your Git repository.

r10k Basics

The primary purpose and benefit of r10k is that it provides a localized place in Puppet for you to manage the configuration of various environments (such as production, development, or testing), including what specific versions of modules are in each of your environments, based on code in branches of one or more Git repositories. R10k accomplishes this by seamlessly connecting the code in your Git repository’s branches with the Puppet environments it creates based on those branches. So the work you do in Git is reflected in your Puppet configuration!

In PE 3.8, r10k comes built-in, meaning you can find everything you need in the /etc/puppetlabs/r10k/ directory. You’ll interact with r10k in three primary ways: through the r10k.yaml file (for configuring your directory environments), through the Puppetfile (for managing your modules), and through the command line (for running r10k).


The yaml file is where you tell r10k where to find the Git repository you’d like to use to create your directory environments. R10k looks for your r10k.yaml file in /etc/puppetlabs/r10k/. You will also find r10k.yaml.example, which gives an example of the most common configuration options.


Puppetfiles are text files, written in a Ruby-based DSL, that specify a list of modules to install, what version of those modules to install, and where to fetch the modules from. R10k can use a Puppetfile to install a set of Puppet modules for local development, or you can use Puppetfiles with r10k environment deployments to install additional modules into a given environment.

Getting Started with r10k

Managing environments with r10k generally entails these steps:

We’ve also included a reference of r10k subcommands.

↑ Back to top