Puppet metadata

The metadata test analyzes the metadata.json for conformity to Puppet tool expectations and module deployment requirements.

Puppet code lint

The lint tool analyzes code for conformity to Puppet style guide. It can catch a number of common coding errors that might otherwise hide bugs, and it will tend to improve the readability of your code.

Common problems caught by lint include the use of nonqualified variables, variable inheritance, documentation problems, embedding of selectors where they don’t belong, use of bare values that should be quoted, and use of double quotes where single quotes are more appropriate.

Lint is especially useful for testing upgrades between major releases of Puppet. It can catch variable inheritance and variable naming issues that would break a Puppet 3 or Puppet 4 upgrade, respectively.

Ruby code cop

Much like Puppet lint, the Rubocop tool analyzes Ruby code for conformity to the Ruby style guide. It can catch a number of common coding errors that might otherwise hide bugs, and will tend to improve the readability of your code.

Dependencies

There are two places that dependencies must be listed for testing to be successful. The PDK autogenerates suitable starting points, but you need to add any new dependencies:

• The module’s .fixtures.yml contains a list of Puppet modules that must be installed to test the module. Always update the fixtures when a new module is added to dependencies in the metadata.

• The module’s Gemfile contains a list of gems that must be installed to test the module. Always add gems used by the module’s Ruby types, providers, functions, or facts to this.

The module skeleton created by pdk new module includes an appropriate Gemfile and fixture starting points.

Input testing with rspec

Input validation ensures compatibility with your documentation and ensures that changes do not break compatibility within a major release of your module. Writing good input validation tests provides the freedom to modify the module with the confidence of knowing that any changes that break compatibility will fail the test.

Perform the following tests for each documented parameter of your module. Start with default values, as shown here:

  context 'with document_root => undef' do
    it { is_expected.to contain_file('/etc/httpd/conf/httpd.conf').with({
        :content => %r{DocumentRoot /var/www/html}
      })
    }
  end

Then, test valid and appropriate values being passed to that resource:

  context 'with document_root => /tmp' do
    let :params do
      { :document_root => '/tmp' }
    end

    it { is_expected.to contain_file('/etc/httpd/conf/httpd.conf').with({
        :content => %r{DocumentRoot /tmp}
      })
    }
  end

Finally, test for some known bad input. Get creative about mismatched data types:

  context "with document_root => false" do
    let :params do
      { :documentroot => false }
    end

    it { is_expected.not_to compile }
    it { is_expected.to raise_error(Puppet::Error, /not an absolute path/) }
  end

If you test all of these situations for every resource, you can have complete confidence that a breaking changes won’t pass the tests.

Resource validation

In most cases, input validation will by its nature check the output of the module. However, there are often resources in your module that are not affected by input parameters. You should test those resources explicitly, as demonstrated here:

  it { is_expected.to contain_service('httpd').with({
      :ensure => 'running',
      :enable => true,
    })
  }

This test has confirmed that the Apache service is configured to run in the catalog.

Testing input validation

Test the module’s input validation to ensure that it behaves as expected. Nothing is more frustrating than having valid input data rejected because of a poorly designed test.

For input validation, we recommend using Test-Driven Development (TDD) practices; write your test cases before you write the module code to implement them. Always test both good and bad input, and positive and negative outcomes. You are much more likely to build the code for input validation correctly if you have a good list of tests available for immediate feedback. Example 10-1 presents some sample input validation code.

  # Positive tests
  good_ports = [ 80, 443 ]
  good_ports.each do |port|
    context "with port #{port}" do
      let :params do
        { :port => port }
      end

      it { is_expected.to contain_file('/etc/httpd/conf/httpd.conf').with({
          :content => /Listen #{port}/
        })
      }
    end
  end

  # Invalid data tests
  bad_ports = [ -1, 65536, 'monkey' ]
  bad_ports.each do |ports|
    context "with port #{port}" do
      let :params do
        { :port => port }
      end

      it { is_expected.to raise_error(Puppet::Error, /expects an Integer/) }
    end
  end

This basic good/bad value-testing pattern is easy to read and comprehend, and the list of values to be tested can grow significantly without adding any new lines of code.

Use containers or virtualization for acceptance testing

The following platform tools are commonly used to provide node creation and destruction for acceptance testing.

Vagrant

Vagrant is a tool for managing ephemeral virtual machines (VMs). Vagrant focuses on simplifying VM distribution, provisioning, and postconfiguration tasks. Vagrant supports most virtualization and cloud platforms, including AWS Elastic Compute Cloud (Amazon EC2) instances, Openstock Compute nodes, VMWare Vsphere clusters, Microsoft Azure Compute nodes, and desktop virtualization such as VMWare Workstation, VMWare Fusion, and VirtualBox.

