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
- Create a topic/feature branch in the repository in which your Puppetfile resides. This is usually the control repository
git checkout -b feature_branch
- Update the Puppetfile to include a section declaring the new module
mod "user-custom_facts", :git => "git://github.com/user/custom_facts"
git commit -a -m ‘Add module user/module to branch feature_branch' git push origin feature_branch
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 ```
-
Modify the exisiting manifest, module or hiera data and commit your changes and push the topic/feature branch upstream
1. Deploy feature_branch Puppet Environmentgit commit -a -m ‘Add feature reference to module’ git push origin feature_branch
Can be a hook to automatically deploy environments
r10k deploy environment -p
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
- 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
- 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
- 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.
- Create topic/feature branch for the manifest, module or hiera data that you are modifying.
git checkout -b feature_branch
git commit -a -m ‘Add feature reference to module’ git push origin feature_branch
- 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"
git commit -a -m ‘updating module user/module to branch feature_branch' git push origin feature_branch
- Deploy feature_branch Puppet Environment
r10k deploy environment -p
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
- 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
git checkout production git merge feature_branch git push origin production
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¶
Sh*t Gary Says: R10k + Directory Environments
Puppetlabs Directory Environments
terrarum: Puppet Infrastructure with r10k