Configure Code Manager
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.
- 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 connection to 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.
Code Manager cannot correctly install or update code if other tools run r10k.
- Disable your previous r10k installation.
- Disable any tools that automatically run r10k. Most
commonly, it is the
zack-r10kmodule.Note: When you upgrade to Code Manager, you can no longer manually use r10k or the
After you disable r10k, you can configure Code Manager.
Enable Code Manager
Enable Code Manager to connect your primary server to your Git repository.
In the console, in the PE Master node group, set
parameters for the
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".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.
"/etc/puppetlabs/puppetserver/ssh/id-control_repo.ed25519". This is the path to the private key that permits the
pe-puppetuser access to your Git repositories.
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.
- Assign a user to the deployment role.
In the console, create a deployment user.
Tip: Create a dedicated deployment user for Code Manager use.
Add the deployment user to the Code Deployers
Note: This role is automatically created on install, with default permissions for code deployment and token lifetime management.
- Create a password by clicking Generate Password.
- 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
expiry permission set, you can change the lifetime of the token to a
duration better suited for a long-running, automated process.
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.
- Enter the user name and password of the deployment user when prompted.
~/.puppetlabs/token. To view the token, run
Test the connection to the control repository
Verify if Code Manager connects to the control repository.
puppet-code deploy --dry-run.
- When the control repository is set up correctly, the command fetches and displays the number of environments in the control repository.
- Environments whose names contain invalid characters are excluded from the number of environments in the control repository. Only environments set up correctly are counted. 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
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.
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
These options are required for Code Manager to work, unless otherwise noted.
- Specifies whether to autoconfigure Code Manager and file sync.
- 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; optional in all other cases.
- Optional proxy used by r10k when accessing the Forge. If empty, no proxy settings are used.
- Configuration option that includes the r10k stacktrace in the error
output of failed deployments when the value is
- Optional setting that specifies whether code is updated in versioned code directories instead of blocking requests and overwriting the live code directory.
falseNote: For more information, see Lockless code deploys
- 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, for example
- Default when Code Manager is enabled:
- Default when Code Manager is not
- Indicates whether a length of time specified by the
environment_timeoutbegins when the environment is created (
from_created) or when it's last used (
To further customize your Code Manager configuration with Hiera, see Customize Code Manager configuration in Hiera.