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 can use a Puppetfile to install a set of Puppet modules for local development, or they can be used with r10k 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. When directly working with Puppetfiles, you can use the `r10k puppetfile` subcommand to interact with a Puppetfile. When using r10k's deploy functionality, interacting with Puppetfiles is handled on a case by case basis. Because the Puppetfile format is actually implemented using a Ruby DSL any valid Ruby expression can be used. That being said, being a bit too creative in the DSL can lead to surprising (read: bad) things happening, so consider keeping it simple. Commands -------- Puppetfile subcommands assume that the Puppetfile to operate on is in the current working directory and modules should be installed in the 'modules' directory relative to the current working directory. 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 Global settings --------------- The following settings can be used to control how the Puppetfile installs and handles modules. ### forge The `forge` setting specifies which server that Forge based modules are fetched from. This is currently a noop and is provided for compatibility with librarian-puppet, but will be made functional in a future version. See [GH-106](https://github.com/adrienthebo/r10k/issues/106) for more information. ### moduledir 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. The moduledir setting should be placed before any modules are declared. Install modules to an absolute path: ```ruby moduledir '/etc/puppet/modules' mod 'branan/eight_hundred' # will be installed into '/etc/puppet/modules/eight_hundred' ``` Install modules to a relative path: ```ruby moduledir 'thirdparty' mod 'branan/eight_hundred' # will be installed into `dirname /path/to/Puppetfile`/thirdparty/eight_hundred ``` **Note**: support for a relative moduledir was added in r10k 1.4.0; the behavior of a relative moduledir path is undefined on earlier versions of r10k. Module types ------------ r10k can install Puppet modules from a number of different sources. Right now modules can be installed via Git, SVN, and from the Puppet Forge. ### Git Git repositories that contain a Puppet module can be cloned and used as modules. When Git is used, the module version can be specified by using `:ref`, `:tag`, `:commit`, and `:branch`. When a module is installed using `:ref`, r10k uses some simple heuristics to determine the type of Git object that should be checked out. This can be used with a git commit, branch reference, or a tag. When a module is installed using `:tag` or `:commit`, r10k assumes that the given object is a tag or commit and can do some optimizations around fetching the object. If the tag or commit is already available r10k will skip network operations when updating the repo, which can speed up install times. Module versions can also be specified using `:branch`. This behaves similarly to `:ref`, and is mainly useful for clarity. #### Examples # Install puppetlabs/apache and keep it up to date with 'master' mod 'apache', :git => 'https://github.com/puppetlabs/puppetlabs-apache' # Install puppetlabs/apache and track the 'docs_experiment' branch mod 'apache', :git => 'https://github.com/puppetlabs/puppetlabs-apache', :ref => 'docs_experiment' # Install puppetlabs/apache and pin to the '0.9.0' tag mod 'apache', :git => 'https://github.com/puppetlabs/puppetlabs-apache', :tag => '0.9.0' # Install puppetlabs/apache and pin to the '83401079' commit mod 'apache', :git => 'https://github.com/puppetlabs/puppetlabs-apache', :commit => '83401079053dca11d61945bd9beef9ecf7576cbf' # Install puppetlabs/apache and track the 'docs_experiment' branch mod 'apache', :git => 'https://github.com/puppetlabs/puppetlabs-apache', :branch => 'docs_experiment' ### Forge Modules can be installed using the Puppet module tool. If no version is specified the latest version available at the time will be installed, and will be kept at that version. mod 'puppetlabs/apache' If a version is specified then that version will be installed. mod 'puppetlabs/apache', '0.10.0' If the version is set to :latest then the module will be always updated to the latest version available. mod 'puppetlabs/apache', :latest ### SVN Modules can be installed via SVN. If no version is given, the module will track the latest version available in the main SVN repository. mod 'apache', :svn => 'https://github.com/puppetlabs/puppetlabs-apache/trunk' If an SVN revision number is specified with `:rev` (or `:revision`), that SVN revision will be kept checked out. mod 'apache', :svn => 'https://github.com/puppetlabs/puppetlabs-apache/trunk', :rev => '154' mod 'apache', :svn => 'https://github.com/puppetlabs/puppetlabs-apache/trunk', :revision => '154' If the SVN repository requires credentials, you can supply the `:username` and `:password` options. mod 'apache', :svn => 'https://github.com/puppetlabs/puppetlabs-apache/trunk', :username => 'azurediamond', :password => 'hunter2' **Note**: SVN credentials are passed as command line options, so the SVN credentials may be visible in the process table when r10k is running. If you choose to supply SVN credentials make sure that the system running r10k is appropriately secured. ## Environment variables It is possible to set an alternate name/location for your `Puppetfile` and `modules` directory. This is useful if you want to control multiple environments and have a single location for your `Puppetfile`. Example: PUPPETFILE=/etc/r10k.d/Puppetfile.production \ PUPPETFILE_DIR=/etc/puppet/modules/production \ /usr/bin/r10k puppetfile install NOTE: using these environment variables is not a suggested configuration, and have different semantics than librarian-puppet. Specifically, the PUPPETFILE_DIR is the environment that r10k will install modules into, and it will take full control over that directory and _remove any unmanaged content_. Use these variables with caution.