Customizing r10k configuration

Set parameters in Hiera to customize your r10k configuration.

The customize your configuration:

In your control repo, open the data/common.yaml file.
Add parameters to the pe_r10k class. Use the following format:
```
pe_r10k::<PARAMETER>: <SETTING>
```
For example, these parameters specify a Git repo cache directory and the location from which to fetch the source repository:
```
pe_r10k::cachedir: /var/cache/r10k
pe_r10k::remote: git://git-server.site/my-org/main-modules
```
Some parameters are described in detail below, along with a list of all r10k parameters.
Run Puppet on the primary server.
Deploy environments with r10k. PE does not automatically run r10k after you configure it.

Configuring the r10k base directory

The r10k base directory specifies the path where environments are created for your control repo.

This directory is entirely managed by r10k, and any contents that r10k did not put there are removed. If r10k_basedir is not set, it uses the default environmentpath in your puppet.conf file.

The r10k_basedir parameter accepts a string-formatted path, such as: /etc/puppetlabs/code/environments

Important: The r10k_basedir setting must match the environmentpath in your puppet.conf file, or Puppet can't access your new directory environments. For details about this setting, refer to environmentpath in the open source Puppet documentation.

If you have multiple source repos, you must specify the basedir for each source (in the sources parameter) instead of the global r10k_basedir setting. Specifying both base directory settings causes errors.

Configuring post-deployment commands

To set commands to run after deployments complete, use the postrun parameter.

This parameter accepts the full command as an array of strings, which can be used as an argument vector. You can set this parameter only once. For example:

postrun: ['/usr/bin/curl', '-F', 'deploy=done', 'http://my-app.site/endpoint']

Configuring purge levels

The purge_levels setting, within the deploy parameter, controls which unmanaged content r10k purges after a deployment.

The purge_levels setting accepts an array of strings specifying what content r10k purges during code deployments. You can specify one or more of deployment, environment, puppetfile, and purge_allowlist.

For example:

deploy:
  purge_levels: [ 'deployment', 'environment', 'puppetfile' ]

The default setting is [ 'deployment', 'puppetfile' ].

Each purge level option is explained below.

`deployment`

After each deployment, in the configured basedir, r10k recursively removes content that is not managed by any of the sources declared in the remote or sources parameters.

Important: Removing deployment from purge_levels allows the number of deployed environments to grow without bound, because deleting branches from a control repo would no longer cause the matching environment to be purged automatically.

`environment`

After a given environment is deployed, r10k recursively removes content that is:

Not committed to the control repo branch that maps to that environment.
Not declared in a Puppetfile committed to that branch.

With the environment purge level, r10k loads and parses the Puppetfile for the environment, even if the --modules flag is not set, so that r10k can check whether content is declared in the Puppetfile. However, r10k doesn't actually deploy Puppetfile content unless the environment is new or the --modules flag is set.

If r10k encounters an error while evaluating the Puppetfile or deploying its contents, no environment-level content is purged.

`puppetfile`

After Puppetfile content for a given environment is deployed, r10k recursively removes content in any directory managed by the Puppetfile, if that content is not declared in the Puppetfile.

Directories managed by a Puppetfile include the configured moduledir (which defaults to modules), as well as any alternate directories specified as an install_path option to any Puppetfile content declarations.

`purge_allowlist`

The purge_allowlist setting exempts the specified filename patterns from being purged. This setting affects only environment purging. The value for this setting must be a list of shell-style filename patterns formatted as strings.

See the Ruby documentation about the fnmatch method for information on valid patterns. Both the FNM_PATHNAME and FNM_DOTMATCH flags are in effect when r10k considers the allowlist.

Patterns are relative to the root of the environment being purged and, by default, do not match recursively. For example, an allowlist value of *myfile* preserves only matching files at the root of the environment. To preserve matching files throughout the deployed environment, you need to use a recursive pattern such as **/*myfile*.

Files matching an allowlist pattern might still get removed if they exist in a folder that is otherwise subject to purging. In this case, use an additional allowlist rule to preserve the containing folder, for example:

deploy:
  purge_allowlist: [ 'custom.json', '**/*.xpp' ]

Configuring Forge settings

To configure how r10k downloads modules from the Forge, specify the forge_settings parameters 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:

pe_r10k::forge_settings:
  baseurl: 'https://private-forge.mysite'

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:

pe_r10k::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:

pe_r10k::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 r10k to use a specific Git provider, a private key, a proxy, or multiple Git source repositories, specify the git_settings parameter.

The r10k git_settings parameter accepts a hash that can use the private_key, provider, proxy, username, and repositories keys. For example:

pe_r10k::git_settings:
  provider: "rugged"
  private_key: "/etc/puppetlabs/puppetserver/ssh/id-control_repo.ed25519"
  username: "git"

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

`provider`

Allows r10k to interact with Git repositories using multiple Git providers. Valid values are rugged and shellgit.

For more information about this setting, refer to the r10k documentation on GitHub.

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

username

If the Git remote URL does not provide a username, supply the relevant username as a 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 a hash that uses the remote, private-key, proxy, and username keys.

The remote key specifies the repository to which the subsequent private-key, username, or proxy settings apply. The private-key, username, 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 a unique private key for one repo and a unique proxy for another repo:

pe_r10k::git_settings:
  repositories:
    - remote: "ssh://tessier-ashpool.freeside/protected-repo.git"
      private_key: "/etc/puppetlabs/r10k/ssh/id_rsa-protected-repo-deploy-key"
    - remote: "https://git.example.com/my-repo.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 r10k 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 r10k operations occurring over an HTTP(S) transport, set the global proxy setting.
