To configure Code Manager, enable it in Puppet Enterprise (PE), set up authentication, and test the communication between the control repo and Code Manager.
When you finished configuration, you're ready to deploy environments with Code Manager.
You can enable and configure Code Manager either during or after r10k installation.
To enable Code Manager after a new installation or in an existing PE installation, set Code Manager parameters in the console. You can also configure Code Manager during a fresh PE installation, but only during a text-mode installation.
- Enable and configure Code Manager, after
installation or upgrade, by setting parameters in the master profile class in the PE console. Alternatively, enable during a fresh
installation, by setting parameters in
pe.conf
-
Test your control repo.
-
Set up authentication for Code Manager.
-
Test Code Manager.
Upgrading from r10k to Code Manager
If you are upgrading from r10k to Code Manager, you must first disable your old r10k installation.
If you are upgrading from r10k to Code Manager, check the following before enabling Code Manager:
- If you used r10k prior to PE
2015.3, you might have configured r10k in the console
using the
pe_r10k
class. If so, you must remove thepe_r10k
class in the console before configuring Code Manager. - If you used any previous versions of r10k, disable any tools that might automatically run
it. Most commonly, this is the
zack-r10k
module. Code Manager cannot install or update code properly if other tools are running r10k.
When you start using Code Manager, it runs
r10k in the background. You can no longer directly
interact with r10k or use the zack-r10k
module.
Enable Code Manager
Usually, you enable Code Manager after PE is already installed. If you are automating your PE installation and using an existing control repo and SSH key, you can enable Code Manager during the PE installation process.
- Your SSH key should be generated without setting a passphrase
- The private key file must be located on the master, owned by the user, and
located in a directory that the user has permission to view. We recommend
/ect/puppetlabs/puppetserver/ssh/id-control_repo.rsa
Enable Code Manager after installation
To enable Code Manager after installing PE or in an existing installation, set parameters in the console.
Next, set up authentication.
Enable Code Manager during installation
To configure Code Manager during a fresh
installation of PE, add
parameters to the pe.conf
file.
Use these parameters only with text-mode PE installation, not with web-based installation. Adding the listed parameters enables and configures file sync and Code Manager.
Next, set up authentication.
Set up authentication for Code Manager
To securely deploy environments, Code Manager needs an authentication token for both authentication and authorization.
If needed, configure the Puppet access command line tool. This comes pre-installed on your master. See Installing PE client tools for more information.
To generate a token for Code Manager, first assign a user to the deployment role, and then request an authentication token.
Assign a user to the deployment role
To request an authentication token, you must first assign a user the correct permissions with role-based access control (RBAC).
- In the console, create a deployment user. We recommend that you create a dedicated deployment user for Code Manager use.
- Add the deployment user to the Code Deployers role. This role is automatically created on install, with default permissions for code deployment and token lifetime management.
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 five-minute 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.
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
.
Test the control repo
To make sure that Code Manager can connect to the control repo, test the connection to the repository.
puppet-code deploy --dry-run
.
-
If the control repo is set up properly, this command fetches and displays the number of environments in the control repo.
-
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
To test whether Code Manager deploys your environments correctly, trigger a single environment deployment on the command line.
Deploy a single environment
Test Code Manager by deploying a single test environment.
This deploys the test environment, and then returns deployment results with the SHA (a checksum for the content stored) for the control repo commit.
puppet-code deploy
my_test_environment --wait
Check to make sure the environment was deployed. If so, you've set up Code Manager correctly.
If the deployment does not work as you expect, check over the configuration steps, or refer to the troubleshooting guide for help.
After Code Manager is fully enabled and configured, you can trigger it to deploy your environments.
There are several ways to trigger deployments, depending on your needs.
- Manually, on the command line.
- Automatically, with a webhook.
- Automatically, with a custom script that hits the deploys endpoint.
Code Manager console settings
After Code Manager is configured, you can adjust some settings in the master profile in the console.
These options are required for Code Manager to work, unless otherwise noted.
Setting | Description | Example |
---|---|---|
code_manager_auto_configure
|
Set to true to auto-configure Code Manager. |
true
|
r10k_remote
|
The location of the Git control repository. Enter a string that is a valid URL for your control repository. |
'git@<YOUR.GIT.SERVER.COM>:puppet/control.git'
|
r10k_private_key
|
Required when using the SSH protocol; optional in all other cases. Enter a string that is the path to the file containing the private key used to access all Git repositories. |
'/etc/puppetlabs/puppetserver/ssh/id-control_repo.rsa'
|
r10k_proxy
|
Optional. A proxy setting r10k Code Manager uses when accessing the Forge. If empty, no proxy settings are used. |
'http://proxy.example.com:3128'
|
To further customize your Code Manager configuration with Hiera, see the related topic about customizing your configuration.