r10k is an absolutely amazing piece of software for managing and deploying Puppet configurations. It leverages the power of Version Control Systems to be able to roll an entire site backwards and forwards in changes.
For general use the standard Ruby Gems installation method should be just fine. If you need more check out the GitHub page.
/opt/puppetlabs/puppet/bin/gem install r10k
Configuration of r10k is also pretty simple and boils down to a couple of edits in the /etc/puppetlabs/r10k/r10k.yaml file. You basically need to tell it which VCS you're using (typically Git) and how to pull.
Note: especially for Git r10k has to be able to perform a pull passwordless which means using SSH keys. I talked with the author about this and he'll make a note in the documentation about it, but it might be easy to miss. If you just can't seem to pull, check that passwordless using the SSH keys work first.
# The location to use for storing cached Git repos :cachedir: '/var/cache/r10k' # A list of git repositories to create :sources: # This will clone the git repository and instantiate an environment per # branch in /etc/puppetlabs/code/environments :puppet: remote: 'https://repo.somecompany.net/operations/puppet.git' basedir: '/etc/puppetlabs/code/environments'
Further configuration is typically handled via the Puppetfile and the environment.conf. Essentially in your repository you should have a directory of self-maintained modules (most likely under /dist) and then use the /modules directory for publicly-pulled and updated modules, then place an environment.conf in your repo's base directory to tell Puppet how to load. With that in mind, in the ROOT of the repository insert two files file named Puppetfile and environment.conf.
# Each environment can have an environment.conf file. Its settings will only# affect its own environment. See docs for more info:# https://docs.puppetlabs.com/puppet/latest/reference/config_file_environment.html# Any unspecified settings use default values; some of those defaults are based# on puppet.conf settings.# If these settings include relative file paths, they'll be resolved relative to# this environment's directory.# Allowed settings and default values:manifest = manifestsmodulepath = dist:modules:site:$basemodulepath# manifest = (default_manifest from puppet.conf, which defaults to ./manifests)# config_version = (no script; Puppet will use the time the catalog was compiled)# environment_timeout = (environment_timeout from puppet.conf, which defaults to 0) # Note: unless you have a specific reason, we recommend only setting # environment_timeout in puppet.conf.
forge 'http://forge.puppetlabs.com' mod 'puppetlabs/apache' mod 'puppetlabs/apt' mod 'puppetlabs/concat' mod 'puppetlabs/firewall' mod 'puppetlabs/inifile' mod 'puppetlabs/java' mod 'dduvnjak/jmeter' mod 'puppetlabs/mysql' mod 'puppetlabs/passenger' mod 'puppetlabs/postgresql', '3.1.0' mod 'puppetlabs/puppetdb' mod 'puppetlabs/ruby' mod 'puppetlabs/stdlib' mod 'example42/puppi' mod 'example42/nrpe' mod 'fsalum/redis' mod 'jfryman/nginx' mod 'mkrakowitzer/deploy' mod "jenkins", :git => "git://github.com/jenkinsci/puppet-jenkins.git" mod 'jira', :git => 'git://github.com/brycejohnson/puppet-jira.git' mod 'ntp', :git => 'git://github.com/puppetlabs/puppetlabs-ntp.git'
r10k pulls and deploys your latest checked-in configurations from the VCS. Typically all changes will be pushed into the VCS, and then you later tell r10k to pull and deploy them. To deploy changes, use the following:
r10k deploy environment -p
Sometimes r10k will encounter an issue deploying a configuration. In order to get more information out of r10k as to what specific command has failed, you'll have to turn on debug output.
r10k deploy environment -p --verbose DEBUG