Tim Sharpe - Puppet

Automatically Test Your Puppet Modules With rspec-puppet, puppet-lint And Travis CI

2012-03-02T00:00:00+11:00

I’m going to assume you’ve got a Puppet module already on GitHub. To save messing around with bundler on your local machine, I recommend installing puppet-lint and rspec-puppet as system gems while you’re getting this all set up.

1
2

$ gem install puppet-lint
$ gem install rspec-puppet

rspec-puppet

First of all, let’s create a directory structure for your spec files

$ mkdir -p spec/classes spec/defines spec/fixtures/manifests
$ mkdir -p spec/fixtures/modules/<your module name>
$ cd spec/fixtures/modules/<your module name>
$ touch spec/fixtures/manifests/init.pp
$ for i in files lib manifests templates; do ln -s ../../../../$i $i; done

If you’re wondering about that last line, we symlink the contents of the module into spec/fixtures/modules/<your module name> so that we can trick Puppet’s autoloader when running the specs.

Next, we need to configure rspec-puppet, so create spec/spec_helper.rb with the following contents

require 'rspec-puppet'

fixture_path = File.expand_path(File.join(__FILE__, '..', '..', 'fixtures'))

RSpec.configure do |c|
  c.module_path = File.join(fixture_path, 'modules')
  c.manifest_dir = File.join(fixture_path, 'manifests')
end

Now, all we need is a Rake task to fire up the tests. Create a Rakefile in the root directory of your module with the following contents

require 'rake'

require 'rspec/core/rake_task'

RSpec::Core::RakeTask.new(:spec) do |t|
  t.pattern = 'spec/*/*_spec.rb'
end

You can now run rake spec to run your rspec-puppet tests

puppet-lint

Next up, we’ll also get some automatic lint testing of your manifests going to ensure you’re writing manifests that comply with the Puppet Labs style guide. This is simply a matter adding the following line near the top of your Rakefile

`1`	require 'puppet-lint/tasks/puppet-lint'

You can now run rake lint to run puppet-lint over your manifests.

Travis CI

Travis CI is a wonderful free continuous integration service that integrates with GitHub, running whatever tests you want against your code every time you push.

To get Travis CI automatically testing your module you need to add a couple of files to the root directory of your module.

First, create a Gemfile which tells bundler which ruby gems your tests need in order to run. If your module needs any additional gems, just add them to the bottom of this file.

source :rubygems

if ENV.key?('PUPPET_VERSION')
  puppetversion = "= #{ENV['PUPPET_VERSION']}"
else
  puppetversion = ['>= 2.7']
end

gem 'rake'
gem 'puppet-lint'
gem 'rspec-puppet'
gem 'puppet', puppetversion

We also need to create .travis.yml which holds our Travis CI test config.

rvm: 1.8.7
notifications:
  email:
    - <your email address>
env:
  - PUPPET_VERSION=2.6.14
  - PUPPET_VERSION=2.7.11

This basically says, we want to use Ruby 1.8.7, run two sets of tests, one against Puppet 2.6.14 and the other against Puppet 2.7.11 and email the notifications through to your email address.

There’s one last thing we need to do and that is create a default rake task that runs both rake spec and rake lint. To do that, add the following to the end of your Rakefile.

`1`	task :default => [:spec, :lint]

If you haven’t already done so, commit and push all this up to GitHub.

Point your browser Travis CI and login with your GitHub account. In your profile page, turn on tests for your module’s repository.

And wait for them to run!

TL;DR

Go check out my logrotate module for a working example.

Stop Writing Puppet Modules That Suck

2011-12-27T00:00:00+11:00

Whenever I need to setup a new service on one of my hosts, the first thing I do is head to the forge and GitHub to try and find a decent Puppet module that already exists for it.

I almost always leave in disappointment.

Puppet modules are libraries

Much like string.h provides everything you need to manipulate strings in C, your Puppet modules should provide everything needed to manage a service out of the box. By that I mean, I want to pull down your module to enable the functionality I need in Puppet without modifying your module at all.

Package, File, Service

Regrettably, most of the modules out there don’t deviate from the basic package, file, service model.

class ntp {
  package { 'ntp':
    ensure => installed,
  }

