Add code and set up Code Manager

Set up your control repo, create a Puppetfile, and configure Code Manager so you can start adding content to your Puppet Enterprise (PE) environments.

The control repo is where you store your code. Code in your control repo is usually bundled in modules.

The Puppetfile specifies detailed information about each environment's Puppet code and data, including where to get that code and data from, where to install it, and whether to update it.

Code Manager automates the management and deployment of your Puppet code. PE doesn't require Code Manager, but it is helpful for ensuring Puppet syncs code to your primary server and all your servers run new code at the same time.

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.

Configure Code Manager

Code Manager stages, commits, and synchronizes your code, automatically managing your environments and modules when you make changes.

Enable Code Manager

Set parameters in the console to enable Code Manager.

Before you begin
See Configure settings using the console for more details about setting parameters in the console.
  1. In the console, click Node groups, and set the following parameters in the puppet_enterprise::profile::master class in the PE Master node group.
    • Set code_manager_auto_configure to true.
    • Set r10k_remote to your control repository's location. Enter a string that is a valid URL for your Git control repository, such as git@<YOUR.GIT.SERVER.COM>:puppet/control.git.
    • For r10k_private_key, enter a string specifying the path to the SSH private key that permits the pe-puppet user to access your Git repositories. This file must be:
      • Located on the primary server.
      • Owned by the pe-puppet user.
      • Located in a directory that the pe-puppet user has permission to view. We recommend: /etc/puppetlabs/puppetserver/ssh/id-control_repo.ed25519
  2. Click Commit.
  3. On the command line, run puppet job run --nodes <NODE NAME> where <NODE NAME> is the name of your primary server.
    For example:
    puppet job run --nodes small-doubt.delivery.puppetlabs.net
    Note: r10k is a code management tool that allows you to manage your environment configurations — production, testing, and development — in a source control repository.
What to do next

Next, set up authentication for Code Manager.

Set up authentication for Code Manager

To securely deploy environments, Code Manager needs an authentication token for both authentication and authorization.

To generate a token for Code Manager:
  1. Assign a user to the deployment role.
  2. In the console, create a deployment user.
    Tip: Create a dedicated deployment user for Code Manager use.
  3. Add the deployment user to the Code Deployers role.
    Note: This role is automatically created on install, with default permissions for code deployment and token lifetime management.
  4. Create a password by clicking Generate Password.
  5. Request an authentication token for deployments

Request an authentication token for deployments

To enable secure deployment of your code, request an authentication token for the deployment user.

By default, authentication tokens have a one-hour lifetime. With the Override default expiry permission set, you can change the lifetime of the token to a duration better suited for a long-running, automated process.

  1. From the command line on the primary server, run puppet-access login --lifetime 180d. This command both requests the token and sets the token lifetime to 180 days.
    Tip: You can add flags to the request to specify additional settings such as the token file's location or the URL for your RBAC API. See Configuration file settings for puppet-access.
  2. Enter the user name and password of the deployment user when prompted.
Results
The generated token is stored in a file for later use. The default location for storing the token is ~/.puppetlabs/token. To view the token, run puppet-access show.

Deploy your code

Use the command line to trigger Code Manager after making changes to your Puppetfile.

When you make changes to your Puppetfile, like adding a new module or creating a repo, you must deploy your code before Code Manager can recognize or start managing the content.
SSH into your primary server and run puppet-code deploy --all --wait.
Results
You have deployed code to all environments. The --wait flag returns results after the deployment is finished. Use the command puppet-code deploy <ENVIRONMENT> to deploy code to only a specific environment. You can also deploy code using a webhook or custom scripts.