In this chapter, we'll start with the basics of the Puppet syntax and show you how some of the syntactic sugar in Puppet is used. We'll then move on to how Puppet deals with dependencies and how to make Puppet do the work for you.

This recipe will introduce the language and show you the basics of writing Puppet code. Puppet code files are called manifests; manifests declare resources. A resource in Puppet may be a type, class, or node. A type is something like a file or package or anything that has a type declared in the language. The current list of standard types is available on the puppetlabs website at https://puppet.com/docs/puppet/latest/type.html. I find myself referencing this site very often. You may define your own types, either using a mechanism, similar to a subroutine, named defined types, extending the language using a custom type. Types are the heart of the language; they describe the things that make up a node (node is the word Puppet uses for client computers/devices). Puppet uses resources to describe the state of a node; for example, we will declare the following package resource for a node using a site manifest: site.pp.

Create a site.pp file and place the following code in it:

node default {
  package { 'httpd':
    ensure => 'installed'
  }
 }

This manifest will ensure that any node on which this manifest is applied will install a package called httpd. The default keyword is a wildcard to Puppet; it applies anything within the node default definition to any node. When Puppet applies the manifest to a node, it uses a Resource Abstraction Layer (RAL) to translate the package type into the package management system of the target node. What this means is that we can use the same manifest to install the httpd package on any system where Puppet has a Provider for the package type. Providers are the pieces of code that do the real work of applying a manifest. When the previous code is applied to a node running on a YUM-based distribution, the YUM provider will be used to install the httpd RPM packages. When the same code is applied to a node running on an APT-based distribution, the APT provider will be used to install the httpd DEB package (which may not exist, as most Debian-based systems call this package apache2; we'll deal with this sort of naming problem later).

• Puppet 3: Beginner's Guide, John Arundel, Packt Publishing, in addition to this section

Facter is a separate utility upon which Puppet depends. It is the system used by Puppet to gather information about the target system (node); facter calls the nuggets of information facts. You may run facter from the command line to obtain real-time information from the system.

We'll compare the output of facter with that of system utilities:

1. Use facter to find the current uptime of the system, the uptime fact:

t@cookbook ~$ facter uptime 0:12 hours

2. Compare this with the output of the Linux uptime command:

t@cookbook ~$ uptime
01:18:52 up 12 min, 1 user, load average: 0.00, 0.00, 0.00

When facter is installed (as a dependency for Puppet), several fact definitions are installed by default. You can reference each of these facts by name from the command line.

Running facter without any arguments causes facter to print all the facts known about the system. We will see in later chapters that facter can be extended with your own custom facts. All facts are available for you to use as variables; variables are discussed in the next section.

Variables in Puppet are marked with a $ character. Variables are immutable; once assigned a value, they cannot be changed. When using variables within a manifest, it is advisable to enclose the variable within braces, such as ${myvariable}, instead of $myvariable. All of the facts from facter can be referenced as top-scope variables (we will discuss scope in the next section). For example, the Fully Qualified Domain Name (FQDN) of the node may be referenced by ${::fqdn}. Variables can only contain alphabetic characters, numerals, and the underscore character, _. As a matter of style, variables should start with an alphabetic character. Never use dashes in variable names.

In the variable example explained in the previous paragraph, the FQDN was referred to as ${::fqdn} rather than ${fqdn}; the double colons are how Puppet differentiates scope. The highest level scope, top-scope, or global is referred to by two colons, as in ::, at the beginning of a variable identifier. To reduce namespace collisions, always use fully scoped variable identifiers in your manifests. A Unix user can think of top-scope variables such as the / (root) level. You can refer to variables using the double colon syntax, similar to how you would refer to a directory by its full path. A developer can think of top-scope variables as global variables; however, unlike global variables, you must always refer to them with the double colon notation to guarantee that a local variable isn't obscuring the top-scope variable. In Puppet5, it is advisable to use the $facts fact, so the previous would be ${facts['fqdn']}. When referring to a variable, the braces ({}) are optional outside of a string, as shown in the following example:

$fqdn_ = $facts['fqdn']
notify {"::fqdn is ${::fqdn}": }
notify {"fqdn_ is ${fqdn_}": }
notify {"facts['fqdn'] is ${facts['fqdn']}": }

This produces the following output:

t@mylaptop ~ $ puppet apply fqdn.pp
Notice: Compiled catalog for mylaptop.example.com in environment production in 0.01 seconds
Notice: ::fqdn is mylaptop.example.com
Notice: /Stage[main]/Main/Notify[::fqdn is mylaptop.example.com]/message: defined 'message' as '::fqdn is mylaptop.example.com'
Notice: fqdn_ is mylaptop.example.com
Notice: /Stage[main]/Main/Notify[fqdn_ is mylaptop.example.com]/message: defined 'message' as 'fqdn_ is mylaptop.example.com'
Notice: facts['fqdn'] is mylaptop.example.com
Notice: /Stage[main]/Main/Notify[facts['fqdn'] is mylaptop.example.com]/message: defined 'message' as 'facts[\'fqdn\'] is mylaptop.example.com'
Notice: Applied catalog in 0.02 seconds

As we'll see in subsequent chapters, facter may be extended with custom facts written in Ruby. By default, custom facts are not loaded when you run facter.

To pull in the custom facts, you need to specify the -p option to facter, as shown here:

t@cookbook:~$ facter puppetversion

t@cookbook:~$ facter -p puppetversion
5.5.2

Although still valid, the facter -p syntax is now deprecated in favor of using the Puppet face, facts. Puppet faces are the various sub-applications supported by the Puppet command. To see the available faces, run Puppet help, as shown here:

t@cookbook:~$ puppet help

Usage: puppet <subcommand> [options] <action> [options]

Available subcommands:
   
 agent             The puppet agent daemon
 apply             Apply Puppet manifests locally
 ca                Local Puppet Certificate Authority management. (Deprecated)
 catalog           Compile, save, view, and convert catalogs.
 cert              Manage certificates and requests
 certificate       Provide access to the CA for certificate management.
 certificate_request  Manage certificate requests. (Deprecated)
 certificate_revocation_list  Manage the list of revoked certificates. (Deprecated)
 config            Interact with Puppet's settings.
 describe          Display help about resource types
 device            Manage remote network devices
 doc               Generate Puppet references
 epp               Interact directly with the EPP template parser/renderer.
 facts             Retrieve and store facts.
 filebucket        Store and retrieve files in a filebucket
 generate          Generates Puppet code from Ruby definitions.
 help              Display Puppet help.
 key               Create, save, and remove certificate keys. (Deprecated)
 lookup            Interactive Hiera lookup
 man               Display Puppet manual pages.
 master            The puppet master daemon
 module            Creates, installs and searches for modules on the Puppet Forge.
 node              View and manage node definitions.
 parser            Interact directly with the parser.
 plugin            Interact with the Puppet plugin system.
 report            Create, display, and submit reports.
 resource          The resource abstraction layer shell
 status            View puppet server status. (Deprecated)

One difference between facter and Puppet facts is that you may request a single fact from facter, whereas Puppet facts will return all the facts for a node at once as a JSON object (you may request other formats with the --render-as option).

To show how ordering works, we'll create a manifest that installs httpd and then ensures the httpd package service is running.

We'll create a manifest to install and start our service:

1. Start by creating a manifest that defines service:

service {'httpd':
  ensure  => running,
  require => Package['httpd'],
}

2. The service definition references a package resource named httpd; we now need to define that resource:

package {'httpd':
  ensure => 'installed',
}

In this example, the package will be installed before the service is started. Using require within the definition of the httpd service ensures that the package is installed first, regardless of the order within the manifest file.

Capitalization is important in Puppet. In our previous example, we created a package named httpd. If we wanted to refer to this package later, we would capitalize its type (package) as follows:

Package['httpd']

To refer to a class- for example, the something::somewhere class, which has already been included/defined in your manifest-you can reference it with the full path as follows:

Class['something::somewhere']

Let's say you have defined the following type:

example::thing {'one':}

The preceding line may be referenced later, as follows:

Example::Thing['one']

Knowing how to reference previously defined resources is necessary for the next section on metaparameters and ordering.

All the manifests that will be used to define a node are compiled into a catalog. A catalog is the code that will be applied to configure a node. It is important to remember that manifests are not applied to nodes sequentially. There is no inherent order to the application of manifests. With this in mind, in the previous httpd example, what if we wanted to ensure that the httpd process started after the httpd package was installed?

We couldn't rely on the httpd service coming after the httpd package in the manifests. What we would have to do is use metaparameters to tell Puppet the order in which we want resources applied to the node. Metaparameters are parameters that can be applied to any resource and are not specific to any one resource type. They are used for catalog compilation and as hints to Puppet, but not to define anything about the resource to which they are attached.

When dealing with ordering, there are four metaparameters used:

• before
• require
• notify
• subscribe

The before and require metaparameters specify a direct ordering; notify implies before and subscribe implies require. The notify metaparameter is only applicable to services; what notify does is tell a service to restart after the notifying resource has been applied to the node (this is most often a package or file resource). In the case of files, once the file is created on the node, a notify parameter will restart any services mentioned. The subscribe metaparameter has the same effect but is defined on the service; the service will subscribe to the file.

The relationship between package and service previously mentioned is an important and powerful paradigm of Puppet. Adding one more resource-type file into the fold creates what puppeteers refer to as the trifecta. Almost all system administration tasks revolve around these three resource types. As a system administrator, you install a package, configure the package with files, and then start the service:

A key concept of Puppet is that the state of the system when a manifest is applied to a node cannot affect the outcome of the Puppet run. In other words, at the end of the Puppet run (if the run was successful), the system will be in a known state and any further application of the manifest will result in a system that is in the same state. This property of Puppet is known as idempotency. Idempotency is the property that, no matter how many times you do something, remains in the same state as the first time you did it. For instance, if you had a light switch and you gave the instruction to turn it on, the light would turn on. If you gave the instruction again, the light would remain on.

There are many examples of this pattern online. In our simple example, we will create an Apache configuration file under /etc/httpd/conf.d/cookbook.conf. The /etc/httpd/conf.d directory will not exist until the httpd package is installed. After this file is created, we would want httpd to restart to notice the change; we can achieve this with a notify parameter.

We will need the same definitions as our last example; we need the package and service installed. We now need two more things. We need the configuration file and index page (index.html) created. For this, we follow these steps:

1. As in the previous example, we ensure the service is running and specify that the service requires the httpd package:

service {'httpd':
  ensure  => running,
  require => Package['httpd'],
}

2. We then define package as follows:

package {'httpd':
  ensure => installed,
}

3. Now, we create the /etc/httpd/conf.d/cookbook.conf configuration file; the /etc/httpd/conf.d directory will not exist until the httpd package is installed. We'll use @heredoc syntax here to make the code a little more readable, assigning the cookbook.conf contents to the $cookbook variable. The require metaparameter tells Puppet that this file requires the httpd package to be installed before it is created:

$cookbook = @(COOKBOOK)
  <VirtualHost *:80>
    Servername cookbook
    DocumentRoot /var/www/cookbook
  </VirtualHost>
  | COOKBOOK
file {'/etc/httpd/conf.d/cookbook.conf':
  content => $cookbook,
  require => Package['httpd'],
  notify => Service['httpd'],
}

4. We then go on to create an index.html file for our virtual host in /var/www/cookbook. Again, we'll use @heredoc syntax to make this more readable. This directory won't exist yet, so we need to create this as well, using the following code:

$index = @(INDEX)
  <html>
    <body>
      <h1>Hello World!</h1>
    </body>
  </html>
  | INDEX
file {'/var/www/cookbook':
  ensure  => directory,
  require => Package['httpd'],
}
file {'/var/www/cookbook/index.html':
  content => $index,
  require => File['/var/www/cookbook'],
}

The require attribute to the file resources tells Puppet that we need the /var/www/cookbook directory created before we can create the index.html file. The important concept to remember is that we cannot assume anything about the target system (node). We need to define everything on which the target depends. Anytime you create a file in a manifest, you have to ensure that the directory containing that file exists. Anytime you specify that a service should be running, you have to ensure that the package providing that service is installed.

In this example, using metaparameters, we can be confident that no matter what state the node is in before running Puppet, after Puppet runs, the following will be true:

• httpd will be running
• The VirtualHost configuration file will exist
• httpd will restart and be aware of the VirtualHost file
• The DocumentRoot directory will exist
• An index.html file will exist in the DocumentRoot directory

If other people need to read or maintain your manifests, or if you want to share code with the community, it's a good idea to follow the existing style conventions as closely as possible. These govern such aspects of your code as layout, spacing, quoting, alignment, and variable references, and the official puppetlabs recommendations on style are available at https://puppet.com/docs/puppet/latest/style_guide.html.

In this section, I'll show you a few of the more important examples and how to make sure that your code is style compliant.

Indent your manifests using two spaces (not tabs), as follows:

service {'httpd':
  ensure => 'running',
}

Always quote your resource names, as follows:

package { 'exim4': }

We cannot do this though:

package { exim4: }

Use single quotes for all strings, except when:

• The string contains variable references, such as ${::fqdn}
• The string contains character escape sequences, such as \n

Consider the following code:

file { '/etc/motd':
  content => "Welcome to ${::fqdn}\n"
}

Puppet doesn't process variable references or escape sequences unless they're inside double quotes.

Always quote parameter values that are not reserved words in Puppet. For example, the following values are not reserved words:

name  => 'Nucky Thompson',
mode  => '0700',
owner => 'deploy',

However, these values are reserved words and therefore not quoted:

ensure => installed,
enable => true,
ensure => running,

There is only one thing in Puppet that is false, that is, the word false without any quotes. The string false evaluates to true and the string true also evaluates to true. Actually, everything besides the literal false evaluates to true (when treated as a Boolean):

if "false" {
  notify { 'True': }
}
if 'false' {
  notify { 'Also true': }
}
if false {
  notify { 'Not true': }
}

When this code is run through puppet apply, the first two notifies are triggered. The final notify is not triggered; it is the only one that evaluates to false.

Always include curly braces {} around variable names when referring to them in strings, for example, as follows:

source => "puppet:///modules/webserver/${brand}.conf",

Otherwise, the Puppet parser has to guess which characters should be a part of the variable name and which belong to the surrounding string. Curly braces make it explicit.

Always end lines that declare parameters with a comma, even if it is the last parameter:

service { 'memcached':
  ensure => running,
  enable => true,
}

This is allowed by Puppet, and makes it easier if you want to add parameters later, or reorder the existing parameters.

When declaring a resource with a single parameter, make the declaration all on one line and with no trailing comma, as shown in the following snippet:

package { 'puppet':
  ensure => installed
}

Where there is more than one parameter, give each parameter its own line:

package { 'rake':
  ensure   => installed,
  provider => gem,
  require  => Package['rubygems'],
}

To make the code easier to read, line up the parameter arrows in line with the longest parameter, as follows:

file { "/var/www/${app}/shared/config/rvmrc":
  owner   => 'deploy',
  group   => 'deploy',
  content => template('rails/rvmrc.erb'),
  require => File["/var/www/${app}/shared/config"],
}

The arrows should be aligned per resource, but not across the whole file, otherwise it may be difficult for you to cut and paste code from one file to another.

When declaring file resources that are symlinks, use the ensure => link and set the target attribute, as follows:

file { '/etc/php5/cli/php.ini':
  ensure => link,
  target => '/etc/php.ini',
}

You may install Puppet locally on your machine or create a virtual machine and install Puppet on that machine.

For YUM-based systems, use https://yum.puppetlabs.com/puppet5, and for APT-based systems, use https://apt.puppetlabs.com/. Use the puppet5-release-[version].deb package to install Puppet 5. After installing the YUM release RPM or the APT release source package, install the puppet-agent package. The puppet-agent package installs all the files necessary to support Puppet in agent mode on a node.

You may also use gem to install Puppet:

1. To use gem, we need the rubygems package as follows:

t@cookbook:~$ sudo yum install rubygems
 Resolving Dependencies
 --> Running transaction check
 ---> Package rubygems.noarch 0:2.0.14.1-30.el7 will be installed
 ...
 Installed:
  rubygems.noarch 0:2.0.14.1-30.el7

2. Now, use gem to install Puppet:

t@cookbook:~$ gem install puppet

Fetching: facter-2.5.1.gem (100%)
Successfully installed facter-2.5.1
Fetching: hiera-3.4.2.gem (100%)
Successfully installed hiera-3.4.2
Fetching: fast_gettext-1.1.0.gem (100%)
Successfully installed fast_gettext-1.1.0
Fetching: locale-2.1.2.gem (100%)
Successfully installed locale-2.1.2
Fetching: text-1.3.1.gem (100%)
Successfully installed text-1.3.1
Fetching: gettext-3.2.6.gem (100%)
Successfully installed gettext-3.2.6
Fetching: gettext-setup-0.29.gem (100%)
Successfully installed gettext-setup-0.29
Fetching: puppet-5.0.0.gem (100%)
Successfully installed puppet-5.5.2
Parsing documentation for facter-2.5.1
Installing ri documentation for facter-2.5.1
Parsing documentation for hiera-3.4.2
Installing ri documentation for hiera-3.4.2
Parsing documentation for fast_gettext-1.1.0
Installing ri documentation for fast_gettext-1.1.0
Parsing documentation for locale-2.1.2
Installing ri documentation for locale-2.1.2
Parsing documentation for text-1.3.1
Installing ri documentation for text-1.3.1
Parsing documentation for gettext-3.2.6
Installing ri documentation for gettext-3.2.6
Parsing documentation for gettext-setup-0.29
Installing ri documentation for gettext-setup-0.29
Parsing documentation for puppet-5.5.2
Installing ri documentation for puppet-5.5.2
8 gems installed

For the examples in this book, I suggest using the puppet-agent package installation. The package installation method of Puppet uses the AIO (All-In-One) mentality. The puppet-agent package installs all the necessary support files for Puppet and does not rely on system libraries and applications. The most important dependency is Ruby: the AIO puppet-agent package installs a Puppet-specific Ruby that has been tested against the version of Puppet to which it belongs.