  file { '/etc/ntp.conf':
    ensure  => file,
    source  => 'puppet:///modules/ntp/etc/ntp.conf',
    owner   => 'root',
    group   => 'root',
    mode    => '0444',
    require => Package['ntp'],
    notify  => Service['ntp'],
  }

  service { 'ntp':
    ensure => 'running',
    enable => 'true',
  }
}

While this might be all you need in your homogeneous environment, it’s unlikely that this will work in someone elses environment without modifications.

Package, File, Service, Facter

A common extension to this model is to add conditionals using Facter variables to cover a set of different use cases (CentOS vs Debian, etc).

class ntp {
  case $::operatingsystem {
    Debian: {
      $packagename = 'openntp'
      $servicename = 'openntp'
    }
    default: {
      $packagename = 'ntp'
      $servicename = 'ntp'
    }
  }

  package { $packagename:
    ensure => installed,
  }

  file { '/etc/ntp.conf':
    ensure  => file,
    source  => 'puppet:///modules/ntp/etc/ntp.conf',
    owner   => 'root',
    group   => 'root',
    mode    => '0444',
    require => Package[$packagename],
    notify  => Service[$servicename],
  }

  service { $servicename:
    ensure => 'running',
    enable => true,
  }
}

While this is slightly more useful, it doesn’t cover the possibility of wanting to override a value on a per-host basis.

Package, File, Service, Facter and… Global Variables? Seriously?

If you ask most people for the “best practice” method of passing parameters to their modules, they’ll probably recommend using global variables - where you set a variable in your node definition or ENC and it magically gets picked up inside the various classes that you’ve included.

node 'foo.example.com' {
  $ntp_running = true
  $monitor = true
  $backup = true
  $fml = true

  include ntp
}

class ntp {
  # trimmed for brevity

  service { $servicename:
    ensure => $ntp_running ? {
      true  => 'running',
      false => 'stopped',
    },
  }
}

Do we really need to go into why this is a bad idea? Puppet’s variable scoping is confusing enough on it’s own.

So what should you be doing

To put it simply, write your Puppet modules like you would write a library for your favorite programming language. Don’t know a programming language? You’re working towards the almighty “Infrastructure as Code” ideal. Stop making excuses like “I don’t know how to program so I didn’t know any better” and go and learn a language.

Don’t make your users edit your code to do the work they want.
Don’t rely on global variables to pass information to your modules.
Make it easy for other people to add features to your module.

While it looks like the 3rd point contradicts the 1st point, it doesn’t. There’s a big difference between someone sending you a patch to your module to support a distro that it doesn’t currently support and someone having to go and edit a template inside your module in order to change a config value that you didn’t think anyone would need to change.

An example of a good module

Take a look at the Puppet Labs NTP module. It’s not perfect, but it’s pretty close.

First off, it’s using a parameterised class, so there’s no global variables polluting the namespace while still allowing us to change the parameters used to configure NTP without editing the module itself. If you’re using an older version of Puppet that doesn’t support parameterised classes, a defined type will work just as well.

Secondly, it has support for a good number of different distributions but it has a default case that causes Puppet to abort and let the user know that this module isn’t supported on their machine. This is much better than just blindly making changes to a system using values that may or may not work for it.

For the folks using ENCs that don’t support parameterised classes or defined types, you’re still OK because you can just put this into your role definition like so

class mycompany::role::frontend {
  class { 'ntp':
    servers => ['ntp.mycompany.com'],
  }
}

How this module could be made even better

The addition of a generic ntp::config type that used either Augeas or parsedfile on the back end to set arbitrary configuration values, i.e.

class { 'ntp':
  servers => ['ntp.example.com'],
}

ntp::config {
  'statsdir':
    value => '/var/log/ntp';
  'statistics':
    value => 'rawstats';
}

Also, replacing the autoupdate parameter with a version parameter so that it was possible to specify a particular package version, ‘latest’, ‘installed’ etc. would be a great addition.

That’s all folks

How would you like to see modules written? What currently annoys you about the modules out there? Do you disagree with everything I’ve written and want the last 10 minutes of your life back? Let me know.

Auto-notify Resources From Your Puppet Types

2011-11-13T00:00:00+11:00

