Customize Code Manager configuration in Hiera

Set parameters in Hiera to customize your Code Manager configuration.

To customize your configuration:

In your control repo, open the data/common.yaml file.
Add parameters to the puppet_enterprise::master::code_manager puppet_enterprise::master::code_management 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.
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 these Forge parameters on the puppet_enterprise::master::code_management class in Hiera (not the puppet_enterprise::master::code_manager class). These parameters replace the single JSON object that was previously given to the puppet_enterprise::master::code_manager::forge_settings parameter.

The Forge related parameters on the puppet_enterprise::master::code_management master class are:

forge_baseurl: Indicate where Forge modules are installed from. The default is https://forgeapi.puppetlabs.com.
forge_authorization_token: Specify the token for authenticating to a custom Forge server.
forge_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_management::forge_baseurl: 'https://private-forge.example'

If your custom Forge server requires authentication, you must specify both forge_baseurl and forge_authorization_token. You must format forge_authorization_token as a string prepended with Bearer, particularly if you use Artifactory as your Forge server. For example:

puppet_enterprise::master::code_management::forge_baseurl: 'https://private-forge.example' puppet_enterprise::master::code_management::forge_authorization_token: 
'Bearer <TOKEN>'

The forge_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_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 forge_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 following Git parameters on the puppet_enterprise::master::code_management class in Hiera (not the puppet_enterprise::master::code_manager class.

Restriction: You can't use these parameters 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 older puppet_enterprise::master::code_manager::git_settings parameter also conflicts with these Git parameters. The new code_managementclass parameters overrides the older code_manager git_settings parameter. To avoid errors, remove the old git_settings parameter from the puppet_enterprise::master::code_manager class.

`git_private-key`

The git_private-key is required if using the SSH protocol for Git remotes, this value is overridden if the puppet_enterprise::profile::master::r10k_private_key parameter is set.

Use git_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:

puppet_enterprise::master::code_management::git_private_key: ‘/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.

`git_proxy`

The git_proxy parameter 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:

puppet_enterprise::master::code_management::git_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, set git_proxy to an empty string.

`git_provider`

The git_provider parameter value is overridden if the puppet_enterprise::profile::master::r10k_git_provider parameter is set. The git_provider must be one of rugged or shellgit, for example:

puppet_enterprise::master::code_management::git_provider: ‘rugged’

`git_oauth_token`

The git_oauth_token parameter is required if using OAuth authenticated Git remotes over the HTTPS protocol. Use git_oauth_token to specify the path to the file containing the token that you want Code Manager to use to access control repos, for example:

puppet_enterprise::master::code_management::git_oauth_token: ‘/etc/puppetlabs/puppetserver/security/github-oauth’

Important: pe-puppet users must have read permissions for the OAuth token file.

`git_default_ref`

Use git_default_ref to specify the ref R10K to use if no ref is specified for a module declaration in a Puppetfile, for example:

puppet_enterprise::master::code_management::git_default_ref: ‘main’

`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.

Important: If you have multiple control repos, the sources setting and the repositories setting must match.

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 git_proxy parameter on the puppet_enterprise::master::code_management class.
To set a proxy only for Forge operations, set the forge_proxy key parameter on the puppet_enterprise::master::code_management class.

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 git_proxy or forge_proxy parameters on the puppet_enterprise::master::code_management class.

To set a proxy for an individual Git repository (or if you have multiple control repos), set the proxy key in the repositories parameter on the puppet_enterprise::master::code_managementclass.

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_management::forge_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.

Related information

Set proxies for Code Manager traffic

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`

Code Management parameters

Important: These parameters are NOT part of the code_manager class, they are part of the code_management class. The full parameter names, including class, are listed below for clarity.


Parameter	Description	Type	Default value
`puppet_enterprise::master::code_management::git_provider`	Whether R10K uses the built in Git library shipped with PE or the system Git CLI. Consult Support before setting to `shellgit`. Valid values are one of `rugged` or `shellgit`. It is overridden by `puppet_enterprise::profile::master::r10k_git_provider` if set.	String	`rugged`
`puppet_enterprise::master::code_management::git_private_key`	A path on the Primary’s files system to an SSH key that can access Git repositories that use the SSH protocol. It is overridden by `puppet_enterprise::profile::master::r10k_private_key`.	String	No default. We recommend placing the key in the `/etc/puppetlabs/puppetserver/ssh/` directory.
`puppet_enterprise::master::code_management::git_default_ref`	The valid value is the name of a branch that R10K uses if the given ref does not exist.	String	No default.
`puppet_enterprise::master::code_management::git_proxy`	The proxy to use for Git repos. This is only necessary if there is a separate proxy for Git repos vs Forge modules. Values include the protocol and port, for example, `http://proxy.example.com:3128`.	String	No default.
`puppet_enterprise::master::code_management::git_oauth_token`	The path on the Primary file system `OAuth`token to use when authenticating to Git repos that require `OAuth` tokens.	String	No default.
`puppet_enterprise::master::code_management::git_repositories`	An array of objects that contain repo specific configuration. The valid keys in each object are `remote`, `private-key`, `proxy`, and `oauth-token`. This is only required if you have multiple control repos and do not share authentication methods between them.	Array	No default.
`puppet_enterprise::master::code_management::forge_proxy`	The proxy to use to download Forge modules. This is only needed if there is a Forge specific proxy different from downloading Git repositories. Values include the protocol and port, for example, `http://proxy.example.com:3128` .	String	No default.
`puppet_enterprise::master::code_management::forge_baseurl`	An HTTPS address of your custom Forge, if you have one.	String	No default.
`puppet_enterprise::master::code_management::forge_authorization_token`	The authorization token to your Forge account, if necessary. In the format of `Bearer <TOKEN>`.	String	No default.

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` (deprecated)	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` (deprecated)	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.

Was this page helpful?

We’re sorry to hear that!
Please tell us why so we can help. Enter your feedback and email. This form is sent to the Puppet docs team. We ask for your email as we might contact you regarding your feedback. If you need help with the product itself, visit Puppet Support or ask in Puppet Community on Slack. Feedback:

Email Address:

To learn about how Puppet uses your personal information, visit our privacy policy.

If you leave us your email, we may contact you regarding your feedback. For more information on how Puppet uses your personal information, see our privacy policy.

See an issue? Please file a JIRA ticket in our [DOCUMENTATION] project.