Configuring Code Manager
This page assumes that you have already set up a control repo and a Puppetfile. Additionally, you should have configured the puppet-access command, so that you can generate an authentication token. If so, you’re ready to set up Code Manager.
- Enable and configure Code Manager, either
- Test your control repo.
- Set up authentication for Code Manager.
- Test Code Manager.
Note: If you enable Code Manager and file sync, do not attempt to follow the workflows in the Puppet Enterprise Quick Start Guides. The
puppet modulecommand is not currently compatible with Code Manager.
Enable Code Manager during installation
The easiest way to configure Code Manager is to add answers to the answer file during a fresh installation. This enables and configures file sync and Code Manager. These answers can only be used with command-line installation using an answer file, not web-based installation.
Note that you must add these answers to the answer file before installation.
Provide the following answers in the answers file:
This setting specifies the location of the control repository. It accepts a string that is a valid URL for your Git control repository. For example:
This setting specifies the path to the file that contains the SSH private key used to access all Git repositories. The file must be located on the Puppet master and owned by the
The setting accepts a string, such as:
After your PE installation is complete, place the private key you created when you set up your control repository in this location. This must be a location that the
pe-puppetuser can access; we recommend
/etc/puppetlabs/puppetserver/ssh/id-control_repo.rsa. The private key file must be located on the Puppet master and owned by the
This setting configures Code Manager using the master profile, along with the Git control repository to use for storing code, and the private key for accessing your Git repos.
Acceptable values are ‘y’ or ‘n’. Set it to ‘y’ to auto-configure Code Manager. If you set it to ‘n’, Code Manager and file sync are disabled.
After PE installation is complete, you are ready to proceed to the next step below, testing the control repo.
Enable Code Manager after installation
If you didn’t provide answers to the answer file during command line installation, or you are upgrading an existing PE installation, you can enable Code Manager after your installation or upgrade.
If you are upgrading an existing PE installation, check the following before enabling Code Manager:
- If you have a .gitmodules file in the
/etc/puppetlabs/codedirectory on any Puppet master, discard it. Code Manager does not support user-modified .gitmodule files.
- If you used r10k prior to PE 2015.3, you might have configured r10k in the PE console using the
pe_r10kclass. If so, you must remove the
pe_r10kclass in the PE console before moving to the steps below. These steps will provide a standard Code Manager configuration that you can further customize in Hiera as needed.
- If you used any previous versions of r10k, disable any tools that might automatically run r10k. Most commonly, this is the zack-r10k module. Code Manager cannot install or update code properly if other tools are running r10k.
Note that when you start using Code Manager, Code Manager is running r10k in the background. You can no longer directly interact with r10k or use the zack-r10k module.
Enable Code Manager
chown -R pe-puppet:pe-puppet /etc/puppetlabs/codeon the command line. This ensures that the
pe-puppetuser owns the code directory and can make changes as needed.
- In the PE Master Node Group in the console, in the
puppet_enterprise::profile::masterclass, set the following parameters:
true. This enables and automatically configures both Code Manager and file sync.
r10k_remote: This is the location of your control repository. Enter a string that is a valid URL for your Git control repository. For example:
r10k_private_key: This is the path to the private key that permits the
pe-puppetuser to access all Git repositories. This file must be owned by the
pe-puppetuser. Enter a string, such as
Run Puppet on all of your masters.
If you run Puppet for all your masters at the same time (for example, with Run Puppet in the console), you might see errors like this your compile masters’ 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://master.example.com:8140/file-sync/v1/latest-commits). java.net.ConnectException: Connection refused
You can ignore these errors for now. They occur because Puppet Server is restarting while the compile masters are trying to poll for new code. These errors should stop as soon as the Puppet Server on the master of masters has finished restarting.
After the Puppet run is complete, test the connection to the control repo.
Test the control repo
Because Code Manager is running r10k in the background, you can test the connection to the control repo with a read-only r10k command. To make sure that Code Manager can connect to the control repo, enter the following on the command line:
r10k deploy display --fetch
If the control repo is set up properly, this command fetches and displays a list of the environments in the control repo.
Set up authentication for Code Manager
Code Manager needs an authentication token for both authentication and authorization. This token allows Code Manager to securely deploy the requested environment.
These steps assume that you have already configured the Puppet Access command line tool.
To generate a token for Code Manager, first you create a deployment role and user, and then you request an authentication token.
Create a deployment role and user
Before you request a token, you must assign a user the correct permissions with role-based access control (RBAC). We recommend that you create a dedicated deployment user for Code Manager use. You can find detailed instructions for creating users and user roles in the RBAC documentation.
To create the deployment user and user role:
- Create a new role named “Deploy Environments”.
- Assign this role the following permissions:
- Add the Puppet Environment type.
- Set Permissions for this type to Deploy code.
- Set Object for this type to All.
- Add the Tokens type.
- Set Permissions for this type to Override default expiry.
- Add the Puppet Environment type.
- Create a deployment user.
- Add the deployment user to the Deploy Environments role.
Next, request the token.
Request an authentication token
Note that by default, authentication tokens have a five-minute lifetime. With the Override default expiry permission set, you can change the lifetime to a duration better suited for a long-running, automated process.
Generate the authentication token using the
On the command line on the master, run
puppet-access login --service-url https://<HOSTNAME OF PUPPET ENTERPRISE CONSOLE>:4433/rbac-api --lifetime 180d.
Enter the username and password of the deployment user when prompted.
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
Test Code Manager
To make sure Code Manager deploys your environments correctly, you should test it. To test, trigger Code Manager on the command line to deploy a single environment.
Deploy a single environment
To test Code Manager, run the following command to deploy one environment:
puppet-code deploy my_test_environment --wait
Check to make sure the environment was deployed. If so, you’ve set up Code Manager correctly.
Reference: Code Manager settings
After Code Manager is configured, you can adjust some settings in the master profile in the PE console. These options are required for Code Manager to work, unless otherwise noted.
code_manager_auto_configure: Set to
trueto auto-configure Code Manager.
r10k_remote: The location of the Git control repository. Enter a string that is a valid URL for your Git control repository. For example:
r10k_private_key: Required when using the SSH protocol; optional in all other cases. The file containing the private key used to access all Git repositories. Enter a string, such as ‘/etc/puppetlabs/puppetserver/ssh/id-control_repo.rsa’.
r10k_proxy: Optional. A proxy setting r10k uses when accessing the Forge. If empty, no proxy settings are used.
You can further customize your Code Manager configuration with Hiera.
When Code Manager is fully enabled and configured, you can trigger Code Manager to deploy your environments: