Dynamic Environment Configuration
=================================

R10k uses a configuration file to determine how dynamic environments should be
deployed.

Config file location
--------------------

### Manual configuration

An explicit configuration file location be specified by providing the `--config`
option to `r10k deploy`, like so:

    r10k deploy --config /srv/puppet/r10k.yaml [...]

### Automatic configuration

If an explicit configuration file is not given, r10k will search the following
locations for a configuration file.

  * `{current working directory}/r10k.yaml`
  * `/etc/puppetlabs/r10k/r10k.yaml` (1.5.0 and later)
  * `/etc/r10k.yaml` (removed in 2.0.0, deprecated in 1.5.0)

As of 2.0.0, r10k will no longer search for a configuration file at
`/etc/r10k.yaml`. In 1.5.0 r10k added `/etc/puppetlabs/r10k/r10k.yaml` to the
configuration search path. The old location, `/etc/r10k.yaml` was deprecated
at that time.

General options
---------------

### cachedir

The 'cachedir' setting specifies where r10k should keep cached information.
Right now this is predominantly used for caching git repositories but will be
expanded as other subsystems can take advantage of caching.

For example:

```yaml
---
# Store all cache information in /var/cache
cachedir: '/var/cache/r10k'
```

[prerun_command](http://docs.puppetlabs.com/references/latest/configuration.html#preruncommand)

The cachedir setting defaults to `~/.r10k`. If the HOME environment variable is
unset r10k will assume that r10k is being run with the Puppet [`prerun_command`][prerun_command]
setting and will set the cachedir default to `/root/.r10k`.

### git

The 'git' setting is a hash that contains Git specific settings.

#### provider

The provider option determines which Git provider should be used.

```yaml
git:
  provider: rugged # one of shellgit, rugged
```

See the [git provider documentation](../git/providers.mkd) for more information
regarding Git providers.

### forge

The 'forge' setting is a hash that contains settings for downloading modules
from the Puppet Forge.

#### proxy

The proxy option sets an optional HTTP proxy to use when downloading modules
from the Forge.

```yaml
forge:
  proxy: 'http://my-site.proxy:3128'
```

If no proxy is given, r10k will check the environment variables 'HTTPS_PROXY',
'https_proxy', 'HTTP_PROXY', and 'http_proxy' in that order for a proxy URL.


Deployment options
------------------

The following options configure how r10k deploys dynamic environments.

### postrun

The `postrun` setting specifies an arbitrary command to run after deploying all
environments. The command must be an array of strings that will be used as an
argument vector. The exit code of the command is not currently used, but the
command should exit with a return code of 0 as the exit code may have semantics
in the future.

```yaml
---
postrun: ['/usr/bin/curl', '-F', 'deploy=done', 'http://my-app.site/endpoint']
```

The postrun setting can only be set once.

### sources

The `sources` setting specifies what repositories should be used for creating
dynamic environments.  It is a hash where each key is the short name of a
specific repository (for instance, "qa" or "web" or "ops") and the value is a
hash of properties for that source.

```yaml
---
sources:
  main:
    # Source settings follow
```

Source options
--------------

The following options are respected by all source implementations. Sources may
implement other options in addition to the ones listed below; see the source
specific documentation for more information.

### remote

The 'remote' setting specifies where the source repository should be fetched
from. It may be any valid URL that the source may check out or clone. The remote
must be able to be fetched without any interactive input, eg usernames or
passwords cannot be prompted for in order to fetch the remote.

```yaml
---
sources:
  mysource:
    remote: 'git://git-server.site/my-org/main-modules'
```

### basedir

The 'basedir' setting specifies where environments will be created for this
source.  This directory will be entirely managed by r10k and any contents that
r10k did not put there will be _removed_.

```yaml
---
sources:
  mysource:
    basedir: '/etc/puppet/environments'
```

If two different sources have the same basedir, it's possible for them to create
two separate environments with the same name and file path. If this occurs r10k
will treat this as a fatal error and will abort. To avoid this, use prefixing on one
or both of the sources to make sure that all environment names are unique. See
also the [prefix](#prefix) setting.

### prefix

The prefix setting allows environment names to be prefixed with the short name
of the given source. This prevents collisions when multiple sources are deployed
into the same directory.

```yaml
---
sources:
  mysource:
    basedir: '/etc/puppet/environments'
    prefix: true # All environments will be prefixed with "mysource_"
```
#### prefix behaviour
* if `true` environment folder will be prefixed with the name of the source.
* if `false` (default) environment folder will not be prefixed
* if `String` environment folder will be prefixed with the `prefix` value.

Examples
--------

### Minimal example

The majority of users will only have a single repository where all modules and
hiera data files are kept. In this case you will specify a single source:

```yaml
---
sources:
  operations:
    remote: 'git://git-server.site/my-org/org-modules'
    basedir: '/etc/puppet/environments'
```

### Separate hiera data

For more complex cases where you want to store hiera data in a different
repository and your modules in another repository, you can specify two sources:

```yaml
---
sources:
  operations:
    remote: 'git://git-server.site/my-org/org-modules'
    basedir: '/etc/puppet/environments'
  hiera:
    remote: 'git://git-server.site/my-org/org-hiera-data'
    basedir: '/etc/puppet/hiera-data'
```

### Multiple tenancy

Alternately you may want to create separate environments from multiple
repositories. This is useful when you want two groups to be able to deploy
Puppet modules but they should only have write access to their own modules and
not the modules of other groups.

```yaml
---
sources:
  main:
    remote: 'git://git-server.site/my-org/main-modules'
    basedir: '/etc/puppet/environments'
    prefix: false # Prefix defaults to false so this is only here for clarity
  qa:
    remote: 'git://git-server.site/my-org/qa-puppet-modules'
    basedir: '/etc/puppet/environments'
    prefix: true
  dev:
    remote: 'git://git-server.site/my-org/dev-puppet-modules'
    basedir: '/etc/puppet/environments'
    prefix: true
```

This will create the following directory structure:

```
/etc/puppet/environments
|-- production       # main-modules repository, production branch
|-- upgrade_apache   # main-modules repository, upgrade_apache branch
|-- qa_production    # qa repository, production branch
|-- qa_jenkins_test  # qa repository, jenkins_test branch
|-- dev_production   # dev repository, production branch
`-- dev_loadtest     # dev repository, loadtest branch
```

#### Multiple tenancy with external hieradata

If hiera data is in a separate repository from your control repository, you
must override the `prefix` so environment folders line up in both directories:

```yaml
---
  sources:
    main:
      app1_data:
        remote: 'git://git-server.site/my-org/app1-hieradata'
        basedir: '/etc/puppet/hieradata'
        prefix: "app1"
      app1_modules:
        remote: 'git://git-server.site/my-org/app1-puppet-modules'
        basedir: '/etc/puppet/environments'
        prefix: "app1"
```


This will create the following directory structure:

```
/etc/puppet/environments
|-- app1_production  # app1 modules repository, production branch
|-- app1_develop     # app1 modules repository, develop branch

/etc/puppet/hieradata
|-- app1_production  # app1 data repository, production branch
|-- app1_develop     # app1 data repository, develop branch
```