Installation

Enterprise Runner - Installation

Installing Runners in remote locations

Once you have configured and downloaded a Runner, upload the binary to the environment where it will run, follow the install instructions and launch the runner.

Pre-Requisites

Same OS requirements as Rundeck
Java 11 is required to run the Runner JAR file.
The Runner binary size is 61MB.

Install steps

Copy the Runner JAR file that was saved when the Runner was created to the server and directory where it will run.
Execute java -jar runner_filename.jar to start the service.
Connection can be confirmed on the Runner Management page on the Last Checkin line. If there are errors in the output resolve those using troubleshooting steps below:
Runner Logs are located in the ./runner/logs folder under the folder where the jar was executed from. The runner.log file contains operational and important messages about the runner. operations.log tracks an operation starts and if it succeeds or fails. Read more about Runner logging configuration to customize logging.

Linux service for the Runner

We recommend setting up the Runners to run as services through systemd.

Create a systemd configuration file /etc/systemd/system/runner.service with the following contents:

[Unit]
Description=Process Automation Runner 

[Service]
WorkingDirectory=/opt/apps/runner
Type=simple
User=rundeck
Group=rundeck

# Put your runner's filename here
ExecStart=/usr/bin/java -jar runner-b40ff722-feac-4f02-9dd1-9b31f677e5a1.jar

Restart=on-failure

[Install]
WantedBy=multi-user.target

Run the following shell commands to enable and start the service.

# sudo systemctl daemon-reload
# sudo systemctl enable runner
# sudo service runner start

Using Runners in containers

A Runner docker image is available from Dockerhubopen in new window.

docker pull rundeckpro/runner

You can use the tag rundeckpro/runner:latest for the latest version, or rundeckpro/runner:$VERSION for a specific version.

You can use either Environment Variables, or a Volume Mount to specify the Connection parameters for the Runner.

API Usage Required

Currently, to obtain the token for a Runner, you must use the Runner Management API to create the Runner.

See:

Docker Environment Variables

Specify connection info and credentials via Env Vars:

RUNNER_RUNDECK_SERVER_TOKEN: The Runner secret token
RUNNER_RUNDECK_SERVER_URL: The Server URL
RUNNER_RUNDECK_CLIENT_ID: The Runner ID

Example:

docker run -it \
	-e RUNNER_RUNDECK_SERVER_TOKEN=$RUNDECK_RUNNER_TOKEN \
	-e RUNNER_RUNDECK_SERVER_URL=$RUNDECK_SERVER_URL \
	-e RUNNER_RUNDECK_CLIENT_ID=$RUNDECK_RUNNER_ID \
	 rundeckpro/runner:latest

Docker Volume Mount

/app/.rdrunner-creds: Volume Mount path

The contents are in this format:

# .rdrunner-creds file contents
RUNDECK_RUNNER_TOKEN=<TOKEN>
RUNDECK_SERVER_URL=<URL>
RUNDECK_RUNNER_ID=<ID>

Example:

docker run -it \
	-v "$(pwd)/rdrunner-creds:/app/.rdrunner-creds:" \
	 rundeckpro/runner:latest

Extending the Docker Image

If you are using certain plugins, such as Ansible, Docker, Kubernetes, etc, you may need additional software that is not included in the base image for the Runner.

You will need to create a custom docker image based on the base image.

Using Ansible

Example Dockerfile to add ansible:

ARG RUNNER_VERSION=latest
FROM rundeckpro/runner:${RUNNER_VERSION}

USER root
## Install python, pip and ansible
RUN apt-get update && \
    DEBIAN_FRONTEND=noninteractive apt-get install -y --no-install-recommends \
    python3-pip && \
    pip3 install --upgrade pip && \
    pip3 install ansible

# include any other necessary packages
#RUN apt-get -y install sshpass

USER runner

Working with ansible you will need to provide the inventory information. You can reach that using:

pass the inventory "inline" in the Jobs definition
Copy the inventory or ansible config files to the Dockerfile

COPY path/ansible.cfg /app/ansible/ansible.cfg
COPY path/hosts /app/ansible/hosts

Mount the inventory or ansible config files to the container

docker run -it \
	-v "$(pwd)/rdrunner-creds:/app/.rdrunner-creds:" \
	-v "$(pwd)/path/ansible.cfg:/app/ansible/ansible.cfg:" \
	-v "$(pwd)/path/hosts:/app/ansible/hosts:" \	
	 rundeckpro/runner:latest

Runner in Kubernetes

These instructions will guide how to install a Runner in Kubernetes.

Create an API Tokenopen in new window or use an existing API Token to download a new Runner via API using the following curl request. Be sure to replace [URL] and [ApiToken] [ProjectName] with your Process Automation instance URL and API Token respectively:
Heads Up!
Be sure to give each Runner a unique name. This is how you will identify one Runner from another in the platform.
```
curl --location --request POST 'https://[URL]/api/42/runnerManagement/runners' \
--header 'Accept: application/json' \
--header 'X-Rundeck-Auth-Token: [ApiToken]' \
--header 'Content-Type: application/json' \
--data-raw '{
"name": "Kubernetes Runner",
"description": "Kubernetes runner",
"assignedProjects": {
"[ProjectName]": ".*",
},
"tagNames": "kubernetes"
}'
```

