From 76588fe0cbded60b413268acfcc48447dac9a699 Mon Sep 17 00:00:00 2001 From: Vincent Behar Date: Tue, 5 Jul 2011 17:44:41 +0200 Subject: [PATCH] documentation (maven site) --- src/site/confluence/download.confluence | 19 +++++++ src/site/confluence/groovy.confluence | 59 ++++++++++++++++++--- src/site/confluence/index.confluence | 6 +-- src/site/confluence/jruby.confluence | 63 +++++++++++++++++----- src/site/confluence/jython.confluence | 67 ++++++++++++++++++++++++ src/site/confluence/scripting.confluence | 10 ++++ src/site/site.xml | 9 ++++ 7 files changed, 212 insertions(+), 21 deletions(-) create mode 100644 src/site/confluence/download.confluence create mode 100644 src/site/confluence/jython.confluence create mode 100644 src/site/confluence/scripting.confluence diff --git a/src/site/confluence/download.confluence b/src/site/confluence/download.confluence new file mode 100644 index 0000000..308838f --- /dev/null +++ b/src/site/confluence/download.confluence @@ -0,0 +1,19 @@ + +h1. Download the librairie + +h2. Maven Central Repository + +We plan on hosting the librairie on the [Maven Central Repository|http://search.maven.org/], with the groupId *org.rundeck* and the artifactId *rundeck-api-java-client*. + +You can see all versions and download the files with this query : [g:"org.rundeck" AND a:"rundeck-api-java-client"|http://search.maven.org/#search%7Cga%7C1%7Cg%3A%22org.rundeck%22%20AND%20a%3A%22rundeck-api-java-client%22]. + +{note} +For the moment, the librairie is not on the repository, so you will need to download it manually... +{note} + +h2. Manual download + +If you want to use this librairie from a [scripting language|./scripting.html], it is often easier to download a single *jar* file with all dependencies included. + +You can download such files on GitHub : [https://github.com/vbehar/rundeck-api-java-client/downloads] + diff --git a/src/site/confluence/groovy.confluence b/src/site/confluence/groovy.confluence index 74b69d5..aed5bf9 100644 --- a/src/site/confluence/groovy.confluence +++ b/src/site/confluence/groovy.confluence @@ -3,27 +3,74 @@ h1. 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|http://groovy.codehaus.org/]. -We can use [Grape|http://groovy.codehaus.org/Grape] to download the lib (and its dependencies) from the [main Maven repository|http://search.maven.org/], so you don't have to install anything manually (except Groovy, of course). +We can use [Grape|http://groovy.codehaus.org/Grape] to download the lib (and its dependencies) from the [Maven Central Repository|http://search.maven.org/], so you don't have to install anything manually (except Groovy, of course). {note} -Note that the lib is NOT in the main maven repository for the moment... but hopefully it should be pretty soon ! +Note that the lib is NOT in the Maven Central Repository for the moment... but hopefully it should be pretty soon ! You can still [download|./download.html] it manually. {note} -h2. Running a job (from its name, group and project) +h2. Basic usage Save the following script in a file named "{{rundeck.groovy}}", and execute it with "{{groovy rundeck.groovy}}". Feeling Groovy ? ;-) {code} +// 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='1.0-SNAPSHOT') import org.rundeck.api.RundeckClient rundeck = new RundeckClient("http://localhost:4440", "admin", "admin") -job = rundeck.findJob("my-project", "main-group/sub-group", "job-name") -println "Running job : ${job}" +println "All RunDeck projects : ${rundeck.projects}" +println "All RunDeck jobs : ${rundeck.jobs}" +{code} +You can also [download|./download.html] 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}}". + +{code} +import org.rundeck.api.RundeckClient + +rundeck = new RundeckClient("http://localhost:4440", "admin", "admin") + +println "All RunDeck projects : ${rundeck.projects}" +println "All RunDeck jobs : ${rundeck.jobs}" +{code} + +h2. Running a job + +{code} +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 "Follow the execution at : ${execution.url}" +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 (in seconds) : ${execution.durationInSeconds}" +{code} + +h2. Running an ad-hoc command + +{code} +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")) {code} h2. And more... diff --git a/src/site/confluence/index.confluence b/src/site/confluence/index.confluence index 773c275..d6eb739 100644 --- a/src/site/confluence/index.confluence +++ b/src/site/confluence/index.confluence @@ -5,15 +5,15 @@ h2. What is it ? A Java librairie that maps the [RunDeck|http://rundeck.org] HTTP REST API. RunDeck is an open-source tool for automating tasks on multiple nodes, with a CLI, a web-based interface and an HTTP REST API. You can read more about its API on the [RunDeck User Manual|http://rundeck.org/docs/RunDeck-Guide.html#rundeck-api]. -This librairie has been extracted from the [Jenkins RunDeck plugin|http://wiki.jenkins-ci.org/display/JENKINS/RunDeck+Plugin], so for the moment it is still incomplete (not all the RunDeck API is mapped). My goal is to have a complete mapping of the RunDeck API, and to publish the librairie on the [main Maven repository|http://search.maven.org/], so that it can easily be used by Java ([Maven|http://maven.apache.org]) and Groovy ([Grape|http://groovy.codehaus.org/Grape]) developers. +This librairie has been extracted from the [Jenkins RunDeck plugin|http://wiki.jenkins-ci.org/display/JENKINS/RunDeck+Plugin], so for the moment it is still incomplete (not all the RunDeck API is mapped). My goal is to have a complete mapping of the RunDeck API, and to publish the librairie on the [Maven Central Repository|http://search.maven.org/], so that it can easily be used by Java ([Maven|http://maven.apache.org]) and Groovy ([Grape|http://groovy.codehaus.org/Grape]) developers. h2. What can I do with it ? +* Use it to write [scripts|./scripting.html] (in [Groovy|./groovy.html], [JRuby|./jruby.html] or [Jython|./jython.html]), for example if you want to automate the execution of RunDeck jobs based on external events. * Use it in a Java application. A good example would be the [Jenkins RunDeck plugin|http://wiki.jenkins-ci.org/display/JENKINS/RunDeck+Plugin], that needs to trigger RunDeck jobs from within the [Jenkins|http://jenkins-ci.org] continuous-integration server. -* Use it to write [Groovy|./groovy.html] or [JRuby|./jruby.html] scripts, for example if you want to automate the execution of RunDeck jobs based on external events. h2. Where can I get more information ? -* You can read the [API documentation|./apidocs/index.html]. +* You can read the [API documentation|./apidocs/index.html], starting with the [RundeckClient|./apidocs/org/rundeck/api/RundeckClient.html] class. * And the code is available on [GitHub|https://github.com/vbehar/rundeck-api-java-client]. diff --git a/src/site/confluence/jruby.confluence b/src/site/confluence/jruby.confluence index 4732e64..ceb0e8b 100644 --- a/src/site/confluence/jruby.confluence +++ b/src/site/confluence/jruby.confluence @@ -3,36 +3,75 @@ h1. Using the RunDeck API from JRuby scripts Here are some examples of what you can do with this lib and a few lines of [Ruby|http://www.jruby.org/] (for the rubyist that don't fear running on the JVM !) -You will have to [download|https://github.com/vbehar/rundeck-api-java-client/downloads] the lib (the .jar file) to use it... +You will have to [download|./download.html] the lib (the .jar file) to use it... -h2. Running a job (from its name, group and project) +h2. Basic usage Save the following script in a file named "{{rundeck.rb}}", and execute it with "{{jruby rundeck.rb}}". {code} require 'java' require '/path/to/rundeck-api-java-client-VERSION-jar-with-dependencies.jar' -java_import org.rundeck.api.RundeckClient +import org.rundeck.api.RundeckClient rundeck = RundeckClient.new("http://localhost:4440", "admin", "admin") -job = rundeck.findJob("my-project", "main-group/sub-group", "job-name") -puts "Running job : #{job}" - -execution = rundeck.triggerJob(job.id) -puts "Follow the execution at : #{execution.url}" +puts "All RunDeck projects : #{rundeck.projects}" +puts "All RunDeck jobs : #{rundeck.jobs}" {code} -You can also extract all the java-related stuff from the script file : save the following script in a file named "{{rundeck.rb}}", and execute it with "{{jruby -rjava -J-cp /path/to/rundeck-api-java-client-VERSION-jar-with-dependencies.jar rundeck.rb}}". +You can also add the librairie to the classpath : save the following script in a file named "{{rundeck.rb}}", and execute it with "{{jruby -rjava -J-cp /path/to/rundeck-api-java-client-VERSION-jar-with-dependencies.jar rundeck.rb}}". {code} -rundeck = org.rundeck.api.RundeckClient.new("http://localhost:4440", "admin", "admin") +import org.rundeck.api.RundeckClient +rundeck = RundeckClient.new("http://localhost:4440", "admin", "admin") + +puts "All RunDeck projects : #{rundeck.projects}" +puts "All RunDeck jobs : #{rundeck.jobs}" +{code} + +h2. Running a job + +{code} +import org.rundeck.api.RundeckClient +import org.rundeck.api.util.OptionsBuilder +import org.rundeck.api.util.NodeFiltersBuilder + +rundeck = RundeckClient.new("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") -puts "Running job : #{job}" +puts "Found job with ID : #{job.id}" +// trigger a simple job with no options execution = rundeck.triggerJob(job.id) -puts "Follow the execution at : #{execution.url}" +puts "Execution started, you can follow it at the URL : #{execution.url}" + +// or with options... +execution = rundeck.triggerJob("job-id", OptionsBuilder.new().addOption("option1", "value one").addOption("option2", "value two").toProperties()) + +// you can also override the nodes on which the job should execute +execution = rundeck.triggerJob("job-id", OptionsBuilder.new().addOption("opt", "value").toProperties(), NodeFiltersBuilder.new().tags("prod+appserv").toProperties()) + +// last one : you can run a job and wait until its execution is finished : +execution = rundeck.runJob("job-id") +puts "Execution finished ! Status : #{execution.status}, duration (in seconds) : #{execution.durationInSeconds}" +{code} + +h2. Running an ad-hoc command + +{code} +import org.rundeck.api.RundeckClient +import org.rundeck.api.util.NodeFiltersBuilder + +rundeck = RundeckClient.new("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", NodeFiltersBuilder.new().osFamily("unix").toProperties()) {code} h2. And more... diff --git a/src/site/confluence/jython.confluence b/src/site/confluence/jython.confluence new file mode 100644 index 0000000..9e58ff9 --- /dev/null +++ b/src/site/confluence/jython.confluence @@ -0,0 +1,67 @@ + +h1. Using the RunDeck API from Jython scripts + +Here are some examples of what you can do with this lib and a few lines of [Python|http://www.jython.org/] (for the pythonist that don't fear running on the JVM !) + +You will have to [download|./download.html] the lib (the .jar file) to use it... + +h2. Basic usage + +Save the following script in a file named "{{rundeck.py}}", and execute it with "{{jython -J-cp /path/to/rundeck-api-java-client-VERSION-jar-with-dependencies.jar rundeck.py}}". + +{code} +from org.rundeck.api import RundeckClient + +rundeck = RundeckClient("http://localhost:4440", "admin", "admin") + +print("All RunDeck projects : %s" % rundeck.projects) +print("All RunDeck jobs : %s" % rundeck.jobs) +{code} + +h2. Running a job + +{code} +from org.rundeck.api import RundeckClient +from org.rundeck.api.util import OptionsBuilder +from org.rundeck.api.util import NodeFiltersBuilder + +rundeck = 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") +print("Found job with ID : %s" % job.id) + +// trigger a simple job with no options +execution = rundeck.triggerJob(job.id) +print("Execution started, you can follow it at the URL : %s" % execution.url) + +// or with options... +execution = rundeck.triggerJob("job-id", OptionsBuilder().addOption("option1", "value one").addOption("option2", "value two").toProperties()) + +// you can also override the nodes on which the job should execute +execution = rundeck.triggerJob("job-id", OptionsBuilder().addOption("opt", "value").toProperties(), NodeFiltersBuilder().tags("prod+appserv").toProperties()) + +// last one : you can run a job and wait until its execution is finished : +execution = rundeck.runJob("job-id") +print("Execution finished ! Status : %s, duration (in seconds) : %s" % (execution.status, execution.durationInSeconds)) +{code} + +h2. Running an ad-hoc command + +{code} +from org.rundeck.api import RundeckClient +from org.rundeck.api.util import NodeFiltersBuilder + +rundeck = 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", NodeFiltersBuilder().osFamily("unix").toProperties()) +{code} + +h2. And more... + +See the API documentation of the [RundeckClient|./apidocs/org/rundeck/api/RundeckClient.html] class for more interactions with your RunDeck instance... + diff --git a/src/site/confluence/scripting.confluence b/src/site/confluence/scripting.confluence new file mode 100644 index 0000000..1256ce5 --- /dev/null +++ b/src/site/confluence/scripting.confluence @@ -0,0 +1,10 @@ + +h1. Scripting with the RunDeck client + +You can use this librairie with your prefered scripting language... as long as it runs on the JVM ! + +You can find some examples with : +* [Groovy|./groovy.html] +* [Ruby / JRuby|./jruby.html] +* [Python / Jython|./jython.html] + diff --git a/src/site/site.xml b/src/site/site.xml index e79fb19..295a312 100644 --- a/src/site/site.xml +++ b/src/site/site.xml @@ -4,14 +4,23 @@ xsi:schemaLocation="http://maven.apache.org/DECORATION/1.1.0 http://maven.apache.org/xsd/decoration-1.1.0.xsd" name="${project.name}"> UA-23435653-1 + + + + + + + + +