Bamboo Remote Agent JVM alignment during server version upgrades

Question

Upgrading a Bamboo server often introduces a new required Java runtime version. While the server is updated, existing remote agents may continue to run on an older JVM, creating a compatibility boundary between the server's communication protocol and the agent's runtime environment.

The primary goal is to maintain agent connectivity and ensure that build capabilities are accurately rediscovered across a distributed fleet without causing registration failures during the transition period.

Since agents discover JDK capabilities at startup, a mismatch between the server's expected version and the agent's current JAVA_HOME can lead to inconsistent job scheduling or total agent disconnection.

What is the specific behavior of the agent-to-server protocol when a remote agent version lags behind the server's minimum supported JVM?
  Does Bamboo support a grace period for mixed-version agent fleets during a Data Center cluster upgrade?

Tasadduq Burney · Answer

Answer
Protocol behaviour: When a Bamboo server’s minimum Java requirement is higher than an agent’s JVM, the initial handshake fails. The server sends the agent’s Java version in the capability payload; if it is lower than the required minimum, the server rejects the connection and the agent is marked incompatible in the UI and logs a warning such as Agent handshake failed: Java version 1.8 < required 11.
Grace period in Data Center upgrades: The Data Center upgrade wizard offers a short mixed‑fleet window. During this phase, agents running older JVMs can still register, but the window ends when the cluster’s upgrade‑mode flag is cleared. After that, any agent whose Java version is below the new minimum is automatically disconnected.
Explanation & Assumptions

Assumes Bamboo 2023.x or later, where the minimum Java version is enforced during handshake.
Assumes the agent runs the standard bamboo-agent.sh or bamboo-agent.bat script with JAVA_HOME pointing to its JVM.
Assumes a Data Center deployment; single‑node upgrades do not provide a mixed‑fleet grace period.

Practical Steps to Keep Agents Online

Verify the server’s required Java version:
# From the Bamboo UI → Administration → Server Settings → Java
# Or via REST: GET /rest/api/latest/server

Check each agent’s reported Java version:
# Bamboo UI → Administration → Agent Management → List agents
# Or REST: GET /rest/api/latest/agent

Update agents that are below the minimum:

Install a newer JDK on the agent host.
Set JAVA_HOME to the new JDK path.
Restart the agent process.

During a Data Center upgrade, enable the mixed‑fleet option:
# In the upgrade wizard, check “Allow existing agents to remain connected during upgrade”
# This flag keeps older agents registered until the wizard completes.

Verify connectivity after the upgrade:
# Bamboo UI: Agent status should be Connected
# Logs: No “handshake failed” entries for the upgraded agents

Missing Diagnostic Detail
To tailor the recommendation precisely, could you confirm the Bamboo server’s current minimum Java requirement (e.g., Java 11, Java 17)?
Common Pitfalls

Agents that remain connected but run an older JVM may lose advanced features (e.g., Java 17‑specific build agents) and may have jobs reassigned.
Some plugins depend on newer Java APIs; running them on an older JVM can cause build failures even if the handshake succeeds.
Never rely on the mixed‑fleet window for long‑term deployments; update all agents before the upgrade completes.

Bamboo Remote Agent JVM alignment during server version upgrades

1 answer

Answer

Explanation & Assumptions

Practical Steps to Keep Agents Online

Missing Diagnostic Detail

Common Pitfalls

Your perspective belongs here.

0 question comments