Upgrading Starter Deployments

Starting from versions 3.2.15 and 3.3.8, the ArangoDB Starter supports a new, automated, procedure to perform upgrades, including rolling upgrades of a Cluster setup.

The upgrade procedure of the Starter described in this Section can be used to upgrade to a new hotfix, or to perform an upgrade to a new minor version of ArangoDB. Please refer to the Upgrade Paths section for detailed information.

Important: rolling upgrades of Cluster setups from 3.2 to 3.3 are only supported from versions 3.2.15 and 3.3.9.

Upgrade Procedure

The following procedure has to be executed on every ArangoDB Starter instance. It is assumed that a Starter deployment with mode single, activefailover or cluster is running.

Install the new ArangoDB version binary

Installing the new ArangoDB version binary also includes the latest ArangoDB Starter binary, which is necessary to perform the rolling upgrade.

The first step is to install the new ArangoDB package.

Note: you do not have to stop the Starter processes before upgrading it.

For example, if you want to upgrade to 3.3.14-1 on Debian or Ubuntu, either call

apt install arangodb=3.3.14

(apt-get on older versions) if you have added the ArangoDB repository. Or install a specific package using

dpkg -i arangodb3-3.3.14-1_amd64.deb

after you have downloaded the corresponding file from https://download.arangodb.com/.

Stop the Standalone Instance

As the package will automatically start the standalone instance, you might want to stop it now, as otherwise this standalone instance that is started on your machine can create some confusion later. As you are using the Starter you do not need this standalone instance, and you can hence stop it:

service arangodb3 stop

Also, you might want to remove the standalone instance from the default runlevels to prevent it to start on the next reboot of your machine. How this is done depends on your distribution and init system. For example, on older Debian and Ubuntu systems using a SystemV-compatible init, you can use:

update-rc.d -f arangodb3 remove

Stop the Starter without stopping the ArangoDB Server processes

Now all the Starter (arangodb) processes have to be stopped.

Please note that no arangod processes should be stopped.

In order to stop the arangodb processes, leaving the arangod processes they have started up and running (as we want for a rolling upgrade), we will need to use a command like kill -9:

kill -9 <pid-of-starter>

The pid associated to your Starter can be checked using a command like ps:

ps -C arangodb -fww

The output of the command above does not only show the PID's of all arangodb processes but also the used commands, which can be useful for the following restart of all arangodb processes.

The output below is from a test machine where three instances of a Starter are running locally. In a more production-like scenario, you will find only one instance of arangodb running:

ps -C arangodb -fww
UID        PID  PPID  C STIME TTY          TIME CMD
max      29419  3684  0 11:46 pts/1    00:00:00 arangodb --starter.data-dir=./db1
max      29504  3695  0 11:46 pts/2    00:00:00 arangodb --starter.data-dir=./db2 --starter.join 127.0.0.1
max      29513  3898  0 11:46 pts/4    00:00:00 arangodb --starter.data-dir=./db3 --starter.join 127.0.0.1

Restart the Starter

When using a supervisor like SystemD, this will happens automatically. In case the Starter was initiated manually, the arangodb processes have to be restarted manually with the same command that has been used before.

After you have restarted the Starter you will find yourself in the following situation:

  • The Starter is up and running, and it is on the new version
  • The ArangoDB Server processes are up and running, and they are still on the old version

Start the upgrade process of all arangod & arangosync servers

Run the following command:

arangodb upgrade --starter.endpoint=<endpoint-of-a-starter>

The --starter.endpoint option can be set to the endpoint of any of the starters. E.g. http://localhost:8528.

Important:

The command above was introduced with 3.3.14 (and 3.2.17). If you are rolling upgrade a 3.3.x version to a version higher or equal to 3.3.14, or if you are rolling upgrade a 3.2.x version to a version higher or equal to 3.2.17 please use the command above.

If you are doing the rolling upgrade of a 3.3.x version to a version between 3.3.8 and 3.3.13 (included), or if you are rolling upgrade a 3.2.x version to 3.2.15 or 3.2.16, a different command has to be used (on all Starters one by one):

curl -X POST --dump - http://localhost:8538/database-auto-upgrade

Deployment mode single

For deployment mode single, the arangodb upgrade command will:

  • Restart the single server with an additional --database.auto-upgrade=true argument. The server will perform the auto-upgrade and then stop. After that the Starter will automatically restart it with its normal arguments.

The arangodb upgrade command will complete right away. Inspect the log of the Starter to know when the upgrade has finished.

Deployment mode activefailover or cluster

The Starters will now perform an initial check that upgrading is possible and when that all succeeds, create an upgrade plan. This plan is then executed by every Starter.

The arangodb upgrade command will show the progress of the upgrade and stop when the upgrade has either finished successfully or finished with an error.

Retrying a failed upgrade

Starting with 3.3.14 and 3.2.17, when an upgrade plan (in deployment mode activefailover or cluster) has failed, it can be retried.

To retry, run:

arangodb retry upgrade --starter.endpoint=<endpoint-of-a-starter>

The --starter.endpoint option can be set to the endpoint of any of the starters. E.g. http://localhost:8528.

Aborting an upgrade

Starting with 3.3.14 and 3.2.17, when an upgrade plan (in deployment mode activefailover or cluster) is in progress or has failed, it can be aborted.

To abort, run:

arangodb abort upgrade --starter.endpoint=<endpoint-of-a-starter>

The --starter.endpoint option can be set to the endpoint of any of the starters. E.g. http://localhost:8528.

Note that an abort does not stop all upgrade processes immediately. If an arangod or arangosync server is being upgraded when the abort was issued, this upgrade will be finished. Remaining servers will not be upgraded.