A collection of task oriented solutions in Puppet

 

Get started with puppet-lint

Challenge

You want to ensure your puppet code meets the Puppet Style Guide

Solution

Install puppet-lint

# install the newest version of puppet-lint
$ gem install puppet-lint

Fetching: puppet-lint-2.3.0.gem (100%)
Successfully installed puppet-lint-2.3.0
1 gem installed

# show the installed versions
$ gem list puppet-lint

*** LOCAL GEMS ***
puppet-lint (2.3.0)

and run it against your manifests

$ puppet-lint foo.pp

ERROR: foo not in autoload module layout on line 1
WARNING: class not documented on line 1

Any code that fails to pass the Puppet Style Guide recommendations will be shown in the output.

Explanation

There is a great quote in programming world, "it doesn't matter which style guide you have, as long as you have one." and this applies to your puppet code as much as it would any other language. Thanks to the awesome work done by Tim Sharpe, in the form of puppet-lint, you can check your code against the Puppet style guide with nothing more than a gem install and running a single command.

There are a few ways to install puppet-lint, the simplest when getting started is to use your systems native gem command. As you become a more advanced user you may want to install it via bundler and a Gemfile but that is outside the scope of this recipe.

# install the newest version of puppet-lint
$ gem install puppet-lint

Fetching: puppet-lint-2.3.0.gem (100%)
Successfully installed puppet-lint-2.3.0
1 gem installed

# show the installed versions
$ gem list puppet-lint

*** LOCAL GEMS ***
puppet-lint (2.3.0)

Once installed you can run puppet-lint against a single manifest or a directory of modules, depending on your tolerance for "I have to change how much?", and read through the exceptions and the corresponding Style Guide sections.

While you might not see an immediate gain in subjecting yourself to all the changes you'll have to make to be compliant, and in some cases you might disagree with the guide, it's well worth taking the time to read through the exceptions at least once and see where they'd improve your code base. You may get early warnings about features that are being deprecated, edge use cases with sometimes subtle, often unexpected behaviour or even, with the addition of plugins, warnings about insecure behaviour in your resources. The wider puppet community also heavily embraces puppet-lint and most of the third party modules, especially those on the Puppet Forge, will be formatted to be compliant with its checks. If you're planning on getting involved in the wider community knowing the common style is an asset.

The amount of output from an initial run can be daunting, especially if you don't follow the one repository per module pattern, but there are a few ways to help handle the ramp up. You can disable certain checks if you disagree with them:

# don't show manifests failing either of these checks
puppet-lint --no-documentation-check --no-80chars-check modules

You can even start even slower and only enable a few checks at a time:

$ puppet-lint --only-checks 140chars mymodules

mymodules/assets.pp - WARNING: line has more than 140 characters on line 65

Once you decide on which checks you do or don't want to run you can add them to a .puppet-lint.rc file and check them in alongside your puppet code to ensure everyone on the team has the same settings:

# puppet-lint will not run
# these checks against your code
$ cat .puppet-lint.rc
--no-140chars-check
--no-documentation-check
--no-star_comments-check

There is also a --fix mode that will attempt to automatically resolve a number of puppet-lint check failures for you. I'd only recommend running this if you're keeping your code under version control, being able to diff the changes it makes is essential. The command itself is simply:

puppet-lint --fix my_module_directory

Once you've become comfortable with the core checks you may decide you want to enforce some additional extra rules or use other peoples. There is a community of plugin writers extending puppet-lint in a number of ways and adding their extensions needs nothing more than a few additional gem install commands. You can find out more about this in the Add puppet-lint checks recipe.

See also