Customize Code Manager configuration in Hiera

Set parameters in Hiera to customize your Code Manager configuration.

To customize your configuration:
  1. In your control repo, open the data/common.yaml file.
  2. Add parameters to the puppet_enterprise::master::code_manager class. Use the following format:
    puppet_enterprise::master::code_manager::<PARAMETER>: <SETTING>
    For example, these parameters increase the size of the default worker pool and reduce the maximum time allowed to deploy a single environment:
    puppet_enterprise::master::code_manager::deploy_pool_size: 4
puppet_enterprise::master::code_manager::timeouts_deploy: 300

    Some parameters are described in detail below, along with a list of all Code Manager parameters.

  3. Run Puppet on the primary server. The Puppet run updates the Code Manager configuration file.
    Important: Do not manually edit the Code Manager configuration file. Puppet automatically manages this file, and it overwrites or discards any manual changes you make.

Configuring post-environment hooks

Post-environment hooks can trigger custom actions after deploying an environment.

To configure a list of hooks to run after Code Manager deploys code to an environment, specify the post_environment_hook parameter in Hiera. This parameter accepts an array of hashes with the url and use-client-ssl keys.

The url key specifies an HTTPS URL to send a POST request to. The request includes a JSON-formatted body containing information about the environment deployment, such as:
{
     "deploy-signature":"482f8d3adc76b5197306c5d4c8aa32aa8315694b",
     "file-sync":{
       "environment-commit":"6939889b679fdb1449545c44f26aa06174d25c21",
       "code-commit":"ce5f7158615759151f77391c7b2b8b497aaebce1"},
     "environment":"production",
     "id":3,
     "status":"complete"
   }

The use-client-ssl key is a Boolean specifying whether to use the client's SSL configuration for HTTPS connections.

By default, use-client-ssl is set to false, which means that when the HTTP client makes a request, it uses certificates from the Puppet Enterprise Java trust store file, which is located at: 
/opt/puppetlabs/server/apps/java/lib/jvm/java/jre/lib/security/cacerts)
Important: When you upgrade PE, any certificates you added to this trust store file, are cleared. If the certificates are still required, you must add them again.

Set use-client-ssl to true only if the url destination is a server that uses the Puppet certificate authority.

For example, the following settings instruct Code Manager to update classes in the console after deploying code to environments:
puppet_enterprise::master::code_manager::post_environment_hooks: 
  - url: 'https://console.example.com:4433/classifier-api/v1/update-classes' 
    use-client-ssl: true
If you wanted to configure multiple post-environment hooks, you would add more hashes to the array.

Configuring garbage collection

By default, Code Manager retains environment deployments in memory for one hour. You can adjust this by configuring garbage collection.

To configure the frequency of Code Manager garbage collection, specify the deploy_ttl parameter in Hiera. This parameter accepts a string that includes one of the following suffixes:
  • d: Days
  • h: Hours
  • m: Minutes
  • s: Seconds
  • ms: Milliseconds

For example, deploy_ttl: '30d' configures Code Manager to keep deployments in memory for 30 days. Similarly, deploy_ttl: '48h' retains deployments in memory for 48 hours.

The default setting is 1h (one hour).

Important: If the value of deploy-ttl is less than the combined values of timeouts_fetch, timeouts_sync, and timeouts_deploy, then all completed deployments are retained indefinitely. This could significantly slow Code Manager's performance over time. Refer to Code Manager parameters for information about the timeouts_* parameters.

Configuring module deployment scope

By default, Code Manager performs incremental deployments of module code. You can use the full_deploy parameter to change the module code deployment scope.

