Rundeck Actions

Rundeck Actions are scripts run by an automation runner (software agent) installed on your infrastructure. By associating these actions with a PagerDuty service, they are available to be initiated when an incident occurs on the service. Responders get push-button access to a library of defined diagnostic or remediation actions that result in quickly resolved incidents with fewer disruptive escalations.

📘

Rundeck Actions Trial

Please contact us if you would like a trial of PagerDuty Rundeck Actions.

Configure Rundeck Actions

📘

Runner Installation

At present, many actions can run on one runner, however, one action cannot run on many runners. If a different relationship is required to achieve your desired use case, it is necessary to create multiple Rundeck actions to apply for different runners. Each runner can be configured to connect to a single Rundeck instance.

🚧

Required User Permissions

Create/Edit/Delete any Rundeck Actions: Actions and/or Runners

  • Admin, Global Admin or Account Owner roles.

Create/Edit/Delete Rundeck Actions: Actions associated with their team(s)

  • Manager team roles.

View all public teams, services, schedules, escalation policies, analytics, postmortems and Rundeck Actions: Actions across the entire account

  • Observer, Responder, Manager, Admin, Global Admin and Account Owner.

Invoke Rundeck Actions from an Incident

  • Observer, Responder, Manager, Admin, Global Admin and Account Owner.

In PagerDuty

Create a ​​PagerDuty API Key

  1. Navigate to Integrations API Access Keys and click Create New API Key.
  2. Enter a Description that will help you identify the key later on. If you would like it to be read-only, check the Read-only option.
  3. Click Create Key.
  4. A unique API key will be generated. Copy it to a safe place, as you will not have access to copy this key again. Once it has been copied, click Close. If you lose a key you will need to delete it and create a new one.

In Rundeck

Create a Rundeck Token

  1. Log in to Rundeck, click your User Icon and select Profile.
  2. To the right of User API Tokens, click +.
  1. Enter a Name for the User API Token and click Generate New Token.
  2. Copy the User API Token and keep it in a safe place for later use.

Create a Rundeck Project

  1. Next, you will need to create a Rundeck Project that contains the Job to be carried out by the ​​responder.

Create a Job

  1. Create a Rundeck Job in the project. After the job is created, copy its ID and keep it in a safe place for later use.

Configure a Runner

At present 50 executions on one runner are supported.

  1. Next, you will add a new runner to generate an ID and secret. Navigate to Automation Rundeck Actions Runners tab +Add Runner. Enter a Name and Description and click Next, Generate Runner Secret & ID.
  2. Now you will download and configure the ID and secret into the runner. On the next screen, click Download ID & Secret. Once the file has downloaded, it can be opened with most text editors. The file will contain the following information. Replace the <API_Token> with the PagerDuty API key and save the file:
id:XXXXXXXXXXXXXXXXXXXXXXX3P1C
secret:XXXXXXXXXXXXXXXXXXXX2I4B
token:<PagerDuty_API_TOKEN>
rundeck_url: http://localhost:4440
rundeck_token: <Your_Saved_RUNDECK_API_TOKEN>
  1. If you are configuring the runner to connect to Rundeck Enterprise, you may also enter your Rundeck URL and Rundeck API token so that runner is able to communicate with the Rundeck instance.

  2. Install Java 11+ on the machine that will host the runner. Assuming Linux (Ubuntu 18) or higher. If the operating system is reasonably new, it is recommended to perform an update:
    a. sudo apt-get update: This will update the Ubuntu version.
    b. sudo apt install openjdk-11-jre-headless: This will install the open source Java version that the runner needs.
    c. mkdir rundeck_runner: Create a folder in a desirable directory on your system to place the credentials files.
    d. cd rundeck_runner: Navigate into the runner directory.
    e. Insert the credentials file that was downloaded from the PagerDuty Runner menu. It should already contain the PagerDuty API key inside the file.
    f. mv credentials.pdrunner-creds .pdrunner-creds: Rename the file to .pdrunner-creds.
    g. wget https://runbook-actions.pagerduty.com/pd-runner.jar: Download the latest PagerDuty Runner software.
    h. ls -larths: View current directory to see all of the files. You should see two files, one from step 12 and step 13.
    i. java -jar pd-runner.jar: Launch pd-runner.
    j. tail -f /home/ubuntu/rundeck_runner/runner/logs/runner.log : Optional verify activity in runner.log.

  3. Next, check the Runner Status in PagerDuty. A green checkmark indicates that the runner is active and running successfully. A red circle would indicate that the runner is not running or there is a problem with the runner. Please refer back to steps for installing Java 11+ and check the local runner logs, or check our troubleshooting FAQs.

Create a Rundeck Action

  1. Once the runner is running successfully, you will add an action. Navigate to the Actions tab and click +Add Action. Perform the following:

Field

Instructions

Name the action

Enter a Name for the action.

Describe the action

Describe the purpose of the action.

Select Type

Select script OR rundeck to determine how you would like the action to be invoked.

Type of action

Select Diagnostic OR Remediation.

Define your action

Depending on your Select Type selection above, enter the following:

  • Enter your desired script: This can be a script in a particular language, or a simple unix command. The key requirement is to ensure that the runner host is capable of running the script and supports the language that the script is written in.

OR

  • Rundeck Job ID: Enter your desired Rundeck Job ID. This should be an existing job ID in the Rundeck instance.
    (Optional): It is also possible to enter Rundeck arguments. E.g: At runtime, the PagerDuty incident ID will be passed as a string argument -pd_incident_id ${pagerduty.incidentId}

Link the runner that will run this action on your infrastructure

Select the runner from the dropdown menu.

Associate this action with service(s) to make the action available to run on the services’ incidents

Select the PagerDuty service from the dropdown menu.

Associate with a team to limit who has access to run this action

Associate this action with a particular PagerDuty Team (Optional).

Click Create Action to complete configuration. You may repeat step 16 multiple times to create more actions.

Example Rundeck Action (Script):

Example Rundeck Action (Rundeck Job)

Run Action on an Incident (Script)

Once Rundeck Actions have been configured, they can be invoked on incidents.

  1. Navigate to an open incident on a service where the Rundeck Action is configured to run. Click Run Actions and select your desired action.
  1. Select the incident’s Timeline tab to see execution of the action from above and click the output report link to view detailed output of the action.
  1. The Output tab will reveal output of the script that has been run.
  1. Select the Script tab to see the detailed view of the script that was run.

This will reveal the script that was run from the pre-configured Rundeck Action.

Run Action on an Incident (Rundeck Job)

Once Rundeck Actions are configured, now they can be invoked on incidents.

  1. Navigate to an open incident on a service where the Rundeck Action is configured to run, click Run Actions and select your desired action.
  1. Click Run Job on the prompt that appears.
  2. Select the incident’s Timeline tab to see execution of the action from above and click the output report link to view detailed output of the action.
  1. The Output tab will show the output of the script or Rundeck Job that has been invoked.
  1. Click the View full output in Rundeck button to view the Rundeck Job and see the results:
  1. Select the Script tab to see the detailed view of the script or Rundeck Job that was invoked.

FAQ

Are there specific user permissions required to use Rundeck Actions?

  • Create a Runner and Rundeck Actions: Responder, Manager, Global Admin, Account Owner.
  • Run Actions on Incidents: Responder, Manager, Global Admin, Account Owner.

What network port does a runner use?

The runner requires outbound access to PagerDuty’s Public API: api.pagerduty.com. There is no inbound access requirement.

What happens if I trigger an action and the runner is down?

Currently the action will be queued until the runner is available again. Once the runner is online, the pending action will execute.

How long does a runner need to be inactive before it switches to offline (red) status?

The runner will switch to red status after 5 minutes of inactivity.

What should the successful messages look like in the runner.log?

See output below:

[email protected]:~$ more /home/ubuntu/rundeck_runner/runner/logs/runner.log 
10:33:16.643 [main] INFO  io.micronaut.context.env.DefaultEnvironment - Established active environments: [ec2, cloud]
10:33:18.389 [main] INFO  com.dtolabs.rundeck.core.plugins.JarPluginScanner - Deleting plugin jar cache at /home/ubuntu/runner/runner/var/tmp/pluginJars
10:33:18.389 [main] INFO  com.dtolabs.rundeck.core.plugins.JarPluginScanner - Deleting plugin lib dependency directory at /home/ubuntu/runner/runner/plugin-cache
10:33:18.450 [main] INFO  io.micronaut.flyway.AbstractFlywayMigration - Running migrations for database with qualifier [default]
10:33:18.452 [main] INFO  org.flywaydb.core.internal.license.VersionPrinter - Flyway Community Edition 7.5.3 by Redgate
10:33:18.621 [main] INFO  org.flywaydb.core.internal.database.base.DatabaseType - Database: jdbc:sqlite:/home/ubuntu/runner/runner/storage/db.sqlite (SQLite 3.32)
10:33:18.657 [main] INFO  org.flywaydb.core.internal.command.DbValidate - Successfully validated 1 migration (execution time 00:00.011s)
10:33:18.664 [main] INFO  org.flywaydb.core.internal.schemahistory.JdbcTableSchemaHistory - Creating Schema History table "main"."flyway_schema_history" ...
10:33:18.699 [main] INFO  org.flywaydb.core.internal.command.DbMigrate - Current version of schema "main": << Empty Schema >>
10:33:18.702 [main] INFO  org.flywaydb.core.internal.command.DbMigrate - Migrating schema "main" to version "1 - create tables"
10:33:18.713 [main] INFO  org.flywaydb.core.internal.command.DbMigrate - Successfully applied 1 migration to schema "main" (execution time 00:00.015s)
10:33:19.210 [main] INFO  io.micronaut.runtime.Micronaut - Startup completed in 2652ms. Server Running: http://localhost:4441

Is the runner process running on Ubuntu?

Command ps aux | grep -i runner should show similar output to below:

ubuntu   19741  0.7  9.6 3758548 386980 pts/0  Sl+  10:33   0:55 java -jar pd-runner.jar
ubuntu   20385  0.0  0.0  14860  1144 pts/2    S+   12:35   0:00 grep --color=auto -i runner

Is it possible to reveal PagerDuty incident id or user who ran the Runbook Action from within the script?

Yes. These are the available two placeholders for each ${incident.id} and ${user.id}. Example below shows usage to escape them so that they print. These placeholders can also be used in a non-escaped fashion

# script
df -h
"script ran by user:" \${user.id}
"for incident id" \${incident.id}

How can I setup the Rundeck Action with a Rundeck Job that requires passing of PD incident ID as variable?

This is possible by specifying an argument string when configuring Rundeck Action in PagerDuty. The string argument to be passed in is: -pd_incident_id ${pagerduty.incidentId}

Updated 16 days ago


Rundeck Actions


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.