Migrating to Java 11

8 minute read

Java 11 was released on September 25, 2018 as a long-term support (LTS) version. The Jenkins LTS core that CloudBees Jenkins Platform is based on has been capable of using Java 11 for some time, but all core and plugin code was limited to using only Java 8 language features (Java 8 byte code). It is expected that the Jenkins community will move to supporting Java 11-specific features soon (Java 11 byte code), at which point it will no longer be possible to use a Java 8 runtime environment. Because CloudBees Jenkins Platform is based on the Jenkins LTS, future releases of CloudBees Jenkins Platform will have the same requirement.

CloudBees has validated the core functionality and all plugins in the CloudBees Assurance Program work correctly when using Java 11. Plugins that are not part of the CloudBees Assurance Program may work, but they have not been verified and thus may cause issues.

CloudBees strongly recommends upgrading CloudBees CI on traditional platforms and CloudBees Jenkins Platform to Java 11 as soon as possible. Starting in release 2.332.1.4, CloudBees CI and CloudBees Jenkins Platform will support both Java 8 and Java 11 until the Jenkins community releases an LTS that requires Java 11.

Supported configurations

CloudBees performs full test flows with the following supported JDKs or JREs:

  • OpenJDK JDK/JRE 8 - 64 bits

  • OpenJDK JDK/JRE 11 - 64 bits

CloudBees Jenkins Platform versions prior to 2.332.1.4*

Table 1. CloudBees Jenkins Platform versions prior to 2.332.1.4
Component Supported Java version

Operations center

Java 8

Controller and agents

Java 8

Operations center shared agents

Java 8

CloudBees Jenkins Platform version 2.332.1.4*

Table 2. CloudBees Jenkins Platform version 2.332.1.4
Component Supported Java version

Operations center

Java 8 and Java 11

Controller and agents

Java 8 and Java 11

Operations center shared agents

Java 8 and Java 11

CloudBees Jenkins Platform (after the September 2022 release)

Table 3. CloudBees Jenkins Platform (post September 2022 release)
Component Supported Java version

Operations center

Java 11

Controller and agents

Java 11

Operations center shared agents

Java 11

As of 2.357.x, CloudBees CI no longer supports Java 8. However, older fixed line releases will continue to support Java 8 until the end of their support windows. CloudBees strongly recommends you update your environment to run on Java 11 to avoid issues with future upgrades.

Action required

CloudBees began supporting mixed-mode JVM usage beginning in the March 2022 release, version 2.332.1.4, and will continue to support it until the Jenkins community releases a Java 11 native LTS version. That update is expected to happen within the July - September 2022 timeframe, allowing you to transition into a supported version of Java, without impacting CloudBees Jenkins Platform operations. CloudBees supports the operations center running Java 11, with controllers running Java 8 or 11 only. Agents must be on the same JVM version as their controller.

Customers using RPM, WAR, or Windows MSI installation files may continue to run Java 8 on versions up to and including the 2.332.1.4 release. However, as this is expected to be the last release that will support Java 8, we urge customers to start migrating to Java 11 environments before it becomes a requirement in future releases.

The CloudBees Jenkins Platform Docker images are built with Java 11 by default. If you use custom build agents, you must ensure that they are upgraded to use Java 11.

You should first update any operations center instances to Java 11 before upgrading controllers and agents. Once the operations center has been updated, you can begin upgrading each controller and its associated agents while operating in a mixed JVM environment.

CloudBees will not support mixed JVM usage in the CloudBees Jenkins Platform fixed line releases. CloudBees anticipates the fixed lines will move to Java 11 in the next year. Customers running in fixed line environments will be required to upgrade their environments to Java 11 when they upgrade to the release that has native support for Java 11.

Upgrading the JVM used to run CloudBees Jenkins Platform

You should keep the following things in mind when upgrading the JVM used to run CloudBees Jenkins Platform.

Operations center instances must be updated to use Java 11 before you can update controllers and their agents. Failure to do so may result in the loss of connectivity between the operations center and controllers using Java 11.

As with any upgrade, CloudBees recommends backing up JENKINS_HOME and testing the upgrade with a backup before performing the upgrade on your production instance.

To upgrade CloudBees Jenkins Platform as well as the JVM, complete the following steps:

  1. Complete the steps in Upgrading CloudBees CI on traditional platforms or Upgrading CloudBees Jenkins Platform.

  2. Complete the steps in Upgrading plugins from the Plugin Manager.

  3. Back up JENKINS_HOME again after upgrading CloudBees Jenkins Platform and any required plugins.

  4. Stop the CloudBees Jenkins Platform instance.

  5. Upgrade the JVM in the environment where CloudBees Jenkins Platform is running. The upgrade process varies by system and your preferences (for example, tar ball, package manager, etc.). Make sure the JVM is the newly updated Java 11.

  6. Update any JVM arguments as documented in JVM recommended arguments.

If you use Docker containers to run CloudBees Jenkins Platform, the default Docker containers are configured with Java 11 beginning in version 2.332.1.4.

