Skip to content
Tutorials Center
My learning

Topics

Lesson 13 of 38 ยท Manifests and Resources

Resource Relationships and Ordering

Control Puppet resource order with require, before, notify, subscribe and chaining arrows, understand the dependency graph, refresh events, autorequire and avoid cycles.

In a shell script, the order of lines is the order of execution. In Puppet, it is not. Puppet reads all resources into a dependency graph and decides the order itself. If you do not say that one resource must come before another, Puppet may apply them in any order (in practice the order of the file by default, but never rely on it). Relationships are how you express "A before B".

The four metaparameters

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

file { '/etc/nginx/nginx.conf':
  ensure  => file,
  source  => 'puppet:///modules/nginx/nginx.conf',
  require => Package['nginx'],     # package first, then file
  notify  => Service['nginx'],     # when the file changes, refresh the service
}

service { 'nginx':
  ensure => running,
  enable => true,
}
Metaparameter Meaning
before => X this resource is applied before X
require => X this resource is applied after X
notify => X like before, plus send a refresh to X if this resource changed
subscribe => X like require, plus refresh this resource if X changed

notify and subscribe are two spellings of the same relationship, viewed from opposite ends. The reference Package['nginx'] has a capitalised type and the title in brackets. You can use an array to point at several resources: require => [Package['a'], File['/etc/b']].

Refresh events

A refresh is a signal sent after a resource really changed. A service reacts by restarting (or reloading, if the provider supports it); an exec with refreshonly => true runs its command; a mount remounts. If the file did not change, no refresh is sent, so the service is not needlessly restarted. This is the standard recipe for "config file changed, restart the daemon".

PUPPET
exec { 'rebuild-index':
  command     => '/usr/local/bin/build-index',
  refreshonly => true,
  subscribe   => File['/etc/app/index.conf'],
}

Chaining arrows

For short relationships you can write arrows between references (or between whole collections):

PUPPET
Package['nginx'] -> File['/etc/nginx/nginx.conf'] ~> Service['nginx']
  • -> ordering only (left before right).
  • ~> ordering plus refresh notification.
  • The arrows point from the earlier resource to the later one; <- and <~ are the reverse.

Arrows are compact for a short chain, but metaparameters are easier to read and search for inside a resource. Pick one style per module and stay consistent. Resource collectors also work with arrows (for example Yumrepo <| |> -> Package <| |>), but use these carefully: they are powerful and affect many resources at once.

Autorequire

Puppet already knows some obvious relationships. A file automatically requires its parent directory resource if you manage it, a user requires its primary group, a service that has a matching config does not (it cannot know). These autorequires are listed in each type's documentation. They save typing, but only when both resources are in the catalog; they never create missing resources.

Ordering classes

Relationships work between classes as well, which makes them useful for stages of a build:

PUPPET
class { 'base': }
class { 'webapp':
  require => Class['base'],
}

Or inside a class with contain so everything declared in a nested class counts as part of the outer class:

PUPPET
class profile::web {
  contain nginx          # nginx's resources are inside profile::web
  contain app
  Class['nginx'] -> Class['app']
}

Without contain, a class declared with include is not "inside" the outer class for ordering: a relationship on the outer class would not wait for it. If you order a class, use contain for the classes it declares.

Dependency cycles

If A requires B and B requires A, Puppet cannot compute an order and fails the compile with a dependency cycle error that prints the cycle:

TEXT
Error: Failed to apply catalog: Found 1 dependency cycle:
(File[/etc/a] => Service[b] => File[/etc/a])

Fix it by removing one of the relationships, or by realising that two of your resources have no real dependency. The error output can be turned into a graph with --graph, which writes .dot files that you can render with Graphviz.

Explicit ordering mode

By default Puppet applies unrelated resources in the order they appear in the manifest (ordering = manifest). This is deterministic, but never rely on it as a dependency: a refactor that moves code around would change behaviour silently. Always declare what must be ordered.

flowchart LR
    P["Package[nginx]"] --> F["File[nginx.conf]"]
    F -- "refresh if changed" --> S["Service[nginx]"]
    U["User[deploy]"]

The user has no relationships, so it can be applied at any point.

A stand-in: the dependency graph

Python Stand-in: order resources and detect cycles

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: refresh only on change

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.

Running the file resource twice with the same content restarts the service only once, which is why notify beats an unconditional restart.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What is the difference between require and notify?

    notify orders resources and triggers a refresh (e.g. restart) on change.
  2. 2. What does Package['a'] -> Service['b'] mean?

    The arrow points from the earlier to the later resource.
  3. 3. Why use contain inside a class?

    contain makes ordering on the outer class apply to the contained class.
  4. 4. What does Puppet do on a dependency cycle?

    A cycle makes ordering impossible, so the catalog fails.

Summary

  • Order is not implied by position; declare it with require, before, notify, subscribe or arrows.
  • notify/subscribe also send refresh events (restart services, run refreshonly execs).
  • -> orders, ~> orders and notifies.
  • Use contain for classes inside a class; avoid cycles.
  • Autorequire covers obvious cases such as a file and its managed parent directory.

Next: Iteration, Functions, and Lambdas