Upgrade a Bitbucket cluster through the API without downtime



アトラシアン コミュニティをご利用ください。


このドキュメントでは、API 呼び出しを使用してローリング アップグレードを開始および確定する方法について説明します。このアップグレード方法は、メンテナンス タスク (アップグレードなど) を調整するためのスキルと自動化ツールを持つ管理者に適しています。

tip/resting Created with Sketch.

For an overview of rolling upgrades (including planning and preparation information), see Upgrade Bitbucket without downtime.


API のリファレンス

ローリング アップグレード プロセス全体は、次の API によって管理されます。


この API では、次の呼び出しを使用します。

GET /rest/zdu/cluster

アップグレード モードを有効化します。
Get an overview of a node's status.
アップグレード モードを無効化します。このコールは、アップグレードの進捗が MIXED でない場合にのみ使用できます。

すべてのノードがアップグレードされたら、ローリング アップグレードを終了します。これにより、アップグレード モードが無効化されます。

For detailed information about each API call, see Bitbucket REST API Documentation.

Authenticating REST API calls

In a secure environment, you'll need to authenticate your REST API calls. See Personal access tokens and Bitbucket Server REST API Example - Basic Authentication for more information.

Downloading upgrade files

Before you start the upgrade, download the right Bitbucket version first. You'll be installing this on each node. Remember, you can only upgrade to a higher bug fix version (for example, from Bitbucket 7.9.0 to 7.9.4). Download the file directly from here:


Alternatively, you can also use the Pre-upgrade planning tool to help you download a compatible bug fix version. Choose   > Administration > Plan your upgrade to open the tool.

ローリング アップグレードの開始

ローリング アップグレードを開始するには、最初にローリングアップ グレードを有効にします。これを行うには、次のものを使用します。


Enabling upgrade mode allows your cluster to accept nodes running a later bug fix version. This lets you upgrade one node and let it rejoin the cluster (along with the other non-upgraded nodes). Both upgraded and non-upgraded active nodes work together in keeping Bitbucket available to all users.

まだノードをアップグレードしていない場合、アップグレード モードを無効化できます。


In general, upgrading a node during a rolling upgrade consists of four phases:

Disconnecting the node from the load balancer
tip/resting Created with Sketch.


We recommend that you start upgrading the node with the least number of running tasks and active users. This will typically be the node with the lowest amount of CPU usage. 

When you disconnect a node from the load balancer, user requests will no longer be routed to the node. The following table provides guidance how to do so for popular load balancers:


NGINX defines groups of cluster nodes through the upstream directive . To prevent the load balancer from connecting to a node, delete the node's entry from its corresponding upstream group. Learn more about the upstream directive in the ngx_http_upstream_module module


HAProxy で、ノードへのトラフィックをすべて無効にするには、maint 状態にします。

set server <node IP or hostname> state maint

Learn more about forcing a server's administrative state


You can disable a node (or "worker") by setting its activation member attribute to disabled. Learn more about advanced load balancer worker properties in Apache

Azure アプリケーション ゲートウェイ

We provide a deployment template for Bitbucket Data Center on Azure; this template uses the Azure Application Gateway as its load balancer. The Azure Application Gateway defines each node as a target within a backend pool. Use the Edit backend pool interface to remove your node's corresponding entry. Learn more about adding (and removing) targets from a backend pool

Shutting down Bitbucket gracefully on the node

With upgrade mode enabled, you can now upgrade your first node. Start by shutting down Bitbucket gracefully on the node:

  1. コマンド ラインまたは SSH からノードにアクセスします。

  2. Shut down Bitbucket gracefully on the node. This will provide Bitbucket with some time to finish all of its tasks first before going offline. If you installed Bitbucket manually, run the bin/stop-bitbucket.sh script to gracefully shut down Bitbucket. Learn more about gracefully shutting down Bitbucket

  3. ノードがオフラインになるまで待ちます。[ローリング アップグレード] ページの [クラスタ概要] セクションの [ノード ステータス] 列でステータスを監視できます。

Extracting the downloaded files into a new directory

