RunDeck Plugin

Skip to end of metadata
Go to start of metadata

Plugin Information

Plugin ID rundeck Changes In Latest Release
Since Latest Release
Latest Release
Latest Release Date
Required Core
Dependencies
3.3
Apr 15, 2014
1.424
Source Code
Issue Tracking
Maintainer(s)
GitHub
Open Issues
Vincent Behar (id: vbehar)
Greg Schueler (id: gschueler)
Usage Installations 2013-Apr 237
2013-May 261
2013-Jun 285
2013-Jul 314
2013-Aug 308
2013-Sep 309
2013-Oct 358
2013-Nov 353
2013-Dec 349
2014-Jan 387
2014-Feb 386
2014-Mar 402

This plugin is a Notifier that will talk to a RunDeck instance (via its HTTP API) to schedule a job execution on RunDeck after a successful build on Jenkins.
It is also a Trigger that will schedule a build on Jenkins after a job execution on RunDeck (using RunDeck WebHook Notification).
In addition, it turns Jenkins into an Option provider for RunDeck, if you want to use your Jenkins build artifacts as an option to a RunDeck job.

Table of Contents

Use

RunDeck is an open-source tool for automating tasks on multiple nodes, with both a CLI and a web-based interface. You can use it to deploy your application to multiple nodes/appserv easily. It has a concept of jobs and build similar to Jenkins.

You have 3 ways to use this plugin :

  • build a "deployment pipeline", (the "0-click deployment process") : you commit a change, Jenkins picks it up, build, test and so on, and then triggers a job execution on RunDeck for deploying your application. This requires some configuration on Jenkins (both global configuration and job configuration), to link a Jenkins job with a RunDeck job.
  • continue your pipeline after the deployment : RunDeck deploys your application, then triggers a build on Jenkins to run some integration tests (Selenium ?). This requires some configuration on RunDeck (WebHook notification) and on Jenkins (Trigger configuration, and optionally filter the notifications from RunDeck).
  • use Jenkins as an Option provider for RunDeck : when you execute a RunDeck job, you can have an (input) option, whose values could be retrieve from an external system (here, Jenkins). So you can have a RunDeck-job that use a Jenkins-artifact (from a Jenkins-build) as an input.

Note that you can combine those use-cases.

Deployment Pipeline

The goal is to have a 0-click deployment process : you commit a change, Jenkins picks it up, build, test and so on, and then triggers a job execution on RunDeck for deploying your application.
You can also have an "on-demand" process : configure a "tag" in the job configuration (see below), and the plugin will only notify RunDeck if the tag is present in the SCM changelog (= in the commit message).

Configuration

First, you need to configure your RunDeck instance on the main Jenkins configuration page :

As of Rundeck plugin version 3.0, you can specify an Authtoken instead of Login/Password.  Additionally you can set the API version if you need to use a lower number than the latest version.

You can use the "Test Connection" button to make sure that Jenkins can talk to your RunDeck instance :

Error message in case of error Success message when your credentials are valid

Then, for each Jenkins job, configure the target RunDeck job that should be executed, along with its options :

The per-job configuration screen If you click "Check Job" it will display the job details (group, job name and project)
  • Note that the "options" should be expressed in the java-properties format, and that Jenkins environment variables are expanded when making the RunDeck API calls (for more details, read the integrated-help in your Jenkins instance by clicking the "?" icon next to the "options" field).
  • The "tag" field is used to perform "on-demand" job scheduling on RunDeck : if the value is not empty, we will check if the SCM changelog (= the commit message) contains the given tag, and only schedule a job execution if it is present. For example you can set the value to "#deploy". Note that if this value is left empty, we will ALWAYS schedule a job execution.
  • You can choose to wait for the RunDeck job to finish before finishing the Jenkins build. Otherwise, the default behavior is to trigger a RunDeck job, and finish the Jenkins build (usually before the RunDeck job has ended).
  • If the last checkbox is checked, then a failure to schedule the job execution on RunDeck will fail the Jenkins build. Otherwise, the RunDeck integration won't interact with the result of your Jenkins build (even if RunDeck is down).

Post-deployment job

The goal is to continue the deployment pipeline after a successful deployment : RunDeck deploys your application, and triggers a build on Jenkins to run some integration tests (using Selenium for example).

