rs-mule

A CLI tool that runs "stuff". Meant primarily for running RightScripts or Chef recipes on individual nodes, identified by tags.

Also a Library that allows you to do the same sorta stuff in your own app, cause I'm generous like that.

The CLI requires you to authenticate with right_api_client. Typically providing your rightscale email address, password, and an account id are sufficient for getting authenticated. However you can also use an oAuth token. For more information on the required parameters check out the right_api_client documentation

When using the CLI you can provide RightScale API authentication info in two ways.

Perhaps the easiest way to provide the authentication parameters is on the commandline with the --rs-auth-hash option.

Example:

rs-mule [COMMAND] --rs-auth-hash=email:foo@bar.baz password:password account_id:12345

You can also create a YAML file which contains the authentication parameters you want to supply, then point rs-mule at your authentication parameter file.

You can find an example of this file at the root of this project as "auth_file.yaml.example", and it looks a little like this.

Example File:

---
:email: foo@bar.baz
:password: password
:account_id: 12345

You can tell rs-mule to use your parameters file thusly.

Example:

rs-mule [COMMAND] --rs-auth-file=/path/to/auth_file.yaml

rs-mule has one (soon to be two) commands.

Commands:
  rs-mule help [COMMAND]                       # Describe available commands or one specific command
  rs-mule run_executable --tags=one two three  # Runs a specified recipe or RightScript on instances targeted by tag

This is used to run a RightScript or Chef recipe on instances found using a tag search.

The simplest usage requires the executable to run, and at least one tag.

rs-mule run_executable "Some RightScript Name" --tags=tag1

If you provide more than one tag, rs-mule will assume that you want target instances to possess all of the supplied tags in order for the executable to be run on them. However, you can be a little more lenient and have rs-mule run the executable on instances which have any of the tags.

Script will run only on instances which have both "tag1" and "tag2"

rs-mule run_executable "Some RightScript Name" --tags=tag1 tag2

The explicit version of above

rs-mule run_executable "Some RightScript Name" --tags=tag1 tag2 --tag-match-strategy=all

Script will run on any instance which has either "tag1" or "tag2"

rs-mule run_executable "Some RightScript Name" --tags=tag1 tag2 --tag-match-strategy=any

When you are running a RightScript, rs-mule will assume you want to run the latest and greatest version. It'll also assume that revision is not the HEAD revision. You can supply a specified revision number, or use 0 if you want to live on the edge and use the HEAD revision.

Specify revision 3

rs-mule run_executable "Some RightScript Name" --tags=tag1 --right-script-revision=3

Specify HEAD revision

rs-mule run_executable "Some RightScript Name" --tags=tag1 --right-script-revision=0

The executable value can be one of the following;

• The name of a RightScript
• An API href of a RightScript (Eg. /api/right_scripts/abc123)
• The name of a Chef recipe (Eg. cookbook::recipe)

rs-mule will attempt to automatically detect which one you've supplied by applying some regular expressions and other detection mechanisms against the executable string provided.

However, you can remove the guesswork by specifying the executable type as an option.

RightScript HREF:

rs-mule run_executable "/api/right_scripts/abc123" --executable-type=right_script_href --tags=tag1

RightScript Name:

rs-mule run_executable "Some RightScript Name" --executable-type=right_script_name --tags=tag1

Chef Recipe:

rs-mule run_executable "cookbook::recipe" --executable-type=recipe_name --tags=tag1

Of course you might want to pass some inputs to the script or recipe that you're executing. Shockingly enough, you can!

Passing INPUT_ONE and INPUT_TWO to a script RightScript:

rs-mule run_executable "Some RightScript Name" --tags=tag1 --inputs=INPUT_ONE:text:foo INPUT_TWO:text:bar

Passing some/chef/attribute1 and some/chef/attribute2 to a recipe:

rs-mule run_executable "cookbook::recipe" --tags=tag1 --inputs='some/chef/attribute:text:foo' 'some/chef/attribute2:text:bar'

Suppose you want to set those inputs so that they stick around after you've run the executable. You can do that too. You just need to specify where you want the inputs to be set.

Saving the inputs on the current instance:

rs-mule run_executable "Some RightScript Name" --tags=tag1 --inputs=INPUT_ONE:text:foo INPUT_TWO:text:bar --update_inputs=current_instance

Saving the inputs on the next instance:

rs-mule run_executable "Some RightScript Name" --tags=tag1 --inputs=INPUT_ONE:text:foo INPUT_TWO:text:bar --update_inputs=next_instance

Saving the inputs on the deployment containing the instance:

rs-mule run_executable "Some RightScript Name" --tags=tag1 --inputs=INPUT_ONE:text:foo INPUT_TWO:text:bar --update_inputs=deployment

You can save the inputs on any mix of them as well, since the update_inputs option is an array.

Saving the inputs on EVERYTHING:

rs-mule run_executable "Some RightScript Name" --tags=tag1 --inputs=INPUT_ONE:text:foo INPUT_TWO:text:bar --update_inputs=current_instance next_instance deployment

The library does all this cool stuff, and I'll document it, I swear...

Created and maintained by Ryan Geyer (me@ryangeyer.com)

MIT (see LICENSE)