Upgrading Starter Deployments

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

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

Important:

  • Rolling upgrades of Cluster setups from 3.2 to 3.3 are only supportedfrom versions 3.2.15 and 3.3.9.
  • Rolling upgrades of Cluster setups from 3.3 to 3.4 are only supportedfrom versions 3.3.20 and 3.4.0.

Upgrade Scenarios

The following four cases are possible:

  • You have installed via an installation package (e.g. a .deb or .rpm package)and you will upgrade this installation using again an installation package(e.g. a .deb or .rpm).
  • You have installed via the .tar.gz distribution and you will upgrade thisinstallation using again a .tar.gz distribution.
  • You have installed via an installation package (e.g. a .deb or .rpm package)and you will upgrade this installation using a .tar.gz distribution.
  • You have installed via the .tar.gz distribution and you will upgrade thisinstallation using an installation package (e.g. a .deb or .rpm package).Cases 1. and 2. are more common, though cases 3. and 4. are also possible.

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 orcluster 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

  1. apt install arangodb=3.3.14

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

  1. dpkg -i arangodb3-3.3.14-1_amd64.deb

after you have downloaded the corresponding file fromwww.arangodb.com/download/.

If you are using the .tar.gz distribution (only available from v3.4.0),you can simply extract the new archive in a differentlocation and keep the old installation where it is. Note thatthis does not launch a standalone instance, so the following section canbe skipped in this case.

Stop the Standalone Instance

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

  1. service arangodb3 stop

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

  1. 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 noarangod processes should be stopped.

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

  1. kill -9 <pid-of-starter>

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

  1. 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 followingrestart of all _arangodb processes.

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

  1. ps -C arangodb -fww
  2. UID        PID  PPID  C STIME TTY          TIME CMD
  3. max      29419  3684  0 11:46 pts/1    00:00:00 arangodb --starter.data-dir=./db1
  4. max      29504  3695  0 11:46 pts/2    00:00:00 arangodb --starter.data-dir=./db2 --starter.join 127.0.0.1
  5. 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 happen automatically. In casethe Starter was initiated manually, the arangodb processes have to be restartedmanually with the same command that has been used before.

If you are using the .tar.gz distribution (only available from v3.4.0),your new version of the executable might be located in adifferent directory. Make sure that you now start the new Starter_executable (bin/arangodb) in the new installation place. If you areusing a supervisor like _SystemD, you might have to adjust the path tothe executable in the service description to the new location. Do thisbefore you kill -9 the Starter or else the old version will berestarted in this case. If you forgot, simply do the kill -9 again.

After you have restarted the Starter you will find yourself in the followingsituation:

  • 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 theold version

Start the upgrade process of all arangod & arangosync servers

Run the following command for any of the starter endpoints (e.g. http://localhost:8528) to upgrade the entire cluster:

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

Note: if you have connected clusters across multiple datacenter, you need to update each of the clusters.

Important:

The command above was introduced with 3.3.14 (and 3.2.17). If you are rolling upgrade a 3.3.x versionto a version higher or equal to 3.3.14, or if you are rolling upgrade a 3.2.x version to a version higheror 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):

  1. 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 possibleand when that all succeeds, create an upgrade plan. This plan is thenexecuted by every Starter.

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

Uninstall old package

This step is required in the cases 2., 3. and 4. only. It is not requiredin case 1., see Upgrade Scenarios above.

After verifying your upgraded ArangoDB system is working, you can removethe old package. This can be done in different ways, depending on the caseyou are:

  • Cases 2. and 4.: just remove the old directory created by the .tar.gz(assumes your —starter.data-dir is located outside of thisdirectory - which is a recommended approach).
  • Case 3.: just remove the old package by running the correspondinguninstallation command (the exact command depends on whether you areusing a .deb or .rmp package and it is assumed that your—starter.data-dir is located outside of the standard directoriescreated by the installation package - which is a recommended approach).

Retrying a failed upgrade

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

To retry, run:

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

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

Aborting an upgrade

Starting with 3.3.14 and 3.2.17, when an upgrade plan (in deploymentmode activefailover or cluster) is in progress or has failed, it canbe aborted.

To abort, run:

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

The —starter.endpoint option can be set to the endpoint of anyof 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 abortwas issued, this upgrade will be finished. Remaining servers will not beupgraded.