Upgrading Jenkins Java version from 8 to 11

There are a few details and steps to upgrade the JVM used to run Jenkins, more specifically from Java 8 to Java 11.

If you’re upgrading the JVM used to run Jenkins, and particularly if you’re upgrading from Java 8 to Java 11, there are some details you should know and precautions you should take.

Backup

As with any upgrade, we recommend backing up JENKINS_HOME and testing the upgrade with the backup before performing the upgrade on your production instance.

Upgrading Jenkins

If you need to upgrade Jenkins as well as the JVM, we recommend that you:

  1. Back up JENKINS_HOME

  2. Upgrade Jenkins to the most recent version

    • How you upgrade Jenkins is dependent upon your original Jenkins installation method.

    • We recommend that you use the package manager of your system (such as apt or yum).

  3. Validate the upgrade to confirm that all plugins and jobs are loaded

  4. Upgrade the required plugins (see Upgrading Plugins)

  5. Make a second backup of JENKINS_HOME after upgrading Jenkins and the required plugins

  6. Stop the Jenkins instance

  7. Upgrade the JVM on which Jenkins is running

    • Use a package manager to install the new JVM.

    • Make sure the default JVM is the newly installed version. If it is not, run systemctl edit jenkins and set either the JAVA_HOME environment variable or the JENKINS_JAVA_CMD environment variable.

If you use Docker containers to run Jenkins, the default Docker containers use Java 11 beginning with Jenkins 2.303.1. If you need to remain with Java 8 in a Docker container, append -jdk8 to the Docker image tag.

Starting with the 2.353 weekly release line, Java 11 will be required for future weekly release lines. These instructions will still apply to the Long Term Support release line until September 2022, when the LTS release line will mirror the weekly release line Java requirements.

Upgrading Plugins

It’s important not just to upgrade Jenkins and the JVM but also to upgrade the plugins which support Java 11. Plugin upgrades assure compatibility with the most recent Jenkins releases.

If you discover a previously unreported issue, please let us know: read how to report a Java 11 Compatibility issue for guidance.

Javax XML Bind libraries

Some plugins use JAXB libraries provided by the JDK. However, the java.xml.bind and javax.activation modules are no longer included in OpenJDK 11, and plugins might fail if no replacement is offered.

To fix this problem, we’ve bundled those libraries into a new detached plugin: JAXB plugin. When any Jenkins core more recent than 2.163 is running on Java 11, this plugin is automatically installed. However, if you manage your plugins outside Jenkins (for example, if you use plugins.txt in your Docker images), you might need to install the plugin explicitly.

JVM version on agents

All agents must be running on the same JVM version as the controller (because of how controllers and agents communicate). If you’re upgrading your Jenkins controller to run on Java 11, you also need to upgrade the JVM on your agents.

You can validate the version of each agent with the Versions Node Monitors plugin. This plugin provides information about the JVM version of each agent on the node management screen of your Jenkins instance. You can also configure this plugin to automatically disconnect any agent with an incorrect JVM version.

Java Web Start

Java Web Start has been removed in Java 11. When a Jenkins controller runs on Java 11, the Java Web Start button will no longer appear in the Web UI. You can’t launch agents for a Java 11 Jenkins server from a *.jnlp file downloaded to a web browser.

There are no plans to replace this functionality. Connect agents to Jenkins on Java 11 with plugins like SSH Build Agents Plugin, with operating system command line calls to java -jar agent.jar, or using containers.

JDK Tool Automatic installer

Oracle JDK 11 licensing prevents the Jenkins community from listing the Oracle JDKs. Because of this licensing restriction, Oracle JDK 11 can’t be automatically installed by Jenkins. This problem is tracked in the issue JENKINS-54305.

As an alternative, we encourage you to use containers based on images that contain all the tooling needed for your builds.