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.
- Create a control repo with a Puppetfile, as explained in Managing environments with a control repository.
- Upgrade from r10k to Code Manager, if applicable.
- Enable Code Manager.
- Set up authentication for Code Manager.
- Test the control repository.
- 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.
- Disable your previous r10k installation.
- Disable any tools that automatically run r10k.
Usually this is the
zack-r10kmodule.Note: When you upgrade to Code Manager, you can no longer manually use r10k or the
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.
pe-puppetuser to access your Git repositories. The SSH key must be:
- Owned by the
- Located on the primary server.
- Located in a directory the
pe-puppetuser has permission to view, such as
In the console, click Node groups, locate the
PE Master node group, and set these parameters for
trueto enable Code Manager.
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.
r10k_private_key, enter a string specifying the path to the SSH private key that permits the
pe-puppetuser to access your Git repositories, such as
- Click Commit.
Run Puppet on your primary server and all
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: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.
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
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.
In the Puppet Enterprise (PE) console, create a deployment
Tip: Create a dedicated deployment user for Code Manager to use.
Add the deployment user to the Code Deployers
When you install PE, this role is automatically created with default permissions for code deployment and token lifetime management.
- Click Generate Password to create a password for the deployment user.
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
default expiry permission set to change the token lifetime to a
duration better suited for a long-running, automated process.
puppet-access command to generate the authentication token.
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.
- Enter the deployment user's username and password when prompted.
The generated token is stored in a file for later use. The default token storage location is
~/.puppetlabs/token. You can run
show to view the token.
Test the control repository
To make sure Code Manager can connect to the control repository, test the connection to the repository.
puppet-code deploy --dry-run
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.
puppet-code deploy my_test_environment --wait
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.
Code Manager settings
After configuring Code Manager, you can adjust its settings
in the PE Master node group in the
- Specifies whether to autoconfigure Code Manager and file sync.
- Setting this to
- The location, as a valid URL, for your Git control repository.
- 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.
- Optional proxy used by r10k when
accessing the Forge. If empty, no proxy
settings are used.Restriction: If
r10k_proxyis specified, you must use an HTTP URL for the
r10k_remoteparameter and all Puppetfile module entries.
- 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)
- Configuration option that includes the r10k stacktrace in the error output of failed deployments when the value
- Optional setting that specifies whether code is updated in versioned code directories instead of blocking requests and overwriting the live code directory.
- More information: Lockless code deploys
- 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:
- Retain environment data caches indefinitely:
- Cache environments for a specified length of time after their
last use: Any length of time, such as
- No caching:
- Default when Code Manager is enabled:
- Default when Code Manager is not enabled:
code_manager_auto_configureis set to
- More information: Change the environment_timeout setting
Customize Code Manager configuration in Hiera explains how you can use Hiera to further customize your Code Manager configuration.