Incremental deploys only sync modules whose definitions (in the environment's Puppetfile) allow their version to "float" (such as Git branches) and modules whose definitions have been added or changed since the environment's last deployment. Incremental deploys do not support SVN modules.

If you want to deploy all module code regardless of change or float status, you can disable incremental deploys by setting the following parameter to true:
puppet_enterprise::master::code_manager::full_deploy

To re-enable incremental deploys, set the full_deploy parameter to false.

Configuring Forge settings

To configure how Code Manager downloads modules from the Forge, specify the forge_settings parameter in Hiera.

This parameter specifies where Forge modules are installed from, and it sets a proxy for all Forge interactions. The forge_settings parameter accepts a hash that can use the following keys:
  • baseurl: Indicate where Forge modules are installed from. The default is https://forgeapi.puppetlabs.com.
  • authorization_token: Specify the token for authenticating to a custom Forge server.
  • proxy: Set the proxy for all Forge interactions.
For example, this configuration specifies a custom Forge server that doesn't require authentication:
puppet_enterprise::master::code_manager::forge_settings: 
  baseurl: 'https://private-forge.example'
If your custom Forge server requires authentication, you must specify both baseurl and authorization_token. You must format authorization_token as a string prepended with Bearer, particularly if you use Artifactory as your Forge server. For example:
puppet_enterprise::master::code_manager::forge_settings: 
  baseurl: 'https://private-forge.example'
  authorization_token: 'Bearer <TOKEN>'
The proxy parameter sets a proxy for all Forge interactions. This setting overrides the global proxy setting but only for Forge operations (refer to the global proxy setting for more information). You can set an unauthenticated proxy or an authenticated proxy with either Basic or Digest authentication. For example:
puppet_enterprise::master::code_manager::forge_settings: 
  proxy: 'http://proxy.example.com:3128'
Tip: If you set a global proxy, but you don't want Forge operations to use a proxy, under the forge_settings parameter, set proxy to an empty string.

Configuring Git settings

To configure Code Manager to use a private key, a proxy, or multiple Git source repositories, specify the git_settings parameter in Hiera.

Restriction: You can't use the git_settings parameter with the default Code Manager r10k_private_key settings. To avoid errors, remove the r10k_private_key parameter from the puppet_enterprise::profile::master class.

The git_settings parameter accepts a hash that can use the private-key, proxy, and repositories keys.

private-key

The private-key setting is required, and, if it is not specified, it gets a default value from the puppet_enterprise::profile::master class.

Use private-key to specify the path to the file containing the default private key that you want Code Manager to use to access control repos, for example:
/etc/puppetlabs/puppetserver/ssh/id-control_repo.ed25519
Important: The pe-puppet user must have read permissions for the private key file, and the SSH key can't require a password.

proxy

The proxy key sets a proxy specifically for Git operations that use an HTTP(S) transport. This setting overrides the global proxy setting but only for Git operations (For more information, refer to the global proxy setting). You can set an unauthenticated proxy or an authenticated proxy with either Basic or Digest authentication. For example:
proxy: 'http://proxy.example.com:3128'
Tip:

To set a proxy for only one specific Git repository (or when you have multiple control repos), set proxy within the repositories key.

If you set a global proxy, but you don't want Git operations to use a proxy, under the git_settings parameter, set proxy to an empty string.

repositories

The repositories key specifies a list of repositories and their respective private keys or proxies. Use repositories if:
  • You need to configure different proxy settings for specific repos, instead of all Git operations.
  • You have multiple control repos.
    Important: If you have multiple control repos, the sources setting and the repositories setting must match.

The repositories setting accepts an array of hashes that use the remote, private-key, and proxy keys.

The remote key specifies the repository to which the subsequent private-key or proxy setting applies. The private-key and proxy settings have the same requirements and functions as described above, except that, when inside repositories, these settings only apply to a single repository.

For example, this repositories hash specifies unique private keys for two repos and a unique proxy for a third repo:
repositories: 
  - remote: "jfkennedy@gitserver.puppetlabs.net:repositories/repo_one.git"
    private-key: "/test_keys/jfkennedy"
  - remote: "whtaft@gitserver.puppetlabs.net:repositories/repo_two.git"
    private-key: "/test_keys/whtaft"
  - remote: "https://git.example.com/git_repos/environments.git"
    proxy: "https://proxy.example.com:3128"
Tip: If you set a global proxy or a git_settings proxy, but you don't want a specific repo to use a proxy, in the repositories hash, set that specific repo's proxy to an empty string.

Configuring proxies

If you need Code Manager to use a proxy connection, use the proxy parameter. You can set a global proxy for all HTTP(S) operations, proxies for Git or Forge operations, or proxies for individual Git repositories.

Where you specify the proxy parameter depends on how you want to apply the setting:
  • To set a proxy for all Code Manager operations occurring over an HTTP(S) transport, set the global proxy setting.
  • To set proxies only for Git operations or individual Git repos, set the appropriate proxy key under the git_settings parameter.
  • To set a proxy only for Forge operations, set the proxy key under the forge_settings parameter.
You can set an unauthenticated proxy or an authenticated proxy with either Basic or Digest authentication. For example, this setting is for an unauthenticated proxy:
proxy: 'http://proxy.example.com:3128'
Whereas this setting is for a password-authenticated proxy:
proxy: 'http://user:password@proxy.example.com:3128'

Override proxy settings

You can override the global proxy setting if you want to:
  • Set a different proxy setting for Git or Forge operations.
  • Specify a different proxy setting for an individual Git repo.
  • Specify a mix of proxy and non-proxy connections.
To override the global proxy setting for all Git or Forge operations, you need to set the proxy key under the git_settings or forge_settings parameters.

To set a proxy for an individual Git repository (or if you have multiple control repos), set the proxy key in the repositories hash under the git_settings parameter.

If you have set a global, Git, or Forge proxy, but you don't want a certain setting to use any proxy, set the proxy parameter to an empty string. For example, if you set a global proxy, but you don't want Forge operations to use a proxy, you would specify an empty string under the forge_settings parameter, such as:
puppet_enterprise::master::code_manager::forge_settings: 
  proxy: ''
Tip: You can use curl commands to test Git and Forge proxy connections, such as:
curl --proxy "<YOUR_PROXY_URI>" --head "https://github.com"
curl --proxy "<YOUR_PROXY_URI>" --head "https://forgeapi.puppet.com"

For general information about forming curl commands, authentication in commands, and Windows modifications, go to Using example commands.

Configuring sources

If you are managing multiple control repos with Code Manager, you must use the sources parameter to specify a map of your source repositories.

The sources parameter is necessary when Code Manager is managing multiple control repos. For example, your Puppet environments are in one control repo and your Hiera data is in a separate control repo.

Important:

The sources setting and the repositories setting (under git_settings) must match.

If sources is set, you can't use Code Manager's global remote parameter.

The sources parameter consists of a list of source names along with a hash containing the remote and prefix key for each source. For example:
myorg: 
  remote: "git://git-server.site/myorg/main-modules"
  prefix: true
mysource: 
  remote: "git://git-server.site/mysource/main-modules"
  prefix: "testing"

The remote parameter specifies the location from which to fetch the source repo. Code Manager must be able to fetch the remote without any interactive input. This means fetching the source can't require inputting a user name or password. You must supply a valid URL, as a string, that Code Manager can use to clone the repo, such as: "git://git-server.site/myorg/main-modules"

The prefix parameter specifies a string to use as a prefix for the names of environments derived from the specified source. Set this to a specific string if you want to use a specific prefix, such as "testing". Set this to true to use the source's name as the prefix. The prefix parameter prevents collisions (and confusion) when multiple sources with identical branch names are deployed into the same directory.

For example, the following settings might cause errors or confusion because there would be two main-modules environments deployed to the same base directory:
myorg: 
     remote: "git://git-server.site/myorg/main-modules"
     prefix: true
   mysource: 
     remote: "git://git-server.site/mysource/main-modules"
     prefix: true
However, by changing one prefix to "testing", the two environments become more distinct, since the directory would now have a main-modules environment and a testing-main-modules environment:
myorg: 
     remote: "git://git-server.site/myorg/main-modules"
     prefix: true
   mysource: 
     remote: "git://git-server.site/mysource/main-modules"
     prefix: "testing"

Code Manager parameters

Parameter Description Type Default value
r10k_remote (also referred to as Code Manager's global remote) A valid SSH URL specifying the location of your Git control repository, if you have only one control repo.

If you have multiple Git repos, specify sources instead of remote. If you specify both sources and remote, then sources overrides remote.

 String If r10k_remote is specified in the puppet_enterprise::profile::master class, that value is used here. Otherwise, there is no default value.
authenticate_webhook Indicates whether to enable RBAC authentication for the POST /v1/webhook endpoint. Boolean true
cachedir The file path to the location where Code Manager caches Git repositories. String /opt/puppetlabs/server/data/code-manager/cache
certname The certname of the Puppet signed certs to use for SSL String or string variable $::clientcert
data The file path to the directory where Code Manager stores internal file content. String /opt/puppetlabs/server/data/code-manager
deploy_pool_cleanup_interval Specifies how often workers pause to clean their on-disk caches. If cleanup takes too long, increase this value so that cleanup happens less often. Integer indicating a 1 out of n percent chance. 100 (Cleanup occurs after 1 of every 100 code deployments, or after 1% of code deployments.)
deploy_pool_size Specifies the number of threads in the worker pool, which determines how many deployment processes can run in parallel. Integer 2
download_pool_size Specifies the number of threads used to download modules. Integer 4
deploy_ttl For Configuring garbage collection. String with a required suffix 1h
full_deploy For Configuring module deployment scope. Boolean false
hostcrl The file path to the SSL CRL. String or string variable $puppet_enterprise::params::hostcrl
localcacert The file path to the SSL CA cert. String or string variable $puppet_enterprise::params::localcacert
post_environment_hooks For Configuring post-environment hooks, which are hooks that you want to run after Code Manager deploys an environment. Array of hashes No default.
timeouts_deploy Maximum execution time (in seconds) allowed for deploying a single environment. Integer 600
timeouts_fetch Maximum execution time (in seconds) allowed for updating the control repo state. Integer 30
timeouts_hook Maximum time (in seconds) to wait for a single post-environment hook URL to respond. Controls both the socket connect timeout and the read timeout; therefore, the longest total timeout is twice the specified value. Integer 30
timeouts_shutdown Maximum time (in seconds) to wait for in-progress deployments to complete when shutting down the service. Integer 610
timeouts_wait Maximum time (in seconds) to wait for the environment's deployment to finish before timing out. Only applies to requests sent with the wait key. Integer 700
timeouts_sync Maximum time (in seconds) to wait for all compilers to receive deployed code before timing out. Only applies to requests sent with the wait key. Integer 300
webserver_ssl_host The IP address of the host that Code Manager listens on. IP address 0.0.0.0
webserver_ssl_port The port that Code Manager listens on.
Important: Port 8170 must be open if you're using Code Manager.
 Integer 8170

r10k-specific parameters

Code Manager uses r10k in the background. In the context of Code Manager, the following r10k parameters apply.
Parameter Description Type Default value
environmentdir The file path to the single directory where Code Manager deploys all sources. String If file_sync_auto_commit is set to true, then this defaults to: /etc/puppetlabs/code-staging/environments
forge_settings For Configuring Forge settings. Hash No default.
invalid_branches Specifies how you want Code Manager to handle branch names that can't cleanly map to Puppet environment names. Either of these strings:
  • 'error': Ignore branches that have non-word characters, and report an error about the invalid branches
  • 'correct': Without providing a warning, replace non-word characters with underscores
 'error'
git_settings For Configuring Git settings. Hash Can use the default private-key value set in console. Otherwise, there are no default settings.
proxy For Configuring proxies. Can be global (all HTTP(s) transports) or part of the git_settings or forge_settings hashes. An empty string or a string indicating a proxy server (with or without authentication) No default.
sources For Configuring sources when you have multiple control repos. Hash No default.