Configure Code Manager

To configure Code Manager you must enable Code Manager in Puppet Enterprise (PE), set up authentication, and test the connection between the control repository and Code Manager.

To configure Code Manager:
  1. Create a control repo with a Puppetfile, as explained in Managing environments with a control repository.
  2. Upgrade from r10k to Code Manager, if applicable.
  3. Enable Code Manager.
  4. Set up authentication for Code Manager.
  5. Test the control repository.
  6. Test Code Manager.

Depending on your needs, you might need to configure additional Code Manager settings, enable Lockless code deploys, or Customize Code Manager configuration in Hiera.

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. Usually this 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 disabling r10k, configure Code Manager.

Enable Code Manager

Set parameters in the console to enable Code Manager and connect your primary server to your Git repository.

Before you begin
Set up an SSH key to permit the pe-puppet user to access your Git repositories. The SSH key must be:
  • Owned by the pe-puppet user.
  • Located on the primary server.
  • Located in a directory the pe-puppet user has permission to view, such as /etc/puppetlabs/puppetserver/ssh/id-control_repo.ed25519.
  1. In the console, click Node groups, locate the PE Master node group, and set these parameters for the puppet_enterprise::profile::master class:
    1. Set code_manager_auto_configure to true to enable Code Manager.
    2. For r10k_remote, enter a string that is a valid SSH URL for your Git control repository, such as git@<YOUR.GIT.SERVER.COM>:puppet/control.git.
      Important: Some Git providers have additional requirements for enabling SSH access. For example, BitBucket requires ssh:// at the beginning of the SSH URL (such as ssh://git@<YOUR.GIT.SERVER.COM>:puppet/control.git). See your provider's documentation for this information.
    3. 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, such as "/etc/puppetlabs/puppetserver/ssh/id-control_repo.ed25519".
      Important: If your PE installation includes disaster recovery, you must also set the puppet_enterprise::profile::master::r10k_private_key parameter in pe.conf. This ensures that the r10k private key is synced to your primary server replica.
    4. For the r10k_known_hosts parameter, enter an array of hashes, with each hash containing the following key-value pairs:
      • "name":"<HOSTNAME>": Specify the hostname of your control repository host.
      • "type":"<HOST_KEY_TYPE>": Specify the type of host key, such as rsa, dsa, ecds, or ed25519.
      • "key":"<HOST_PUBLIC_KEY>": Specify the SSH public key for your control repository host.
      Structure the parameter as shown in the following example:
      [{"name":"<HOSTNAME>","type":"<HOST_KEY_TYPE>","key":"<HOST_PUBLIC_KEY>"},{"name":"<HOSTNAME>","type":"<HOST_KEY_TYPE>","key":"<HOST_PUBLIC_KEY>"}]

      Optionally, each hash can accept values for "title", "ensure", and "host_aliases".

      The r10k_known_hosts parameter manages your known_hosts file to allow SSH host key verification, which is required when you use Code Manager or r10k.

    5. If you want to enable lockless code deploys, ensure that the versioned_deploys parameter is set to true.
      With the lockless code deploys feature enabled, code deployments are saved in versioned code directories, so that the live code directory is not overwritten. This process allows Puppet operations to continue during code deployments.
      If you do not require lockless code deploys, set the value to false.
      Tip: Enabling lockless code deploys will help to minimize disruptions associated with upgrading to future PE versions in which the feature will be enabled by default.
  2. Click Commit.
  3. Run Puppet on your primary server and all compilers.
    Potential errors:

    If you use Run Puppet in the console to trigger the Puppet run, the job, on the Jobs page, appears to fail due to underlying services being restarted. This error is not fatal and the Reports page shows the actual, successful result.

    Additionally, if you run Puppet on your primary server and all compilers at the same time, the compilers' logs might report these errors:
    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
    These errors occur when Puppet Server is restarting when the compilers poll for new code, and they usually stop when Puppet Server finishes restarting on the primary server. You can ignore these errors while the primary server starts.
What to do 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.

Before requesting an authentication token, you must assign a user to the deployment role.

  1. In the Puppet Enterprise (PE) console, create a deployment user.
    Tip: Create a dedicated deployment user for Code Manager to use.
  2. Add the deployment user to the Code Deployers role.
    When you install PE, this role is automatically created with default permissions for code deployment and token lifetime management.
  3. Click Generate Password to create a password for the deployment user.
What to do next
Request an authentication token for deployments.

Request an authentication token for deployments

To securely deploy your code, request an authentication token for the deployment user.