Once the node’s status is offline, you can start upgrading the node. Copy the Bitbucket files you downloaded (from Downloading upgrade files section) to the node’s local file system:

1 つ目のノードをアップグレードするには:
  1. Extract the files to a directory. This will be your new installation directory and it must be different from your existing installation directory.
  2. Update the value of BITBUCKET_HOME in the <Installation-directory>/bin/set-bitbucket-home.sh file so the new Bitbucket installation points to your existing Bitbucket home directory.

    If you’re using a BITBUCKET_HOME environment variable to specify the home directory location, no change is required.

  3. Copy any other immediately required customizations from the old version to the new one. For example, if you aren’t running Bitbucket on the default ports or if you’re managing users externally, you'll need to update or copy the relevant files.

    If you’ve configured Bitbucket to run as a Linux service, don't forget to update its service configuration as well. Learn more about running Bitbucket as a Linux service

  4. Start Bitbucket on the node. Learn more about starting Bitbucket

Why doesn’t Bitbucket search work after the upgrade?

When you’re starting up your Bitbucket Data Center instance after the upgrade, the bundled search server won’t run. Instead, the remote search will be started.

This happens because Data Center instances use the remote search, not the bundled search.

During the upgrade, the --no-search flag is inserted in the /etc/init.d/atlbitbucket file. This flag allows running the remote search but blocks the bundled search.

Reconnecting the node to the load balancer

After Bitbucket starts successfully on the node, reconnect it to the load balancer. This will allow the node to rejoin the cluster. As soon as the first upgraded node joins the cluster, your cluster status will transition to Mixed. This means that you won’t be able to disable Upgrade mode until all nodes are running the same version.

Finalizing the rolling upgrade

Once all nodes are upgraded, finalize the rolling upgrade. To do this, use:


This call will automatically disable upgrade mode.

After completing the rolling upgrade, you should:

ノード ステータス



ACTIVEBitbucket is connected to the cluster and running with no errors. 
STARTINGBitbucket is still loading, and should transition to Active once finished.
TERMINATINGBitbucket was gracefully shut down, and should transition to Offline once finished.
OFFLINEBitbucket is not responding on the node. This node will be removed from the cluster completely if it is still offline after Upgrade mode is disabled.
エラーSomething went wrong with Bitbucket on the node.

クラスタ ステータス



STABLEアップグレード モードをオンにできます。 

アップグレード モードは有効ですが、まだアップグレードされたノードはありません。最初のノードのアップグレードを開始できます。 

mixedAt least one node is upgraded, but you haven't finished upgrading all nodes yet. Your cluster has nodes running different Bitbucket versions. You need to upgrade all nodes to the same bug fix version to transition to the next status (READY_TO_RUN_UPGRADE_TASKS)

すべてのノードがアップグレード済みです。ローリング アップグレードを完了できます。



ローリング アップグレード中のノード エラー

If a node’s status transitions to Error, it means something went wrong during the upgrade. You can’t finish the rolling upgrade if any node has an Error status. However, you can still disable Upgrade mode as long as the cluster status is still Ready to upgrade.


  • Shut down Bitbucket gracefully on the node. This should disconnect the node from the cluster, allowing the node to transition to an Offline status.

  • If you can’t shut down Bitbucket gracefully, shut down the node altogether.

すべてのアクティブ ノードがアップグレードされたら、ローリング アップグレードを完了できます。問題のあるノードの問題を後で調査し、エラーに対処したら、クラスタに再接続できます。

Disabling upgrade mode

You can disable Upgrade mode as long as all nodes in the cluster:
  • まだアップグレードされていない
  • エラー状態になっている

アップグレードされたノードがクラスタに参加するか、ノードがエラー状態になると、クラスタのステータスは Mixed に変わります。 

アップグレード モードが無効になっている Mixed ステータス

アップグレード モードが無効のノードが Error 状態の場合、アップグレード モードを有効にすることはできません。問題を修正するか、クラスタからノードを削除して、アップグレード モードを有効にします。 

最終更新日: 2023 年 10 月 10 日


Powered by Confluence and Scroll Viewport.