Configuration

First, you need to configure the WebHook Notification in your RunDeck jobs. Set it to the url http://JENKINS_HOST/plugin/rundeck/webhook/.

Then, configure the "RunDeck Trigger" on your Jenkins jobs : activate it, and optionally filter the notifications from RunDeck.

Use

If your Jenkins job is started by a RunDeck notification, you can access the data of the RunDeck notification as environment variables :

  • RDECK_JOB_ID : the ID (UUID) of the job
  • RDECK_JOB_NAME : the name of the job
  • RDECK_JOB_GROUP : the group of the job
  • RDECK_JOB_DESCRIPTION : the description of the job
  • RDECK_PROJECT : the name of the project
  • RDECK_EXEC_ID : the ID of the execution
  • RDECK_EXEC_STATUS : the status of the execution (one of SUCCEEDED, FAILED or ABORTED)
  • RDECK_EXEC_STARTED_BY : the user who started the execution
  • RDECK_EXEC_STARTED_AT : the date at which the execution started
  • RDECK_EXEC_ENDED_AT : the date at which the execution ended
  • RDECK_EXEC_ABORTED_BY : the user who aborted the execution (if the status is ABORTED)
  • RDECK_EXEC_DURATION_MILLIS : the duration of the execution, in milli-seconds
  • RDECK_EXEC_DURATION_SECONDS : the duration of the execution, in seconds
  • RDECK_EXEC_DURATION : the duration of the execution, as a human-readable string ("3 minutes 34 seconds")
  • RDECK_EXEC_SHORT_DURATION : the duration of the execution, as a short human-readable string ("0:03:34.187")
  • RDECK_EXEC_URL : the url of the execution (on the RunDeck Web GUI)
  • RDECK_EXEC_DESCRIPTION : the description of the execution
  • RDECK_EXEC_ARG_[NAME] : the value of a Job option passed to the execution (plugin version 3.0 or later)

Option Provider

Using Jenkins as an Option provider for RunDeck is very easy, because you don't need to configure anything on the Jenkins side. You just need to point your RunDeck option "remote url" to one of the following url :

Option Provider for artifacts

List all artifacts for a given project / build, with a reference to the absolute url of the artifact. Useful if you have multiple artifacts to deploy (one per architecture for example).
Example (RunDeck screen when executing a job with an "artifact" option, taking its values from Jenkins) :

The url : http://JENKINS_HOST/plugin/rundeck/options/artifact

  • The parameter project is mandatory (name of the job)
  • The parameter build is optional (default value is 'last'). It could be either a build number, or "last", "lastStable" or "lastSuccessful".
  • The parameter artifactRegex is optional. It is a java-regex used to filter the artifacts to return (if empty, all artifacts will be returned).

Example : http://JENKINS_HOST/plugin/rundeck/options/artifact?project=my-job&build=lastSuccessful&artifactRegex=.*\.war

Option Provider for builds

List all builds (versions) for a given project / artifact, with a reference to the absolute url of the artifact. Useful if you have only 1 main artifact, but want to easily re-deploy an older version of the artifact.
Example (RunDeck screen when executing a job with a "build" option, taking its values from Jenkins) :

The url : http://JENKINS_HOST/plugin/rundeck/options/build

  • The parameter project is mandatory (name of the job)
  • Either the parameter artifact (exact filename of the artifact) or artifactRegex (java-regex matching the filename of the artifact) is mandatory
  • The parameter limit is optional. It should be an integer, and is used to limit the number of builds (versions) to return.
  • The parameters includeLastStableBuild, includeLastSuccessfulBuild and includeLastBuild are optional booleans. If it is equals to "true", then we will add an entry for the last / last stable / last successful build.

Example : http://JENKINS_HOST/plugin/rundeck/options/build?project=my-job&artifact=my-webapp.war&limit=5&includeLastSuccessfulBuild=true&includeLastStableBuild=true

Compatibility Matrix

This plugin is not compatible with all versions of RunDeck

Plugin version RunDeck 1.0 / 1.1 RunDeck 1.2+
1.x
2.x
3.x

If you are using Plugin version 3.x and need to access an older Rundeck server, you can set the API version in the plugin settings.