Upgrading plugins

In addition to upgrading CloudBees Jenkins Platform and the JVM, you must upgrade any plugins that support Java 11. Plugin upgrades ensure compatibility with the most recent CloudBees Jenkins Platform releases. CloudBees has verified that all plugins in the CloudBees Assurance Program run without issue when using Java 11.

If you discover a previously unreported issue, let us know by contacting CloudBees Support. If the issue involves a Jenkins community plugins, CloudBees reports a Java 11 compatibility issue and can suggest workarounds to avoid a broken plugin.

Monitoring Java versions automatically

The Versions Node Monitors plugin provides detailed Java version monitoring and can detect unsupported JVM versions.

Known issues

Refer to the following sections for any known issues that may affect your migration to Java 11.

Mixed-mode (Java 11 and Java 8) support to end in September 2022

It is expected that the Jenkins LTS on which CloudBees Jenkins Platform is based will begin requiring Java 11 in September 2022. At that time, CloudBees Jenkins Platform will also require Java 11 and running in a mixed JVM environment will no longer be supported. CloudBees strongly recommends that you begin planning your upgrade now, while a mixed JVM is still supported, in order to avoid being forced to upgrade when Java 11 is required.

Java 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 resolve this issue, those libraries are now bundled in a new detached plugin called the JAXB plugin. When CloudBees Jenkins Platform detects that it is running in a Java 11 environment, this plugin is automatically installed. However, if you manage your plugins outside of CloudBees Jenkins Platform (for example, if you use plugins.txt in your Docker images), you may 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 upgrade your CloudBees Jenkins Platform controller to run on Java 11, you must also upgrade the JVM on your agents.

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

JVM version on operations center shared agents

JVM instances are used to establish the remoting connection between shared agents and controllers, as well as shared agents and the operations center. Additional JVMs could be installed on the agent computer and used as build tools by controller jobs. Those JVMs are irrelevant in this context, and there is no need to update them as part of the CloudBees Jenkins Platform Java 11 migration.

Depending on the launch method and agent configuration, you might have to take additional actions when upgrading to Java 11.

"Launch agent by connecting it to the controller" launch method

This launch method is also known as an "inbound" agent. It is the agent initiating the connection to the controller. This configuration also requires the agent computer to initiate the connection to the operations center.

This launch method requires two JVM instances. One maintains the connection to the operations center and it is called the shared agent control JVM. The other connects to the controller when the agent is leased and it is called the agent JVM. These two JVM instances do not need to be running the same JVM version.

When you upgrade the operations center JVM to Java 11, the shared agent control JVM must also be upgraded to run Java 11. If the shared agent is going to be leased to a controller that runs Java 11, the agent JVM must be upgraded to run Java 11 as well.

"Launch build agents via SSH" launch method

This launch method is also known as an "outbound" agent. It means the controller is initiating the connection to the agent computer via SSH and then automatically starting the agent JVM.

There is no shared agent control JVM involved in this configuration. There is only one JVM, the agent JVM. The agent JVM must be updated if the agent is going to be leased to controllers that run Java 11. The path to this JVM binary is configurable in the shared agent configurations.

Java Web Start

Java Web Start was removed in Java 11. When a CloudBees Jenkins Platform controller runs on Java 11, the Java Web Start button no longer appears in the UI. You can’t launch agents for a Java 11 Jenkins server from a *.jnlp file that was downloaded to a web browser.

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

Executing jobs on CloudBees Jenkins Platform

CloudBees Jenkins Platform jobs may be executed on Java versions that differ from the controller/agent runtime’s Java version. Generally, CloudBees Jenkins Platform allows any version of JRE/JDK to be invoked during the build. That includes executing Java commands from the CLI, as well as installing and executing build steps using a JDK managed by JDK tool installers.

There are still Java requirements for particular plugins:

  • Maven Integration plugin: You must configure any builds that use it to use JDK 11 or higher once Java 11 becomes a requirement. For more information, refer to Maven jobs and Java versions compatibility.

  • Swarm plugin: If you use the Swarm plugin to create agents, the JRE version must be equal to the JRE version of the controller.

  • Docker Pipeline plugin: If you use the Docker Pipeline plugin with a bundled JRE/JDK to execute jobs, the bundled Java versions must be equal to the Java version of the controller.

Custom JVM arguments

Some JVM arguments have changed or are no longer supported by Java 11. If you customized the JVM arguments used to start your CloudBees Jenkins Platform operations center, controllers, or agents, you may need to modify them. For more information about the recommended JVM arguments, refer to Adding Java arguments to the Jenkins service configuration file.

Garbage collection logging parameters have changed in Java 11. If you have enabled garbage collection logging on your instance, you must update these parameters or your instance may fail to start. CloudBees recommends removing garbage collection logging, unless you use it specifically to troubleshoot an issue.

For a complete list of JVM arguments that have been removed in Java 11, refer to the following topics: