r10k deploys Puppet environments and modules from a Puppetfile

A deployment tool that its own maintainer calls feature complete

r10k provides a general purpose toolset for deploying Puppet environments and modules. It implements the Puppetfile format and provides a native implementation of Puppet environments.

The status note at the top of the README is the most important thing in the document, and it is unusual to see it stated so plainly. R10k is supported and maintained by Puppet, but it is considered feature complete and there are currently no plans for any new development. The commitment is to keep it working within the context of Puppet Enterprise, with no other maintenance promises at this time.

That sentence should shape any adoption decision. r10k is not a project where you will request a feature and wait for a release. It is infrastructure that Puppet will keep working inside Puppet Enterprise, and everything else about it is stable by design.

The audience is Puppet users and the people who run Puppet for them: platform engineers, release engineers and anyone whose job involves getting the right module versions and the right environment code onto a set of machines. The problem it solves is the unglamorous one of turning a text file that lists dependencies into an installed set of modules and a deployed environment.

The repository is a Ruby gem rather than a standalone binary service. The layout has the lib directory with the code, bin for the executable, doc for the guides, spec and integration for the tests, locales for the translations, and the usual project files: a gemspec, a Gemfile, a Rakefile, CHANGELOG.mkd, CONTRIBUTING.mkd, CODEOWNERS, LICENSE and a r10k.yaml.example.

Two roles: a standalone Puppetfile and dynamic environments

The README describes r10k's two primary roles explicitly: installing Puppet modules using a standalone Puppetfile, and managing Git and SVN based dynamic environments.

A standalone Puppetfile is a dependency list for one environment. r10k reads it, resolves the modules it names and installs them. The Puppetfile format is the contract, and the documentation for it lives in doc/puppetfile.mkd, with a separate guide on updating your Puppetfile in doc/updating-your-puppetfile.mkd.

Dynamic environments are the other half. In that model, the environment itself is a Git or SVN repository and its branches become Puppet environments, which is the approach Puppet's own documentation on environments describes. The documentation set here is doc/dynamic-environments.mkd for the concept, doc/dynamic-environments/quickstart.mkd for a starting point, doc/dynamic-environments/workflow-guide.mkd for the workflow, and doc/common-patterns.mkd for the shapes this takes in practice. There is a general FAQ at doc/faq.mkd.

The split matters when you are evaluating. If your organisation keeps a single Puppetfile per environment and applies it with an ordinary version control workflow, you only need the first role and can ignore the environment machinery. If you want branch-per-environment, the second role is the point.

One detail to notice in the file listing is r10k.yaml.example, a configuration file shipped as an example. The example extension on its name is a reminder that the configuration surface is documented by example rather than in the README, so it is worth reading before you configure anything.

The requirements list is what decides whether r10k fits

The README lists the requirements, and they are specific enough to check before you plan an adoption.

On Ruby, r10k supports the versions greater than or equal to 2.6.0, and it is tested on Ruby 2.6.0 up to Ruby 3.1.0 with Jruby.

On Puppet, the version requirement depends on what you are doing. Installing modules from the Puppet Forge requires Puppet 7.0.0 or later. Puppet 5 and 6 may work, but are generally not recommended.

On version control, the requirement follows the source. Git is required for creating environments and modules from Git, and SVN is required for creating environments and modules from SVN. In practice that means a mixed estate needs both tools installed on whatever machine runs r10k.

The Puppet Forge requirement is the one that catches teams out. It applies only to Forge modules, so a deployment that pulls everything from Git could run against an older Puppet, but any environment that pulls a module from the Forge needs Puppet 7 or later on the machine that runs r10k. Since that machine is often a control node or a CI runner, and those are frequently the last places to be upgraded, this is a real scheduling constraint rather than a detail.

The Ruby requirement also implies something about the platform. A Ruby gem has to be installed somewhere, and r10k is usually run from a control node, a CI job or a developer's workstation, so the interpreter version on those machines is part of the deployment story.

Four installation paths, and the bundled Ruby trick

The installation section covers four cases, and the middle two exist for a reason worth understanding.

For general use, the README says to install r10k from Ruby gems:

    gem install r10k
    r10k help

Then there are two variants for Puppet products that bundle their own Ruby. Puppet Enterprise bundles a copy of Ruby, so if you do not want to use the system version of Ruby with r10k, the bundled PE gem command is used for installation:

    /opt/puppet/bin/gem install r10k
    r10k help

Puppet 4 bundles a copy of Ruby too, with its own path:

    /opt/puppetlabs/puppet/bin/gem install r10k
    /opt/puppetlabs/puppet/bin/r10k help

The point of the bundled interpreters is version isolation. Running r10k on the Ruby that ships with the Puppet installation avoids a mismatch between the gem's Ruby and the one on the path, which is the kind of thing that produces confusing errors on an otherwise working control node.

For development or specific needs, the README points at Bundler and a git checkout:

    git clone https://github.com/puppetlabs/r10k
    cd r10k
    bundle install
    bundle exec r10k help