You can find older versions of the plugin here : http://maven.jenkins-ci.org/content/repositories/releases/org/jenkins-ci/plugins/rundeck/

FAQ

Known Issues

  • If you have invalid links to RunDeck executions, check your RunDeck configuration : fix the property "grails.serverURL" in the file $RDECK_HOME/server/config/rundeck-config.properties.
  • With the versions 1.x of the plugin, you can't have RunDeck jobs with the same groupPath/jobName on multiple projects.

Links

Change Log

TODO list

  • Internationalization
  • Configure multiple RunDeck instances (in the global config), and choose the instance to use in the job configuration
  • Option provider : add integration with the Promoted Builds Plugin and/or Promoted Builds Simple Plugin so that we can filter only "promoted" builds.
  • Use a drop-down field to select the RunDeck job (list of jobs retrieved using the API) instead of the basic text field

Previous versions

Version 3.0 (January 28, 2014)
  • Update rundeck API client lib to latest (9.3)
  • Support Token authentication
  • Fix authentication against Rundeck running as a war in Tomcat
  • Support RDECK_EXEC_ARG_[NAME] in triggers from Rundeck webhook notifications
  • Update naming ("RunDeck" changed to "Rundeck"), update icon
Version 2.11 (January 4, 2012)
  • Fix JENKINS-12228 : allow to filter artifacts returned by the option provider, based on a java-regex
Version 2.10 (October 12, 2011)
  • Fix icon path URL - Thanks to Joe Passavanti for the patch !
  • Small UI fix : don't display job's ID (in rundeck 1.3+, ID is an UUID, and it breaks the UI because it is too long)
Version 2.9 (September 18, 2011)
  • Allow to filter nodes when triggering a rundeck job (using the "nodeFilters" parameter)
Version 2.8 (September 16, 2011)
  • Configure RunDeck jobs with either a job ID, or an UUID (rundeck 1.3+), or a "reference". A job reference is expressed in the format "project:group/job", for example : "my-project-name:main-group/sub-group/my-job-name", or "my-project-name:my-job-name" (for a job without a group).
Version 2.7 (September 14, 2011)
  • Add a build trigger, using RunDeck 1.3 WebHook Notification, so that you can run integration tests with Jenkins after a RunDeck deployment (alternative to the "Wait for RunDeck job to finish ?" checkbox in the notifier configuration and a post-build action to schedule another job)
  • Upgrade RunDeck API Java client to version 1.2
Version 2.6 (September 2, 2011)
Version 2.5 (July 11, 2011)
  • Internal refactoring : use the RunDeck API Java client
  • Never display the RunDeck password in logs (even in case of error)
Version 2.4 (June 28, 2011)
  • Change Job ID support to use Strings instead of Long, allowing UUIDs (coming in RunDeck 1.3) - Thanks to Greg Schueler for the patch !
Version 2.3.1 (June 22, 2011)
  • Fix a bug introduced in version 2.3 : NPE related to the new field (shouldWaitForRundeckJob) in already configured jobs. Workaround is to re-save job configuration or use version 2.3.1
Version 2.3 (June 21, 2011)
  • Add an option to wait for the RunDeck job to finish (by polling the execution every 5 seconds via the RunDeck API)
  • Add a validation button on the job configuration screen, to check the RunDeck job (display job name, group and project)
Version 2.2 (June 17, 2011)
  • Add SSL support for RunDeck REST API (trust all certificates and hosts)
Version 2.1 (June 8, 2011)
  • New feature : display information about the RunDeck job on the page of a Jenkins job (with a direct link to the RunDeck job details webpage)
Version 2.0.1 (June 8, 2011)
  • Rerelease 2.0 and mark it as incompatible with versions 1.x (jobs configuration needs to be updated), so that users can see it in the update-center before updating.
Version 2.0 (June 6, 2011)
Compatibility Warning !
This version won't work with RunDeck 1.0/1.1, and the configuration per job has changed, you will need to update the configuration for all your jobs that use this plugin !
  • Use the new RunDeck 1.2+ HTTP REST API, and thus is incompatible with RunDeck 1.0 or RunDeck 1.1
  • Use "jobId" to reference RunDeck jobs, instead of the "groupPath/jobName" couple, so you'll need to reconfigure your Jenkins jobs. We switched to the "jobId" reference because it is unique across all projects in a RunDeck instance, which is not the case for the "groupPath/jobName" couple.
  • Set required Jenkins version to 1.400
