Giving your Puppet Code the Onceover

08 Oct 2018

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 processing your 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.

Installation

For the best Onceover experience, install a separate Ruby environment:

rbenv
RVM

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

Enhancing 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.

Onceover-codequality checks:

Syntax:
- Puppet
- Templates
- Yaml
- Puppetfile
Lint

We also run Puppet Strings over your site/role and 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

Launching onceover-codequality and then onceover manually is quite a bit of typing, so we like to automate this process:

Installation

Gemfile

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 a Gemfile with the above content and then run:

bundle install

This needs to be done whenever you want to upgrade Onceover and/or its libraries.

Tests

Using a Makefile lets us run a batch of commands:

Makefile

onceover:
	cat Puppetfile > Puppetfile.onceover
	cat Puppetfile.mock >> Puppetfile.onceover
	bundle exec onceover run codequality
	bundle exec onceover run spec --puppetfile Puppetfile.onceover

With the Makefile in-place at the top level of our Control Repository, we can run all tests in our bundler environment really easily:

make

Mocks for Onceover

The eagle-eyed amongst you will have spotted Puppetfile.mock in Makefile.

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 Puppetfile.

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

Onceover enforcing mandatory documentation using the onceover-codequality plugin… Write those docs!

Conclusion

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!

geoffwilliams@home:~$