Upgrading Bamboo Data Center

This guide applies to Bamboo Data Center running in a cluster. Upgrading Bamboo to the next version will incur a downtime.

Plan your upgrade

1. Check upgrade requirements

Make sure your environment meets the minimum requirements to run the desired version of Bamboo Data Center. To ensure your instance works correctly after the upgrade, see the latest End of support announcements.

You can update any version of Bamboo Data Center to the latest version, as there is no required upgrade path.

Learn more about migrating to Bamboo Data Center

If you're planning to migrate from Bamboo Server to Bamboo Data Center, remember to:

• Check the infrastructure and hardware requirements described in Clustering with Bamboo Data Center.

• Get familiar with Migrating Bamboo 7.X.X to Bamboo 8.X.X and read about Bamboo home migration.

2. Complete pre-upgrade checks

1. See the Bamboo release notes and Version specific upgrade notes for the version you plan to upgrade to (and any in between).

2. Go to Administration  > Troubleshooting and support tools, then review the Log analyzer for any issues that may need to be resolved.

3. Check the compatibility of your apps with the version of Bamboo Data Center you plan to upgrade to.

   1. Go to Administration  > Manage apps > Bamboo update check.

   2. Select the version you plan to upgrade to, then select Check.

      If your apps are incompatible

      If your users rely on particular apps, you may want to wait until the apps are compatible with the desired version of Bamboo Data Center.

4. Make sure that all important builds are finished before the upgrade. A new Bamboo Data Center version might not be able to process old build results or complete the old builds successfully.

3. Upgrade in a test environment

Before you upgrade Bamboo Data Center to the next major or minor version, perform the upgrade in a test environment first:

1. Create a staging copy of your current production environment.

2. Follow the upgrade steps below.

3. If possible, test any unsupported apps, customizations, and proxy configuration.

Upgrade Bamboo Data Center

1. Stop the cluster

Before you upgrade, you need to stop all the nodes in the cluster. Start with all your non-primary nodes, so they won’t try to take over after you stop the primary node.

If you run Bamboo as a Windows service, uninstall the service by using the UninstallService.bat executable from Bamboo binaries.

Configure your load balancer to redirect the traffic away from Bamboo until the upgrade is complete on all nodes. Your router settings shouldn't allow agents and user traffic until all nodes are updated and confirmed operational.

2. Back up your data

Export your database

Use native database tools to create a backup. For more information about external databases, see Connect Bamboo to an external database.

Back up your configuration

Create a backup for <bamboo-home> directories from each node as well as the <bamboo-shared-home> directory. At the bare minimum, you should back up:

• bamboo.cfg.xml and cluster-node.properties from <bamboo-home> on each node.

• all content of the configuration directory from <bamboo-shared-home>.

3. Download Bamboo Data Center

Download the appropriate file for your operating system from our software download page.

4. Upgrade the first node

A. Install a new instance

To upgrade, you need to install a new Bamboo Data Center instance in a <bamboo-install> directory that's different from the original instance's installation directory.

B. Configure the new instance

Set home directories

Set the <bamboo-home> and <bamboo-shared-home> to use the same paths as the original Bamboo instance:

1. Go to the new instance's <bamboo-install> directory

2. Open atlassian-bamboo/WEB-INF/classes/bamboo-init.properties 

3. Set the bamboo.home variable to use the <bamboo-home> path of the original instance

4. Set the bamboo.shared.home variable to use the <bamboo-shared-home> path of the original instance

Install a JDBC driver

If the JDBC driver for your database isn't bundled with Bamboo, you need to install it for the new Bamboo instance yourself. See Connect Bamboo to an external database for detailed instructions.

Migrate the existing configurations to your new Bamboo installation

If you've modified any properties in the configuration files of your existing Bamboo installation, make the same modifications in your new installation. Note that you can't simply copy the configuration files from the existing installation and replace the equivalent files in your new installation, because the properties in the configuration files may have changed between versions.

For each file you've modified in your existing Bamboo installation, you need to manually edit each equivalent file in your new Bamboo installation and re-apply your modifications.

The table below lists the most commonly modified files and their locations within your Bamboo installation directory.

Check database access permission

Before you start the new Bamboo instance, make sure that it has the write access to the database, which is required to complete the upgrade tasks.

C. Start Bamboo

Start the new Bamboo instance and wait for the upgrade to finish. You can check whether the upgrade was successful in the atlassian-bamboo.log file.

Don’t reconfigure your load balancer yet. Traffic to Bamboo should be restored only after all nodes are updated and confirmed operational.

Upgrading Bamboo may require reindexing. Depending on the number of existing builds and tests, the reindexing process may take a significant amount of time, during which Bamboo won't be available.

D. Update any installed apps

If you installed any apps in addition to the pre-installed system apps:

• Check if all apps are compatible with the new version of Bamboo.

• Update any apps that are out of date.

• Disable any apps that are incompatible with the new version of Bamboo.

5. Install Bamboo on remaining nodes

The next step is replicating your upgraded Bamboo directories to other nodes in the cluster.  

1. Stop Bamboo on the first node.

2. Install the new Bamboo version on the next node the same way you did on the first node.

   1. Make sure to use <bamboo-home> and <bamboo-shared-home> specific to the node.

   2. You don’t need to update installed apps again.

   3. You can copy any modified configuration files from the first node.

3. Start Bamboo and confirm that everything works as expected.

4. Stop Bamboo on this node before continuing with the next node. 

Repeat this process for each remaining node. 

6. Start Bamboo

Once all nodes have been upgraded, you can start Bamboo Data Center on each node, one at a time. Then, restore your load balancer configuration to direct agents and user traffic to Bamboo.

Automatic update of remote agents

Most of the time, remote agents are updated automatically. Remote agents detect when a new version is available and download new classes from the server.

For more information, see Bamboo remote agent installation guide.

Troubleshooting

If you followed the documentation and still experience problems with the upgrade process:

• Check the How to upgrade/migrate Bamboo article in the Bamboo Knowledge Base.

• Check other Knowledge Base articles.

• Ask questions at https://answers.atlassian.com.

• Create a support ticket. To help us address the issue, attach the atlassian-bamboo.log file to the ticket.