Puppet Modules and Manifests

A newer version is available; see the version menu above for details.

Summary

Puppet uses its own domain-specific language (DSL) to describe machine configurations. Code in this language is saved in files called manifests.

Puppet works best when you isolate re-usable chunks of code into their own modules, then compose those chunks into more complete configurations.

This page covers the first part of that process: writing manifests and modules. For information on composing modules into complete configurations, see the Assigning Configurations to Nodes page of this manual.

Other References

This page consists mostly of small examples and links to detailed information. If you want more complete context, you should read some of the following documents instead:

Learning the Puppet Language

If you are new to Puppet, start here. For a complete introduction to the Puppet language, read and follow along with the Learning Puppet series, which will introduce you to the basic concepts and then teach advanced class writing and module construction.

Quick Start

For those who learn by doing, the PE user’s guide includes a pair of interactive quick start guides, which walk you through installing, using, hacking, and creating Puppet modules.

Modules in Context

The Puppet Enterprise Deployment Guide includes detailed walkthroughs of how to choose modules and compose them into complete configurations.

Geppetto IDE

Geppetto is an integrated development environment (IDE) for Puppet. It provides a toolset for developing puppet modules and manifests that includes syntax highlighting, content assistance, error tracing/debugging, and code completion features. Geppetto also provides integration with git, enabling side-by-side comparison of code from a given repo complete with highlighting, code validation, syntax error parsing, and expression troubleshooting.

In addition, Geppetto provides tools that integrate with Puppet products. It includes an interface to the Puppet Forge, which allows you to create modules from existing modules on the Forge as well as easily upload your custom modules. Geppetto also provides PE integration by parsing PuppetDB error reporting. This allows you to quickly find the problems with your puppet code that are causing configuration failures. For complete information, visit the Geppetto documentation.

Printable References

These two cheat sheets are useful when writing your own modules or hacking existing modules.

The Puppet Language

Puppet configurations are written in the Puppet language, a DSL built to declaratively model resources.

Manifests

Manifests are files containing Puppet code. They are standard text files saved with the .pp extension. Most manifests should be arranged into modules.

Resources

The core of the Puppet language is declaring resources. A resource declaration looks like this:

    # A resource declaration:
    file { '/etc/passwd':
      ensure => file,
      owner  => 'root',
      group  => 'root',
      mode   => '0600',
    }

When a resource depends on another resource, you should explicitly state the relationship to make sure they happen in the right order.

Conditional Logic, Variables, and Facts

Puppet manifests can dynamically adjust their behavior based on variables. Puppet includes a set of useful pre-set variables called facts that contain system profiling data.

    # Set the name of the Apache package based on OS
    case $operatingsystem {
      centos, redhat: { $apache = "httpd" }
      debian, ubuntu: { $apache = "apache2" }
      default: { fail("Unrecognized operating system for webserver") }
    }
    package {$apache:
      ensure => installed,
    }
  • See the Variables page (and the Facts subsection) of the Puppet language reference for information on variables.
  • See the Conditional Statements page for information on if, case, and selector statements.

Classes and Defined Types

Groups of resource declarations and conditional statements can be wrapped up into a class:

    class ntp {
      package { 'ntp':
        ensure => installed,
      }
      file { 'ntp.conf':
        path    => '/etc/ntp.conf',
        ensure  => file,
        require => Package['ntp'],
        source  => "puppet:///modules/ntp/ntp.conf"
      }
      service { 'ntp':
        name      => ntpd
        ensure    => running,
        enable    => true,
        subscribe => File['ntp.conf'],
      }
    }

Classes are named blocks of Puppet code that can be assigned to nodes. They should be stored in modules so that the puppet master can locate them by name.

Defined types are similar to classes, and should also be stored in modules. They cannot be assigned directly to nodes, but can enable you to build much more sophisticated classes.

Puppet Modules

Modules are a convention for arranging Puppet manifests so that they can be automatically located and loaded by the puppet master. They can also contain plugins, static files for nodes to download, and templates.

Modules can contain many Puppet classes. Generally, the classes in a given module are all somewhat related. (For example, an apache module might have a class that installs and enables Apache, a class that enables PHP with Apache, a class that turns on mod_rewrite, etc.)

A module is:

  • A directory…
  • …with a specific internal layout…
  • …which is located in one of the puppet master’s modulepath directories.

In Puppet Enterprise, the main modulepath directory for users is located at /etc/puppetlabs/puppet/modules on the puppet master server.

Module Structure

This example module, named “my_module,” shows the standard module layout:

  • my_module/ — This outermost directory’s name matches the name of the module.
    • manifests/ — Contains all of the manifests in the module.
      • init.pp — Contains one class named my_module. This class’s name must match the module’s name.
      • other_class.pp — Contains one class named my_module::other_class.
      • my_defined_type.pp — Contains one defined type named my_module::my_defined_type.
      • implementation/ — This directory’s name affects the class names beneath it.
        • foo.pp — Contains a class named my_module::implementation::foo.
        • bar.pp — Contains a class named my_module::implementation::bar.
    • files/ — Contains static files, which managed nodes can download.
      • service.conf — This file’s URL would be puppet:///modules/my_module/service.conf.
    • lib/ — Contains plugins, like custom facts and custom resource types.
    • templates/ — Contains templates, which the module’s manifests can use.
      • component.erb — A manifest can render this template with template('my_module/component.erb').
    • tests/ — Contains examples showing how to declare the module’s classes and defined types.
      • init.pp
      • other_class.pp — Each class or type should have an example in the tests directory.
    • spec/ — Contains spec tests for any plugins in the lib directory.
  • See the Module Fundamentals page of the Puppet 3 reference manual for details about module layout and location.

Downloading Modules

You can search for pre-built modules on the Puppet Forge and use them in your own infrastructure.

  • Use the puppet module search command to locate modules, or browse the Puppet Forge’s web interface.
  • The Puppet Forge provides Puppet Enterprise supported modules; these modules are rigorously tested with PE, supported via the usual support channels, maintained for a long-term lifecycle, and are compatible with multiple platforms and architectures.
  • On your puppet master server, use the puppet module install command to install modules from the Forge.
  • See the Installing Modules page for details about installing pre-built modules.

Catalogs and Compilation

In standard master/agent Puppet, agents never see the manifests and modules that comprise their configuration. Instead, the puppet master compiles the manifests down into a document called a catalog, and serves the catalog to the agent node.

As mentioned above, manifests can contain conditional logic, as well as things like templates and functions, all of which can use variables to change what the manifest manages on a system. A catalog has none of these things; it contains only resources and relationships.

Only sending the catalog to agents allows Puppet to do several things:

  • Separate privileges: Each individual node has little to no knowledge about other nodes. It only receives its own resources.
  • Simulate changes: Since the agent has a declarative document describing its configuration, with no contingent logic, it has the option of simulating the changes necessary to apply the configuration. If you do a Puppet run in noop mode, the agent will check against its current state and report on what would have changed without actually making any changes.
  • Record and query configurations: Each node’s most recent catalog is stored in PuppetDB, and you can query the database service for information about managed resources.

↑ Back to top