Configure Puppet to work with Relay




314 latest version

5.0 quality score

Version information

  • 2.1.0 (latest)
  • 2.0.0
  • 1.2.0
  • 1.1.0
  • 1.0.1
  • 1.0.0
released Nov 19th 2020
This version is compatible with:
  • Puppet Enterprise 2019.8.x, 2019.7.x, 2019.5.x, 2019.4.x, 2019.3.x, 2019.2.x, 2019.1.x, 2019.0.x, 2018.1.x, 2017.3.x, 2017.2.x, 2016.4.x
  • Puppet >= 4.10.0 < 7.0.0
  • CentOS

Start using this module


puppetlabs/relay — version 2.1.0 Nov 19th 2020


Table of Contents

  1. Description
  2. Setup - The basics of getting started with relay
  3. Usage - Configuration options and additional functionality
  4. Limitations - OS compatibility, etc.
  5. Development - Guide for contributing to the module


This module configures a report processor to submit any changed resources to the Relay SaaS event trigger API. Workflows may subscribe to the triggers and decide whether to run based on the run status and log lines.

Second, it runs a Relay agent on your puppetserver which can be used to trigger puppet run (without requiring inbound connectivity to your puppetserver).


0. Requirements

You must already have a puppetserver to which puppet agents submit reports and that can connect to the internet.

You must also have a Relay account registered. You can sign up for one at if you do not already have one.

1. Setup the Relay workflow

The report processor needs a Relay push-trigger access token that is authorized to talk to the Relay API. To get an access token, add a workflow push trigger to a Relay workflow and copy the token from the sidebar.

The workflow trigger in Relay will look something like this:

  - name: puppet-report
      type: push
        host: !Data host
        resource_statuses: !Data resource_statuses
        status: !Data status
        time: !Data time

You'll then copy the access token from the sidebar:  Copying access token from the sidebar

To see an example of a Relay workflow that uses this trigger, check it out here.

Please see our documentation for further details on configuring push triggers.

2. Configure the puppetserver

The report processor may be automatically set up by classifying the puppetserver host with the relay class. This class will:

  1. configure the report processor list of the puppetserver to include the relay report processor if you specify one or more trigger tokens
  2. (on Puppet Enterprise) reload the puppetserver process to load the new report processor
  3. configure the agent to synchronize with the Relay service if you specify a connection token
  4. set up the Relay agent configuration and service to run automatically

The classification will look something like this for Puppet Enterprise:

class { 'relay':
  relay_trigger_token => [
  relay_connection_token => Sensitive('eyJhbG...adQssw5c'),
  backend_options => {
    # This is a Puppet RBAC token for connecting to the Orchestrator API,
    # generated using the `puppet-access` command.
    token => Sensitive(''),

For open source Puppet, the agent can use Bolt to execute the Puppet agent:

class { 'relay':
  # ...
  backend_options => {
    ssh_host_key_check => false,
    ssh_user => 'puppet-automation',
    ssh_password => Sensitive('@utom@tion'),

Example #1: Trigger Relay workflow from Puppet run

Run the Puppet agent (either in noop or enforce mode) to trigger the Relay workflow.

Note that the report will only be sent if resources are out of sync.

$ puppet agent -t --noop

Example #2: Trigger Puppet run from Relay

Configure a Puppet step in your Relay workflow:

- name: start-puppet-run
  image: relaysh/puppet-step-run-start
    connection: !Connection { type: puppet, name: my-puppet-server }
    environment: production
      - !Parameter host

When your Relay workflow runs, it will start a puppet run on the target host.


relay class

This is class used to configure the report processor and agent.



Type: Boolean

Whether to enable debug logging for the report processor and agent.

Default: false


Type: Boolean

Whether to enable test mode and verbosity for the report processor and agent.

Default: false


Type: String

The base URL to the Relay API to connect to.

Default: ""


Type: Sensitive[String]

The connection token to use for the agent. If not specified, the agent is disabled.


Type: Sensitive[String] or Array[Sensitive[String]]

One or more trigger tokens to use to start Relay workflows from the report processor. If not defined or an empty array, the report processor is disabled.


Type: String

The backend to use for running the Puppet agent.


  • "orchestrator"
  • "bolt"
  • "ssh" (coming soon!)

Default: "orchestrator" in Puppet Enterprise, "bolt" otherwise.


Type: Hash[String, Variant[Data, Sensitive[Data]]]

A hash of options to configure the given backend. The options available differ depending on which backend is chosen.

For backend "orchestrator":

  • api_url: The URL to the orchestrator API. Make sure to include the trailing slash in the URL. Default: "https://{puppetserver}:8143/orchestrator/v1/"
  • token: The RBAC token to use to access the orchestrator API. Sensitive. Required.

For backend "bolt":

  • bolt_command: The path to the Bolt command as an array. Default: ["bolt"]
  • ssh_user: The username to use to connect to the node to run Puppet on. Default: "root"
  • ssh_password: The password to use to connect to the node to run Puppet on. Sensitive.
  • ssh_host_key_check: Whether to enable host key checking for the target node. Default: true

Type: String

The name of the Puppet service.

Default: "pe-puppetserver" in Puppet Enterprise, "puppetserver" otherwise.


Type: String

The user the Puppet service and Relay agent run under.

Default: "pe-puppet" in Puppet Enterprise, "puppet" otherwise.


Type: String

The group the Puppet service and Relay agent run under.

Default: "pe-puppet" in Puppet Enterprise, "puppet" otherwise.

Report processor event

Every relay trigger event payload includes several fields from the report. The field are derived from the Puppet report object as detailed in the official documentation.



The hostname that submitted the report.


True if the agent was run in no-op mode, false if the agent was run in enforce mode.


This is the run status ("changed", etc.). Useful for detecting failures.


The timestamp of when the puppet run began in ISO 8601 format.


The version of the catalog applied to the node.


The unique identifier for the catalog run.


The code ID for the static file content server.


This is the long-form summary of the puppet run. It is more useful from a human perspective but may be inspected programmatically for puppet run information.


For each resource that changed or was out of sync when the run occurred, a map of the resource name to an object containing:

  • resource_type: The type of the resource, such as File
  • title: The title of the resource, such as /tmp/test
  • change_count: The number of property changes to the resource
  • out_of_sync_count: The number of properties that were out of sync on the node
  • containment_path: The full hierarchical path to the resource
  • corrective_change: True if this change reflected a correction of configuration drift, false otherwise


The report processor submits a subset of the full report. Full report submission will come soon, as they need to be compressed before transmission.