Customizing r10k configuration

baseurl

Indicates where Forge modules should be 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.

proxy: 'http://proxy.example.com:3128'

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

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_whitelist

The purge_whitelist 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_whitelist: [ 'custom.json', '**/*.xpp' ]

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.

private_key

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.

proxy

Sets a proxy specifically for Git operations that use an HTTP(S) transport.

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 the pe-puppet user. This setting overrides the global private_key setting.
• proxy: The proxy setting allows you to set or override the global proxy setting for a single, specific repository. See the global proxy 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.

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:

The proxy server used is logged at the "debug" level when r10k runs.