Skip to content

R10K

What is R10K ?

Description

R10k provides a general purpose toolset for deploying Puppet environments and modules. It implements the Puppetfile format and provides a native implementation of Puppet dynamic environments.

Synopsis

Fundamentally, R10k installs a set of modules into a speicifed module directory and verifies their freshnes

So why is it called R10k ?

In true fasion the Puppet guys are terible at names. While Adrien aka finch was attempting to come up with a clever name, he recalled that Randall Munroe wrote a bot for controlling IRC chatter, and gave it the most generic name he could think of - Robot 9000. Since Adrien just needed a name, any name,he decided to go with an equally generic name by incrementing the robot index.

Installation and Configuration

The easiest way to manually install R10k is via ruby gems

gem install r10k

Configure r10k by editing /etc/r10k.yaml and ensuring it has the following contents:

:cachedir: /var/cache/r10k
:sources:
  puppet:
    basedir: /etc/puppet/environments
    prefix: false
    remote: https://github.com/repo.git

:purgedirs:
  - /etc/puppet/environments

Another common solution for installation is via the R10K Puppet module. This will install the R10k Ruby gem as well as configure the /etc/r10k.yaml file

Example Installation:

class { 'r10k':
    version           => '1.4.1',
    sources           => {
      'puppet' => {
        'remote'  => 'PATH_TO_REPO',
        'basedir' => "${::settings::confdir}/environments",
        'prefix'  => false,
      },
    },
    purgedirs         => ["${::settings::confdir}/environments"],
    manage_modulepath => false,
  }

Puppetfile

Puppetfiles are a simple Ruby based DSL that specifies a list of modules to install, what version to install, and where to fetch them from.

R10k uses a Puppetfile to install a set of Puppet modules for local development, or environment deployments to install additional modules into a given environment.

Unlike librarian-puppet, the r10k implementation of Puppetfiles does not include dependency resolution, but it is on the roadmap.

Global Settings

The forge setting specifies which server that Forge based modules are fetched from.

forge "https://forge.puppetlabs.com"

The moduledir setting specifies where modules from the Puppetfile will be installed. This defaults to the modules directory relative to the Puppetfile. If the path is absolute then the modules will be installed to that absolute path, otherwise it's assumed that the moduledir setting should be relative and the modules will be installed in that directory relative to the Puppetfile.

Common Patterns

GIT

mod 'puppetlabs-apache',
  :git => 'https://github.com/puppetlabs/puppetlabs-apache.git'

SVN

mod 'apache',
  :svn => 'https://github.com/puppetlabs/puppetlabs-apache/trunk'

FORGE

mod 'puppetlabs/apache'

Common Commands

Install or update all modules in a given Puppetfile into ./modules)

r10k puppetfile install

Verify the Puppetfile syntax

r10k puppetfile check

Remove any modules in the 'modules' directory that are not specified in the Puppetfile:

r10k puppetfile purge

Dynamic Environments

One of the most important functions of r10k is its ability to dynamically manage your Puppet environments.

The core idea of dynamic environments is that you should be able to manage your Puppet modules in the same manner that you would manage any other code base. This builds on top of the GIT topic/feature branch model

Whenever changes need to be made that need to be reviewed or tested before going live, they should be done in a different, short lived branch called a topic/feature branch. Work can be freely done on a topic branch in isolation and when the work is completed it is merged into a "master" or "production" branch.

How it works

R10k works by tracking the state of your Git repository or repositories. Each repository's branches will be cloned into a directory with a matching name, creating a Puppet environment for the branch.

If a repository includes a Puppetfile such as a control repository. Forge modules and Git/SVN repositories described within will be cloned as well into the same directory. Subsequent changes to the branches will be kept in sync on the filesystem by future r10k runs.

Finally, if there are directories that do not match existing branches, r10k will assume that the branches for those environments were delete and will remove those environments.

r10k will need to be be able to authenticate with each repository. Most Git systems support authentication with SSH keys. GitHub calls them deploy keys. Bitbucket calls them deployment keys. Stash calls them SSH access keys.

Workflow

Adding New Modules

This workflow is used when adding new modules via the forge or a VCS source such as git. These can be either public or internally-developed

  1. Create a topic/feature branch in the repository in which your Puppetfile resides. This is usually the control repository
