Customizing r10k configuration
If you need a customized r10k configuration, you can set specific parameters with Hiera.
To customize your configuration, add keys to your control
repository hierarchy in the
hieradata/common.yaml file in the format
In this example, the first parameter specifies where to store the cache of your Git repos, and the second sets where the source repository should be fetched from.
pe_r10k::cachedir: /var/cache/r10k pe_r10k::remote: git://git-server.site/my-org/main-modules
Add r10k parameters in Hiera
To customize your r10k configuration, add parameters to your control
repository hierarchy in the
Add the parameter in the
hieradata/common.yamlfile in the format
- Run Puppet on the master to apply changes.
Configuring Forge settings
To configure how r10k downloads modules from the Forge, specify
forge_settings in Hiera.
forge_settingsparameter accepts a hash with the following values:
Indicates where Forge modules should be installed from. Defaults to
pe_r10k::forge_settings: baseurl: 'https://private-forge.mysite'
Sets the proxy for all Forge interactions.
overrides the global
proxy setting on
Forge operations only. You can set
an unauthenticated proxy or an authenticated proxy with either Basic or Digest
authentication. See the global
setting for more information and examples.
Configuring purge levels
purge_levels setting controls which unmanaged content r10k purges during a deployment.
['deployment', 'puppetfile']. With these values, r10k purges:
Any content that is not managed by the sources declared in the
Any content that is not declared in the Puppetfile, but is found in a directory managed by the Puppetfile.
deploy: purge_levels: [ 'deployment', 'environment', 'puppetfile' ]
After each deployment, in the configured basedir, r10k recursively removes content that is not
managed by any of the sources declared in the
Disabling this level of purging could cause 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.
After a given environment is deployed, r10k recursively removes content that is neither committed to the control repo branch that maps to that environment, nor declared in a Puppetfile committed to that branch.
With this purge level, r10k loads and parses the Puppetfile for the environment even if the
--puppetfile flag is not set. This
allows r10k to check whether
or not content is declared in the Puppetfile. However, Puppetfile content is deployed
only if the environment is new or the
--puppetfile 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 also declared in that Puppetfile.
Directories considered to be 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
setting exempts the specified filename patterns from being purged.
This setting affects
environment level purging only. Any given value must be a list of shell
style filename patterns in string format.
See the Ruby documentation for the
fnmatch method for more details on valid patterns. Both the
FNM_DOTMATCH flags are in effect when r10k considers the whitelist.
Patterns are relative to the root of the environment being purged
and, by default, do not match recursively. For
example, a whitelist value of
would preserve only a matching file at the root of the environment. To preserve the file
throughout the deployed environment, you would need to use a recursive pattern such as
Files matching a whitelist pattern might still be removed if they exist in a folder that is otherwise subject to purging. In this case, use an additional whitelist rule to preserve the containing folder.
deploy: purge_whitelist: [ 'custom.json', '**/*.xpp' ]
Locking r10k deployments
write_lock setting allows you to temporarily disallow r10k code deploys without completely removing the r10k configuration.
deploy subsetting is
useful to prevent r10k deployments at
certain times or to prevent deployments from interfering with a common set of code that might be
touched by multiple r10k
deploy: write_lock: "Deploying code is disallowed until the next maintenance window."
If you are managing more than one repository with r10k, specify a map of your source repositories.
to specify a map of sources. Configure this setting if you are managing more than just Puppet environments, such as when you are
also managing Hiera data in its own control
To use multiple control repos, the
sources setting and the
repositories setting must match.
sources is set, you
cannot use the global
r10k_basedir settings. Note that r10k raises an error if different sources collide in a
single base directory. If you are using multiple sources, use the
prefix option to prevent collisions.
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'
Specifies where the source repository should be fetched from. The remote must be able to be fetched without any interactive input. That is, you cannot be prompted for usernames or passwords in order to fetch the remote.
Accepts a string that is any valid URL that r10k can clone, such as:
Specifies the path where environments will be created for this source. This directory is entirely managed by r10k, and any contents that r10k did not put there will be removed.
Note that the
basedir setting must match the
environmentpath in your puppet.conf file,
or Puppet won't be able to access your
new directory environments.
Allows environment names to be prefixed with this string. Alternatively, if
prefix is set to true, the source's name
will be used. This prevents collisions when multiple sources are deployed into the same
sources example above, two "main-modules" environments are set up in the same
base directory. The prefix setting is used to differentiate the environments: the first will
be named "myorg-main-modules", and the second will be "testing-main-modules".
Causes branches from a source which match any of the prefixes listed in
the setting to be ignored. The match can be full or partial. On deploy, each branch in the
repo will have its name tested against all prefixes listed in
ignore_branch_prefixes and, if the prefix is found,
then an environment will not be deployed for this branch.
The setting is a list of strings. In the following example, branches in "mysource" with the prefixes "test" and "dev" will not be deployed.
--- sources: mysource: basedir: '/etc/puppet/environments' ignore_branch_prefixes: - 'test' - 'dev'
ignore_branch_prefixes is not specified, then all branches will be
Specifies how branch names that cannot be cleanly mapped to Puppet environments are handled. This option accepts three values:
- 'correct_and_warn' is the default value and replaces non-word characters with underscores and issues a warning.
- 'correct' replaces non-word characters with underscores without warning.
- 'error' ignores branches with non-word characters and issues an error.
Configuring the r10k base directory
The r10k base directory specifies the path where environments will be created for this source.
This directory is entirely managed by r10k, and any contents that r10k did not put there will be removed. If
r10k_basedir is not set, it uses
environmentpath in your
puppet.conf file. If
r10k_basedir is set, you cannot set the
Note that the
r10k_basedir setting must match the
environmentpath in your
puppet.conf file, or Puppet won't be able to
access your new directory environments.
Accepts a string, such as:
Configuring r10k Git settings
To configure r10k to use a specific Git provider, a private key, a proxy, or multiple repositories
with Git, specify the
git_settingsparameter accepts a hash of the following settings:
pe_r10k::git_settings: provider: "rugged" private_key: "/etc/puppetlabs/puppetserver/ssh/id-control_repo.rsa" username: "git"
Specifies the file containing the default
private key used to access control repositories, such as
/etc/puppetlabs/puppetserver/ssh/id-control_repo.rsa. This file
must have read permissions for the
pe-puppet user. The SSH key cannot require a password. This setting is
required, but by default, the value is supplied by the master profile in the console.
Sets a proxy specifically for Git operations that use an HTTP(S) transport.
proxysetting on Git operations only. You can set an unauthenticated proxy or an authenticated proxy with either Basic or Digest authentication. To set a proxy for a specific Git repository only, set
git_settings. See the global
proxysetting for more information and examples.
Specifies a list of repositories and their respective private keys. Use this setting if you want to use multiple control repos.
use multiple control repos, the
setting and the
must match. Accepts an array of hashes with the following keys:
remote: The repository these settings should apply to.
private_key: The file containing the private key to use for this repository. This file must have read permissions for the
pe-puppetuser. This setting overrides the global
proxysetting allows you to set or override the global proxy setting for a single, specific repository. See the global
proxysetting for more information and examples.
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"
Optionally, specify a username when the Git remote URL does not provide a username.
To configure proxy servers, use the
proxy setting. You can set a global proxy for all HTTP(S)
operations, for all Git or Forge
operations, or for a specific Git
To set a proxy for all operations occurring over an
HTTP(S) transport, set the global
setting. You can also set an authenticated proxy with either Basic or Digest
To override this setting for Git or Forge operations only, set the
proxy subsetting under the
forge_settings parameters. To override for a specific Git repository, set a proxy in the
repositories list of
git_settings. To override this setting with no proxy for Git, Forge, or a particular repository, set that specific
proxy setting to an empty
In this example, the first proxy is set up without authentication, and the second proxy uses authentication:
proxy: 'http://proxy.example.com:3128' proxy: 'http://user:firstname.lastname@example.org:3128'
r10k proxy defaults and logging
By default, r10k looks for and uses the first environment variable it finds in this list:
proxysetting defaults to no proxy.
The proxy server used is logged at the "debug" level when r10k runs.
Configuring postrun commands
To configure a command to be run after all deployment is
complete, add the
command to be run after r10k finishes
deploying environments. The command must be an array of strings to be used as an
argument vector. You can set this parameter only one time.
postrun: ['/usr/bin/curl', '-F', 'deploy=done', 'http://my-app.site/endpoint']
The following parameters are available for r10k. Parameters are optional unless otherwise stated.
||Specifies the path to the directory where you want the cache of your Git repos to be stored.||A valid directory path||
Controls how r10k code deployments behave.
|Accepts settings for:
Contains settings for downloading modules from the Puppet Forge. See Configuring Forge settings for usage details.
|Accepts a hash of:
Configures Git settings: Git provider, private key, proxies, and repositories. See Configuring Git settings for usage details.
|Accepts a hash of:
Configures a proxy server to use for all operations that occur over an HTTP(S) transport.
See Configuring proxies for usage details.
|Accepts a string specifying a URL to proxy server, without authentication, or with Basic or Digest authentication.||No default set.|
An optional command to be run after r10k finishes deploying environments.
|An array of strings to use as an argument vector.||No default set.|
Specifies where the source
repository should be fetched from. The remote cannot require any prompts,
such as for usernames or passwords. If
|Accepts a string that is any valid SSH URL that r10k can clone.||By default, uses the
Specifies the path where environments will be created for this source. See Configuring the base directory for usage details.
|A valid file path, which must match the value of
||Uses the value of the
Specifies a map of sources to be passed to r10k. Use if you are managing more than just Puppet environments.
See Configuring sources for usage details.
|A hash of: