r10k
====

Puppet environment and module deployment

[![Build Status](https://travis-ci.org/puppetlabs/r10k.png?branch=master)](https://travis-ci.org/puppetlabs/r10k)

Description
-----------

[workflow]: http://puppetlabs.com/blog/git-workflow-and-puppet-environments/

R10k provides a general purpose toolset for deploying Puppet environments and
modules. It implements the [Puppetfile](doc/puppetfile.mkd) format and provides a native
implementation of Puppet [dynamic environments][workflow].

Requirements
------------

R10k supports the following Ruby versions:

  - 1.8.7 (POSIX minimum version, deprecated)
  - 1.9.3 (Windows minimum version)
  - 2.0.0
  - 2.1.0

R10k requires additional components, depending on how you plan on managing
environments and modules.

  - Installing modules from the Puppet Forge requires Puppet 3.0.0+ or later.
  Puppet 2.7 may work, but is generally not recommended as Puppet 2.7 is EOL.
  - Git is required for creating environments and modules from Git
  - SVN is required for creating environments and modules from SVN

### Ruby 1.8.7 is deprecated

As of r10k 1.5.0, support for Ruby 1.8.7 is deprecated. Because of the
increasing cost of supporting Ruby 1.8.7, issues only affecting 1.8.7 will be
fixed but will have a lower priority.

Support for 1.8.7 will be dropped entirely in r10k 2.0.0.

Installation
------------

### Rubygems

For general use, you should install r10k from Ruby gems:

    gem install r10k
    r10k help

### Puppet Enterprise

Puppet Enterprise bundles a copy of Ruby, so if you do not want to use the
system version of Ruby with r10k, you need to use the bundled PE gem command for
installation:

    /opt/puppet/bin/gem install r10k
    r10k help

### Bundler

If you have more specific needs or plan on modifying r10k you can run it out of
a git repository using Bundler for dependencies:

    git clone git://github.com/puppetlabs/r10k
    cd r10k
    bundle install
    bundle exec r10k help

Usage
-----

R10k has two primary roles: installing Puppet modules using a standalone
Puppetfile, and managing Git and SVN based dynamic environments. For more
information see the topic specific documentation:

  * [Puppetfile Documentation](doc/puppetfile.mkd)
  * [Environment Deployment Documentation](doc/dynamic-environments.mkd)
  * [Quickstart](doc/dynamic-environments/quickstart.mkd)
  * [Common Patterns](doc/common-patterns.mkd)
  * [Workflow Guide](doc/dynamic-environments/workflow-guide.mkd)

For more general questions, see the [FAQ](doc/faq.mkd).

Getting help
------------

  * IRC: r10k has a dedicated channel, `#r10k`, on Freenode where r10k questions
  can be directed. Questions about r10k can frequently be asked in `#puppet` as well.
  * Mailing lists: [puppet-users](https://groups.google.com/forum/#!forum/puppet-users)
  * Q&A: [Puppet Ask](https://ask.puppetlabs.com/questions/)


More information
----------------

The original impetus for r10k is explained at http://somethingsinistral.net/blog/rethinking-puppet-deployment/

Contributors
------------

Please see the CHANGELOG for a listing of the (very awesome) contributors.