Deploying environments with r10k

Deploy environments on the command line with the r10k deploy command.

The first time you run r10k, deploy all environments and modules by running:
r10k deploy environment
This command:
  1. Checks your control repository to see which branches are present.
  2. Maps those branches to the Puppet directory environments.
  3. Clones your Git repo and either creates (if this is your first run) or updates (if it is a subsequent run) your directory environments with the contents of your repo branches.
Restriction: When running commands to deploy code on your primary server, r10k needs write access to your environment path. You need to run r10k as the pe-puppet user, as root, or use sudo. Running as root requires access control to the root user.

Updating environments

To update environments with r10k, use the r10k deploy environment command.

Update all environments

The r10k deploy environment command updates all existing environments and recursively creates new environments.

From the command line, run: r10k deploy environment

Structured in this way, this command updates modules only on the environment's first deployment. On subsequent updates, it only updates the environment.

Update all environments and modules

Add the --modules flag to the r10k deploy environment command to update all environments and their modules.

From the command line, run: r10k deploy environment --modules

This command:
  • Updates all existing environments.
  • Creates new environments, if any new branches are detected.
  • Deletes old environments, if any branches no longer exist.
  • Recursively updates all environment modules declared in each environment's Puppetfile.

This command does the maximum possible deployment work. Therefore it is the slowest method for r10k deployments. Usually, you'll use the less resource-intensive commands for updating specific environments and modules.

Update a single environment

To update a single environment, specify the environment name with the r10k deploy environment command.

From the command line, run: 
r10k deploy environment <ENVIRONMENT_NAME>

Formatted in this way, this command updates one environment. It deploys modules only during the environment's first deployment. On subsequent deployments, it only updates the environment.

If you are actively developing a specific environment, this command is the quickest way to deploy your changes so you can test them.

Update a single environment and its modules

To update a specific environment's content and its modules, add the --modules flag to your environment-specific command. This is useful if you want to make sure that a given environment is fully up to date and has modules recently declared in the environment's Puppetfile.

On the command line, run:
r10k deploy environment <ENVIRONMENT_NAME> --modules

Installing and updating modules

The r10k deploy module command installs or updates the modules specified in each environment's Puppetfile.

Update specific modules across all environments

To update specific modules across all environments, specify the modules with the r10k deploy module command.

Important: Before updating modules, you must Update all environments and modules.
To update one module across all environments, append the module name to the command, such as:
r10k deploy module <MODULE_NAME>
To update multiple modules across all environments, append the module names to the command, separated by spaces. For example, this command updates the apache, jenkins, and java modules:
r10k deploy module apache jenkins java

If a specified module is not declared in an environment's Puppetfile, that environment is skipped.

Update one or more modules in a single environment

To update specific modules in a specific environment, specify both the environment and the modules in your command.

Important: Before updating modules, you must Update a single environment and its modules.
The command format is:
r10k deploy module -e <ENVIRONMENT_NAME> <MODULE_NAME>
The first argument supplied after -e is interpreted as an environment name. Anything after this is treated as a module name. You can append multiple module names, but only one environment name.
For example, this command updates the apache, jenkins, and java modules in the production environment:
r10k deploy module -e production apache jenkins java

If the specified module is not described in a given environment's Puppetfile, that module is skipped.

Get environment details with r10k

The r10k deploy display command returns information about your environments and modules. This subcommand does not deploy environments, it only displays information about the environments and modules r10k is managing.

This command can return various levels of detail about the environments:

  • To get information about all environments r10k manages, run: 
    r10k deploy display
  • To get information about all managed environments and modules declared in their Puppetfiles, append the Puppetfile flag (-m). For example:
    r10k deploy display -m
  • To get expected and actual versions of modules in all environments, append the -m and --detail flags. For example:
    r10k deploy display -m --detail
  • To get expected and actual versions of modules in specific environments, append the -m and --detail flags along with one or more environment names, such as:
    r10k deploy display -m --detail <ENVIRONMENT_NAME> <ENVIRONMENT_NAME>