Version 1.8 (June 5, 2011)
  • Fix JENKINS-9876 : password field in system configuration should be hidden.
Version 1.7 (June 1, 2011)
  • New improvement to the option provider : you can now match artifacts with a java-regex in addition to exact-match of the artifact filename (see the new 'artifactRegex' parameter).
Version 1.6 (April 6, 2011)
Version 1.5.1 (March 24, 2011)
Version 1.5 (March 4, 2011)
  • Fix bug : when using a "tag" to auto-deploy, we should also check the SCM changelog from upstream builds. So that you can commit to an upstream job, and have all downstream jobs redeployed.
Version 1.4 (March 1, 2011)
  • New improvement to the option provider : in addition to the list of artifacts for a given build, you can now get the list of builds (versions) for a given artifact.
Version 1.3 (February 27, 2011)
  • Jenkins can now be used as an "Option provider" for RunDeck, if you want to use your Jenkins build artifacts as an option to a RunDeck job.
Version 1.2 (February 27, 2011)
  • Jenkins environment variables specified in the "options" are now correctly expanded (GitHub issue)
Version 1.1 (February 11, 2011)
  • Do nothing if the build is failing
  • Add a link to the RunDeck job execution page (on each Jenkins successful build)
  • Validation on the form fields (test if RunDeck is alive, test credentials, etc)
Version 1.0 (February 10, 2011)
  • Initial release
  • Compatible (and tested) with Jenkins 1.396 and RunDeck 1.1

Labels

plugin-notifier plugin-notifier Delete
plugin-external plugin-external Delete
plugin-trigger plugin-trigger Delete
Enter labels to add to this page:
Please wait 
Looking for a label? Just start typing.
  1. Jun 01, 2011

    star latch says:

    Hi Vincent, My Jenkins build job is currently setup to generate a single ZIP ar...

    Hi Vincent,

    My Jenkins build job is currently setup to generate a single ZIP artifact that includes version and build number as part of the filename. Is it possible for me to use the second form of query (list all builds for a given project/artifact), and give it a wildcard for the filename? If yes, can you provide an example of how it can me done.

    Thanks!

    -starlatch

    1. Jun 01, 2011

      Vincent Behar says:

      Hi, I just did a new version of the plugin (1.7) with this feature : I added a ...

      Hi,

      I just did a new version of the plugin (1.7) with this feature : I added a new parameter 'artifactRegex' that should be a java-regex. Use it instead of the 'artifact' parameter.
      I will update the wiki page.

      Vincent

      1. Jun 01, 2011

        star latch says:

        Thanks Vincent! I really appreciate the quick turnaround. I build the plugi...

        Thanks Vincent! I really appreciate the quick turnaround.

        I build the plugin from sources and tried it out. I can confirm the artifactRegex works!

        1. Jun 01, 2011

          Vincent Behar says:

          No problem. Next time you want to try a plugin that has been released but has no...

          No problem.
          Next time you want to try a plugin that has been released but has not made it to the update-center yet (the update-center is rebuilt every 6 hours or so), you don't need to build it from source, you can just download the .hpi from http://maven.jenkins-ci.org/ (for example search for 'rundeck'...)

  2. Jun 05, 2011

    star latch says:

    Hi Vincent, The system configuration to specify the URL, login and password doe...

    Hi Vincent,

    The system configuration to specify the URL, login and password does not hide the password. I created an issue JENKINS-9876 for this. Also, I am wondering if you considered having Jenkins talk to multiple RunDeck admin servers?

    Thanks!

    - starlatch

    1. Jun 05, 2011

      Vincent Behar says:

      yes, each time I use the admin interface I say to myself that I must change that...

      yes, each time I use the admin interface I say to myself that I must change that, but I always forget. Anyway, this time it's fixed (version 1.8).

      I did not consider talking to multiple rundeck instances, because I prefer having just 1 instance with multiple projects, but I can understand that some people might prefer to have multiple instances. I can do something similar to the "tools" installs (a list of instances, each identified by a name/label. and then in the job configuration you choose which instance you want to use). I'll look into that.

  3. Jul 05, 2011

    star latch says:

    Hi Vincent, Her is another place where password needs to be masked- — SN...

    Hi Vincent,

    Her is another place where password needs to be masked-

    — SNIP —
    Scheduling failed for job Jobs/Deployment/deploy-e2e on RundeckInstance [url=http://4826.example.com:4440, login=admin, password=admin] : Invalid HTTP code result : 500 for http://4826.example.com:4440/scheduledExecution/runJobByName.xml
    — SNIP —

    Thanks in Advance!

    1. Jul 07, 2011

      Vincent Behar says:

      Ok I'll give it a look. But with the new version (rundeck 1.3) we will be able t...

      Ok I'll give it a look. But with the new version (rundeck 1.3) we will be able to use auth tokens, so no more login/password !

  4. Apr 25, 2012

    gregory spranger says:

    hola, so i didn't want to be one of those guys that posts a bogus BUG, so i wil...

    hola,

    so i didn't want to be one of those guys that posts a bogus BUG, so i will just ask it here .. we are trying to use the below plugin with the rundeck plugin:

    https://wiki.jenkins-ci.org/display/JENKINS/Multijob+Plugin

    when we trigger multiple rundeck jobs (with checked "Wait for RunDeck job to finish ?" AND "Should fail the build ?") sequentially, all works as expected .. however, when we trigger multiple rundeck jobs in parraellel (yes, same ones), we get errors .. more accurately, we get this jenkins error and rundeck error:

    JENKINS

    ====================================

    Notifying RunDeck...
    Error while talking to RunDeck's API at http://rundeck.XXX.net : Invalid HTTP response 'HTTP/1.1 500 Internal Server Error' for http://rundeck.XXX.net/api/1/job/90569740-5b52-4737-80a6-d4de8d354604/run?argString=-host+w-d.XXX.net+-runmode+publish
    Build step 'RunDeck' marked build as failure
    Notifying upstream projects of job completion

    RUNDECK

    ====================================

    INFO ScheduledExecutionService: scheduling immediate job run: TEMP:deploy:32:474
    ERROR GrailsExceptionResolver: Exception occurred when processing request: [GET] /api/1/job/90569740-5b52-4737-80a6-d4de8d354604/run
    Stacktrace follows:
    org.hibernate.StaleObjectStateException: Row was updated or deleted by another transaction (or unsaved-value mapping was incorrect): [ScheduledExecution#32]
    ....
    2012-04-25 13:13:16.874::INFO: Cache Eviction for deploy.
    2012-04-25 13:13:16.876::INFO: Attempting authentication: uid=deploy,ou=People,dc=dso,dc=XXX,dc=net
    ERROR PatchedDefaultFlushEventListener: Could not synchronize database state with session
    org.hibernate.StaleObjectStateException: Row was updated or deleted by another transaction (or unsaved-value mapping was incorrect): [ScheduledExecution#32]
    at org.hibernate.persister.entity.AbstractEntityPersister.check(AbstractEntityPersister.java:1792)
    ....

    any ideas on what we might be doing wrong ?? of course if we don't "wait" on the rundeck job, all works AOK when running in parrallel -- but we really need to "wait" for the results ..

    thanks for the help !!

    1. Apr 25, 2012

      gregory spranger says:

      after further investigation .. it seems like this is on rundeck's side of the ho...

      after further investigation .. it seems like this is on rundeck's side of the house:

      http://rundeck.lighthouseapp.com/projects/59277-development/tickets/563-multipleexecutions-error

      BTW -- thanks for the great plugin !!

      1. Apr 26, 2012

        Vincent Behar says:

        ok good

        ok good

  5. Aug 22, 2013

    firass Gz says:

    Hi All, Just discovered that the plugin is not working for rundeck 1.6, which i...

    Hi All,

    Just discovered that the plugin is not working for rundeck 1.6, which is a waste!

    The "Test connection" fails on 1.6 whilst it worked just great on 1.5 before upgrade with the same credentials 

    Anybody knows why it happens and how to fix it?

    Thanks +

  6. Sep 22, 2013

    Marcel Stör says:

    That's nice, works well but Rundeck is spelled Rundeck and not RunDeck or Run De...

    That's nice, works well but Rundeck is spelled Rundeck and not RunDeck or Run Deck.