Class and Modules
• Modules – an advanced, portable collection of resources that can include classes, definitions, and other supporting configuration
Resource:
Manifests
Puppet programs are called "manifests", and they use the .pp file extension.
The core of the Puppet language is the resource declaration. A resource declaration describes a desired state for one resource.
(Manifests can also use various kinds of logic: conditional statements, collections of resources, functions to generate text, etc. You can go further reading on its official site)
Syntax Hints
Watch out for these common errors:
- Don't forget commas and colons! Forgetting them causes errors like Could not parse for environment production: Syntax error at 'mode'; expected '}' at /root/manifests/1.file.pp:6 on node learn.localdomain.
- Capitalization matters! The resource type and the attribute names should always be lowercase.
- The values used for titles and attribute values will usually be strings, which you should usually quote. Read more about Puppet’s data types here.
- There are two kinds of quotes in Puppet: single (') and double ("). The main difference is that double quotes let you interpolate $variables, which we cover in another lesson.
- Attribute names (like path, ensure, etc.) are special keywords, not strings. They shouldn’t be quoted.
Also, note that Puppet lets you use whatever whitespace makes your manifests more readable. We suggest visually lining up the => arrows, because it makes it easier to understand a manifest at a glance.
Titles and Namevars
# /root/examples/file-1.pp
file {'testfile':
path => '/tmp/testfile',
ensure => present,
mode => 0640,
content => "I'm a test file.",
}
# /root/examples/file-2.pp
file {'/tmp/test1':
ensure => file,
content => "Hi.",
}
Notice how the first file resource had a path attribute, but the next left it out?
Almost every resource type has one attribute whose value defaults to the resource's title. For the file resource, that's path. Most of the time (user, group, package…), it's name.
These attributes are called "namevars". They are generally the attribute that corresponds to the resource's identity, the one thing that should always be unique.
If you leave out the namevar for a resource, Puppet will re-use the title as its value. If you do specify a value for the namevar, the title of the resource can be anything.
So why even have a namevar, if Puppet can just re-use the title?
There are two kinds of identity that Puppet recognizes:
- Identity within Puppet itself
- Identity on the target system
Most of the time these are the same, but sometimes they aren't. For example, the NTP service has a different name on different platforms: on Red Hat-like systems, it's called ntpd, and on Debian-like systems, it's ntp. These are logically the same resource, but their identity on the target system isn't the same.
Also, there are cases (usually exec resources) where the system identity has no particular meaning, and putting a more descriptive identity in the title can help tell your colleagues (or yourself in two months) what a resource is supposed to be doing.
By allowing you to split the title and namevar, Puppet makes it easy to handle these cases. We'll cover this later when we get to conditional statements.
Uniqueness
Note that you can't declare the same resource twice: Puppet always disallows duplicate titles within a given type, and usually disallows duplicate namevar values within a type.
This is because resource declarations represent desired final states, and it’s not at all clear what should happen if you declare two conflicting states. So Puppet will fail with an error instead of accidentally doing something wrong to the system.
Aside: Compilation
Manifests don't get used directly when Puppet syncs resources. Instead, the flow of a Puppet run goes a little like this:
As we mentioned above, manifests can contain conditional statements, variables, functions, and other forms of logic. But before being applied, manifests get compiled into a document called a "catalog", which only contains resources and hints about the order to sync them in.
With puppet apply, the distinction doesn’t mean much. In a master/agent Puppet environment, though, it matters more, because agents only see the catalog:
- By using logic, manifests can be flexible and describe many systems at once. A catalog describes desired states for one system.
- By default, agent nodes can only retrieve their own catalog; they can’t see information meant for any other node. This separation improves security.
- Since catalogs are so unambiguous, it's possible to simulate a catalog run without making any changes to the system. (This is usually done by running
puppet agent --test --noop
.) You can even use special diff tools to compare two catalogs and see the differences.
The Site Manifest and Puppet Agent
We've seen how to use puppet apply to directly apply manifests on one system. The puppet master/agent services work very similarly, but with a few key differences:
Puppet apply:
- A user executes a command, triggering a Puppet run.
- Puppet apply reads the manifest passed to it, compiles it into a catalog, and applies the catalog.
Puppet agent/master:
- Puppet agent runs as a service, and triggers a Puppet run about every half hour (configurable).
- On your VM, the agent service is named
puppet
. (Puppet agent can also be configured to run from cron, instead of as a service.)
- On your VM, the agent service is named
- Puppet agent does not have access to any manifests; instead, it requests a pre-compiled catalog from a puppet master server.
- On your VM, the puppet master appears as the puppetmaster service. A sandboxed copy of Apache with Passenger manages the puppet master application, spawning and killing new copies of it as needed.
- The puppet master always reads one special manifest, called the "site manifest" or site.pp. It uses this to compile a catalog, which it sends back to the agent.
- On your VM, the site manifest is at
/etc/puppetlabs/puppet/manifests/site.pp
.
- On your VM, the site manifest is at
- After getting the catalog, the agent applies it.
This way, you can have many machines being configured by Puppet, while only maintaining your manifests on one (or a few) servers. This also gives some extra security, as described above under "Compilation".