Managing environments with a control repository

To manage your Puppet code and data with Code Manager or r10k, you need a Git version control repository. This control repository is where code management stores code and data to deploy your environments.

How the control repository works

Code management relies on version control to track, maintain, and deploy your Puppet code and data. The control repository (or control repo) is a Git repository that code management uses to manage environments in your infrastructure. When you update code and data in your control repo, code management updates your environments accordingly.

Code management creates and maintains environments based on the branches in your control repo. For example, if your control repo has a production branch, a development branch, and a testing branch, code management creates a production environment, a development environment, and a testing environment. Each environment has its own version of your Puppet code and data based on the contents of the corresponding branch.

Environments are created on the primary server at /etc/puppetlabs/code/environments. You can learn more About environments in the Puppet documentation.
CAUTION: When you enable code management, Puppet manages the environment directories and does not preserve existing environments. Existing environments with the same names as new ones are overwritten, and environments not represented in the control repo are erased. If you were already using environment directories, make sure you commit those files or code to the corresponding branches of your control repo (or back them up elsewhere) before you start configuring code management.
At minimum, a control repo includes:
  • A Git remote repository. This is where your control repo is stored on your version control host.
  • A default branch named production, rather than the usual Git default of master. You might have additional branches for other environments, such as development or testing.
  • A Puppetfile to manage your environment content.
  • An environment.conf file that modifies the $modulepath setting to allow environment-specific modules and settings.

There are two ways to create control repos. To ensure your control repo has the recommended structure, code examples, and configuration scripts, Create a control repository from the Puppet template. This template covers most customer situations. If you cannot access the internet or cannot download modules directly from the Forge because of your organization's security rules, Create an empty control repo and add the necessary files to it.

Restriction: For Windows systems, make sure your version control is configured to use CRLF line endings. Check your version control host's documentation for instructions on how to do this.
It is possible to have multiple control repos, and you can use separate repos to contain your module content or other data. If you have multiple repos, you need to:

Create a control repository from the Puppet template

To create a control repository (or control repo) that has the recommended structure, code examples, and configuration scripts, base your control repo on the Puppet control repo template. This template covers most customer situations.

The Puppet control repo template contains the necessary files to configure a functioning code management control repo plus helpful Puppet code examples, including:
  • Basic code examples for setting up roles and profiles.
  • A Puppetfile that references modules to manage content in your environments.
  • An example Hiera configuration file and hieradata directory.
  • A config_version script that tells you which version of code from your control repo was applied to your agents.
  • An environment.conf file that implements the config_version script and a site-modules directory for roles, profiles, and custom modules.

In situations where you can't access the internet, or where organizational security policies prevent downloading modules from the Forge, you can Create an empty control repo and add the necessary files to it.

To use the template, you must set up a private SSH key, copy the control repo template to your development workstation, set your own remote Git repository as the default source, and then push the template contents to that source.

Important: The following steps assume you are using GitHub Enterprise with SSH. For more information and instructions for other version control hosts, such as GitLab or BitBucket, go to the Puppet control-repo template README.
  1. To allow access to the control repo, generate a private SSH key without a password:
    1. To generate the key pair, run: 
      ssh-keygen -t ed25519 -P '' -f /etc/puppetlabs/puppetserver/ssh/id-control_repo.ed25519
    2. To allow the pe-puppet user to access the key, run: 
      puppet infrastructure configure
      Your private key is located at /etc/puppetlabs/puppetserver/ssh/id-control_repo.ed25519, and your public key is at /etc/puppetlabs/puppetserver/ssh/id-control_repo.ed25519.pub.
    3. Configure your Git host to use the SSH public key you generated. Usually, this involves creating a user or service account and assigning the SSH public key to it, but the exact process varies for each Git host. For instructions on adding SSH keys to your Git server, check your Git host's documentation (such as GitHub, BitBucket Server, or GitLab).
      Important: Code management needs read access to your control repository, as well as any module repositories referenced in the Puppetfile.
  2. In your Git user account or organization, create a repository named control-repo, and make sure a README is not automatically generated when you create the repo. Take note of the repo's SSH URL.
    Important: Do not use an existing repo. The template requires a new, empty repo named control-repo.
  3. If you haven't already installed Git, run yum install git.
  4. To clone the Puppet control-repo template, run: 
    git clone https://github.com/puppetlabs/control-repo.git
  5. Change to the control-repo directory: cd control-repo
  6. Remove the template repo as the origin: git remote remove origin
  7. Set your control repo as the origin: git remote add origin <SSH_URL_FOR_YOUR_CONTROL_REPO>
  8. Push the contents of the production branch of the cloned control repo to your remote control repo: git push origin production
Results

