The Puppet RAL: An Introduction

The Puppet RAL is one of the main parts of Puppet that people use on a daily basis. The RAL is how system state is actually inspected and enforced by Puppet, it’s where most extensions to Puppet are added, and it’s one of the parts of Puppet that really set it apart.

Unfortunately, the RAL is a little lacking on the side of documentation and explanation. The RAL provides a lot of powerful functionality but unless you’ve been digging through that code on a regular basis, it can prove hard to make full use of the RAL.

As of late the state of developer documentation has been improving. Puppet 3.1 added much improved inline documentation to a lot of the code base and covered a lot of the RAL, which is a welcome improvement. In addition Dan Bode and Nan Liu wrote the excellent Types and Providers book, which is arguably the best reference to the RAL to date.

But even with these resources there’s still a need for deep dives into Puppet, and specifically the RAL. This blog post will provide a brief introduction to the RAL and how you can interact with it.

The RAL in a nutshell

The RAL stands for the Resource Abstraction Layer, and it refers to the components of Puppet that interact with the system. The RAL provides an abstract concept of something you can manage, and it defines concrete ways of managing things. The Puppet RAL is what allows you to write a manifest that works on several different platforms without having to remember if you should invoke apt-get install or yum install.

The RAL is the underpinning of how catalogs actually get applied. To perform a normal Puppet run, Puppet needs to compile a catalog, send it to an agent, and then apply the catalog. When the catalog is being applied, all the actual work is done by interacting with the RAL. (For reference, the Transaction is the class that provides the interface between a catalog and the RAL).

The best way to explain the RAL is that it’s built to model the system. That is, it can build an internal representation of something, can determine what state the actual system is, and make changes so that the actual system matches the model.

The RAL is so powerful because it lets you define abstract resources, implement concrete methods of managing resources, and then allow you to manage the variations between implementations.

For example, the concept of installing a package is common to pretty much every operating system in at least the last two decades. However the actual execution of managing a package varies wildly between platforms. The RAL allows you to define the characteristics of a package regardless of the implementation, handle that behavior on every platform under the sun, and support different package features where possible, all in a well defined way.

Getting started with the RAL

If you’ve used Puppet at all, then you’ve already been making very heavy use of the RAL. The standard way of working with the RAL is by writing manifests, but there are several tools available to interact more directly with the RAL.

puppet describe

The puppet describe subcommand queries types and providers for their built in documentation. This lets you look up the behavior of types, their properties and parameters, and so forth.

$ puppet describe package

Manage packages.  There is a basic dichotomy in package
support right now:  Some package types (e.g., yum and apt) can
retrieve their own package files, while others (e.g., rpm and sun)
cannot.  For those package formats that cannot retrieve their own files,
you can use the `source` parameter to point to the correct file.

puppet resource

The puppet resource subcommand lets you work with the RAL on the fly. You can query existing resources as well as modify, create, and delete resources. (mostly.)

orestes# puppet resource package puppet
package { 'puppet':
  ensure => '3.2.1-1puppetlabs1',
orestes# puppet resource package puppet ensure=latest
Notice: /Package[puppet]/ensure: ensure changed '3.2.1-1puppetlabs1' to '3.2.2-1puppetlabs1'
package { 'puppet':
  ensure => '3.2.2-1puppetlabs1',

Going Deeper

I have this nasty tendency of writing blog posts that are 2000+ words and take about a month, per post. It’s a nasty model because there are fewer updates, and I spend more time obsessing and editing and less time actually creating useful content.

Instead of the ONE MASSIVE BLOG POST model, I’m trying to keep this series short and sweet. In the coming blog posts I’ll cover parts of the RAL in manageable chunks.

Additional Resources


Puppet Resource Limitations

Not all Puppet types support puppet resource. For instance puppet resource file will not work, because it would have to checksum every single file on your system. Yeah… no.