Customizing r10k configuration
If you need a customized r10k configuration, you can set specific parameters with Hiera.
- Add parameters to the
data/common.yaml
file in your control repo. Use the formatpe_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
Refer to the other sections on this page for information about other settings you might want to configure.
- Run Puppet on the primary server.
- Deploy environments with r10k. PE does not automatically run r10k after you configure it.
Configuring Forge settings
To configure how r10k downloads modules from the Forge,
specify forge_settings
in Hiera.
forge_settings
parameter accepts a hash with the
following values: -
baseurl
: Indicates where Forge modules are installed from. Defaults tohttps://forgeapi.puppetlabs.com
. -
authorization_token
: Specifies the token for authenticating to a custom Forge server. -
proxy
: Sets the proxy for all Forge interactions.
baseurl
Indicates where Forge modules
are installed from. Defaults to https://forgeapi.puppetlabs.com
.
pe_r10k::forge_settings:
baseurl: 'https://private-forge.mysite'
proxy
Sets the proxy for all Forge interactions. This setting 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 proxy
setting for
more information and examples.
puppet_enterprise::master::code_manager::forge_settings:
proxy: 'http://proxy.example.com:3128'
Configuring purge levels
The purge_levels
setting controls which unmanaged content r10k purges during a deployment.
This setting accepts an array of strings specifying what content r10k purges during code deployments. Available values are:
-
deployment
-
environment
-
puppetfile
-
purge_allowlist
The default value for this setting is ['deployment', 'puppetfile']
. With
these values, r10k purges:
- Any content that is not managed by the sources declared in the
remote
orsources
settings. - 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' ]
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.
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.
environment
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 --modules
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 --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 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 declarations.
purge_allowlist
The purge_allowlist
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_PATHNAME
and
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
*myfile*
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 **/*myfile*
.
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_allowlist: [ 'custom.json', '**/*.xpp' ]
Locking r10k deployments
The deploy:
write_lock
setting allows you to temporarily disallow r10k code deploys without completely removing the r10k configuration.
This 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 configurations.
deploy:
write_lock: "Deploying code is disallowed until the next maintenance window."
Configuring sources
If you are managing more than one repository with r10k, specify a map of your source repositories.
Use the source
parameter
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 repository.
To use multiple control repos, the sources
setting and the repositories
setting must match.
If sources
is set, you
cannot use the global remote
and 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.
remote
basedir
prefix
invalid_branches
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'
remote
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:
git://git-server.site/my-org/main-modules
basedir
Specifies the path where environments are created for this source. This directory is entirely managed by r10k, and any contents that r10k did not put there are 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.
prefix
Allows environment names to be prefixed with this string. Alternatively, if
prefix
is set to true, the source's name is used. This prevents
collisions when multiple sources are deployed into the same directory.
In the 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 is named "myorg-main-modules", and the second is "testing-main-modules".
ignore_branch_prefixes
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 has its name
tested against all prefixes listed in ignore_branch_prefixes
and, if the prefix is found, then an environment is not deployed for this branch.
The setting is a list of strings. In the following example, branches in "mysource" with the prefixes "test" and "dev" are not deployed.
---
sources:
mysource:
basedir: '/etc/puppet/environments'
ignore_branch_prefixes:
- 'test'
- 'dev'
If ignore_branch_prefixes
is not specified, then all
branches are deployed.
invalid_branches
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 are created for this source.
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. If r10k_basedir
is set, you cannot set the sources
parameter.
Note that the r10k_basedir
setting must match the
environmentpath
in your puppet.conf
file, or Puppet can't access your new directory
environments.
Accepts a string, such as: /etc/puppetlabs/code/environments
.
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_settings
parameter.
The r10k git_settings
parameter accepts a
hash of the following settings: Contains settings specific to Git.
private_key
proxy
repositories
provider
Accepts a hash of values, such as:
pe_r10k::git_settings:
provider: "rugged"
private_key: "/etc/puppetlabs/puppetserver/ssh/id-control_repo.ed25519"
username: "git"
private_key
Specifies the file containing the default private key used to
access control repositories, such as
/etc/puppetlabs/puppetserver/ssh/id-control_repo.ed25519
. 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 in the
puppet_enterprise::profile::master
class.
proxy
Sets a proxy specifically for Git operations that use an HTTP(S) transport.
proxy
setting 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 proxy
in the
repositories
subsetting of git_settings
. See the global proxy
setting for more information and
examples.proxy: 'http://proxy.example.com:3128'
repositories
Specifies a list of repositories and their respective private keys. Use this setting if you want to use multiple control repos.
To use multiple control repos, the sources
setting and the
repositories
setting 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 thepe-puppet
user. This setting overrides the globalprivate_key
setting. -
proxy
: Theproxy
setting allows you to set or override the global proxy setting for a single, specific repository. See the globalproxy
setting 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"
username
Optionally, specify a username when the Git remote URL does not provide a username.
Configuring proxies
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 repository only.
proxy
To set a proxy for all operations occurring over an
HTTP(S) transport, set the global proxy
setting. You can also set an authenticated proxy with either Basic or Digest
authentication.
To override this setting for Git or Forge operations
only, set the proxy
subsetting under
the git_settings
or 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 string.
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:password@proxy.example.com:3128'
r10k proxy defaults and logging
By default, r10k looks for and uses the first environment variable it finds in this list:
- HTTPS_PROXY
- https_proxy
- HTTP_PROXY
- http_proxy
If no proxy setting is found in the environment, the global proxy
setting 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 postrun
parameter.
The postrun
optional
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']
r10k parameters
The following parameters are available for r10k. Parameters are optional unless otherwise stated.
Parameter | Description | Value | Default |
---|---|---|---|
cachedir
|
Specifies the path to the directory where you want the cache of your Git repos to be stored. | A valid directory path |
/var/cache/r10k
|
deploy
|
Controls how r10k code deployments behave. See Configuring purge levels and Locking deployments for usage details. |
Accepts settings for:
|
|
forge_settings
|
Contains settings for downloading modules from the Puppet Forge. See Configuring Forge settings for usage details. |
Accepts a hash of:
|
No default. |
git_settings
|
Configures Git settings: Git provider, private key, proxies, and repositories. See Configuring Git settings for usage details. |
Accepts a hash of:
|
No default. |
proxy
|
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. |
postrun
|
An optional command to be run after r10k finishes deploying environments. |
An array of strings to use as an argument vector. | No default set. |
remote
|
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 r10k_remote value set in the console. |
r10k_basedir
|
Specifies the path where environments are created for this source. See Configuring the base directory for usage details. |
A valid file path, which must match the value
of environmentpath in
your puppet.conf
file. |
Uses the value of the environmentpath in your puppet.conf file. |
sources
|
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:
|
No default. |