Forge Home


Configure Puppet to work with Relay


2,112 latest version

4.7 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.5.1 (latest)
  • 2.5.0
  • 2.4.0
  • 2.3.2
  • 2.3.1 (deleted)
  • 2.3.0
  • 2.2.0
  • 2.1.5
  • 2.1.0
  • 2.0.0
  • 1.2.0
  • 1.1.0
  • 1.0.1
  • 1.0.0
released May 4th 2022
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
  • , , , , ,
This module has been deprecated by its author since Jun 23rd 2023.

Start using this module


puppetlabs/relay — version 2.5.1 May 4th 2022


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 runs on specific nodes, without requiring inbound connectivity from Relay to your puppetserver.



You must already have a puppetserver to which puppet agents submit reports and that can connect to the internet (optionally through a proxy). Because you'll need to store access tokens for Relay, we strongly recommend using eyaml to encrypt the tokens as hiera keys.

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

Set up Relay

The report processor needs a Relay push-trigger access token that is authorized to talk to the Relay API. To generate 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 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 Triggers section of the workflow page:  Copying access token from the workflow page

To see an example of a Relay workflow that uses this trigger, see the puppet-shutdown-ec2 example workflow, which watches for unexpected changes to the sudoers file and shuts down affected nodes for investigation.

To use the Relay agent capability, which enables you to trigger Puppet runs from Relay workflows, you'll also need to set up a Puppet connection in the Relay app. This will generate a separate token that the Relay agent, running on your puppetserver, uses to authenticate run requests from the service. To configure this, go to the Connections screen and click Add connection. Select the Puppet connection type from the drop-down menu, give it a name, and save the resulting token - it won't be displayed again.

Adding a new Puppet connection in Relay

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 setting on 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

For Puppet Enterprise, add the relay class to the Node Classifier group that contains your primary server. Open source Puppet classification will vary per local setup, but you'll need to make sure the hosts running puppetservers also are classified with the relay class.

We recommend using hiera to store the configuration for the Relay module, and specifically to use hiera-eyaml to prevent hardcoding the tokens in your configuration. For more information on hiera-eyaml, see the hiera-eyaml documentation on Github. You'll need to hiera keys with the eyaml-encrypted values of the Relay push token at a minimum. Additionally, if you're using the Relay agent functionality, add the token for the Puppet connection and either the PE Orchestrator access token or a ssh key to enable Bolt to access nodes.

# this token is from the "trigger" configuration
relay::relay_trigger_token: >
# this token is from the Puppet connection setup
relay::relay_connection_token: >
# For PE, this token is from `puppet access show`
  token: >
# For ssh access to nodes, configure ssh backend options instead
relay::backend: ssh
  host_key_check: false,
  user: puppet-automation
  password: >

Example #1: Trigger Relay workflow from Puppet run

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

If the Relay report processor detects an out-of-sync resource, with the agent in either no-op or enforce mode, it will send the report details to the Relay push API, authenticated with the relay_trigger_token we configured above. The workflow can then take action using any combination the steps from the Relay integration library.

The example puppet-shutdown-ec2 module looks for unexpected changes in sudoers and fences off potentially compromised nodes by shutting them down.

Example #2: Trigger Puppet run from Relay

To connect Relay workflows to your Puppet estate, configure the Puppet connection in Relay as described above. Make sure the relay agent is running on your puppetserver node; this agent makes outbound connections to periodically poll the Relay service for new actions to take, and will then use the transport configured in backend_options parameters to kick off Puppet agent runs on the nodes the workflow specifies.

To set this up, add a Puppet connection in Relay, then add a step like the following to your Relay workflow. Make sure the name field in the !Connection value matches the name you set at creation time. In this example, the workflow has a parameter host which the user supplies; instead of !Parameter host, you could use the output of an earlier step or data fields from a push or webhook trigger.

    description: Which host to kick off a puppet agent run
- 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. See PE RBAC documentation for more information on PE RBAC tokens.

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.


Type: String

The proxy hostname or IP address. The Relay agent will use this proxy to connect to Relay.


Type: Integer

The proxy port to connect to on the proxy_host.


Type: String

The user for authenticating to the proxy. Do not specify this parameter if the proxy does not require authentication.


Type: Sensitive[String]

The password for authenticating to the proxy. Do not specify this parameter if the proxy does not require authentication.

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.