Giving your Puppet Code the Onceover
Ever wanted to do some basic testing of your Puppet Control Repository but no idea how to get started?
Dylan Ratcliffe from Puppet had this problem a couple of years ago and his answer was Onceover.
What does Onceover do?
Onceover lets you quickly and easily test your Puppet Control Repository before you do any real testing on your dedicated Puppet testing nodes.
Onceover runs on your developer workstation or CI platform. It works by
Puppetfile, installing all listed modules locally and then
automatically generating RSpec Puppet
tests to see if your Puppet Code will compile.
Onceover is pretty clever about this: It also includes your Hiera data and facts while allowing you to override the real values with special ones just for testing if you like.
For the best Onceover experience, install a separate Ruby environment:
And then install Bundler:
gem install bundler
Onceover comes with good documentation so there’s no point duplicating it here.
Once your workstation is setup, follow the instructions and install Onceover
Out of the box, Onceover gives us automatic and painless Rspec Puppet testing which is great but on its own can still let a few little niggles through:
- Lint errors
- Syntax errors on code that has no corresponding RSpec Puppet tests (eg hiera)
To catch these too, we developed onceover-codequality , a Onceover plugin (That’s right, Onceover even has plugins..!) to scan for easy to fix bugs before you re-deploy your Control Repository.
We also run
Puppet Strings over your
site/profile directories to generate reference documentation
in Markdown format so that your team can easily have up-to-date docs for your
roles and profiles, assuming you documented the classes correctly.
Putting it all together
onceover-codequality and then
onceover manually is quite a bit of
typing, so we like to automate this process:
source 'https://rubygems.org' # FIXME: for repeatable builds, version your rubygems(!) gem 'rake' gem 'bundler' gem 'onceover' gem 'onceover-codequality' gem 'rugged' gem 'pry' gem 'r10k' gem 'puppet-strings'
With your workstation setup with a separate Ruby and the
bundler Gem, create
Gemfile with the above content and then run:
This needs to be done whenever you want to upgrade Onceover and/or its libraries.
Using a Makefile lets us run a batch of commands:
onceover: cat Puppetfile > Puppetfile.onceover cat Puppetfile.mock >> Puppetfile.onceover bundle exec onceover run codequality bundle exec onceover run spec --puppetfile Puppetfile.onceover
Makefile in-place at the top level of our Control Repository, we can
run all tests in our bundler environment really easily:
Mocks for Onceover
The eagle-eyed amongst you will have spotted
There are a few Puppet modules that either only exist inside a Puppet Enterprise server or that require a Puppet Enterprise Server + Licence to download.
This makes testing really difficult, so we have developed Mock Modules to allow your code to compile without error so that you can still test all the classes you want to using Onceover.
Mocks are made by taking the real code and deleting the implementation, leaving only the class signature. These classes are then packaged up and published on the Puppet Forge for easy installation.
To reference mock modules in Onceover, add them to
Puppetfile.mock and when
you run Onceover by typing
make, we will add them to a temporary
Puppetfile.onceover that we will use to test the system.
Since our mock modules are listed last, they will be installed in place of any
real modules in your main
Here’s a basic
Puppetfile.mock to get you started:
# Mock modules needed for testing mod 'geoffwilliams-pe_staging', '0.1.0' mod 'geoffwilliams-pe_repo', '0.2.0' mod 'geoffwilliams-puppet_enterprise', '0.7.0'
Onceover in action
Onceover enforcing mandatory documentation using the
plugin… Write those docs!
Onceover is a great tool that’s easy to use, fully documented and extendable.
It cuts down on nuisance work like the typical:
git commit -am "enable foobar" git push origin development git commit -am "fixed syntax error" git push origin development git commit -am "fixed another syntax error" git push origin development git commit -am "asdf q2sdjasj @!@(#$@#)!!!" git push origin development
Workflow that’s often seen when errors are progressively revealed only by deploying and running code on the Puppet Master.
In summary: Onceover saves time, money and frustration!