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