The response will provide a runnerId and token. Here is an example output:

{"description":"Kubernetes runner","downloadTk":"d98d21bb-not-real-token-85bcf618ffd0",
"name":"Kubernetes Runner","projectAssociations":{"Kubernetes":".*"},
"runnerId":"ad45e0c6-not-real-runner-044b4624fff3","token":"NopObWnk1MnotRealTokenvfwJzPTd"}

(Optional) Verify that the runner was created as intended by navigating to System Menu (upper-right gear icon) -> Runner Management and see if the Runner is listed.
(Optional) Create a Kubernetes namespace for the Runner: kubectl create namespace rundeck
Create a deployment YAML for the Runner. Be sure to replace [namespace], [RUNNER ID], [TOKEN], and [INSTANCE-SUBDOMAIN]:

apiVersion: v1
kind: Pod
metadata:
  namespace: [namespace]
  name: rundeck-runner
  labels:
    app: rundeck-runner
spec:
  containers:
  - image: rundeckpro/runner
    imagePullPolicy: IfNotPresent
    name: rundeck-runner
    env:
    - name: RUNNER_RUNDECK_CLIENT_ID
      value: "[RUNNER ID]"
    - name: RUNNER_RUNDECK_SERVER_TOKEN
      value: "[TOKEN]"
    - name: RUNNER_RUNDECK_SERVER_URL
      value: "https://[INSTANCE-SUBDOMAIN].runbook.pagerduty.cloud"
    lifecycle:
      postStart:
        exec:
          command:
          - /bin/sh
          - -c
          - touch this_is_from_rundeck_runner
  restartPolicy: Always

Creat the deployment: kubectl create -f deployment.yml.
Confirm that the Runner was deployed successfully: kubectl logs -f rundeck-runner --namespace=[NAMESPACE]
Verify that the Runner is communicating with Process Automation correctly by looking in the Status column on the Runner Management page:

Tip: Multiple Pods for Scalability

Multiple replicas of the Runner container can be associated with a single deployment, though they will appear as a single Runner in Process Automation. This is useful for horizontally scaling the Runner. Here is an example deployment yaml where 2 replicas are used:

apiVersion: apps/v1
kind: Deployment
metadata:
  namespace: rundeck
  name: rundeck-runner
  labels:
    app: rundeck-runner
spec:
  replicas: 2
  selector:
    matchLabels:
      app: runner
template:
  metadata:
    labels:
      app: runner
  spec:
    containers:
    - image: rundeckpro/runner
      imagePullPolicy: IfNotPresent
      name: rundeck-runner
      env:
      - name: RUNNER_RUNDECK_CLIENT_ID
        value: "[RUNNER ID]"
      - name: RUNNER_RUNDECK_SERVER_TOKEN
        value: "[TOKEN]"
      - name: RUNNER_RUNDECK_SERVER_URL
        value: "[URL]"

Verify that the pods were deployed successfully:

Runner on Windows OS

The “Runner Management” menu will appear on under the “System” settings:

If you are installing a Runner on a Windows OS as localhost node, you have to specify the “OS Family” setting as “windows”.

Choose related to the project.
Go to the left side bar menu and choose "EDIT NODES".
Click on "Resources" tab.
Click on "Edit" on the local node.
On the field "OS Family" set "windows".

Powershell script steps are fully supported on the Runner. Commands that run through the cmd.exe shell are not supported at the moment.

Secure Your Deployment

We recommend installing Runners in private directories that are only accessible by the user/group holding the runner process (e.g.: C:\Users\runnerUser\ directory) so that other users are not able to access or even modify script files created by the runner.

Note

Runner installations that are not isolated properly are exposed to potential security risks:

1. Privilege escalation, in the case that the runner agent runs with Administrator privileges
2. Local user impersonation by allowing code execution in the session of the runner
3. Denial of service of the Job functionality for the specific runner
4. AV / EDR evasion by facilitating code execution in remote processes

Configure using environment variables

The Runner properties can be updated through environment variables which can be set when the Runner process is started. This approach is suitable for secure environments where the Runner is deployed because tokens can be kept externally in keystores and updated at runtime when the Runner is launched. Here is an example of the env variables:

RUNNER_RUNDECK_CLIENT_ID=6cd5c8c0-3824-463f-addb-cf2df1e882ef3
RUNNER_RUNDECK_SERVER_TOKEN=8FpagGtalnxnv1fmllyYYz4quhNHpBR8
RUNNER_RUNDECK_SERVER_URL=http://192.168.100.2:4440/

Removing Runners

Before removing a Runner it is advisable to verify that there are other active runners tagged with the same tags. This will ensure that jobs that are configured with those tags have at least one available Remote runner to carry out the tasks for the job.

Installation

# Enterprise Runner - Installation

# Installing Runners in remote locations

# Pre-Requisites

# Install steps

# Linux service for the Runner

# Using Runners in containers

# Docker Environment Variables

# Docker Volume Mount

# Extending the Docker Image

# Using Ansible

# Runner in Kubernetes

# Runner on Windows OS

# Secure Your Deployment

# Configure using environment variables

# Removing Runners