Rundeck

• Overview
• Initial Configuration
• Projects
• Deployment Configuration
• Application Interface
• API
• CLI
• Everyday Usage
• Jobs
• Activity
• Nodes and Commands
• User Management
• ACLs
• User Authentication
• Advanced Customization
• Execution Cleanup
• Troubleshooting
• Upstream Project
• Links

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.

• 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.

• Jobs : A job encapsulates a sequence of steps, job options and nodes where the steps execute.

• Nodes: A node is a resource that is either a physical or virtual instance of a network accessible host. A resource model is a representation of Nodes in a project.

• Commands: A 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.

• Executions: An execution is a representation of the activity of a running or completed command or job. The data about the execution is used in rundeck to monitor the progress of a job or command, and later for reporting about what happened.

• Role-based 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.

• Plugins: Extending Rundeck functionality is done through plugins. Plugins exist to execute commands on nodes, perform steps in a job, send a notification about job status, gather information about the hosts in your network, copy a file to a remote server, store and stream logs, talk to a user directory, and so much more.

Interfaces

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

• Web GUI: Most Rundeck navigation is done using the navigation bar on the left side of the page. Using the left navigation bar you can choose between available projects and, once inside a project, you can switch to the project's Dashboard, Jobs, Nodes, Commands and Activity pages. Project administrators will also be able to access the Project Settings pages.
• CLI: Rundeck includes a number of shell tools to dispatch commands, load and run Job definitions, and interact with the dispatcher's queue. These command line tools are an alternative to functions accessible in the graphical console.
• API: You can also use the Web API to interface with all aspects of Node and Job execution.

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

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

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

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

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:

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:

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

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

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

Deleting a Project

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

Deployment Configuration

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.

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.

 

Popular API Commands

Jobs

Executions

Projects

 

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

Jobs

Main Jobs Page

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

The "Jobs" link on the left-hand column will take us to a listing of all the jobs in this project. From there, all runnable jobs are displayed in alphabetical order in their Job Group.

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:

There are only two required fields:

1. Details > Job Name
2. Workflow > Step

Everything else is optional

Details

• Job Name: Shows up on main jobs page
• Job Group: Section on main jobs page
• Description: Shows up as small text under job on main jobs page

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:

• Option Name: The name you will use to pass it to the steps
• Option Label: The prompt you will see when you go to run the job
• Input Type: One of Text/Date/Secure (passwords)
• Allowed Values: comma-separated list
• Restrictions: Can enforce from the Allowed Values list

Workflow Control

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

• If a step fails either stop immediately or run the rest before failing
• Strategy: Node First/Parallel/Sequential
  • See the "Explain" menu for more details
• Global Log Filters: https://docs.rundeck.com/docs/manual/log-filters/ 
  • Mask Passwords
  • Key/Value Data

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:

• Node Steps: Runs once for every node
  • Command: Run a command from the command line
  • Script: Run a shell script
  • Job Reference: Run another job
• Workflow Steps: Runs once per workflow
  • Job Reference: Run another job
  • Global Variable: Set global variables to be used in other steps or notifications
  • Flow control: Halt indicates that the execution should halt. Enter a Status to halt with a custom status string. Otherwise, enable Fail to exit with failure, or not to exit with success.

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

Nodes

Remote nodes or locally. We always execute locally.

Schedule

• Run Repeatedly: Actually schedule when you want it to run
• Enable Scheduling: Turning the repeat runs on/off
• Enable Execution: Allow/Disallow ANYONE to run it at all

Notifications

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

• On Start
• On Success
• On Failure
• On Retryable Failure
• Average Duration Exceeded

Other

• Log Level: Debug level produces more output
• Multiple Executions: Allow this Job to be executed more than one time simultaneously
• Limit Multiple Executions: Max number of multiple executions
• Timeout
• Retry
• Default Tab: Nodes/Log Output/HTML

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

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

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.

 

Nodes and Commands

Nodes

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

A 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

• Run a command. Choosing this menu item will forward your browser to the Commands page.
• Create a job. Choosing this menu item will forward you to the Job create page and enter the filter expression in the edit form.

Commands

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

A 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.

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:

• group memberships assigned to a user login.
• access control policy that grants access to one or more policy actions to a group or user.

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:

• aclpolicy

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 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:

• Executable War: $RDECK_BASE/server/config/realm.properties

#
# 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

Execution Cleanup

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

Troubleshooting

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