Migrate to Java 21

Java 21 was released on September 19, 2023, as a long-term support (LTS) version. The Jenkins community supports running Jenkins with Java 21 since version 2.426.1 and CloudBees CI supports running in Java 21 since version 2.479.3.1.

To learn how to upgrade from Java 17 to Java 21, watch the following video.

Upgrading CloudBees CI Java Version From 17 to 21

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

CloudBees strongly recommends upgrading CloudBees CI on traditional platforms to use Java 21 as soon as possible. CloudBees CI version 2.479.3.1 supports both Java 21 and Java 17. Java 17 support will be removed in a future release and announced in our release notes at that time.

Supported configurations

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

OpenJDK JDK/JRE 17 - 64 bits
OpenJDK JDK/JRE 21 - 64 bits

CloudBees CI version 2.479.3.1 or later

Table 1. CloudBees CI 2.479.3.1 or later
Component	Supported Java version
Operations center	Java 21 and Java 17
Controller and agents	Java 21 (if and only if the operations center is also running Java 21) and Java 17
Operations center shared agents	Java 21 (if and only if the operations center is also running Java 21) and Java 17

Action required

CloudBees supports mixed-mode JVM usage in CloudBees CI versions starting with 2.479.3.1. This allows you to transition into a supported version of Java without impacting the CloudBees CI operations. Mixed-mode JVM usage is not supported in versions prior to 2.479.3.1.

CloudBees supports the operations center running Java 21, with controllers running only Java 21 or Java 17.

An operations center that runs Java 17 with controllers that run Java 21 is not supported.
All agents must run a Java version at least as new as the currently minimum version required by controllers.

CloudBees recommends that you update them to Java 21

If you use RPM, DEB, or WAR installation files, CloudBees recommends that you upgrade to Java 21 in version 2.479.3.1 or later. You can still continue to run Java 17 but should consider upgrading.

If you use Windows MSI installation files and the installer embedded JVM, you will be automatically upgraded to Java 21. You can still use Java 17 if you change the JRE used to run CloudBees CI according to these instructions.

The CloudBees CI Docker images use Java 21 beginning in version 2.479.3. If you use custom build agents, we recommend that they are upgraded to use Java 21 before upgrading to version 2.479.3.

You should first update any operations center instances to Java 21 before upgrading controllers and agents. After the operations center has been updated, CloudBees recommends that you upgrade the agents, and then upgrade the associated controllers while operating in a mixed JVM environment. If that is not possible due to specific installation constraints, you can first upgrade the controllers and then upgrade the agents.

Upgrade the JVM used to run CloudBees CI

You must keep the following things in mind when you upgrade the JVM used to run CloudBees CI:

Operations center instances must be updated to use Java 21 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 21.
As with any upgrade, CloudBees recommends that you back up JENKINS_HOME and test the upgrade with a backup before you perform the upgrade on your production instance.

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

Complete the steps in Upgrading CloudBees CI on traditional platforms.
Complete the steps in Upgrading plugins from the Plugin Manager.
Back up JENKINS_HOME again after upgrading CloudBees CI and any required plugins.
Stop the CloudBees CI instance.
Upgrade the JVM in the environment where CloudBees CI is running. The upgrade process varies by system and your preferences (for example, tarball, or a package manager). Make sure the JVM is the newly updated Java 21.
Update any JVM arguments, as documented in JVM recommended arguments. If you use Docker containers to run CloudBees CI, the Docker containers provided by CloudBees are configured with Java 21 beginning in version 2.479.3.

Upgrade the plugins

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

If you discover a previously unreported issue, contact CloudBees Support. If the issue involves a Jenkins community plugin, CloudBees will report it and can suggest workarounds to avoid a broken plugin.

Monitor the Java versions automatically

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

JVM version on container images

CloudBees provides the following naming structure for container images:

an image with the -jdk21 suffix indicates Java 21
an image with the -jdk17 suffix indicates Java 17
an image without a suffix is the same as using the -jdk21 suffix

Known issues

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

JVM version on agents

All agents must run a Java version at least as new as the current minimum version required by controllers. CloudBees recommends that you update them to Java 21 as soon as possible.

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 CI 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 CI Java 21 migration.

Depending on the launch method and agent configuration, you may have to take additional actions when you upgrade to Java 21.

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

This launch method is also known as an "inbound" agent. It is the agent that initiates 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 run the same JVM version.

CloudBees recommends that when you upgrade the operations center JVM to Java 21, you also upgrade the shared agent control JVM to run Java 21. If the shared agent is going to be leased to a controller, CloudBees recommends that you upgrade the JVM to Java 21 before the controller runs Java 21. If that is not possible, using Java 17 on the agent and Java 21 on the controller is supported, but CloudBees recommends that you upgrade your agent to Java 21 as soon as possible.

"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. CloudBees recommends that you upgrade the JVM to Java 21 before the controller runs Java 21. If that is not possible, using Java 17 on the agent and Java 21 on the controller is supported, but CloudBees recommends that you upgrade your agent to Java 21 as soon as possible. The path to this JVM binary is configurable in the shared agent configurations.

Execute the jobs on CloudBees CI

CloudBees CI jobs can be executed on Java versions that differ from the controller/agent runtime Java version. Generally, CloudBees CI 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.