Forge Home

Modules

Puppet

Resources

PuppetEcosystemPuppet CommunityUpdates

transition

Provides a Puppet type and provider for describing conditional transition states.
Project URLRSS FeedReport issues

738,313 downloads

16,090 latest version

5.0 quality score

We run a couple of automated
scans to help you access a
module's quality. Each module is
given a score based on how well
the author has formatted their
code and documentation and
modules are also checked for
malware using VirusTotal.

Please note, the information below
is for guidance only and neither of
these methods should be considered
an endorsement by Puppet.

Version information

  • 2.0.0 (latest)
  • 1.0.0
  • 0.1.3
  • 0.1.1
  • 0.1.0
released Jun 2nd 2023
This version is compatible with:
  • Puppet Enterprise 2023.8.x, 2023.7.x, 2023.6.x, 2023.5.x, 2023.4.x, 2023.3.x, 2023.2.x, 2023.1.x, 2023.0.x, 2021.7.x, 2021.6.x, 2021.5.x, 2021.4.x, 2021.3.x, 2021.2.x, 2021.1.x, 2021.0.x
  • Puppet >= 7.0.0 < 9.0.0
  • , , , , , , , , , , ,

Start using this module

  • r10k or Code Manager
  • Bolt
  • Manual installation
  • Direct download

Add this module to your Puppetfile:

mod 'puppetlabs-transition', '2.0.0'
Learn more about managing modules with a Puppetfile

Add this module to your Bolt project:

bolt module add puppetlabs-transition
Learn more about using this module with an existing project

Manually install this module globally with Puppet module tool:

puppet module install puppetlabs-transition --version 2.0.0

Direct download is not typically how you would use a Puppet module to manage your infrastructure, but you may want to download the module in order to inspect the code.

Download
Tags: catalog, transition

Documentation

puppetlabs/transition — version 2.0.0 Jun 2nd 2023

Transition

Table of Contents

  1. Overview
  2. Module Description - What the module does and why it is useful
  3. Usage - Configuration options and additional functionality
  4. Reference - An under-the-hood peek at what the module is doing and how
  5. Limitations - OS compatibility, etc.

Overview

This module provides a Puppet type and provider for describing conditional transition states. It allows users to describe a scenario where prior to performing a change, a temporary state should be invoked.

Module Description

Consider the following scenario.

The desired end state is that the myapp service is running, and that the myapp.cfg file has some specific content. In Puppet this can be modeled with the following code.

file { '/etc/myapp/myapp.cfg':
  ensure  => file,
  content => 'enabled=1',
  notify  => Service['myapp'],
}

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

The myapp service, however, is sensitive to the configuration file being changed while it is running. In order to ensure consistency, its developers recommend that the configuration file not be changed while the application is running.

Puppet is designed to model end state, and by default it cannot model the desired procedure of shutting down myapp, modifying myapp.cfg, and then starting myapp back up.

The transition module provides a new type that can be used to express intermediate state, thus modeling transactions such as

  1. stop service
  2. modify configuration
  3. start service

Usage

Conceptually, the transition type specifies two things. First, it specifies a desired transition state in the form of a Puppet resource reference and parameters for that resource. Second, it specifies an array of other resources in the catalog, for which this temporary transition state should be invoked prior to changing.

Example Usage

In relation to the problem laid out above in the Module Description, the transition type is used used as follows.

transition { 'stop myapp service':
  resource   => Service['myapp'],
  attributes => { ensure => stopped },
  prior_to   => File['/etc/myapp/myapp.cfg'],
}

file { '/etc/myapp/myapp.cfg':
  ensure  => file,
  content => 'enabled=1',
  notify  => Service['myapp'],
}

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

Attributes

resource

The resource for which a transitional state is being defined. This should be a resource reference (e.g. Service['apache']). This resource will be made to autorequire the transitional state.

attributes

The hash of attributes to set on the resource when applying a transitional state. Each hash key must be a valid attribute for the resource being transitioned.

prior_to

An array of resources to check for synchronization. If any of these resources are out of sync (change pending), then the transition state will be applied. These resources will each be made to autorequire the transitional state.

Reference

The transition type operates by performing a look-ahead operation on the catalog to determine whether or not to create and apply a transient single-resource state.

The type automatically adds a before edge to each resource in the prior_to parameter, and a before edge to the resource specified in the resource parameter.

When evaluated, the transition provider will retrieve each resource specified in the prior_to hash from the catalog, and for each resource, invoke each managed property'sinsync? method. If any of the resources are found to have any properties out of sync, the transition resource will apply the transitional state defined by the resource and attribute parameters.

By requiring that the resource parameter refer to a resource that exists in the catalog, there should always exist a desired state which is enforced following the transition.

Limitations

The resource parameter must refer to a native type

The resource parameter may only refer to a native type, it cannot refer to a defined type. This is because the transition provider operates on the catalog, and does not have or assume access to the original Puppet manifest(s) that build defined types.

Resources given to prior_to should not specify noop

While the transition resource operates correctly with the global noop flag set either true or false, it does not currently check each individual prior_to resource to determine if the individual resource is noop. Therefore, do not at this time specify resources in the prior_to parameter that use the noop metaparameter.

Do not transition resources that use resource generators

The current implementation of the transition type performs resource transitions by invoking the equivalent of puppet resource <type> <parameters=values>. Notably, this state change operation is done outside the scope of the current catalog. For most resources and types this works just fine, but resources invoked in a way that trigger additional resource generation (generate and eval_generate methods) may have unexpected behavior if a transition using them is attempted.

tl;dr: DO NOT attempt to transition a file resource that has either recurse=true or purge=true. There may exist other conditions under which a resource should not be transitioned, but we haven't thought of or found them yet.