Skip to content
Tutorials Center
My learning

Topics

Lesson 10 of 38 ยท Manifests and Resources

Resources and Resource Types

Master Puppet resources: declaration syntax, titles and namevars, the core types file, package, service, user, group and exec, ensure, and resource defaults.

Everything Puppet manages is a resource. A resource declaration says: "this thing of this type should have these properties". This lesson covers the syntax, the most important built-in types and the rules that make resources predictable. Because Puppet cannot run on the site, the Puppet code below is read-only, and a runnable stand-in at the end checks resource declarations.

Declaration syntax

PUPPET
type { 'title':
  attribute1 => value1,
  attribute2 => value2,
}
  • type is lowercase when declaring (file) and capitalised when referring (File['/etc/motd']).
  • title identifies the resource inside the catalog. Two resources of the same type cannot share a title; Puppet fails the compile with a duplicate declaration error.
  • attributes are name => value pairs, separated by commas. A trailing comma after the last pair is allowed and recommended.
  • Each type has a namevar, the attribute that identifies the real-world thing (for file it is path, for package it is name). By default the title supplies it, so these two are equivalent:
PUPPET
file { '/etc/motd': ensure => file }
file { 'motd': path => '/etc/motd', ensure => file }

Use an explicit namevar when you want a human-friendly title or when the same file is managed under different names on different platforms.

Attributes split into properties (things Puppet can read and change, such as ensure, content, mode) and parameters (instructions that do not map to a thing on the system, such as provider, purge, source). Puppet only reports a change when a property differs.

The ensure attribute

ensure is the main property for most types. It says whether the thing should exist.

Type Common ensure values
file file, directory, link, absent
package installed (or present), latest, absent, a version string
service running, stopped
user, group present, absent

ensure => latest upgrades on every run and can cause surprise changes in production. Prefer installed and a deliberate version pin, or a managed repository.

The core types

file

PUPPET
file { '/etc/app':
  ensure => directory,
  owner  => 'root',
  group  => 'root',
  mode   => '0755',
}

file { '/etc/app/app.conf':
  ensure  => file,
  owner   => 'root',
  mode    => '0640',
  content => "port = 8080\n",   # inline text
  # source => 'puppet:///modules/app/app.conf',   # or a file from a module
}

file { '/etc/app/current':
  ensure => link,
  target => '/opt/app/releases/42',
}

Always quote mode as a string ('0644'): an unquoted 0644 can be misread. With source => 'puppet:///modules/app/app.conf', Puppet fetches files/app.conf from the app module (Modules). To manage content with variables use a template (covered in the Facts and Templates chapter).

package

PUPPET
package { 'nginx':
  ensure => installed,
}
package { 'oldtool':
  ensure => absent,
}

The provider is chosen automatically (apt, dnf, yum, gem, pip...). The package name can differ by platform (apache2 on Debian, httpd on Red Hat); the title is typically the name but you can set name => explicitly.

service

PUPPET
service { 'nginx':
  ensure => running,
  enable => true,     # start at boot
}

ensure controls whether it runs now; enable controls whether it starts at boot. They are separate.

user and group

PUPPET
group { 'deploy':
  ensure => present,
  gid    => 2001,
}
user { 'deploy':
  ensure     => present,
  uid        => 2001,
  gid        => 'deploy',
  shell      => '/bin/bash',
  home       => '/home/deploy',
  managehome => true,
  require    => Group['deploy'],
}

exec

exec runs a command. It is the escape hatch and the least idempotent type, so guard it:

PUPPET
exec { 'initialise-db':
  command => '/usr/local/bin/initdb /var/lib/app',
  creates => '/var/lib/app/PG_VERSION',   # skip if this file exists
  path    => ['/usr/bin', '/usr/local/bin'],
}
exec { 'reload-nginx-config':
  command     => '/usr/sbin/nginx -s reload',
  refreshonly => true,                   # only when notified
}

Without creates, onlyif, unless or refreshonly, an exec runs on every single run. Reach for a proper type before using exec.

Other useful types

cron, host, mount, notify (print a message), ssh_authorized_key, file_line (from stdlib), and on Windows registry_key. List all with puppet resource --types. Inspect a live resource as Puppet sees it:

Terminal
puppet resource service nginx
puppet resource user root

Resource defaults and metaparameters

Some attributes work on every type. They are metaparameters: require, before, notify, subscribe (see Relationships and Ordering), noop, tag, alias, loglevel, audit and a few more.

To avoid repeating attributes, use a capitalised type as a resource default:

PUPPET
File {
  owner => 'root',
  group => 'root',
  mode  => '0644',
}
file { '/etc/a': content => "a\n" }
file { '/etc/b': content => "b\n", mode => '0600' }   # overrides the default

Defaults are scoped to the class or node block they are written in (and the code it declares), so a default in one class does not leak into unrelated code.

Duplicate resources are the most common compile error for beginners: "Duplicate declaration: Package[nginx] is already declared". Two classes both declared the same resource. Fix it by declaring it in one place only, or use ensure_packages() / a shared class.

A stand-in: a resource declaration checker

Python Stand-in: validate declarations

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Python Stand-in: exec guards

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What happens if two resources of the same type share a title?

    Type and title together must be unique in the catalog.
  2. 2. Which file ensure value creates a folder?

    ensure => directory creates a directory.
  3. 3. What does enable => true do on a service?

    enable is about boot; ensure => running is about the current state.
  4. 4. How do you stop an exec from running every time?

    Guards make the command run only when needed.

Summary

  • A resource is type { 'title': attribute => value }; type plus title must be unique.
  • ensure states existence; properties are enforced, parameters are instructions.
  • Core types: file, package, service, user, group, exec.
  • Guard exec; avoid ensure => latest in production.
  • Capitalised type blocks set resource defaults.

Next: Variables and Data Types