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
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
pe_r10kclass. If so, you must remove the
pe_r10kclass 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-r10kmodule. 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
Enable Code Manager
Enabling Code Manager connects your master to your Git repository.
- Does not have a passphrase.
- Is owned by the
- Is located on the master in a directory that the
pe-puppetuser has permission to view. We recommend
In the console, set the following parameters in the
puppet_enterprise::profile::masterclass in the PE Master node group.
code_manager_auto_configureto true: This enables and configures both Code Manager and file sync.
r10k_remote: This is the location of your control repository, as accessed by SSH. Enter a string that is a valid SSH URL for your Git control repository. For example: "git@<YOUR.GIT.SERVER.COM>:puppet/control.git".Note: Some Git providers, such as Bitbucket, might have additional requirements for enabling SSH access. See your provider's documentation for information.
r10k_private_key: Enter a string specifying the path to the SSH private key that permits the user to access your Git repositories.
Run Puppet on your master and all
If you run Puppet for your master and all compilers at the same time, such as with Run Puppet in the console, you might see errors like this your compilers' 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. They occur because Puppet Server is restarting while the compilers are trying to poll for new code. These errors generally stop as soon as the Puppet Server on the master has finished restarting.
Set up authentication for Code Manager
To securely deploy environments, Code Manager needs an authentication token for both authentication and authorization.
If you would like to use PE client tools, configure these now. PE client tools let you access PE services from a workstation that is not necessarily managed by Puppet. They come pre-installed on your master, but you need to configure them by creating a configuration file. See Configuring 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.
- Create a password by clicking Generate Password.
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 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.
Generate the authentication token using
From the command line on the master, run
puppet-access login --lifetime 180d. This command both requests the token and sets the token lifetime to 180 days.
- 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
~/.puppetlabs/token. To view the token, run
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.
Deploy code without blocking requests to Puppet Server
When compiling code, Puppet Server typically blocks requests, including catalog compilation, until file sync is done updating the Puppet code directory. You can enable lockless deploys so the file sync client updates code into versioned code directories instead of blocking requests and overwriting the live code directory.
/opt/puppetlabs/server/data/puppetserver/filesync/client/versioned-dirs/puppet-code/. The standard code directory,
/etc/puppetlabs/codeis reconfigured to
/etc/puppetlabs/puppetserver/code, which points via symlink to the most recent versioned code directory. If you disable lockless deploys after enabling it, your code directory is moved back to the default location.
To conserve disk space, code written to version directories is optimized to
reduce duplication, and directories older than the latest and its predecessor are
cleaned up after 30 minutes. If you deploy code very frequently, you might prefer to
versioned-dirs-ttl setting, which is
specified, in minutes, in
file-sync.conf within each
- In the console, click Node groups and select the PE Master node group.
On the Classes tab, in the
versioned_deploys= true and click Add parameter.
- Commit changes.
Run Puppet on your master and all compilers:
puppet agent -t
/etc/puppetlabs/puppetserver/code, and versioned code directories are added at
System requirements for lockless deploys
Enabling lockless deploys increases the disk storage required on your master and compilers, because code is written to multiple versioned directories, instead of a single live code directory. Follow these guidelines for estimating your required system capacity.
You can roughly estimate your required disk storage with this equation:
(Size of typical environment)(Number of active environments)
For example, if your typical environment, when deployed, is 200 MB on disk, and you have
25 active environments, your disk storage calculation is 200 MB
= 5,000 MB or 5 GB.
The number of times you deploy a given environment each day also impacts your disk use. Deploying multiple versions of the same environment uses approximately 25 percent more disk space than deploying multiple unique environments. To estimate the additional disk storage required for deploying environments multiple times a day, use this equation:
(Size of typical environment x .25)(Number of environments deployed multiple times per day)(Number of deployments per day)
Expanding on the previous example, if 10 of your active environments are deployed up to 10 times per day, your disk storage calculation is 50 MB x 10 x 10 = 5,000 MB or an additional 5 GB of disk space. In total then, you need 10 GB available for your master and each compiler.
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.
||Specifies whether to autoconfigure Code Manager.||
||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.||
||Optional setting that specifies whether code is updated in versioned code directories instead of blocking requests and overwriting the live code directory.||
To further customize your Code Manager configuration with Hiera, see the related topic about customizing your configuration.