Clustering with Bamboo Data Center

Clustering is designed for enterprises with large or mission-critical Data Center deployments that require continuous uptime and disaster recovery.  Bamboo Data Center allows you to run a cluster of multiple Bamboo nodes, providing high availability and failover. That is, if one node in your cluster goes down, the others take on the load, ensuring minimal interruptions in accessing Bamboo.

On this page:


A Bamboo Data Center consists of a cluster of components, each on a dedicated machine, and connected over a high-speed LAN connection, plus the agents. The following diagram depicts a typical Bamboo Data Center instance:

  • Multiple identical application nodes running the same version of Bamboo Data Center

  • A load balancer to distribute traffic to all of your application nodes

  • A shared file system that stores build results, build logs, artifacts, and other shared files

  • A shared database that all nodes read and write to

Bamboo Data Center supports only one primary node at a time and an unlimited number of secondary nodes ready to take over operations if the primary node goes down. A user will access the same Bamboo node for all requests until their session times out, they log out, or a node is removed from the cluster.

Cluster state replication

The warm standby clustering architecture requires continuous state replication between all nodes in your Data Center cluster. In Bamboo, most of the state replication is based on invalidation events, which indicate the state change that has occurred on a node. Invalidation events don't carry the new data but provide information about which data needs to be refreshed. Nodes use that information to apply the required changes and rectify the state on all nodes (regardless of where the change originated).

For more information on how this works, see Cluster state replication.

Cluster and node lifecycle states

The Bamboo Data Center warm standby architecture supports different lifecycle states. Some of them are related to the cluster as a whole and others are specific only to individual nodes. These states are used mostly internally but can give you an idea of the health of your cluster.

For more information about lifecycle states, see Cluster and node lifecycle states.

Infrastructure and requirements

Each component has specific requirements. However, only the load balancer must have a publicly accessible URL. Both user and agent traffic should go through the load balancer. The remaining machines don't need to be publicly accessible. The choice of hardware and infrastructure is up to you.

Below are some areas to think about when planning your hardware and infrastructure requirements:


You shouldn't run additional applications (other than core operating system services) on the same servers as Bamboo. Running Bamboo, Bitbucket, and Jira on a dedicated Atlassian software server works well for small installations but is discouraged when running at scale. 

Bamboo Data Center can run successfully on virtual machines.

Cluster nodes

Each node does not need to be identical, but for consistent performance, we recommend they are as close as possible. All cluster nodes must:

  • be a dedicated machine, physical or virtual

  • be located in the same data center, or region (for AWS and Azure)

  • be connected to a high-speed LAN (that is, high bandwidth and low latency)

  • run the same versions of the operating system, Java, and Bamboo Data Center (See Supported platforms)

  • have the same memory configuration (both the JVM and the physical memory) (recommended)

  • have synchronized time zones and clocks (using ntpd or a similar service is a good way to ensure this)

 You must ensure the clocks on your nodes don't diverge, as it can result in a range of problems with your cluster.

Your Data Center license does not restrict the number of nodes in your cluster. The right number of nodes depends on the size of your Bamboo instance, and the size of your nodes.


Just like a single-node Data Center deployment, you'll need an external production database.

The database:

  • must be officially supported (see Supported platforms)
  • must run on a dedicated machine
  • must be shared with all nodes in the cluster through a high-speed LAN connection in the same physical data center

Shared home and storage

Bamboo Data Center requires a high-performance shared file system such as a SAN, NAS, RAID server, or high-performance file server optimized for I/O. 

The shared file system:

  • must run on a dedicated machine.

  • must be available to all cluster nodes through a high-speed LAN (it must be in the same physical data center). 

Load balancer

Bamboo Data Center doesn't bundle a load balancer, so you can use the load balancer of your choice. If you don't have a particular preference or policy for load balancers, you can use HAProxy, which is a popular open-source load balancer. For more information, go to Configuring the HAProxy load balancer.

The load balancer:

  • should run on a dedicated machine

  • must have a high-speed LAN connection to the Bamboo cluster nodes (that is, high bandwidth and low latency)

  • must support both HTTP mode for web traffic and TCP mode for remote agents ActiveMQ traffic

  • should support session affinity (also known as "sticky sessions")
  • should have SSL termination enabled to improve performance

Many load balancers require a URL to constantly check the health of their backends in order to automatically remove them from the pool. It's important to use a stable and fast URL for this, but lightweight enough to not consume unnecessary resources. The following URL returns Bamboo’s status and can be used for this purpose. 

URLExpected HTTP status
http://<BAMBOO_URL>/rest/api/latest/status200 OK

Only the primary node returns the 200 status code. All secondary nodes always return the 503 status code. So, with a warm standby configuration, you should route the traffic only to the primary node, which returns the 200 status code. 

HTTP status code (primary node/secondary nodes)ResponseDescription
200 OK{"status": "RUNNING"}The primary node is running normally.
503  Service Unavailable{“status”: "RUNNING_AS_SECONDARY"}The secondary node is running normally.
200 OK/503 Service Unavailable{"status": "STARTING"}The node is starting.
200 OK/503 Service Unavailable{"status": "PAUSING"}The cluster is pausing and transitioning to the “PAUSED” state
200 OK/503 Service Unavailable{"status": "PAUSED"}The cluster is paused.
200 OK/503 Service Unavailable{“status”: "PREPARING_FOR_RESTART"}The node is preparing for a restart and transitioning to the “READY_FOR_RESTART” state.
200 OK/503 Service Unavailable{“status”: "READY_FOR_RESTART"}The node is ready to be restarted.
tip/resting Created with Sketch.

To maintain smooth caching and reduce unnecessary load on the server when using a load balancer that filters headers, configure your load balancer to pass the "If-Modified-Since" header from the client browser to Bamboo nodes. This header is essential for efficient caching and optimized resource retrieval. Without it, your servers might unnecessarily transmit unchanged resources, impacting performance.

If you're using a proxy such as nginx with caching enabled, disable caching just for the avatar REST endpoints (/rest/api/latest/avatar/*) to prevent the proxy from returning outdated avatars. Bamboo handles avatar image caching on its own.

Network adapters

Use separate network adapters for communication between servers. Cluster nodes should have a separate physical network (i.e. separate NICs) for inter-server communication. This is the best way to get the cluster to run fast and reliably. Performance problems are likely to occur if you connect cluster nodes over a network that has lots of other data streaming through it. 

App compatibility

The process for installing Marketplace apps (also known as add-ons) in a Bamboo cluster is the same as for a standalone installation. You will not need to stop the cluster or bring down any nodes to install or update an app. 

The Atlassian Marketplace indicates apps that are compatible with Bamboo Data CenterLearn more about Data Center approved apps

Last modified on Feb 8, 2024

Was this helpful?

Provide feedback about this article
Powered by Confluence and Scroll Viewport.