Using the RunDeck API from Groovy scripts

Here are some examples of what you can do with this lib and a few lines of Groovy.

We can use Grape to download the lib (and its dependencies) from the Maven Central Repository, so you don't have to install anything manually (except Groovy, of course).

Basic usage

Save the following script in a file named "rundeck.groovy", and execute it with "groovy rundeck.groovy". Feeling Groovy ? ;-)

// we use Grape (Ivy) to download the lib (and its dependencies) from Maven Central Repository
@Grab(group='org.rundeck', module='rundeck-api-java-client', version='2.0')
import org.rundeck.api.RundeckClient

rundeck = new RundeckClient("http://localhost:4440", "admin", "admin")

println "RunDeck uptime : ${rundeck.systemInfo.uptime}"
println "All RunDeck projects : ${rundeck.projects}"
println "All RunDeck nodes : ${rundeck.nodes}"
println "All RunDeck jobs : ${rundeck.jobs}"
println "All RunDeck running executions : ${rundeck.runningExecutions}"

You can also download the lib and all its dependencies in 1 big jar file, and add it to your classpath before running your script : save the following script in a file named "rundeck.groovy", and execute it with "groovy -cp /path/to/rundeck-api-java-client-VERSION-jar-with-dependencies.jar rundeck.groovy".

import org.rundeck.api.RundeckClient

rundeck = new RundeckClient("http://localhost:4440", "admin", "admin")

println "RunDeck uptime : ${rundeck.systemInfo.uptime}"
println "All RunDeck projects : ${rundeck.projects}"
println "All RunDeck nodes : ${rundeck.nodes}"
println "All RunDeck jobs : ${rundeck.jobs}"
println "All RunDeck running executions : ${rundeck.runningExecutions}"

Authentication

Starting with RunDeck API 2, there are 2 ways to authenticate :

  • the login-based authentication : with your login and password
  • the token-based authentication : with a unique token that you can generate from the RunDeck webUI
// using login-based authentication (admin/admin is the default login/password for a new RunDeck instance) :
rundeck = new RundeckClient("http://localhost:4440", "admin", "admin");

// using token-based authentication :
rundeck = new RundeckClient("http://localhost:4440", "PDDNKo5VE29kpk4prOUDr2rsKdRkEvsD");

Running a job

import org.rundeck.api.RundeckClient
rundeck = new RundeckClient("http://localhost:4440", "admin", "admin")

// find a job from its name, group and project
job = rundeck.findJob("my-project", "main-group/sub-group", "job-name")
println "Found job with ID : ${job.id}"

// trigger a simple job with no options
execution = rundeck.triggerJob(job.id)
println "Execution started, you can follow it at the URL : ${execution.url}"

// or with options...
execution = rundeck.triggerJob("job-id", new Properties(option1: "value one", option2: "value two"))

// you can also override the nodes on which the job should execute
execution = rundeck.triggerJob("job-id", new Properties(opt: "value"), new Properties(tags: "prod+appserv"))

// last one : you can run a job and wait until its execution is finished :
execution = rundeck.runJob("job-id")
println "Execution finished ! Status : ${execution.status}, duration : ${execution.duration}"

Running an ad-hoc command

import org.rundeck.api.RundeckClient
rundeck = new RundeckClient("http://localhost:4440", "admin", "admin")

// trigger the execution of the "uptime" command on the RunDeck server
execution = rundeck.triggerAdhocCommand("my-project", "uptime")

// run the "uptime" command on all unix nodes
execution = rundeck.runAdhocCommand("my-project", "uptime", new Properties(os-family: "unix"))

Running an ad-hoc script

import org.rundeck.api.RundeckClient
rundeck = new RundeckClient("http://localhost:4440", "admin", "admin")

// trigger the execution of a custom bash script on the RunDeck server
execution = rundeck.triggerAdhocScript("my-project", "/tmp/my-script.sh")

// run a bash script (with options) on all unix nodes
execution = rundeck.runAdhocCommand("my-project", "/tmp/my-script-with-options.sh", new Properties(option1: "value one"), new Properties(os-family: "unix"))

Exporting jobs

import org.rundeck.api.RundeckClient
rundeck = new RundeckClient("http://localhost:4440", "admin", "admin")

rundeck.exportJobsToFile("/tmp/jobs.xml", "xml", "my-project")
rundeck.exportJobToFile("/tmp/job.yaml", "yaml", "job-id")

Importing jobs

import org.rundeck.api.RundeckClient
rundeck = new RundeckClient("http://localhost:4440", "admin", "admin")

result = rundeck.importJobs("/tmp/jobs.xml", "xml")
println "${result.succeededJobs.size} jobs successfully imported, ${result.skippedJobs.size} jobs skipped, and ${result.failedJobs.size} jobs failed"

And more...

See the API documentation of the RundeckClient class for more interactions with your RunDeck instance...