Vagrant streamlines the process and reduces it to a repeatable configuration. Postprovisioning configuration tasks such as configuring port forwarding, mapping shared directories, and invoking Puppet are declared in the Vagrantfile. It’s simple enough that a developer otherwise completely inexperienced with virtualization should be able to bring up and use a VM for testing.

Packer

Packer is a tool for building VM images, cloud provider images, and containers. These capabilities make it possible to automate the creation and maintenance of versioned and tested images. You can run Packer-built machines through the same CI systems as your Puppet code. You can even use them as part of the Puppet CI process.

Packer provides a simple way to create and maintain Vagrant boxes that mirror production deployment standards. Although Hashicorp’s Vagrant Cloud provides a large number of boxes from reputable sources, there are many cases for which a locally built box might be necessary to test site-specific code. For these cases, the Box Cutter project is an excellent starting point for the creation of custom boxes built entirely in-house.

Docker

Docker and other containerization solutions are an excellent option for the creation of development nodes. Containers are light on resources, easy to manage, and offer extremely high performance. Containers are ideal for testing applications or services without (waiting for) deployment of an entire operating system (OS), or when large number of nodes are needed for testing or experimentation within a small footprint. If you need to test multiple application or service interactions without utilizing signficant test resources, a container offers significant benefits over conventional VMs.

Even though containers do allow you to bring up machines with a different distribution or library set, they are not ideal for testing your application on multiple platforms. Containers share the kernel of the base OS, and cannot easily host a 32-bit kernel on a 64-bit host OS, host different kernel releases, or bring up instances with completely different operating systems. There are solutions (such as Docker for Mac) that utilize a VM running Docker that can deploy containers for the VM’s OS.

Resource validation

With acceptance tests, verify the functionality of the applied module and the return codes from applying the module. For example, with an apache module, you might want to ensure that the Apache package is present on the system and that the service is running and responds with the boilerplate site when queried.

It’s also valuable to ensure that Puppet returns an exit code indicating that it modified system state with no errors upon initial invocation and that further invocations produced no change. These tests will quickly ensure that your module is idempotent when applied to a live system:

  apply_manifest('include myapp', :catch_failures => true)
  apply_manifest('include myapp', :catch_changes => true)

  describe package('httpd') do
    it { is_expected.to be_installed }
  end

  describe service('httpd') do
    it { is_expected.to be_running }
  end

Beaker supports multiple backends for acceptance testing. The most commonly used backend is Vagrant, which is compatible with your existing boxes. However, Beaker can build and invoke tests on Docker, OpenStack, VMWare, AWS, Azure, and many other cloud providers. We cover these tools in “Acceptance Testing”.

When writing Beaker tests, it’s important to begin with a base system image, free of debris from earlier tests, to ensure that your module is not implicitly dependent on some system state left behind by other tests. If your site uses a custom base image, use a fresh copy of that image base for Puppet testing. Local security policy can create restrictions that are not present on public images. The testing will also be more relevant if the base image has preconfigured package repositories for your site.

If you intend to publicly release the module, you should test the module against a publicly available base image to ensure maximum compatibility.

Custom facts

Custom facts are written in Ruby, stored in the lib/facter/ directory of Puppet modules, and register the fact name using Facter.add().

Unless execution of a different language is required, you should write custom facts in Ruby. The interfaces for facts are stable, the syntax is simple, and native facts allow you to do anything an executable fact can, with the advantage of Ruby’s excellent parsing functionality and access to Puppet configuration values and other facts.

External facts

Facter also supports external facts, which are files stored within the facts.d directory of Puppet module. If named with one of the following file extensions, they will be read as data facts:

.txt

Read expecting text format

.yaml

Read expecting YAML format

.json

Read expecting JSON format

If the file does not have one of these file extensions, it will be executed as a program if one or the other of the following is true:

• It’s on a Unix/Linux/POSIX system and the file has the execution bit set.

• It’s on a Windows system and the file has one of the known Windows executible extensions, including .exe, .com, .bat, .cmd, or .ps1.

The expected output from each supported method is well documented at Custom Facts Walkthrough: External Facts.

PowerShell DSC

Microsoft has put a fairly heroic effort into making Windows automation friendly in all supported versions. PowerShell Desired State Control (DSC) is your best bet for implementing Windows configuration changes.

In many cases, you probably won’t need to write a custom type or provider for Windows; the dsc resource type and provider should be able to handle most common tasks. If DSC does not offer a built-in resource that suits your needs, consider the Lite module.