The default lifetime for authentication tokens is one hour. You can use the Override default expiry permission set to change the token lifetime to a duration better suited for a long-running, automated process.

Use the puppet-access command to generate the authentication token.

  1. From the command line on the primary server, run puppet-access login --lifetime 180d. This command requests the token and sets the token lifetime to 180 days.
    Tip: You can specify additional settings in this command, such as the token file's location or your RBAC API URL, as explained in Configuration file settings for puppet-access.
  2. Enter the deployment user's username and password when prompted.
Results

The generated token is stored in a file for later use. The default token storage location is ~/.puppetlabs/token. You can run puppet-access show to view the token.

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

Test the control repository

To make sure 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 a list of environments in the control repository as well as the total number of environments.

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.

From the command line, deploy one environment by running: puppet-code deploy my_test_environment --wait
Results

If Code Manager is configured correctly, this command deploys the test environment and returns deployment results with the SHA (a checksum for the content stored) for the control repository commit.

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

What to do next
After fully enabling and configuring Code Manager, you can trigger Code Manager to deploy your environments. You can:

Code Manager settings

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

Code Manager requires these options, unless otherwise noted:
puppet_enterprise::profile::master::code_manager_auto_configure
Specifies whether to autoconfigure Code Manager and file sync.
Default: false
Setting this to true also sets environment_timeout to unlimited.
puppet_enterprise::master::file_sync::chown_code_to_pe_puppet
By leaving this enabled, users help ensure they do not hit a class of errors that can occur by committing Puppet code files with the wrong permissions (or at least have those errors resolved on the next Puppet run). However, some users have codedirs large enough and I/O throughput restrictive enough that they require disabling these executive resources in the compiler catalogs.
Defaults: true
Valid values: true or false
puppet_enterprise::master::file_sync::copy_method
Specifies the implementation method used for copying versioned deploys to their location.
Default:shell-cp
Valid values are shell-cp and java. Using the previous default of java is slower but may resolve issues if you see compilation errors where files appear non-existent or partially written during first compilation, but upon inspection appear to exist in their totality.
puppet_enterprise::master::file_sync::versioned_sync_pool
Specifies the number of threads available for concurrent code deployments.
Default: 2
This may be set higher for faster deploy alls of environments. Deploying multiple environments at once may saturate I/O on the compiler syncing code with adverse effects. Watch metrics for I/O usage during code deploys and adjust the concurrency level as appropriate.
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, and 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.
Restriction: If r10k_proxy is specified, you must use an HTTP URL for the r10k_remote parameter and all Puppetfile module entries.
Example: "http://proxy.example.com:3128"
More information: Set proxies for Code Manager traffic
Additional and alternative Code Manager proxy configurations: Customize Code Manager configuration in Hiera (specifically Configuring proxies and Configuring Forge settings)
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
Setting for the lockless code deploys feature. Define the parameter to specify whether code is updated in versioned code directories instead of blocking requests and overwriting the live code directory.
Tip: Setting versioned_deploys to false will cause the Puppet Server process to lock the JRuby pool for each deployment. This will cause the compiler to become unavailable every time Puppet code is updated. This is the older method for code deployment, if you experience issues with code deployments trying this method may work for you. This setting should only be set to false in consultation with Puppet Support.
Default: true
More information: Lockless code deploys
puppet_enterprise::master::environment_timeout
Specifies if and how long environments are cached, which can significantly reduce your Puppet Server's CPU usage. You can specify these values:
  • No caching: 0
  • Retain environment data caches indefinitely: unlimited
  • Cache environments for a specified length of time after their last use: Any length of time, such as 5m
Default when Code Manager is enabled: 5m
Default when Code Manager is not enabled: 0
If code_manager_auto_configure is set to true: unlimited
More information: Change the environment_timeout setting
puppet_enterprise::master::file_sync::copy_method
Specifies the implementation method used for copying versioned deploys to their location.
Default: java
Valid values are java and shell-cp. Changing the method to shell-cp can help to improve file sync speed for lockless code deploys.
puppet_enterprise::master::file_sync::versioned_sync_pool
Specifies the number of threads available for concurrent code deployments.
Default: 1
Increasing the value allows multiple code environments to be deployed concurrently, enhancing the performance of lockless code deploys when puppet code deploy --all is run. Increasing the thread pool size can also improve file sync performance when different code environments are deployed in quick succession.

Customize Code Manager configuration in Hiera explains how you can use Hiera to further customize your Code Manager configuration.