git checkout -b feature_branch
  1. Update the Puppetfile to include a section declaring the new module

mod "user-custom_facts",
  :git => "git://github.com/user/custom_facts"
1. Commit your changes and push the Puppetfile topic/feature branch upstream

git commit -a -m ‘Add module user/module to branch feature_branch'
git push origin feature_branch
1. Reference the new module in manifest, module and/or hiera

If you are simply adding the module at this time and not referencing it in other modules or manifests, you may skip these step(s). 1. Create topic/feature branch for the manifest, module or hiera data that you are modifying.

  ```
  git checkout -b feature_branch
  ```
  1. Modify the exisiting manifest, module or hiera data and commit your changes and push the topic/feature branch upstream

    git commit -a -m ‘Add feature reference to module’
    git push origin feature_branch
    
    1. Deploy feature_branch Puppet Environment

    Can be a hook to automatically deploy environments

r10k deploy environment -p 
1. Testing New Module Branches

If you are simply adding the module at this time and not referencing it in other modules or manifests, you may skip this step.

There are many methods for testing a cheap/easy for testing is to specify the environment and noop flags

puppet agent -t --environment feature_branch --noop
Verify the changes are successful, match your expected changes and you are satisfied by the results

  1. Merge your changes for the repository in which your Puppetfile resides ( Control Repository ) into the master/production branch.
git checkout production
git merge feature_branch
git push origin production
  1. Merge your changes for the manifest, module and/or hiera repositories referencing the new module.

    If you are simply adding the module at this time and not referencing it in other modules or manifests, you may skip this step.

git checkout production
git merge feature_branch
git push origin production
  1. Cleanup topic/feature branches

    You may skip this step for long-lived branches, however most feature branches should be short-lived and can be pruned once testing and merging is complete.

git branch -D feature_branch
git push origin :feature_branch

Editing Existing Modules

This workflow is used when updating existing modules.

  1. Create topic/feature branch for the manifest, module or hiera data that you are modifying.

git checkout -b feature_branch
1. Modify the exisiting manifest, module or hiera data, commit your changes and push the topic/feature branch upstream

git commit -a -m ‘Add feature reference to module’
git push origin feature_branch
  1. Update the Puppetfile repository to to reference new branch of the updated module

mod "user-custom_facts",
    :git => "git://github.com/user/custom_facts"
    :ref => "feature_branch"
1. Commit your changes and push the Puppetfile topic/feature branch upstream

git commit -a -m ‘updating module user/module to branch feature_branch'
git push origin feature_branch
  1. Deploy feature_branch Puppet Environment

r10k deploy environment -p 
1. Test New Module Branches

There are many methods for testing a cheap/easy for testing is to specify the environment and noop flags

puppet agent -t --environment feature_branch --noop

Verify the changes are successful, match your expected changes and you are satisfied by the results

  1. Merge your changes for the manifest, module and/or hiera repositories for the updated module(s).

git checkout production
git merge feature_branch
git push origin production
1. Merge your changes for the repository in which your Puppetfile resides ( Control Repository ) into the master/production branch.

git checkout production
git merge feature_branch
git push origin production
1. Cleanup topic/feature branches

You may skip this step for long-lived branches, however most feature branches should be short-lived and can be pruned once testing and merging is complete.

git branch -D feature_branch
git push origin :feature_branch

This is a vanilla workflow. You may need or desire to customize the workflow to fit the needs of your team, tools and methodolgy used.

Post Receive Hooks

SVN and GIT post-receive hooks can but used to help streamline your R10k workflow. Providing you with the ability to quickly and painlessly create Puppet environments to verify and test your code changes.

The Puppet r10k module by Zack Smith details the integration support for MCollective and R10k in combination with a custom webhook that provides GitHub support.

Another popular post-receive hook is reaktor.

References

Puppetlabs Github R10k

Sh*t Gary Says: R10k + Directory Environments

Puppetlabs Directory Environments

terrarum: Puppet Infrastructure with r10k

somthingsinisetal: Rethinking Puppet Deployment

R10k Control Repos

Reaktor: post-receive hook

R10k Puppetfile

R10k: Workflow Guide

http://webcache.googleusercontent.com/search?q=cache:-FkbO79nhqEJ:www.geoffwilliams.me.uk/r10k_mco_publisher+&cd=6&hl=en&ct=clnk&gl=us&client=safari