Skip to content
Tutorials Center
My learning

Topics

Lesson 31 of 38 ยท Testing and Code Management

R10k and the Control Repo

Manage Puppet code with Git: the control repository layout, Puppetfile modules, r10k deploy environment, branch-to-environment mapping, a promotion workflow and webhooks.

Writing good code is half the job; the other half is getting it onto the Puppet server safely, and being able to roll it back. Copying files by hand does not scale and leaves no history. The standard solution is to keep everything in Git and let a tool turn branches into Puppet environments. That tool is r10k (and its successor-style commercial tool, Code Manager, which is r10k running inside the server with a web API).

This lesson explains the control repository, the Puppetfile, how r10k deploys, and a branching workflow. These are command-line and Git workflows that cannot run on this site, so examples are read-only and the runnable blocks are stand-ins that model branch-to-environment mapping and Puppetfile parsing.

What is an environment?

An environment is an isolated directory tree of Puppet code, usually below /etc/puppetlabs/code/environments/. Each node is assigned to exactly one environment (by default production, set in puppet.conf or by an ENC). The server compiles that node's catalog from that environment's code and data. Environments let you test a change on a few machines before everybody gets it.

The control repo

The control repository is one Git repository that describes an entire environment:

TEXT
control-repo/
  Puppetfile                # which modules, from where, at which version
  environment.conf          # environment settings (module path, etc.)
  hiera.yaml                # environment-level Hiera config
  data/                     # Hiera data (common.yaml, nodes/, os/)
  manifests/site.pp         # node classification entry point
  site-modules/
    role/manifests/...
    profile/manifests/...

Your own modules (role, profile) live right in site-modules/ and are versioned with the repo. Everything else is declared in the Puppetfile and downloaded at deploy time, so the repository stays small.

The Puppetfile

Ruby
forge 'https://forgeapi.puppet.com'

moduledir 'modules'

# From the Forge, pinned to an exact version
mod 'puppetlabs-stdlib', '9.4.1'
mod 'puppetlabs-apache', '12.1.0'

# From Git, pinned to a tag
mod 'acme_ntp',
  git: 'https://git.example.com/puppet/acme_ntp.git',
  tag: 'v1.3.0'

# From Git, pinned to a full commit (safest)
mod 'acme_backup',
  git: 'https://git.example.com/puppet/acme_backup.git',
  ref: '3f2a9c1d4b6e8f00a1b2c3d4e5f60718293a4b5c'

Rules of thumb:

  • Pin every module to an exact version, tag or commit. A floating :latest means a deploy next Tuesday may behave differently from a deploy today with the same repository.
  • Update versions deliberately, in a pull request, and test them like any other change.
  • Resolve and install dependencies yourself: r10k does not resolve dependency trees. If your module needs stdlib, list it.

Deploying with r10k

Terminal
r10k deploy environment            # all environments, modules not touched if unchanged
r10k deploy environment production --puppetfile   # one environment, and its modules
r10k deploy environment -p         # same, update modules
r10k deploy display                # list deployed environments

For each branch of the control repository, r10k creates a directory with the branch name as the environment name, checks out the code, and installs the Puppetfile modules into modules/. Removed branches are removed from the server on the next deploy.

Configuration lives in /etc/puppetlabs/r10k/r10k.yaml:

YAML
cachedir: /var/cache/r10k
sources:
  main:
    remote: [email protected].com:puppet/control-repo.git
    basedir: /etc/puppetlabs/code/environments
flowchart LR
  G["Git: control repo"] -->|branch main| P["environment production"]
  G -->|branch feature_ntp| F["environment feature_ntp"]
  M["Puppetfile modules"] --> P
  M --> F
  P --> S["Puppet server"]
  F --> S

One branch, one environment, built from the control repo plus pinned modules.

A branching workflow

A simple and widely used flow:

  1. Create a branch, for example feature_ntp_servers. After the next r10k deploy a matching environment exists.
  2. Point one test node at it: puppet agent --test --noop --environment feature_ntp_servers.
  3. Open a pull request. CI runs lint, validate and tests.
  4. After review, merge into main. The production environment now contains the change.
  5. Roll back by reverting the commit. History is the safety net.

Environment names may only contain letters, digits and underscores, so branches like feature/ntp or fix-ntp need renaming (r10k can rewrite them with invalid_branches: correct), and - and / are best avoided in the first place.

Deploys are triggered by hand, by a CI job, or by a Git webhook that calls the server after each push. Many teams deploy with a pipeline step that runs r10k deploy environment <branch> -p on the server, or with Code Manager's puppet-code deploy command.

Stand-ins

The first stand-in turns a list of branch names into environment names and warns about invalid ones. The second parses a simplified Puppetfile and flags unpinned modules. Both are JavaScript stand-ins for ideas that r10k implements.

JS Stand-in: branch names to environment names

Press Run (or Ctrl + Enter) to see the console output here.

No output.

JS Stand-in: Puppetfile pin checker

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What does r10k create for each branch of the control repo?

    Branches map to environments; the branch name is the environment name.
  2. 2. Why pin modules in the Puppetfile to exact versions or commits?

    Floating versions make deployments non-reproducible.
  3. 3. Where do your own role and profile modules usually live?

    Site modules are versioned with the control repo; the Puppetfile covers external modules.
  4. 4. Does r10k resolve module dependencies automatically?

    r10k installs exactly what the Puppetfile lists.

Summary

  • Keep all code in a Git control repository; r10k turns branches into environments.
  • The Puppetfile lists external modules; pin each one to a version, tag or commit.
  • Own modules live in site-modules/; the Forge and other modules are installed into modules/.
  • Test a change by pointing one node at the feature environment, then merge to main.
  • Use valid environment names (letters, digits, underscores).

Next: Compile Masters and Scaling