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

Edit
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.

Add Comment