inifile

The puppetlabs/inifile module has providers to parse files that use INI or Java properties syntax. This provider is useful for any file that uses a separator between key and value, such askey = value, key: value pairs to manage configuration settings. The ini_setting resource is fast, easy to use, and it handles all of the complexity in handling loosely or inconsistently formatted files.

INI syntax files are surprisingly common in both the Windows and Linux/Unix worlds; this provider can easily be used to parse the following:

• EL interface configuration files and other files in /etc/sysconfig/

• Java properties files

• Most application configuration files in /etc/ entries

XML

If you want to parse XML files, there are a few options available:

• Gary Larizza’s xmlsimple module makes it easy to read XML into hashes for use in Puppet, and write them back out again.

• Ian Oberst’s xml_fragment makes it easy to ensure specific fragments of an XML file exist.

• You can use the built-in augeas resource type with the XML lens. This is a good approach to use if you’re already familiar with Augeas and need to perform a fairly simple task.

The archive resource

The archive resource is a powerful type for deploying files from web sources. It implements methods to download files via the HTTP, FTP, and other protocols on multiple platforms. It can also extract the archives and run commands from the contents.

This resource can pull packages from sources not supported by the underlying package provider. For example, it can download an executable installer from a web server, which can then be run locally. It’s useful in any situation for which you need to download a file from a source other than a Puppet mountpoint.

A huge benefit of archive is that it abstracts away the underlying tools. You can specify an FTP, HTTP, Puppet or local filesystem source, and archive will do the right thing, going so far as to use the correct platform-specific tools. This abstraction is invaluable for module development and testing; it avoids the need to set up a web server to perform simple experimentation. It allows for local fixtures to be used during testing rather than leaving you reliant on external infrastructure.

In a previous example, we used an exec resource to run wget for illustrative purposes. That’s never the best way to do it. Use an archive resource, instead. In almost every single case, the best practice is to use an archive resource.

The archive resource depends on the availability of wget, unzip, and other tools that might or might not be installed on your hosts by default. It is a good idea to install these tools prior to invoking the archive resource. For more details, see Chapter 7.

The archive resource type is provided by the puppet/archive module.

Describing state with a type

Before writing a custom resource, decide whether your need would be satisfied by developing a provider for an existing resource type.

Puppet resource types describe the interface to your module; they model the resource declaratively. The provider has methods to acquire the existing state for comparison and to bring the resource to the desired state. If there is an existing resource type that provides a good interface, you can simply add a new provider for that resource type, as discussed in “Adding providers to a resource”.

Resource types attempt to be platform agnostic where possible. For instance, the user resource type creates users for Windows, Linux, and Solaris. It can also create users in Lightweight Directory Access Protocol (LDAP). Each platform has its own provider, but a single resource type provides a common interface for all of them. Platform-specific parameters are available where needed.

Defining the type’s interface

Custom types are written in Ruby and created by the newtype() method of Puppet::Type. Puppet’s type framework is relatively straightforward to implement: it is a simple interface between the Puppet DSL and underlying Ruby logic. The resource type (found in the lib/puppet/type directory of a module) is a declaration of the attributes accepted (and required) for the resource and invocations of the provider’s method calls that get or set the current state.

Puppet Types and Providers by Dan Bode and Nan Liu provides an excellent reference for the types and providers interfaces. Although it predates Puppet 4, very little has changed in the creation of Puppet types and providers, so it remains relevant. See also Puppet’s Custom Types documentation.

Resource types comprise the following components:

1. The type’s name

2. Properties: measurable or comparable things to be evaluated (e.g., user uid and file mode)

3. Parameters: configuration options that inform the provider how to apply (path for exec command, options for package installation, etc.)

4. Input validation for parameters and properties

5. Method calls implemented by the underlying provider(s)

6. Documentation of the type and its parameters

It is possible to implement resource types that do not rely on a backend provider. This is practical only when a resource doesn’t directly make changes. The following are circumstances in which a backend provider is not necessary:

The resource type can provide its own implementation

The notify resource has no provider because it does nothing more than output a message within Puppet.

The resource type can declare other resources

The tidy resource is a metatype. It declares one or more instances of the file resource, which has its own providers.

As shown in this description, the resource type provides a clean abstraction layer for declaration of the resource, without concerning itself with how to implement those changes on any given platform.

Adding providers to a resource

Puppet resource types are intended to be a generic interface to the resource, and providers are expected to implement the platform-specific calls to manage that resource. For example, the package resource has drastically different providers that implement the package management functionality for each operating system: apt, yum, and so on.