So, I ran into a bit of a problem yesterday. I was working on a Puppet module for the Sensu monitoring framework, part of which involved writing a custom Puppet type to manage the configuration of service checks. Normally this is a trivial matter, however in this case, the checks must be configured on both the server and the client and must therefore be able to notify either the server process or the client process or both to restart after a configuration change.

Obviously, I couldn’t just do this:

sensu_check { 'mycheck':
  notify => [
    Service['sensu-client'],
    Service['sensu-server'],
  ],
}

As if the host was only running the client process, this would result in an error during the Puppet runs.

One option would be to use the following mess:

if(defined(Service['sensu-client']) && defined(Service['sensu-server'])) {
  Sensu_check {
    notify => [
      Service['sensu-client'],
      Service['sensu-server'],
    ],
  }
} elsif defined(Service['sensu-client']) {
  Sensu_check {
    notify => Service['sensu-client'],
  }
} else {
  Sensu_check {
    notify => Service['sensu-server'],
  }
}

Not the most elegant solution in the world. Ideally what I needed was something like the existing autorequire functionality that creates require relationships between your custom type and the named resources automatically but only if the resources exist in the node catalogue.

Unfortunately, such functionality doesn’t exist (yet), so I had to go some digging around in Puppet’s codebase to implement it. The first thing to do was to establish a way to create arbitrary notify relationships. This turned out to be easily done:

Puppet::Type.newtype(:mytype) do
  def initialize(*args)
    super
    self[:notify] = [
      "Service[myservice]",
      "Service[myotherservice]",
    ]
  end
end

Now, all I needed to do was make it so that it only notified the resources that actually existed in the node’s manifest

Puppet::Type.newtype(:mytype) do
  def initialize(*args)
    super
    self[:notify] = [
      "Service[myservice]",
      "Service[myotherservice]",
    ].select { |ref| catalog.resource(ref) }
  end
end

The moral of this extremely drawn out story? Anything is possible in Puppet if you’re willing to get your hands dirty. And this should really be a built in feature *hint*.

Test Your Puppet Modules - Functions

2011-11-04T00:00:00+11:00

11:00 <hubot> [puppet/master] merge branch 'mysql-module-refactor' - dave
11:00 <hubot> dave is deploying puppet/master to production
11:23 <nagios> PROBLEM - MySQL on dbmaster1.initech.com is CRITICAL
11:24 <dave> oh fuck

Look familiar?

If you’ve worked with configuration management systems for a while, a situation like this has probably cropped up and ruined your day. If you’re lucky enough to have a homogeneous environment, then you might have a staging environment that you can test changes out on, but what if you don’t? A slight mistake in that harmless change you’re working on could stop a service on hundreds of machines or worse (purge the mysql-server package and all it’s data *cough*).

Why you should be writing unit tests for your Puppet modules

Prevent situations like the one above.
Catch any problems moving between Puppet releases before it hits production.
Now we can do this too

Getting started

In this article, we’ll cover setting up your testing environment and cover how to write unit tests for your Puppet functions. I’m going to make a few assumptions now:

You store your Puppet manifests in git.
You run a *nix machine as your workstation.
You don’t mind getting your hands dirty with a bit of simple Ruby.
You have Ruby installed (1.8.7).

First of all, we’re going to install Bundler to manage the dependencies our Puppet testing rig will have.

$ gem install bundler --no-ri --no-rdoc
Fetching: bundler-1.0.21.gem (100%)
Successfully installed bundler-1.0.21
1 gem installed
$ bundle --version
Bundler version 1.0.21

Next we’re going to create a Gemfile in the top level of our Puppet repo with the list of gems we’re going to need. Adjust the puppet and facter versions to match your environment.

source :rubygems

gem 'puppet',       '2.6.12'
gem 'facter',       '1.6.0'
gem 'rspec-puppet', '0.1.0'
gem 'rake',         '0.8.7'

Next we’re going to add a couple of things to your .gitignore.

1
2

vendor/gems/
.bundle/

Now we just need to tell bundler to install everything and commit our changes to the repository.

$ bundle install --path vendor/gems
Fetching source index for http://rubygems.org/
Installing rake (0.8.7)
Installing diff-lcs (1.1.3)
Installing facter (1.6.0)
Installing puppet (2.6.12)
Installing rspec-core (2.7.1)
Installing rspec-expectations (2.7.0)
Installing rspec-mocks (2.7.0)
Installing rspec (2.7.0)
Installing rspec-puppet (0.1.0)
Using bundler (1.0.21)
Your bundle is complete! It was installed into ./vendor/gems
$ git add Gemfile
$ git add Gemfile.lock
$ git commit -a -m "Bundler setup for testing"