You now have a control repository based on the Puppet control-repo template. After configuring Code Manager, when you make changes to your control repo on your workstation and push the changes to the remote control repo on your Git host, Code Manager detects and deploys your infrastructure changes.

By using the control-repo template, you now also have a Puppetfile to which you can add and manage content, like module code.

Create an empty control repo

In situations where you can't access the internet, or where organizational security policies prevent downloading modules from the Forge, you can create an empty control repo and add the necessary files to it.

When you can't use the Puppet control repo template, you must create a new repo on your Git host, clone it to your workstation, make changes to the repo (such as adding a configuration file to allow code management tools to find modules in your module directories), and push your changes to the remote repo on your Git host.
  1. To allow access to the control repo, generate a private SSH key without a password:
    1. To generate the key pair, run: 
      ssh-keygen -t ed25519 -P '' -f /etc/puppetlabs/puppetserver/ssh/id-control_repo.ed25519
    2. To allow the pe-puppet user to access the key, run: 
      puppet infrastructure configure
      Your private key is located at /etc/puppetlabs/puppetserver/ssh/id-control_repo.ed25519, and your public key is at /etc/puppetlabs/puppetserver/ssh/id-control_repo.ed25519.pub.
    3. Configure your Git host to use the SSH public key you generated. Usually, this involves creating a user or service account and assigning the SSH public key to it, but the exact process varies for each Git host. For instructions on adding SSH keys to your Git server, check your Git host's documentation (such as GitHub, BitBucket Server, or GitLab).
      Important: Code management needs read access to your control repository, as well as any module repositories referenced in the Puppetfile.
  2. In your Git account, create a repository with the name you want your control repo to have (we recommend control-repo), and take note of the repo's SSH URL.
    Check your Git host's documentation for exact instructions, because this process varies for each host. For example, to create a new repo on GitHub:
    1. Click + at the top of the page, and choose New repository.
    2. Select the account Owner for the repository.
    3. Name the repository (for example, control-repo).
    4. Note the repository's SSH URL for later use.
    Tip: While you can use an existing repo as your control repo, we recommend starting with a new repo to avoid possible unexpected changes to existing files and directories once you enable code management.
  3. Clone the new repo to your workstation: git clone <REPOSITORY_URL>
  4. In the control repo's main directory, create a configuration file named environment.
    The environment.conf file allows code management tools to find modules in your site- and environment-specific module directories. You can learn more about this file and its contents in the Puppet environment.conf documentation.
  5. To set the module path, open the environment.conf file in a text editor, add the following line, and then save and close the file. 
    modulepath=site-modules:modules:$basemodulepath
  6. Add the new file to the index and commit your change by running git add environment.conf and then git commit -m "add environment.conf"
  7. Rename the master branch to production by running git branch -m master production
    Important: Puppet Enterprise requires the control repo's default branch to be production.
  8. Push your repository's production branch from your workstation to your Git host by running: git push -u origin production
Results
After configuring the Puppetfile and code management, when you make changes to your control repo on your workstation and push the changes to the remote control repo on your Git host, code management detects and deploys your infrastructure changes.
What to do next

After creating your control repo, you must create a Puppetfile to manage your environment content with code management. Then, you must configure either Code Manager (recommended) or r10k.

Add an environment

Create new environments by creating branches based on your control repo's production branch.

Before you begin
You must have:
Restriction: If you have multiple control repos, you can't repeat branch names unless you use a source prefix. Go to Configuring sources for more information.
  1. In your control repo, create a new branch based on the production branch: git branch <NEW_BRANCH_NAME>
  2. Check out the new branch: git checkout <NEW_BRANCH_NAME>
  3. Edit the Puppetfile to track the necessary modules and data for your new environment, and then save your changes.
  4. Commit your changes: git commit -m "prepare Puppetfile for new environment"
  5. Push your changes: git push origin <NEW_BRANCH_NAME>
  6. Deploy your environments as you normally would, either on the command line or with a webhook.
Results
Code management detects the new environment in your control repo and begins managing it, as explained in How the control repository works.

Delete an environment from code management

To delete an environment that is being managed by Code Manager or r10k, delete the corresponding branch from your control repository.

  1. On your control repo's production branch, delete the environment's corresponding remote branch by running git push origin --delete <BRANCH_TO_DELETE>
  2. Delete the local branch by running git branch -d <BRANCH_TO_DELETE>
  3. Deploy your environments as you normally would, either on the command line or with a webhook.
    Important: If you use webhooks to deploy environments, Code Manager deletes the environment from the primary server's live code directories the next time it deploys changes to any other environment. If you want to immediately delete the environment from the primary server's live code directories, deploy all environments manually by running puppet-code deploy --all --wait