Migrating from On-Premise Executors to standard agents


I’m currently relying on OPEs on DEV@cloud.



On-Premise Executors feature is going to be removed in favor of the standard Jenkins way of creating agents.
After 24th April 2017, only agents created from the standard Jenkins UI will be available in DEV@cloud.
Former On-Premise Executors, launched using on-premise-executor or customer-managed-slave commands of the CLI, will not be able to connect to your instance anymore.

As a user of OPE, you have to convert your OPEs to standard agents.
Thankfully, migrating is quite a simple process. You need to do the following steps:

  1. follow Build Executor Status link on the left of Jenkins homepage to go to the agent management page
  2. follow New Node link
  3. choose a Node name and select Permanent Agent
  4. select a launch method. We advise you to use Launch agent via Java Web Start, which creates a JNLP agent. Even if it is now supported to use SSH agents, JNLP agents work like former OPEs from a network perspective, as outbound connection is initiated by the agent process. You don’t need to configure firewalls to let SSH traffic in, simplifying the migration from OPE.
  5. configure node properties like the OPE you’re replacing, especially Labels and Usage properties
  6. disconnect the OPE by stopping the OPE process
  7. connect the agent you’ve just created. Refer to the following section for JNLP agents.

If you were using ephemeral OPE, you will to create a dedicated agent for each agent to connect.
It is mandatory to use Java 8 to launch the JNLP agent process.

Connecting a JNLP agent

Like for former OPEs, there’s a extra configuration step involved to connect to the JNLP port in DEV@cloud.
In a recent change to secure DEV@cloud network infrastructure, we removed the possibility to connect to the JNLP port directly.
To allow using this port this while still keeping things secure, we’ve added a proxy service.
When starting an JNLP agent, you need to specify -Dhttp.proxyHost=dac-cli-proxy.cloudbees.com -Dhttp.proxyPort=3128 on the command line to tell the agent to use that hostname/port as a proxy for connecting to the actual Jenkins instance.
Omitting this proxy setting will result in a connection failure.

Assuming you created a agent called agent1, you will start it with the following command line:

/usr/bin/java -Dhttp.proxyHost=dac-cli-proxy.cloudbees.com -Dhttp.proxyPort=3128 \
  -jar /home/ubuntu/slave.jar \
  -jnlpUrl https://YOUR_INSTANCE.ci.cloudbees.com/computer/agent1/slave-agent.jnlp \

You must have slave.jar available before starting the agent. It can be downloaded from https://YOURINSTANCE.ci.cloudbees.com/jnlpJars/slave.jar.
A recent CLI JAR is needed and should be updated whenever a new Jenkins version is rolled out on DEV@cloud.

Issues with SVN

Because we require setting the HTTPS proxy of the JVM agent to our proxy service, you might encounter issues to connect to other HTTPS services like SVN.
In that case, you should add a proxy exclusion by adding the JVM property -Dhttp.nonProxyHosts.
Say you want to use the Apache Foundation SVN server and access https://svn.apache.org/repos/project1, you would add -Dhttp.nonProxyHosts=svn.apache.org to the JVM arguments.
This would turn the complete command line to launch the JNLP agent to:

/usr/bin/java -Dhttp.nonProxyHosts=svn.apache.org \
  -Dhttp.proxyHost=dac-cli-proxy.cloudbees.com -Dhttp.proxyPort=3128 \
  -jar /home/ubuntu/slave.jar \
  -jnlpUrl https://YOUR_INSTANCE.ci.cloudbees.com/computer/agent1/slave-agent.jnlp \

You can find a detailed documentation of JVM proxy settings in the official Oracle documentation

Have more questions? Submit a request


  • 0
    Anton Berezin

    Does it affect on-premise executors created via: java -jar jenkins-cli.jar -s ${jenkins_master_url}
    -i ${ssh_key} customer-managed-slave ?

  • 0
    Stefano Zilli

    The procedure work fine. Just a note, the proxy properties in the text differ from those in the command.

  • 0
    Yoann Dubreuil

    Thanks Stefano for the note, I'm fixing the article right now

  • 0
    Yoann Dubreuil

    Anton, it affects all OPEs. You will have to migrate the one connected with customer-managed-slave too. I've updated the article to reflect this.

  • 0
    Arnaud Heritier

    This KB should redirect (for a part of it) to the official documentation: https://go.cloudbees.com/docs/cloudbees-documentation/dev-at-cloud/#_on_premise_executors

Please sign in to leave a comment.