Rundeck

Overview

Rundeck is runbook automation. Give anyone self-service access to the operations capabilities that previously only your subject matter experts could perform. Popular use cases include incident management, business continuity, service requests, or just spreading the operational load among your colleagues.

Automation Frontend

Automation frontends come into play between writing scripts and automated remediation and/or orchestration. This tool is for running scripts and CLI commands.

Essential Concepts

Several fundamental concepts underlie and drive the Rundeck system. If you are a new user, knowing about them will help you use or integrate Rundeck into your environment.

Interfaces

There are several different way to interact with Rundeck's functionality:

Initial Configuration

Initial Configuration

Projects

A project is a place to separate management activity. All Rundeck activities occur within the context of a project. Multiple projects can be maintained on the same Rundeck server. Projects are independent from one another, so you can use them to organize unrelated systems within a single Rundeck installation. This can be useful for managing different teams, infrastructures, environments or applications.

Projects can be archived and imported to other Rundeck servers to help promote changes between environments.

A new installation will not contain any projects so Rundeck will present you with a dialog to create one.

Creating A Project

Creating a New Project: Setting the name

image-1632280367747.png

In the Execution History Clean Settings, you can set the length of time you would like to keep execution history:

image-1632280421335.png

Jobs are set to run automatically, this can be disabled as well as scheduling jobs can be disabled via the Execution Mode tab:

image-1632280488061.png

The user interface setting within the project allows for view settings such as the Job Group Expansion Level, Showing the Project Readme/Homepage, and the MOTD

image-1632280640192.png

Node Executor settings deal with how commands are executed on remote nodes, note there is a local setting to run rundeck strictly on the local machine, and the script execution setting which delegates command execution to an external script:

image-1632280791287.png

