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.

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"

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.

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.

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.