There is also a distribution package: Arch Linux provides a system package for r10k, built against the system Ruby, which the README notes was Ruby 3.0.2 as of 2021-08-03, maintained by Tim Meusel.

Whichever route you take, the first command to run is r10k help, which is what the README shows in every case.

g10k is the alternative, and it differs in one specific way

The README itself names an alternative and is honest about the difference.

You might also consider g10k as a non-ruby based alternative. That is the whole comparison the README offers, and the axis is the implementation language.

Why that matters is concrete. r10k is a gem, so adopting it means having Ruby on the machine that runs it and managing a gem installation, which is why the installation section spends so much space on the different bundled Ruby paths. A non-Ruby tool removes that requirement entirely, and for organisations that have already decided Ruby is not on the menu for the machines that deploy infrastructure, that is the deciding factor rather than a preference.

The other difference follows from the same point. r10k is written in Ruby and integrates with a Puppet installation by sitting alongside it, which means it shares the assumptions of that installation: the Ruby version, the gem set, the Forge client behaviour. A tool written in another language is a separate binary with its own release cadence and its own notion of what it needs from the system.

The honest way to frame the choice is not which tool has more features, because the README makes no claim about g10k's capabilities and this repository's documentation says nothing about it. The choice is whether a Ruby gem in your deployment path is an asset, because it fits the Puppet ecosystem you already run, or a liability, because it adds an interpreter and a gem install to a machine you would rather keep minimal.

Documentation, translations and the release process

The documentation structure is the strongest part of this repository, and it is worth mapping before you read anything else.

Under doc there are the Puppetfile documentation and the guide on updating your Puppetfile, the dynamic environments documentation with its quickstart and workflow guide, the common patterns guide, and the FAQ. The README points at these as the topic-specific documentation for each of the two roles, which is a clear sign that the author considers the README a summary rather than the manual.

The repository also has a spec directory and an integration directory, so the behaviour is covered by unit and integration tests, and a Rakefile to run them.

Internationalisation is handled properly. R10k has all user-facing strings in error messages and log messages externalized, and the README gives the two links a contributor needs: one for writing translatable code and one describing the translation workflow, which explains the rake tasks that generate the .po files for each locale. The locales directory at the root holds those translations. For a tool whose output people read when something has gone wrong, externalized strings are a real operational property rather than a nicety.

The release process is documented too. To release a new version of the r10k gem, ensure the changelog is up to date and open a pull request updating the version file at lib/r10k/version.rb, and when that pull request is merged a new release of the gem is triggered. By default a patch release is triggered, and to release a new major or minor version you include the marker in the commit message. That is an automated, reviewable release path, which is a meaningful contrast with the fact that the repository itself lists no GitHub releases.

Where r10k is the wrong tool

The limitations are mostly consequences of the maintenance stance, and one of them is severe.

The severe one is that there is no new development planned. If your workflow needs a capability r10k does not have today, it will not appear, and the project is not looking for contributors to build it either. For a tool that sits in the deployment path of every environment, that is a strategic risk that a young project with an active roadmap would carry differently.

The second limitation is the Ruby dependency, which is the price of the Puppet Enterprise integration. Every machine that deploys environments needs an interpreter and a gem install, and if that is a place where you do not want Ruby, g10k is the alternative the README names.

The third is that the documentation is distributed. The README is short and links out to eight separate documents, which is fine for reading at a desk and awkward for searching, and it means the details that matter for a specific setup, such as caching behaviour, credentials handling and Git versus SVN specifics, are somewhere in doc rather than in one place.

The fourth is the Forge requirement. Puppet 7.0.0 or later is needed for Forge modules, and Puppet 5 and 6 may work but are generally not recommended, so an estate still on an old Puppet has to treat that as a blocker rather than a warning.

On licensing, the repository records a licence that GitHub cannot classify, so the LICENSE file is the text that governs rather than a badge. For a gem that Puppet publishes and supports, that is likely a permissive upstream grant with some additional terms, but it is worth reading before you redistribute it inside a product. The CODEOWNERS file at the root points at the current project owners, which is the place to look for who actually answers questions, alongside the Puppet Community Slack, the puppet-users mailing list and Puppet Ask.

Editorial conclusion

Puppet users who deploy modules from a Puppetfile or run dynamic environments from Git should adopt r10k, because it implements the Puppetfile format natively and the Puppetfile and dynamic environment documentation is complete enough to work from. It is the wrong choice if you want new features from the tool, since the README states that r10k is feature complete with no plans for new development, and it is the wrong choice for teams without Ruby in their stack, where the README points to g10k as a non-Ruby based alternative. Before adopting, check the Ruby and Puppet versions in the requirements, confirm whether you have Git or SVN available for the sources you use, and read the FAQ in doc/faq.mkd, since the tool's behaviour around caching and credentials is documented there rather than in the README.

Frequently asked questions

Official sources

1. Issues
2. puppetlabs/r10k on GitHub
3. README