How Code Manager works

To automatically manage your environments and modules, Code Manager uses r10k and the file sync service to stage, commit, and sync your code.

Code Manager requires Managing environments with a control repository. You must create a control repository with branches for each environment that you want to create (such as production, development, or testing). Each branch must have a Puppetfile specifying exactly which modules to install in each environment. You can learn more About Environments in the Puppet documentation.

Code Manager creates directory environments based on the branches you've set up. Your control repository lives on a Git server, and this is where you push code that you want Code Manager to deploy.

There are three ways to trigger Code Manager to start a code deployment:
  • A webhook from your Git server automatically starts the code deployment when you push code to the control repo.
  • Continuous Delivery sends a deploy request to Code Manager.
  • You use the puppet-code command to manually trigger Code Manager from the command line or with a custom script.
Once triggered, Code Manager uses r10k to fetch code from the Git server and places it into the staging directory on the primary server (at /etc/puppetlabs/code-staging). Next, the file sync storage service on the primary server detects the change in the staging directory, and the file sync clients pause Puppet Server to avoid conflicts during synchronization. Finally, the file sync clients synchronize the new code to the live code directories on the primary server and compilers (usually at /etc/puppetlabs/code). The following diagram illustrates this code deployment process.
Diagram of the Code Manager code deployment process.

Understanding file sync and the staging directory

To sync your code across your primary server and compilers, and to make sure that code stays consistent, Code Manager relies on file sync and two different code directories: the staging directory and the live code directory.

Without Code Manager or file sync, Puppet code lives in the codedir, or live code directory, at /etc/puppetlabs/code.

With Code Manager and file sync, the file sync client service regularly checks for changes to staged code files in the staged code directory on the primary server (at /etc/puppetlabs/code-staging). If it detects a change, the file sync client service fetches the changes and syncs the files to the live codedir on each compiler and the primary server (at /etc/puppetlabs/code). The file sync client service uses HTTPS to poll for changes and JGit to fetch changes.

Because Code Manager moves new code from source control into the staging directory, and file sync moves it into the live code directory, you no longer write code in the codedir. If you manually edit the codedir, the next time Code Manager deploys code from source control, it overwrites your changes.
Important: Don't directly modify code in the staging directory or live code directory (codedir). Code Manager overwrites the staging directory with changes from the control repo, and file sync overwrites the codedir with changes from the staging directory. Any changes made to these directories manually are overwritten.

Environment isolation metadata and Code Manager

The live code and staging code directories contain metadata files generated by file sync, which provide environment isolation for your resource types.

The metadata files, which have a .pp extension, ensure that each environment uses the correct version of the resource type.
CAUTION: Do not delete or modify the metadata files. Do not use expressions from these files in regular manifests.

These files are generated when Code Manager deploys new code in your environments. If you are new to Code Manager, these files are generated when you first deploy your environments. If you already use Code Manager, the files are generated as you make and deploy changes to your existing environments.

You can learn more about these files and their role in Environment isolation in the Puppet documentation.

Moving from r10k to Code Manager

Moving from r10k to Code Manager can improve automation of your code management and deployments.

While we recommend using Code Manager whenever possible, reasons you might not want to upgrade from r10k to Code Manager include:

  • Code Manager does not allow you to manually deploy code with r10k. If you depend on the ability to deploy modules directly from r10k (with the r10k deploy module command), we recommend continuing to use r10k.
  • Code Manager must deploy all control repositories to the same directory. If you use r10k to deploy control repositories to different directories, we recommend continuing to use r10k.
  • Code Manager supports the shellgit provider, but only for HTTPS. It does not support system .SSH configuration or other shellgit options.
  • Code Manager does not support post-deploy scripts.

If you rely on any of the above configurations Code Manager does not support, or if you are using a custom script to deploy code, carefully assess whether or not Code Manager can support your goals.