To manage your Puppet code and data with either Code Manager or r10k, you need a control repository on Git. This control repository is where code management stores code and data to deploy your environments.
Code management uses Git repository 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/environments on 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.
Your control repo must have a production branch. The production branch is the default branch for your control repo, and you’ll base your other branches and environments on this production branch. If you are using multiple control repos, do not duplicate branch names.
Warning: Enabling code management means that Puppet manages the environment directories and existing environments are not preserved. Environments with the same name as the new one are overwritten. Environments not represented in the 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.
Code management relies on version control, so before you begin configuring or using either Code Manager or r10k, set up your control repository.
Maintain this control repo using a development machine that is separate from your Puppet master.
Set up an SSH key to authenticate your control repository.
Generate a private SSH key to allow access to the control repository.
This SSH key cannot require a password. Your development machine needs full read/write access to your repos, and the Puppet master needs read access.
See GitHub’s Generating SSH keys for instructions on generating an SSH key for your repo.
Place the private key in
This key must be in a location that the
pe-puppet user can access. Verify that the file itself has the correct permissions for the
pe-puppet user to use the key.
pe-puppet user is created during installation, so installation must be complete for this step. If you are preparing your control repo before installing, place the key in the directory after installation.
Create a repository in your Git account.
Steps for creating a repository vary, depending on what Git host you are using (GitHub, GitLab, Bitbucket, or another provider). See your Git host’s documentation for complete instructions.
Clone the repository to your development machine.
You can clone the empty repository you just created, or you can clone the Puppet
control repo template, which provides a minimal example of a control repo. In either case, on the command line, run:
git clone <repository URL>
If you cloned the Puppet
control repo template, set your own repository as the default remote and push the template contents to it:
git remote remove origin.
git remote add origin <url of your github repository>.
git push -u origin production.
If you cloned the control repo template, the default branch of your repo is already the production branch and you can skip to the next step of creating a Puppetfile in your production environment.
If you cloned your own empty repo, create a production branch and set it as your default branch:
git commit --allow-empty -m "initial empty commit". You cannot change or create branches in Git until you have committed at least one change.
git branch -m master production.
git push origin production
After you’ve set up your control repo, create a Puppetfile for managing your environment content with code management.
If you already have a Puppetfile, you can now configure code management. Code management configuration steps differ, depending on whether you’re using Code Manager (recommended) or r10k. For important information about the function and limitations of each of these tools, see the Code Manager and r10k pages. For configuration instructions, see the Code Manager configuration page or the r10k configuration page.
If you already have a Puppetfile in your production branch, create new environments by creating new branches based on your production branch.
Before you add environments to your control repo, you must have:
puppet-codecommand or a configured webhook).
On the production branch of your control repo directory, on the command line:
git branch <NAME-OF-NEW-BRANCH>.
git checkout <NAME-OF-NEW-BRANCH>.
git commit -m "a commit message summarizing your change".
git push origin <NAME-OF-NEW-BRANCH>.
If you have set up a Code Manager webhook or script trigger, Code Manager deploys the environments automatically. Alternately, deploy the environments on the command line with Code Manager or r10k commands.
Delete environments by deleting their branch from your control repo.
git push origin :<BRANCH-TO-DELETE>. For example,
git push origin :oldbranch.
git branch -d <BRANCH-TO-DELETE>.
Note: If you deploy environments with the Code Manager webhook, deleting a branch from your control repository does not immediately delete that environment from the Puppet master’s live code directories.
Code Manager will delete the environment when it next deploys changes to any other environment. Alternately, to delete the environment immediately, deploy all environments manually:
puppet-code deploy --all --wait