Customizing r10k configuration
Set parameters in Hiera to customize your r10k configuration.
- In your control repo, open the
- Add parameters to the
pe_r10kclass. 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
r10k_basedir is not set, it uses the default
environmentpath in your
r10k_basedir parameter accepts a string-formatted
path, such as:
r10k_basedirsetting must match the
puppet.conffile, 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: ['/usr/bin/curl', '-F', 'deploy=done', 'http://my-app.site/endpoint']
Configuring purge levels
purge_levels setting, within the
deploy parameter, controls which unmanaged content r10k purges after a deployment.
purge_levels setting accepts an array of strings
specifying what content r10k purges during code
deployments. You can specify one or more of
deploy: purge_levels: [ 'deployment', 'environment', 'puppetfile' ]
The default setting is
[ 'deployment', 'puppetfile' ].
Each purge level option is explained below.
After each deployment, in the configured basedir, r10k recursively removes content that is not managed by any of the sources
declared in the
purge_levelsallows 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.
- Not committed to the control repo branch that maps to that environment.
- Not declared in a Puppetfile committed to that branch.
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.
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
moduledir (which defaults to
modules), as well as any alternate directories specified as an
install_path option to any Puppetfile content declarations.
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
See the Ruby documentation about the
for information on valid patterns. Both the
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
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.
forge_settingsparameter accepts a hash that can use the following keys:
baseurl: Indicate where Forge modules are installed from. The default is
authorization_token: Specify the token for authenticating to a custom Forge server.
proxy: Set the proxy for all Forge interactions.
pe_r10k::forge_settings: baseurl: 'https://private-forge.mysite'
authorization_token. You must format
authorization_tokenas 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>'
proxyparameter sets a proxy for all Forge interactions. This setting overrides the global
proxysetting but only for Forge operations (refer to the global
proxysetting 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'
proxy, but you don't want Forge operations to use a proxy, under the
proxyto 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_settingsparameter accepts a hash that can use the
repositorieskeys. For example:
pe_r10k::git_settings: provider: "rugged" private_key: "/etc/puppetlabs/puppetserver/ssh/id-control_repo.ed25519" username: "git"
private-key setting is required, and, if it is
not specified, it gets a default value from the
private-keyto specify the path to the file containing the default private key that you want Code Manager to use to access control repos, for example:
pe-puppetuser must have read permissions for the private key file, and the SSH key can't require a password.
Allows r10k to interact with Git repositories using multiple Git providers. Valid values are
For more information about this setting, refer to the r10k documentation on GitHub.
proxykey sets a proxy specifically for Git operations that use an HTTP(S) transport. This setting overrides the global
proxysetting but only for Git operations (For more information, refer to the global
proxysetting). You can set an unauthenticated proxy or an authenticated proxy with either Basic or Digest authentication. For example:
To set a proxy for only one specific Git
repository (or when you have multiple control repos), set
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.
If the Git remote URL does not provide a username,
supply the relevant
username as a string.
repositorieskey specifies a list of repositories and their respective private keys or proxies. Use
- 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
sourcessetting and the
repositoriessetting must match.
repositories setting accepts a hash that uses the
remote key specifies the repository to which the
proxy settings apply. The
proxy settings have the
same requirements and functions as described above, except that, when inside
repositories, these settings only apply to a single
repositorieshash 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"
git_settingsproxy, but you don't want a specific repo to use a proxy, in the
repositorieshash, set that specific repo's
proxyto an empty string.
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.
proxyparameter 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
proxysetting.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
*_proxyenvironment variable as the global r10k
proxy. In order of precedence, r10k looks for
HTTP_PROXY, and finally
http_proxy. If you have defined neither a global
*_proxyenvironment variables, the global
proxysetting defaults to no proxy.
- To set proxies only for Git operations or
individual Git repos, set the appropriate
proxykey under the
- To set a proxy only for Forge operations, set the
proxykey under the
Whereas this setting is for a password-authenticated proxy:
Override proxy settings
proxysetting 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.
proxykey under the
To set a proxy for an individual Git repository (or if
you have multiple control repos), set the
repositories hash under the
proxyparameter 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_settingsparameter, 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.
If you are managing multiple control repos with r10k,
you must use the
sources parameter to specify a map of your source
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.
sources setting and the
git_settings) must match.
sources is set, you can't use r10k's
sourcesparameter consists of a list of source names along with a hash that can contain the
invalid_brancheskey 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 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:
providersparameter in the r10k Git settings.
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.
basedirsetting must match the
puppet.conffile, or Puppet can't access your new directory environments.
If you specify
sources, do not also specify the global
r10k_basedir setting. Specifying both base directory settings causes
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
main-modulesenvironments 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'
"testing", the two environments become more distinct, since the directory would now have a
myorg-main-modulesenvironment and a
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 if you want r10k to not deploy some branches in a specified source.
If you omit this parameter, then r10k attempts to deploy all
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.
"test"ignores branches starting with
test, which could be
testas a complete branch name, or
testfollowed by any amount or variation of characters, such as
test_*, and so on.
ignore_branch_prefixesstrings 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
"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
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.
write_locksetting under the
deployparameter 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."
The following parameters are available for r10k. Parameters are optional unless otherwise stated.
||The file path to the location where r10k caches Git repositories.||String||
||For Configuring purge levels and Locking r10k deployments.||Hash||
||For Configuring Forge settings.||Hash||No default.|
||For Configuring Git settings.||Hash||Can use the default
||For Configuring proxies. Can be global (all
HTTP(s) transports) or part of the
||An empty string or a string indicating a proxy server (with or without authentication)||The global
||For Configuring post-deployment commands.||Array of strings to use as an argument vector||No default.|
||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
||For Configuring the r10k base directory, if you have
only one control repo.
If you have multiple Git repos, specify
|String||No default, but must match the
||For Configuring sources if you have multiple control repos.||Hash||No default.|