Language: Run stages

Run stages are an additional way to order resources. They allow groups of classes to run before or after nearly everything else, without having to explicitly create relationships with every other class.

Run stages have several major limitations; you should understand these before attempting to use them.

The run stage feature has two parts:

  • A stage resource type.
  • A stage metaparameter, which assigns a class to a named run stage.

The default main stage

By default there is only one stage (named main). All resources are automatically associated with this stage unless explicitly assigned to a different one. If you do not use run stages, every resource is in the main stage.

Custom stages

Additional stages are declared as normal resources. Each additional stage must have an order relationship with another stage, such as Stage['main']. As with normal resources, these relationships can be specified with metaparameters or with chaining arrows.

stage { 'first':
  before => Stage['main'],
}
stage { 'last': }
Stage['main'] -> Stage['last']

In the above example, all classes assigned to the first stage will be applied before classes in the main stage, and both will be applied before the last stage.

Assigning classes to stages

Once stages have been declared, a class can be assigned to a custom stage with the stage metaparameter.

class { 'apt-keys':
  stage => first,
}

The above example ensures the apt-keys class happens before all other classes, which is useful if most of your package resources rely on those keys.

Limitations and known issues

  • To assign a class to a stage, you must use the resource-like class declaration syntax and supply the stage explicitly. You cannot assign classes to stages with the include function or by relying on automatic parameter lookup from Hiera with resource-like declarations.
  • You cannot subscribe to or notify resources across a stage boundary.
  • Classes that contain other classes (with either the contain function or the anchor pattern) can sometimes behave badly if declared with a run stage. If the contained class is only declared by its container it will work fine, but if it is also declared anywhere outside its container it will often create a dependency cycle that prevents the involved classes from being applied.

Due to these limitations, stages should only be used with the simplest of classes, and only when absolutely necessary. Mass dependencies like package repositories are effectively the only valid use case.