Docs Grey arrow pointing right Puppet Enterprise Grey arrow pointing right Managing and deploying Puppet code Grey arrow pointing right Managing code with Code Manager Grey arrow pointing right Configure Code Manager Grey arrow pointing right

Configure Code Manager

Sections

To configure Code Manager, first enable Code Manager in Puppet Enterprise (PE), then set up authentication, and test the communication between the control repository and Code Manager.

Before you begin: Set up Code Manager.

Complete the following steps to enable and configure Code Manager.

  1. Upgrade from r10k to Code Manager
  2. Enable Code Manager
  3. Set up authentication for Code Manager
  4. Test the control repository
  5. Test Code Manager

Upgrade from r10k to Code Manager

To upgrade from r10k to Code Manager, you must disable the previous r10k installation.

Code Manager cannot correctly install or update code if other tools run r10k.

  1. Disable your previous r10k installation.
  2. Disable any tools that automatically run r10k. Most commonly, it is the zack-r10k module.
    Note: When you upgrade to Code Manager, you can no longer manually use r10k or the zack-r10k module.

After you disable r10k, you can configure Code Manager.

Enable Code Manager

Enable Code Manager to connect your primary server to your Git repository.

Before you begin
You must have an SSH key without a passphrase saved on your primary server at /etc/puppetlabs/puppetserver/ssh/id-control_repo.ed25519.
  1. In the console, in the PE Master node group, set parameters for the puppet_enterprise::profile::master class.
    • code_manager_auto_configure - Specify true to enable Code Manager.
    • r10k_remote - Enter a string that is a valid SSH URL for your Git control repository. For example: "git@<YOUR.GIT.SERVER.COM>:puppet/control.git".
      Note: Some Git providers, such as Bitbucket, may have additional requirements for enabling SSH access. See your provider's documentation for information.
    • r10k_private_key - Enter "/etc/puppetlabs/puppetserver/ssh/id-control_repo.ed25519". This is the path to the private key that permits the pe-puppet user access to your Git repositories.
  2. Run Puppet on your primary server and all compilers.
    Note: If you run Puppet for your primary server and all compilers at the same time, such as with Run Puppet in the console, the following errors might display in your compilers' logs:
    2015-11-20 08:14:38,308 ERROR [clojure-agent-send-off-pool-0]
[p.e.s.f.file-sync-client-core] File sync failure: Unable to get
latest-commits from server (https://primary.example.com:8140/file-sync/v1/latest-commits).
java.net.ConnectException: Connection refused
Copied!
    Ignore these errors while the primary is starting. These errors display when Puppet Server restarts as the compilers poll for new code. These errors should stop when the Puppet Server on the primary server finishes restarting.

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

Request an authentication token for the deployment user to enable secure deployment of your code.

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.

Generate the authentication token using the puppet-access command.

  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 specifying 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 username 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.

What to do next
Test the connection to the control repo.

Test the control repository

To make sure that Code Manager can connect to the control repository, test the connection to the repository.

From the command line, run puppet-code deploy --dry-run.
Results
  • If the control repository is set up properly, this command fetches and displays the number of environments in the control repository.
  • If an environment is not set up properly or causes an error, it does not appear in the returned list. Check the Puppet Server log for details about the errors.

Test Code Manager

Test Code Manager by deploying a single test environment.

Deploy a single test environment to test Code Manager:
From the command line, deploy one environment by running puppet-code deploy my_test_environment --wait

This deploys the test environment, and then returns deployment results with the SHA (a checksum for the content stored) for the control repository commit.

If the environment deploys and returns the deployment results, Code Manager is correctly configured.

If the deployment does not work, review the configuration steps, or refer to Troubleshooting for help.

Results

After Code Manager is fully enabled and configured, you can trigger Code Manager to deploy your environments.

There are several ways to trigger deployments, depending on your needs.

Code Manager settings

After Code Manager is configured, you can adjust its settings in the PE Master node group, in the puppet_enterprise::profile::master class.

These options are required for Code Manager to work, unless otherwise noted.

puppet_enterprise::profile::master::code_manager_auto_configure
Specifies whether to autoconfigure Code Manager and file sync.
Default: false
puppet_enterprise::profile::master::r10k_remote
The location, as a valid URL, for your Git control repository.
Example: 'git@<YOUR.GIT.SERVER.COM>:puppet/control.git'
puppet_enterprise::profile::master::r10k_private_key
The path to the file containing the private key used to access all Git repositories. Required when using the SSH protocol; optional in all other cases.
Example: '/etc/puppetlabs/puppetserver/ssh/id-control_repo.ed25519'
puppet_enterprise::profile::master::r10k_proxy
Optional proxy used by r10k when accessing the Forge. If empty, no proxy settings are used.
Example: 'http://proxy.example.com:3128'
puppet_enterprise::profile::master::r10k_trace
Configuration option that includes the r10k stacktrace in the error output of failed deployments when the value is true.
Default: false
puppet_enterprise::profile::master::versioned_deploys
Optional setting that specifies whether code is updated in versioned code directories instead of blocking requests and overwriting the live code directory.
Default: false
Note: For more information, see Deploying Code without blocking requests to Puppet Server
puppet_enterprise::master::environment_timeout
Specifies whether and how long environments are cached, which can significantly reduce CPU usage of your Puppet Server. You can specify any of these values:
  • 0 – no caching
  • unlimited – all environments are cached forever
  • a length of time for environments to be cached since their last use, for example 5m
Default when Code Manager is enabled: 5m
Default when Code Manager is not enabled: 0

To further customize your Code Manager configuration with Hiera, see Customize Code Manager configuration in Hiera.