r10k
====

Puppet environment and module deployment

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

> R10k is supported and maintained by Puppet, but we consider it to be feature
> complete and currently have no plans for any new development. We will keep it
> working within the context of Puppet Enterprise, but we cannot make any other
> maintenance promises at this time.


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

[workflow]: https://puppet.com/docs/puppet/latest/environments_about.html

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 [environments][workflow].

You might also consider [g10k](https://github.com/xorpaul/g10k) as a non-ruby
based alternative.


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

R10k supports the Ruby versions `>= 2.6.0`. It's tested on Ruby 2.6.0 up to
Ruby 3.1.0 + Jruby.

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

  - Installing modules from the Puppet Forge requires Puppet 7.0.0+ or later.
  Puppet 5 and 6 may work, but is generally not recommended.
  - Git is required for creating environments and modules from Git
  - SVN is required for creating environments and modules from SVN

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

### Rubygems

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

    gem install r10k
    r10k help

### Puppet Enterprise 3.x

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

### Puppet 4

Puppet 4 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 puppet gem command
for installation.

    /opt/puppetlabs/puppet/bin/gem install r10k
    /opt/puppetlabs/puppet/bin/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 https://github.com/puppetlabs/r10k
    cd r10k
    bundle install
    bundle exec r10k help

### Arch Linux

Arch Linux provides a [system package](https://archlinux.org/packages/extra/any/r10k/) for r10k.
This is built against the [system Ruby](https://archlinux.org/packages/extra/x86_64/ruby/) (which is Ruby 3.0.2 as of 2021-08-03).
This package is maintained by [Tim Meusel](https://github.com/bastelfreak).

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)
   * [Updating your Puppetfile](doc/updating-your-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).

Development
-----------

### i18n

R10k has now had all user-facing strings in error messages and log messages
externalized. When adding new error or log messages please follow the
instructions for [writing translatable code](https://github.com/puppetlabs/gettext-setup-gem#writing-translatable-code).

### l10n

When localizing the strings found in R10k, follow the prescribed
[translation workflow](https://github.com/puppetlabs/gettext-setup-gem#translation-workflow).
The workflow describes the rake tasks provided to generate the .po files for
each locale.

Releasing
---------
To release a new version of the r10k gem, ensure the [changelog](CHANGELOG.mkd) is up to date and open a pull request updating the [version file](lib/r10k/version.rb). When the PR is merged, a new release of the gem will be triggered.

By default, a patch (Z) release will be triggered. To release a new major (X) or minor (Y) version, include `#major` or `#minor` (respectively) in your commit message to trigger the appropriate release.

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

  * [Puppet Community Slack](https://puppetcommunity.slack.com/)
  * Mailing lists: [puppet-users](https://groups.google.com/forum/#!forum/puppet-users)
  * Q&A: [Puppet Ask](https://ask.puppetlabs.com/questions/)

## Maintenance

See [CODEOWNERS](CODEOWNERS) for current project owners.