The File Copier is responsible for copying scripts to the remote nodes before they are executed, this means the scripts will be copied to the remote machine before being run (note the default locations for any files being copied is c:\windows\temp on windows systems and /tmp on linux based systems:

image-1632280955253.png

Git Configuration with Projects

Note with SCM Configurations there is an ability to both export jobs to a Git Repository and an Import setting for projects: Configuring these

image-1632281271462.png

Archiving a Project

Maybe a project needs to be archived. When creating an archive, there are some settings that can be modified to select just what is needed on the archive. Some of these include: Jobs/Executions/Configuration/Readme/MOTD/ACL Policies/SCM Configuration/Webhooks

image-1632281445493.png

On the other side of this Importing an Archive can also be done. Some settings to note when importing include: Preserving UUIDs on the imported Jobs, Importing Executions and History, The Project Configuration, Node Sources, ACL Policies, SCM Configuration, Referenced Job Validations, and Webhooks

image-1632281617580.png

Deleting a Project

Maybe you are done with the project, deleting a project can be done via the GUI via:

image-1632281779113.png

Deployment Configuration

Application Interface

Application Interface

API

API Version Numbers
Current Minimum
40 11
Current
    The current version number.
Minimum
    Minimum supported version.

This means you must use at least the API version indicated to access the endpoint, unless otherwise noted. Some features or functionality for the endpoint may only be supported in later versions.

The API Version Number is required to be included in all API calls within the URL.

If the version number is not included or if the requested version number is unsupported, then the API call will fail. The error response will include the code "api-version-unsupported" and have HTTP status code of 400 Bad Request

 

Authentication

Authentication can be done in two different ways, either with Token based authentication, or with a username and password.

Token Authentication consists of including a string known as an "API Token" with every request to the Rundeck API.

To obtain an API Token, you must first log in to the Rundeck GUI using a user account. Click on your username in the header of the page, and you will be shown your User Profile page. From this page you can manage your API Tokens.

image-1640745900524.png

image-1640745918807.png

image-1640746100564.png

XML and JSON

The API supports both XML and JSON. Some import/export features support YAML or text/plain formatted documents, but XML and JSON are used for all API-level information.

 

Jobs

Executions

Projects

 

Application Interface

CLI

RD-CLI

https://docs.rundeck.com/docs/learning/howto/learn-rd-cli.html 

Rundeck CLI (RD-CLI) is a Java client to access and interact with a Rundeck Instance from the command line. In a few words, Rundeck CLI is a Rundeck API abstraction tool. With Rundeck CLI is possible to view system information, list executions, list and manage jobs, manage keys, list and manage node source, projects, and jobs in the command line.

Installing

In OurCompose, the CLI can be installed by including the instructions given in the Rundeck documentation into the compositional_rundeck_additional_setup variable. At the moment, that is curling the install script down and running it to set up the repos, then using apt to install it.

Configuration

You need at least three environment variables to run the CLI tool against the server:

  1. RD_URL
  2. RD_USER
  3. RD_PASSWORD

You can either export these env vars into the shell itself, or set up an rd.conf filie. However, you would have to tell the CLI where that file was by pointing to it with the RD_CONF environment var.

Keep in mind that you can also use an API token instead of a user/password combination.

Available Commands

https://rundeck.github.io/rundeck-cli/commands/ 

   adhoc      - Dispatch adhoc COMMAND to matching nodes
   executions - List running executions, attach and follow their output, or kill them
   jobs       - List and manage Jobs
   keys       - Manage Keys via the Key Storage Facility.
   nodes      - List and manage node resources
   projects   - List and manage projects
   run        - Run a Job
   scheduler  - View scheduler information
   system     - View system information
   tokens     - Create, and manage tokens
   users      - Manage user information

 

Everyday Usage

Everyday Usage

Jobs

Main Jobs Page

https://docs.rundeck.com/docs/manual/04-jobs.html 

image-1633308972681.png

NOTE: Jobs do not have to have a Job Group. If they don't, they will be displayed at the bottom underneath all of the job groups.

New Job

The top right "Job Actions" button will provide an option to create a new job:

image-1633309408066.png

There are only two required fields:

  1. Details > Job Name
  2. Workflow > Step

Everything else is optional

Details

Workflow

https://docs.rundeck.com/docs/manual/job-workflows.html 

This spells out the steps and variables to use for the job.

NOTE: Every change in each of the following sections has to be saved separately before the workflow itself can be saved.

Options

https://docs.rundeck.com/docs/manual/job-options.html 

Arguments/variables that are set when the job is run. Notable options are:

Workflow Control

Several options pertaining to the workflow itself are present separate from the steps:

Steps

Here are where the actual executions are structured. There are a lot of options and ways to construct this, so I'll only lay out what I'm familiar with:

NOTE: This is where plugins will usually be adding functionality.

Nodes

Remote nodes or locally. We always execute locally.

Schedule

Notifications

https://docs.rundeck.com/docs/manual/jobs/job-notifications.html 

Other

FWIW, the Log Output is very handy when executing locally to simply jump directly to the output.

Everyday Usage

Activity

https://docs.rundeck.com/docs/manual/08-activity.html

Execution history for commands and Jobs is stored by the Rundeck server. Execution history can be filtered and viewed inside the "Activity" page.

Execution State

image-1638330999439.png

  1. Currently Running Jobs
  2. Successful Job (green check mark and "1 ok" text)
  3. Failed Job (red dash, and "1 failed" text)
NOTE: The currently running jobs needs to be refreshed to get the latest update on this page, or the 'Auto refresh' box in the top right selected.

Selecting any of these executions will take you to their Log Outputs.

Searching for Prior Executions

Searching is most successful when using the "Name" field to search the name of the job you would like to find. The rest of the filters likely aren't going to be of much help. From there, you can look through the job executions to find the one you were looking for.

NOTE: There is currently no way to search by options (variables) passed.

 

Everyday Usage

Nodes and Commands

Nodes

https://docs.rundeck.com/docs/manual/05-nodes.html

Node is a resource that is either a physical or virtual instance of a network accessible host. Nodes have a few basic attributes but a Node's attributes can be extended to include arbitrary named key/value pairs. Attributes typically describe the properties of a node or reflect the state of the node. One of a Node's built in attributes is called "tags" which is a list of classifications or categories about that Node.

NOTE: To get a listing of all nodes, place .* into the filter on top.

In the docker container, Rundeck will always list itself as a node. The executable directory is the home directory of the user that runs the Rundeck service, in docker's case, the rundeck user.

Node actions

The Node Actions menu contains links to

Commands

https://docs.rundeck.com/docs/manual/06-commands.html

command is a single executable string executed on a Node. Rundeck invokes commands on nodes via a node executor which evaluates the command string and executes it. Node executors evaluate the command string in a data context containing information about the Node resource. Command strings can reference this data and thus avoid hard coding node or environment specific values.

NOTE: The default node executor is /bin/sh
Simply type into the Command field what you would like to be ran in order to execute it on the nodes specified. This is going to be typically one-off commands or status retrieving commands. This is formatted in the same style as Job steps, and can use the same tricks.

User Management

User Management

ACLs

Access Control Policies

A Rundeck access control policy grants users and user groups certain privileges to perform actions against rundeck resources like projects, jobs, nodes, commands and API. Every action requested by a user is evaluated by the Rundeck authorization system and logged for reporting and auditing purposes.

Since Rundeck respects the policy definition, you can define role-based authorization to restrict users to only a subset of actions. This enables a self-service type interface, where some users have access to a limited set of executable actions.

Two dimensions of information dictate authorization inside Rundeck:

Where can I edit the Policy?

This is done in the ACL Policy GUI or in the configuration file.

https://docs.rundeck.com/docs/administration/security/acl-policy-editor.html 

Where and What are Access Control Policies?

Access to running or modifying Jobs is managed in an access control policy defined using the aclpolicy YAML document. This file contains a number of policy elements that describe what user group is allowed to perform which actions.

Please read over this document for information on how to define it, and how to grant access for certain actions to certain resources:

Policies can be organized into more than one file to help organize access by group or pattern of use. The normal Rundeck install will have generated a policy for the "admin" group. Not all users will need to be given "admin" access level to control and modify all Jobs. More typically, a group of users will be given access to just a subset of Jobs.

Lifecycle

The Rundeck server does not need to be restarted for changes to aclpolicy files to take effect.

Scopes

 

User Management

User Authentication

Authenticating Users

PropertyFileLoginModule

The default Rundeck installation handles user authentication via JAAS using the realm.properties file. This file is created at the time that you install the server.

Location:

#
# This file defines users passwords and roles for a HashUserRealm
#
# The format is
#  <username>: <password>[,<rolename> ...]
#
# Passwords may be clear text, obfuscated or checksummed.
#
# This sets the default user accounts for the Rundeck apps
#
admin:admin,user,admin
user:user,user

 

Advanced Customization

Advanced Customization

Execution Cleanup

https://docs.rundeck.com/docs/history/3_1_x/version-3.1.0.html#execution-cleaner

Troubleshooting

Upstream Project

Upstream Project

Links

Official Site: https://www.rundeck.com

Code: https://github.com/rundeck/rundeck

Documentation: https://docs.rundeck.com/docs/

Updates: https://docs.rundeck.com/docs/history/

Community: https://groups.google.com/forum/#!forum/rundeck-discuss

Container Image: https://hub.docker.com/r/rundeck/rundeck