Tip: If you don't supply a global proxy, but you have defined a proxy in an environment variable, r10k uses the value from the highest-ranking *_proxy environment variable as the global r10k proxy. In order of precedence, r10k looks for HTTPS_PROXY, then https_proxy, then HTTP_PROXY, and finally http_proxy. If you have defined neither a global proxy nor any *_proxy environment variables, the global proxy setting defaults to no proxy.
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: ''

Proxy server logging

If r10k uses proxy server during a deployment, r10k logs the server at the debug log level.

Configuring sources

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

The sources parameter is necessary when r10k 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 r10k's global remote and r10k_basedir settings.

The sources parameter consists of a list of source names along with a hash that can contain the remote, basedir, prefix, ignore_branch_prefixes, and invalid_branches key for each source. For example:

myorg: 
  remote: "git://git-server.site/myorg/main-modules"
  basedir: "/etc/puppetlabs/puppet/environments"
  prefix: true
  ignore_branch_prefixes:
    - "doc"
  invalid_branches: 'error'
mysource: 
  remote: "git://git-server.site/mysource/main-modules"
  basedir: "/etc/puppetlabs/puppet/environments"
  prefix: "testing"
  invalid_branches: 'correct_and_warn'

`remote`

The remote parameter specifies the location from which to fetch the source repo. r10k 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 r10k can use to clone the repo, such as: "git://git-server.site/myorg/main-modules"

Tip: If your sources are in different Git providers, you might need to configure the providers parameter in the r10k Git settings.

`basedir`

Specifies the path to the location where this source's environments are created. This directory is entirely managed by r10k, and any contents that r10k did not put there are removed.

Important: The basedir setting must match the environmentpath in your puppet.conf file, or Puppet can't access your new directory environments.

If you specify basedir in sources, do not also specify the global r10k_basedir setting. Specifying both base directory settings causes errors.

`prefix`

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"
  basedir: "/etc/puppetlabs/puppet/environments"
  prefix: true
  invalid_branches: 'error'
mysource: 
  remote: "git://git-server.site/mysource/main-modules"
  basedir: "/etc/puppetlabs/puppet/environments"
  prefix: true
  invalid_branches: 'correct_and_warn'

However, by changing one prefix to "testing", the two environments become more distinct, since the directory would now have a myorg-main-modules environment and a testing-main-modules environment:

myorg: 
  remote: "git://git-server.site/myorg/main-modules"
  basedir: "/etc/puppetlabs/puppet/environments"
  prefix: true
  invalid_branches: 'error'
mysource: 
  remote: "git://git-server.site/mysource/main-modules"
  basedir: "/etc/puppetlabs/puppet/environments"
  prefix: "testing"
  invalid_branches: 'correct_and_warn'

`ignore_branch_prefixes`

Use ignore_branch_prefixes if you want r10k to not deploy some branches in a specified source. If you omit this parameter, then r10k attempts to deploy all branches.

Specify prefixes you want r10k to ignore as a list of strings, such as:

sources:
  mysource:
    remote: "git://git-server.site/mysource/main-modules"
    basedir: "/etc/puppet/environments"
    ignore_branch_prefixes:
      - "test"
      - "dev"

When r10k runs, if the beginning of a branch's name matches one of the supplied prefixes, r10k ignores the branch and does not deploy an environment based on that branch.

For example, ignoring the prefix "test" ignores branches starting with test, which could be test as a complete branch name, or test followed by any amount or variation of characters, such as test*, testing*, tester*, test_*, and so on.

Tip: Your ignore_branch_prefixes strings are inherently followed by a wildcard. For example, "test" is inherently treated like test*. Do not include wildcard characters in your prefix strings, because r10k interprets them as being literally part of the branch names.

This setting is useful for ignoring branches named after support tickets, training branches, documentation branches, or other such branches that you don't want r10k to try to deploy as environments. If you want to ignore a particular branch without excluding other similarly-prefixed branches, supply the branch's full name in the ignore_branch_prefixes list.

`invalid_branches`

Specifies how you want r10k to handle branch names that can't cleanly map to Puppet environment names. Supply one of the following 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.
"correct_and_warn": Replace non-word characters with underscores, and report a warning about the altered branch names. This is the default value if omitted.

Locking r10k deployments

The deploy: write_lock setting allows you to temporarily disallow r10k code deploys without completely removing the r10k configuration.

This setting is useful for preventing r10k deployments at certain times, or for preventing deployments from interfering with a common set of code that might be touched by multiple r10k configurations.

To enable this, add the write_lock setting under the deploy parameter and supply a message that is returned when someone attempts to deploy code. For example:

deploy:
  write_lock: "Deploying code is disallowed until the next maintenance window."

r10k parameters

The following parameters are available for r10k. Parameters are optional unless otherwise stated.


Parameter	Description	Type	Default value
`cachedir`	The file path to the location where r10k caches Git repositories.	String	`/var/cache/r10k`
`deploy`	For Configuring purge levels and Locking r10k deployments.	Hash	`purge_level: ['deployment', 'puppetfile']` `write_lock`: Omitted
`forge_settings`	For Configuring Forge settings.	Hash	No default.
`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)	The global `proxy` can use a `*_proxy` environment variable, if one is set. Otherwise, there are no defaults.
`postrun`	For Configuring post-deployment commands.	Array of strings to use as an argument vector	No default.
`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`.	String	If `r10k_remote` is specified in the `puppet_enterprise::profile::master` class, that value is used here. Otherwise, there is no default value.
`r10k_basedir`	For Configuring the r10k base directory, if you have only one control repo. If you have multiple Git repos, specify `basedir` in `sources` instead.	String	No default, but must match the `environmentpath` in your `puppet.conf` file.
`sources`	For Configuring sources if 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.