Rundeck-ruby

Like the name says, these are ruby bindings for the rundeck API

The usual stuff:

Add this line to your application's Gemfile:

gem 'rundeck-ruby-client'

And then execute:

$ bundle

Or install it yourself as:

$ gem install rundeck-ruby

So, you're not going to be using your username and password in this library. Instead it uses rundeck's token-based authentication for everything. See the API docs for instructions about generating a token.

This gem installs a binstub named rundeck. Surprising, huh? Anyway, rundeck does one thing: execute jobs. Oh, you want more? Well then, send a pull request, buddy.

The USAGE line:

rundeck exec <url> <token> <job guid> [<exec args>]

For example

$ rundeck exec https://my.server afdDSFasdfASD4334fasdfaasWERsW23423
cd51b400-aad2-0131-c7f8-0438353e293e -arg0 1234 - arg1 blah
https://my.server/executions/1234

That will connect to your rundeck server my.server using your auth token, find job cd51b400-aad2-0131-c7f8-0438353e293e and execute it. It prints out the url of the resulting execution.

"But that's a lot of parameters," you say? Well, if you've got a better idea, submit a pull request. Also, you're probably going to alias common executions anyway, so it's really not too bad.

Connections to your rundeck server are handled with the Session class. Like so:

require 'rundeck-ruby-client'
session = Rundeck::Session('https://my.server', 'my token')

That's it. You have a session.

From there you can get a hash of some of the server's system information:

info_hash = session.system_info

The other thing the session lets you do get an array of your projects:

names = session.projects.map(&:name)

To get a single project, any of these will work:

project = session.projects.find{|p| p.name == "ReallyImportantProject"}
project = session.project("ReallyImportantProject")
project = Rundeck::Project.find(session, "ReallyImportantProject")

From each project, you can get a list of jobs. This code:

session.projects.first.jobs.map(&:name)

will give you a list of jobs in the project.

You can get a single job object from the project in any of these ways:

job = project.jobs.find{|j| j.name == "MyJob"} # When you only have the name
job = project.job_by_id(the_job_guid)

You can skip right over the project and go straight to the job too:

job = Rundeck::Job.find(session, the_job_guid)

Once you have a job object, you can work with its executions. To execute the job, do this (new method with a hash):

execution = job.execute!({'env' => 'integration', 'lease' => '22' })

To get all executions from a job, do this:

executions = job.executions

If your rundeck is like mine, then there will be a boatload of executions in each job, so getting all of them will be a pain. Unnecessary, too. To filter down the results, do this:

active_executions = job.executions do |query|
  query.status = :failed
  query.max = 2
  query.offset = 100
end

It does what it looks like.

...or, for the whole project:

active_executions = Rundeck::Execution.where(project) do |query|
  query.status = :failed
  query.max = 2
  query.offset = 100
end

You can also wait job execution end in a blocking way :

log =  execution.wait_end 2, 30

where 2 is the interval to request the execution, and 30 the tieout the call will be blocking until the job end and will log thing such as :

[2014-06-02 17:06:48 +0200] Waiting for job create_linux_ruby, execution 67 to be finished
[2014-06-02 17:06:48 +0200] job create_linux_ruby, execution 67 to be finished .
[2014-06-02 17:06:51 +0200] job create_linux_ruby, execution 67 to be finished .
[2014-06-02 17:06:54 +0200] job create_linux_ruby, execution 67 to be finished .
[2014-06-02 17:06:57 +0200] ok !, duration 9

At the end, it will return the log as a Hash of key, value corresponding to execution result, log time, log value etc ...

To get the valid statuses, ask the query object:

statuses = []
active_executions = job.executions do |query|
  statuses = query.class.valid_statuses
end
puts statuses

Spoiler: they're one of the following: succeeded, failed, aborted, running, or nil.

To get the output from an execution, ask it:

output = execution.output

output will be a hash containing the following keys: id, completed, hasFailedNodes, log. log will, in turn, be a hash of hostnames to log entries, which will be self-explanatory

The usual boilerplate:

1. Fork it
2. Create your feature branch (git checkout -b my-new-feature)
3. Commit your changes (git commit -am 'Add some feature')
4. Push to the branch (git push origin my-new-feature)
5. Create new Pull Request

If you want to contribute, here's what I'd like to do sooner rather than later:

• Add execution tailing to the rundeck binstub, à la:

rundeck tail <execution url> <token>

...or...

rundeck exec -tail ...the other parameters...

• Running ad-hoc commands, both in irb and with the binstub
• Unit tests. While normally more of a TDDer than most, I find writing tests for API wrappers tedious at best. It should probably be done, though.