Setting up a control repository

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

Puppet Enterprise (PE) includes both Code Manager and r10k, so you don’t need to separately download or install them. Before you begin using these code management tools, however, you need to make sure they can communicate with Git.

Managing code with a control repository

Code management in PE uses your existing Git repository (repo) branches to create environments. Environments allow you to designate a node or node group to use a specific environment. For example, you could designate one node group to use the development environment and another to use the production environment. As you update the code in your control repo, code management tracks the state of that repo to keep each environment updated.

Each branch of a connected repository is copied into a directory named after the branch. These environments are created in /etc/puppetlabs/code/environmentson the Puppet master. For instance, if your repository is called “mycontrolrepo”, with branches named “production”, “test”, and “development”, your production branch becomes a production directory, the test branch becomes a test directory, and the development branch becomes a development directory.

Warning! Because these environment directories are managed by Puppet’s code management, existing environments are not preserved. Environments with the same name as the new one are overwritten. Environments not represented in the new control repo are erased. If you were using environments before, commit any necessary files or code to the appropriate new environment branch, or back them up somewhere before you start configuring code management.

Set up your Git repo

Code management relies on version control, so before you begin configuring or using code management, set up your control repository:

  1. Create a Git repository to act as a repo for your code. You’ll maintain this control repo using a development machine that is separate from your Puppet master.

  2. Create a ‘production’ branch in your repo, and then delete the ‘master’ branch. The production branch is the default branch for your control repo. (Note: Your control repo must have a production branch.) If you are using multiple control repos, do not duplicate branch names. The Puppet control repo template provides an example of a control repo.

You’ll base your other branches and environments on the production branch, but before you start creating those branches, you’ll create a base production Puppetfile as detailed in your next steps.

  1. Generate a private SSH key to allow access to the control repository. See Github’s Generating SSH keys for details on generating an SSH key for your repo. Your development machine needs full read/write access to your repos, and the Puppet master needs read access.

  2. After PE installation is complete, place this private key in a location that the pe-puppet user can access; we recommend /etc/puppetlabs/puppetserver/ssh/id-control_repo.rsa. Verify that the file itself has the correct permissions for the pe-puppet user, which is created during PE installation, to use that key.

Next steps

Next, you’ll set up Puppetfiles for managing your modules with code management. If you aren’t managing modules in your environments, you can move on to configuring Code Manager (recommended) or r10k.

↑ Back to top