If you do choose to implement a new provider for an existing resource type, be aware that the resource type and resource provider interfaces are very tightly bound. Your provider will break if it does not handle all of the required attributes and parameters of the parent resource. This requires you to track changes to the resource type and implement the new features.

Note that feature-specific attributes do not need to be supported unless your provider explicitly states that it supports those features. This behavior allows a lot of leeway in implementing new resource parameters without breaking backward compatibility.

Inheriting an existing provider

It’s fairly common to build a provider based on an existing provider. The most common reason to do this is for cases in which you need to change the behavior of an existing provider.

For example, the puppetserver_gem resource provider is based on the built-in gem provider. It overrides a few behaviors of the upstream gem provider so that it can manage gems installed into the Puppet server’s library path rather than the system Ruby library paths:

Puppet::Type.type(:package).provide :puppetserver_gem, :parent => :gem do

To inherent a provider, you simply need to supply the :parent and, optionally, the :source arguments to your provider declaration. Internally, Puppet subclasses the parent class. You can override parent methods by using normal Ruby class inheritance design patterns, including the super() method call. This is well-documented behavior at Provider Development.

Creating a resource provider

Providers have the following components:

• A declaration of a new resource provider

• A list of constraints and requirements to determine when to use

• A list of conditions to help determine the correct provider for a platform

• An optional method call to find all instances of the resource

• A method call to retrieve a specific instance of a resource

• Method calls for getting and setting resource property states

Providers are tightly coupled to their types: resource types call provider methods directly. Each provider must implement the methods of the resource type. Because of the tight coupling of type to the provider, it’s possible to find that an older provider is not compatible with an updated type, or vice versa.

Retrieving existing resource instances

Resource providers can but are not required to implement an instances method. The instances method discovers existing instances of a resource on the node. The instances can then be used by resource metatypes such as the resources resource to purge existing resources that are not declared in the catalog, or by the puppet resource command to output lists of existing resources.

Most package providers provide an instances method. In the case of the RPM provider, the method is implemented by using a simple rpm -qa exec and some regular expression magic.

Implementing the instances method is optional because discovering available instances might not be possible due to the nature of the resource, or might be impractical because of the impact of discovering the resource instances. For example, the file resource doesn’t implement the instances method because discovering every file on a node would incur huge overhead and take far too much time.

The systemd instances method is very simple, and makes for a great example implementation:

def self.instances
  i = []
  out = systemctl(
    'list-unit-files','--type','service','--full','--all','--no-pager'
  )
  out.scan(/^(S+)s+(disabled|enabled|masked)s*$/i).each do |m|
    i << new(:name => m[0])
  end
  return i
rescue Puppet::ExecutionFailure
  return []
end

The instances method is provider specific, and can be implemented for only some of the providers for a given resource.

Text frameworks

Manipulation of text configuration files is fairly common with Puppet, and there are a number of frameworks to help you build custom providers for this task.

Puppet’s IniFile

This framework has documentation for using it as parent classes for providers that need to read and write a key/value pair configuration file. This is by far the easiest provider to use if it meets your needs.

Puppet::Provider::ParsedFile

This framework is intended to be a parent class for any provider that parses or generates files. It is used in a large number of Puppet’s built-in resource providers. ParsedFile is line oriented and quite fast.

herculesteam/augeasproviders_core

This framework is a parent class for any provider that uses Augeas to parse or generate files. It is used in a large number of Puppet approved Augeas provider modules. It’s best if you already use and know Augeas lenses and actions.

Vox Pupuli’s FileMapper

This framework provides a way to map resources to file providers. It is provided as a mixin (Ruby require) that you can include in a provider that has a different parent. It is well documented and thus easier to use than the ParsedFile or Augeas providers. It’s possible to implement complex and recursive multiline parsers that would be very difficult to build with ParsedFile.

Each of these providers enable you to bundle the backend parsing and writing in your type and provide a clean and simple interface for others to consume.

JSON, YAML, XML, and other well-known formats

JSON, YAML, XML and other well-known formats already have excellent library support within Ruby. Don’t attempt to reinvent the wheel and parse them yourselves. You can use these to provide the parsing implementations required by FileMapper. Use of FileMapper together with the appropriate parsing library can remove a lot, if not all, boilerplate tasks.

Windows Management Interface and object linking and embedding

Ruby’s win32ole class (part of the Ruby stdlib) can interact with Windows applications and subsystems with object linking and embedding (OLE) support. Among other things, you can use OLE to issue you can use Windows Management Instrumentation Query Language (WQL) queries, allowing you to determine a lot of information about the system. Facter uses this approach internally to populate a few Windows facts.