README.md 9.32 KB
Newer Older
1 2
# Librarian-puppet

PeteMS's avatar
PeteMS committed
3 4
[![Build Status](https://travis-ci.org/rodjek/librarian-puppet.png?branch=master)](https://travis-ci.org/rodjek/librarian-puppet)

5 6
## Introduction

Tim Sharpe's avatar
Tim Sharpe committed
7
Librarian-puppet is a bundler for your puppet infrastructure.  You can use
8
librarian-puppet to manage the puppet modules your infrastructure depends on,
9
whether the modules come from the [Puppet Forge](https://forge.puppetlabs.com/),
10 11 12
Git repositories or a just a path.

* Librarian-puppet can reuse the dependencies listed in your Modulefile
13
* Forge modules can be installed from [Puppetlabs Forge](https://forge.puppetlabs.com/) or an internal Forge such as [Pulp](http://www.pulpproject.org/)
14
* Git modules can be installed from a branch, tag or specific commit, optionally using a path inside the repository
15 16
* Modules can be installed from GitHub using tarballs, without needing Git installed
* Module dependencies are resolved transitively without needing to list all the modules explicitly
17

Tim Sharpe's avatar
Tim Sharpe committed
18 19 20 21

Librarian-puppet manages your `modules/` directory for you based on your
`Puppetfile`.  Your `Puppetfile` becomes the authoritative source for what
modules you require and at what version, tag or branch.
22

Tim Sharpe's avatar
Tim Sharpe committed
23 24 25
Once using Librarian-puppet you should not modify the contents of your `modules`
directory.  The individual modules' repos should be updated, tagged with a new
release and the version bumped in your Puppetfile.
26

27 28 29 30
It is based on [Librarian](https://github.com/applicationsonline/librarian), a
framework for writing bundlers, which are tools that resolve, fetch, install,
and isolate a project's dependencies.

31 32 33 34 35 36 37
## Versions

Librarian-puppet >= 1.1.0 requires Ruby 1.9 and uses the Puppet Forge API v3.
Versions < 1.1.0 works on Ruby 1.8.

See the [Changelog](Changelog.md) for more details.

38 39
## The Puppetfile

Tim Sharpe's avatar
Tim Sharpe committed
40 41 42
Every Puppet repository that uses Librarian-puppet will have a file named
`Puppetfile` in the root directory of that repository.  The full specification
for which modules your puppet infrastructure repository  depends goes in here.
43

44 45 46 47
### Simple Puppetfile

This Puppetfile will download all the dependencies listed in your Modulefile from the Puppet Forge

48
    forge "https://forgeapi.puppetlabs.com"
49 50 51 52

    modulefile


53 54
### Example Puppetfile

55
    forge "https://forge.puppetlabs.com"
Tim Sharpe's avatar
Tim Sharpe committed
56

57 58
    mod 'puppetlabs-razor'
    mod 'puppetlabs-ntp', "0.0.3"
Tim Sharpe's avatar
Tim Sharpe committed
59

60
    mod 'puppetlabs-apt',
61 62
      :git => "git://github.com/puppetlabs/puppetlabs-apt.git"

63
    mod 'puppetlabs-stdlib',
64 65
      :git => "git://github.com/puppetlabs/puppetlabs-stdlib.git"

66
    mod 'puppetlabs-apache', '0.6.0',
67 68
      :github_tarball => 'puppetlabs/puppetlabs-apache'

69

70
### Recursive module dependency resolution
71

72
When fetching a module all dependencies specified in its
73 74
`Modulefile` and `Puppetfile` will be resolved and installed.

75 76
### Puppetfile Breakdown

77
    forge "https://forge.puppetlabs.com"
Tim Sharpe's avatar
Tim Sharpe committed
78 79 80 81 82

This declares that we want to use the official Puppet Labs Forge as our default
source when pulling down modules.  If you run your own local forge, you may
want to change this.

83
    mod 'puppetlabs-razor'
Tim Sharpe's avatar
Tim Sharpe committed
84 85 86 87

Pull in the latest version of the Puppet Labs Razor module from the default
source.

88
    mod 'puppetlabs-ntp', "0.0.3"
Tim Sharpe's avatar
Tim Sharpe committed
89 90 91

Pull in version 0.0.3 of the Puppet Labs NTP module from the default source.

92
    mod 'puppetlabs-apt',
93 94
      :git => "git://github.com/puppetlabs/puppetlabs-apt.git"

Tim Sharpe's avatar
Tim Sharpe committed
95 96
Our puppet infrastructure repository depends on the `apt` module from the
Puppet Labs GitHub repos and checks out the `master` branch.
97

98
    mod 'puppetlabs-apt',
99
      :git => "git://github.com/puppetlabs/puppetlabs-apt.git",
100 101
      :ref => '0.0.3'

Tim Sharpe's avatar
Tim Sharpe committed
102 103
Our puppet infrastructure repository depends on the `apt` module from the
Puppet Labs GitHub repos and checks out a tag of `0.0.3`.
104

105
    mod 'puppetlabs-apt',
106
      :git => "git://github.com/puppetlabs/puppetlabs-apt.git",
107 108
      :ref => 'feature/master/dans_refactor'

Tim Sharpe's avatar
Tim Sharpe committed
109 110
Our puppet infrastructure repository depends on the `apt` module from the
Puppet Labs GitHub repos and checks out the `dans_refactor` branch.
111

Tim Sharpe's avatar
Tim Sharpe committed
112 113
When using a Git source, we do not have to use a `:ref =>`.
If we do not, then librarian-puppet will assume we meant the `master` branch.
114

Tim Sharpe's avatar
Tim Sharpe committed
115 116
If we use a `:ref =>`, we can use anything that Git will recognize as a ref.
This includes any branch name, tag name, SHA, or SHA unique prefix. If we use a
Joshua Johnson's avatar
Joshua Johnson committed
117
branch, we can later ask Librarian-puppet to update the module by fetching the
Tim Sharpe's avatar
Tim Sharpe committed
118
most recent version of the module from that same branch.
119

Tim Sharpe's avatar
Tim Sharpe committed
120 121 122 123 124 125
The Git source also supports a `:path =>` option. If we use the path option,
Librarian-puppet will navigate down into the Git repository and only use the
specified subdirectory. Some people have the habit of having a single repository
with many modules in it. If we need a module from such a repository, we can
use the `:path =>` option here to help Librarian-puppet drill down and find the
module subdirectory.
126

127
    mod 'puppetlabs-apt',
128
      :git => "git://github.com/fake/puppet-modules.git",
129 130
      :path => "modules/apt"

Tim Sharpe's avatar
Tim Sharpe committed
131 132
Our puppet infrastructure repository depends on the `apt` module, which we have
stored as a directory under our `puppet-modules` git repos.
133 134 135

## How to Use

Tim Sharpe's avatar
Tim Sharpe committed
136
Install librarian-puppet:
137

Tom De Vylder's avatar
Tom De Vylder committed
138
    $ gem install librarian-puppet
139 140 141 142 143

Prepare your puppet infrastructure repository:

    $ cd ~/path/to/puppet-inf-repos
    $ (git) rm -rf modules
Tim Sharpe's avatar
Tim Sharpe committed
144
    $ librarian-puppet init
145

Tim Sharpe's avatar
Tim Sharpe committed
146 147 148 149
Librarian-puppet takes over your `modules/` directory, and will always
reinstall (if missing) the modules listed the `Puppetfile.lock` into your
`modules/` directory, therefore you do not need your `modules/` directory to be
tracked in Git.
150

Tim Sharpe's avatar
Tim Sharpe committed
151 152
Librarian-puppet uses a `.tmp/` directory for tempfiles and caches. You should
not track this directory in Git.
153

Tim Sharpe's avatar
Tim Sharpe committed
154 155
Running `librarian-puppet init` will create a skeleton Puppetfile for you as
well as adding `tmp/` and `modules/` to your `.gitignore`.
156 157 158

    $ librarian-puppet install [--clean] [--verbose]

Tim Sharpe's avatar
Tim Sharpe committed
159 160 161 162
This command looks at each `mod` declaration and fetches the module from the
source specified.  This command writes the complete resolution into
`Puppetfile.lock` and then copies all of the fetched modules into your
`modules/` directory, overwriting whatever was there before.
163

Tim Sharpe's avatar
Tim Sharpe committed
164
Get an overview of your `Puppetfile.lock` with:
165 166 167

    $ librarian-puppet show

Tim Sharpe's avatar
Tim Sharpe committed
168
Inspect the details of specific resolved dependencies with:
169 170 171

    $ librarian-puppet show NAME1 [NAME2, ...]

Tim Sharpe's avatar
Tim Sharpe committed
172
Find out which dependencies are outdated and may be updated:
173 174 175

    $ librarian-puppet outdated [--verbose]

Tim Sharpe's avatar
Tim Sharpe committed
176
Update the version of a dependency:
177 178 179 180 181 182

    $ librarian-puppet update apt [--verbose]
    $ git diff Puppetfile.lock
    $ git add Puppetfile.lock
    $ git commit -m "bumped the version of apt up to 0.0.4."

183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248
## Configuration

Configuration comes from three sources with the following highest-to-lowest
precedence:

* The local config (`./.librarian/puppet/config`)
* The environment
* The global config (`~/.librarian/puppet/config`)

You can inspect the final configuration with:

    $ librarian-puppet config

You can find out where a particular key is set with:

    $ librarian-puppet config KEY

You can set a key at the global level with:

    $ librarian-puppet config KEY VALUE --global

And remove it with:

    $ librarian-puppet config KEY --global --delete

You can set a key at the local level with:

    $ librarian-puppet config KEY VALUE --local

And remove it with:

    $ librarian-puppet config KEY --local --delete

You cannot set or delete environment-level config keys with the CLI.

Configuration set at either the global or local level will affect subsequent
invocations of `librarian-puppet`. Configurations set at the environment level are
not saved and will not affect subsequent invocations of `librarian-puppet`.

You can pass a config at the environment level by taking the original config key
and transforming it: replace hyphens (`-`) with underscores (`_`) and periods
(`.`) with doubled underscores (`__`), uppercase, and finally prefix with
`LIBRARIAN_PUPPET_`. For example, to pass a config in the environment for the key
`part-one.part-two`, set the environment variable
`LIBRARIAN_PUPPET_PART_ONE__PART_TWO`.

Configuration affects how various commands operate.

* The `path` config sets the cookbooks directory to install to. If a relative
  path, it is relative to the directory containing the `Puppetfile`. The
  equivalent environment variable is `LIBRARIAN_PUPPET_PATH`.

* The `tmp` config sets the cache directory for librarian. If a relative
  path, it is relative to the directory containing the `Puppetfile`. The
  equivalent environment variable is `LIBRARIAN_PUPPET_TMP`.

Configuration can be set by passing specific options to other commands.

* The `path` config can be set at the local level by passing the `--path` option
  to the `install` command. It can be unset at the local level by passing the
  `--no-path` option to the `install` command. Note that if this is set at the
  environment or global level then, even if `--no-path` is given as an option,
  the environment or global config will be used.



249 250
## How to Contribute

Tim Sharpe's avatar
Tim Sharpe committed
251 252
 * Pull requests please.
 * Bonus points for feature branches.
253 254 255

## Reporting Issues

Tim Sharpe's avatar
Tim Sharpe committed
256 257
Bug reports to the github issue tracker please.
Please include:
258

Joshua Johnson's avatar
Joshua Johnson committed
259
 * Relevant `Puppetfile` and `Puppetfile.lock` files
260
 * Version of ruby, librarian-puppet, and puppet
Tim Sharpe's avatar
Tim Sharpe committed
261 262 263
 * What distro
 * Please run the `librarian-puppet` commands in verbose mode by using the
  `--verbose` flag, and include the verbose output in the bug report as well.
264

Tim Sharpe's avatar
Tim Sharpe committed
265

266
## License
Tim Sharpe's avatar
Tim Sharpe committed
267 268
Please see the [LICENSE](https://github.com/rodjek/librarian-puppet/blob/master/LICENSE)
file.