OK, time to configure RSpec. Create a spec directory in the root of your Puppet repository and create a file in the spec folder called spec_helper.rb. Adjust c.module_path and c.manifest_dir to point to your modules and manifests directories in your repository.

require 'rspec-puppet'

RSpec.configure do |c|
  c.module_path = "modules"
  c.manifest_dir = 'manifests'
end

The last thing we need to do is create a Rake task to run our tests. Create a Rakefile in the root of your Puppet repository with the following.

require 'rake'
require 'rspec/core/rake_task'

RSpec::Core::RakeTask.new(:test) do |t|
  t.pattern = 'modules/*/spec/*/*_spec.rb'
end

task :default => :test

Testing your first function

For the sake of this example, let’s create a simple module with a single function (that I’m going to borrow from Puppet Lab’s stdlib module).

1
2

$ mkdir -p modules/misc/lib/puppet/parser/functions
$ mkdir -p modules/spec/functions

Download this function and drop it in modules/misc/lib/puppet/parser/functions.

Basically this function should

return 0 if you pass it ‘f’, ‘false’, ‘n’, ‘no’, 0, ”, ‘undef’ or ‘undefined’.
return 1 if you pass it ‘t’, ‘true’, ‘y’, ‘yes’ or 1.
raise Puppet::ParseError if you pass it anything else.

Before we continue, you should now go and read the rspec-puppet README. The tests for this function should live in modules/misc/spec/functions/bool2num_spec.rb.

require 'spec_helper'

describe 'bool2num' do
  it { should run.with_params('true').and_return(1) }
  it { should run.with_params('t').and_return(1) }
  it { should run.with_params('y').and_return(1) }
  it { should run.with_params('yes').and_return(1) }
  it { should run.with_params('1').and_return(1) }

  it { should run.with_params('false').and_return(0) }
  it { should run.with_params('f').and_return(0) }
  it { should run.with_params('n').and_return(0) }
  it { should run.with_params('no').and_return(0) }
  it { should run.with_params('0').and_return(0) }
  it { should run.with_params('undef').and_return(0) }
  it { should run.with_params('undefined').and_return(0) }
  it { should run.with_params('').and_return(0) }

  it { should run.with_params('foo').and_raise_error(Puppet::ParseError) }
end

Most of this should be pretty self explanatory, however there is a couple of important things:

The spec_helper.rb required on line 1 is the spec_helper.rb in the spec directory at the root of your repository, not from the per-module spec directory.
The description on line 3 must be a string and it must be the name of the function that you are testing so that RSpec can set the subject correctly.

Now for the all important running of the tests.

$ bundle exec rake
/usr/bin/ruby -S rspec modules/misc/spec/functions/bool2num_spec.rb
..............

Finished in 2.61 seconds
14 examples, 0 failures

Huzzah! Now go and write tests for the rest of your functions. In the next article in this series, we’ll cover how to test your Puppet manifests (.pp files).

Distributing Augeas lenses with Puppet's pluginsync

2011-01-02T00:00:00+11:00

Sick of having to write file resources to distribute the Augeas lenses that your module depends on? Why not use Puppet’s pluginsync functionality to distribute them with the rest of your module?

Under your module’s lib directory, create the following directory structure

modules/<module>/lib/
                     augeas/
                            lenses/

Your module should now look like this:

modules/<module>/manifests/
                 templates/
                 lib/
                     puppet/
                     facter/
                     augeas/
                            lenses/

Drop your Augeas lenses into this lenses directory and Puppet will distribute them to all your clients automatically. Now we just need to tell Augeas where to find these lenses.

The easiest way to go about this is to set a default load_path value for Augeas type. To do that, add the following to your site.pp.

1
2
3

Augeas {
  load_path => "/usr/share/augeas/lenses:${settings::vardir}/augeas/lenses",
}

Note: Puppet will display an error for each lens during runs as it’ll try to load them as Ruby files. It’s noisy, but it’s not a fatal error. I’m hoping to find an easy way to prevent this.