Java 17 was released on September 14, 2021, as a long-term support (LTS) version. The Jenkins community supports running Jenkins with Java 17 since 2.361.1 and CloudBees CI supports running in Java 17 since version 2.440.1.3. When the Jenkins community moves to support Java 17-specific features (Java 17 byte code), you will not be able to use a Java 11 runtime environment. Because CloudBees CI is based on the Jenkins LTS, future releases of CloudBees CI will have the same requirement.
For more information about the JVM support model, refer to Migrating to Java 17.
To learn how to upgrade from Java 11 to Java 17, watch the following video.
CloudBees has validated the core functionality and all plugins in the CloudBees Assurance Program work correctly when using Java 17. 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 17 as soon as possible. Starting in release 2.440.1.3, CloudBees CI supports both Java 17 and Java 11 until the Jenkins community releases an LTS that requires Java 17 or higher (in late 2024).
Supported configurations
CloudBees performs full test flows with the following supported JDKs or JREs:
-
OpenJDK JDK/JRE 11 - 64 bits
-
OpenJDK JDK/JRE 17 - 64 bits
CloudBees CI version 2.440.1.3 and onward
| Component | Supported Java version |
|---|---|
Operations center |
Java 17 and Java 11 |
Controller and agents |
Java 17 (if and only if Operations center is also running Java 17) and Java 11 |
Operations center shared agents |
Java 17 (if and only if Operations center is also running Java 17) and Java 11 |
| CloudBees Jenkins Platform will continue to support only Java 11 until the end of the support window. |
Action required
CloudBees supports mixed-mode JVM usage beginning in the February 2024 release (version 2.440.1.3) and will continue to support it until a late 2024 release. This lets you transition into a supported version of Java without impacting the CloudBees CI operations. CloudBees supports the operations center running Java 17, with controllers running only Java 17 or Java 11. An operations center that runs Java 11 with controllers that run Java 17 is not supported. All agents must run a Java version at least as new as the currently minimum version required by controllers. We recommend that you update them to Java 17 as soon as possible, as any agent that uses a Java version below 17 will stop working in late 2024.
We recommend that customers who use RPM, DEB, or WAR installation files upgrade to Java 17 after the February release (version 2.440.1.3). They can choose to continue to run Java 11 until support for Java 11 ends in late 2024.
Customers who use the Windows MSI installation files will be automatically upgraded to Java 17 if they use the installer embedded JVM. They can still use Java 11 if they change the JRE used to run CloudBees CI according to these instructions. However, since support for Java 11 will end in late 2024, we urge customers to migrate to Java 17 environments before it is a requirement later in 2024. Customers who use the Windows MSI installation files will be automatically upgraded to Java 17 unless they have customized the Java path used by CloudBees CI.
The CloudBees CI Docker images use Java 17 beginning in the February 2024 release (version 2.440.1.3). If you use custom build agents, you must ensure that they are upgraded to use Java 17 before it is a requirement later in 2024.
| You should first update any operations center instances to Java 17 before upgrading controllers and agents. After the operations center has been updated, we recommend you upgrade the agents and then the associated controllers while operating in a mixed JVM environment. If that is not possible due to specific installation constraints then first upgrading controllers and then the agents is also supported. |
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 17 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 17.
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 or Upgrading CloudBees Jenkins Platform.
-
Complete the steps in Upgrading plugins from the Plugin Manager.
-
Back up
JENKINS_HOMEagain 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, tar ball, package manager, etc.). Make sure the JVM is the newly updated Java 17.
-
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 17 beginning in version 2.440.1.3.
Upgrade the plugins
In addition to upgrading CloudBees CI and the JVM, you must upgrade any plugins to support Java 17. 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 17.
| 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.
Known issues
Refer to the following sections for any known issues that may affect your migration to Java 17.
CloudBees DevOptics Installation plugin
The old versions of DevOptics will prevent your operations center or controller from starting if you try to run Java 17. You must remove the CloudBees DevOptics Installation plugin, if it is installed, before you upgrade to CloudBees CI 2.440.1.3.
JVM version on agents
All agents must run a Java version at least as new as the currently minimum version required by controllers. We recommend that you update them to Java 17 as soon as possible, as any agent using a Java version below 17 will stop working in late 2024.
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 17 migration.
Depending on the launch method and agent configuration, you may have to take additional actions when you upgrade to Java 17.
"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.
We recommend that when you upgrade the operations center JVM to Java 17, the shared agent control JVM is also upgraded to run Java 17. If the shared agent is going to be leased to a controller, we recommend you upgrade the JVM to Java 17 before the controller runs Java 17. If that is not possible, using Java 11 on the agent and Java 17 on the controller is supported, but we recommend you upgrade your agent to Java 17 as soon as possible. All agents must migrate to Java 17 in late 2024.
"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. We recommend you upgrade the JVM to Java 17 before the controller runs Java 17. If that is not possible, using Java 11 on the agent and Java 17 on the controller is supported, but we recommend you upgrade your agent to Java 17 as soon as possible. All agents must migrate to Java 17 before late 2024. 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’s 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.
There are still Java requirements for particular plugins:
-
Maven Integration plugin: You must configure any builds that use it to use JDK 17 or higher once Java 17 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.
Custom JVM arguments
Some JVM arguments have changed or are no longer supported by Java 17. If you customized the JVM arguments used to start your CloudBees CI 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.