Due to some maintenance issues, this service has been switched in read-only mode, you can find more information about the why

and how to migrate your plugin documentation in this blogpost

Skip to end of metadata
Go to start of metadata

Plugin Information

View Rancher on the plugin site for more information.

Enables Jenkins to deploy or upgrade Rancher stack service instance


  • Deploy docker image to Rancher 
  • Upgrade exist service instance in Rancher
  • Support options to finish the upgrade automatically 
  • Support build environment variable as docker image tag, e.q. busybox:${BUILD_NUMBER}

Potential upcoming features

  • Provision rancher stack with docker-compose and rancher-compose file



Jenkins version 2.11 or newer is required.


Rancher version 1.2.2 or newer is required.


Install plugin

Install this plugin via the Jenkins plugin manager.

Or if installing the plugin via other means.

Create Rancher API Key

  1. To enable access to your rancher server, you must create a account api key:
  2. Siigin in to rancher server dashboard
  3. Select Menu → API
  4. Click "Add Account API Key"
  5. Give the  api key any name and description you like, e.g "Jenkins"
  6. Click the "Create Key"
  7. Save the "Access Key" and "Secret Key" any way you like, we will use it later
  8. You can now close the dialog 

Add the Rancher API Key to Jenkins

  1. Navigate to your Jenkins instance
  2. Select "Credentials" from the Jenkins sidebar
  3. Choose a credentials domain and click "Add Credentials"
  4. From the "Kind" drop-down, choose "Username with password"
  5. Enter a description for the credential — the actual value is not important
  6. Click "OK" to create the credential

Per-job configuration

Freestyle job configuration

Deploy or Upgrade Service Instance
  1. Create a new free-style project
  2. Ensure. via whatever build stepds you need, tha the Docker image you want to deploy to Rancher will be available in the docker registry
  3. Add "Deploy/Upgrade Rancher Service" post-build action
  4. Enter the target Rancher Service API endpoint, e.g 'http://rancher-server/v2-beta'
  5. Select the credential name from the drop-down list
  6. Enter the target rancher environment id, e.g '1a5558'
  7. Enter the target service name, e.g 'stack/service'
  8. Enter the docker image name, e.g 'busybox' (image name support current build environment variable like 'busybox:${BUILD_NUMBER}' to support dynamic image tag)
  9. Optionally choose "Auto Confirm" to finish the upgrade automatically
  10. Optionally choose "Public Ports" to export service ports. mutil port shoule e split be ",". e.g 8080:80,9191:91

Version history

Version 1.0.0 (July 13, 2017)

  • Initial release

Version 1.0.1 (July 17, 2017)

  • Fixed dependencies info missing issue.

Version 1.0.2 (August 04 2017)

  • Preserves the log config while upgrading a service.

Version 1.0.3 (September 03 2017)

  • Support export service ports.

Version 1.0.4 (September 12 2017)

  • Support export environment variable.

Version 1.0.5 (October 10 2017)

  • Support health check serialization.

Version 1.0.7 (December 11 2017)

  • Support custom timeout, and build variable in all fields.





  1. Unknown User (vishnuvpotty)


    I am trying to deploy a docker image through plugin.I deployed a hello-world container in Rancher by adding a host and then new container from UI.

    Can you let me know in that case, what should be the service name to be selected and given in the plugin. you have mentioned stack/service as example.

    However my stacks has All / User /Infrastructure only,



    1. Unknown User (kjohns3)

      The "All / User / Infrastructure Only" menu options are just ways of filtering the stacks.

      Using the example image below, the service name field would be the following: sonatype-nexus3/nexus

      1. Unknown User (yunlzheng)

        In this case the service name should be sonatype-nexus3/nexus

  2. Unknown User (fangludi)

    how to specify ports using this plugin, thanks~

    1. Unknown User (yunlzheng)

      I just create a new release 1.0.3 to support specify ports in advanced options. mutil port should be split by ",". e.g 8080:80,9191:91

      1. Unknown User (khros)

        Great job with the multi port!!

        Can we define variables, using a plugin like "EnvInject Plugin", to contain the values for the ports and specify them in the Advanced options?

      2. Unknown User (khros)

        Great job with the multi port!!

        Can we define variables, using a plugin like "EnvInject Plugin", to contain the values for the ports and specify them in the Advanced options?


  3. Unknown User (hopstar)

    Is it possible to acces the rancher plugin though the jenkins pipeline?

  4. Unknown User (slamhan)

    stage ('Upgrade') {
    dir ('account-service') {
    sh 'rancher-compose --url --access-key 602311D6074EC0DFCBB5 --secret-key YttmUwex7ryzBLnM1CctyumSqac16AboL43Va8df -f ../docker-compose-on-rancher-ui.yml -env-file ../secrets -p Applications up account-service --force-upgrade -p -c -d'
    Is it possible read the rancher plugin configs from jenkins pipeline file?

  5. Unknown User (xuxogarcia)

    Unknown User (slamhan) I do the same thing as you. Can't wait to know if I can invoke via pipeline

  6. Unknown User (hyl)

    Stack already exist. skip
    ERROR: Build step failed with exception
    java.lang.RuntimeException: Some Error Happen statusCode 404 response: {"id":"08709811-65e8-481b-97c5-00e1d86b2c09","type":"error","links":{},"actions":{},"status":404,"code":"Not Found","message":"Not Found","detail":null,"baseType":"error"}
    	at jenkins.plugins.rancher.HttpClient.execute(HttpClient.java:72)
    	at jenkins.plugins.rancher.HttpClient.get(HttpClient.java:31)
    	at jenkins.plugins.rancher.RancherClient.services(RancherClient.java:39)
    	at jenkins.plugins.rancher.RancherBuilder.perform(RancherBuilder.java:94)
    	at hudson.tasks.BuildStepCompatibilityLayer.perform(BuildStepCompatibilityLayer.java:81)
    	at hudson.tasks.BuildStepMonitor$1.perform(BuildStepMonitor.java:20)
    	at hudson.model.AbstractBuild$AbstractBuildExecution.perform(AbstractBuild.java:735)
    	at hudson.model.Build$BuildExecution.build(Build.java:206)
    	at hudson.model.Build$BuildExecution.doRun(Build.java:163)
    	at hudson.model.AbstractBuild$AbstractBuildExecution.run(AbstractBuild.java:490)
    	at hudson.model.Run.execute(Run.java:1735)
    	at hudson.model.FreeStyleBuild.run(FreeStyleBuild.java:43)
    	at hudson.model.ResourceController.execute(ResourceController.java:97)
    	at hudson.model.Executor.run(Executor.java:405)
    Build step 'Deploy/Upgrade Rancher Service' marked build as failure
    Finished: FAILURE

  7. Unknown User (dsm_a)

    Are you planning to implement an upgrade for creating volumes on service?


    Thanks for great plugin anyway!

  8. Unknown User (hyl)

    I plan to restart the service container

  9. Unknown User (yangsenlin)

    Does anyone know what the problem is?