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
apt install arangodb=3.3.14
(apt-get
on older versions) if you have added the ArangoDB repository. Orinstall a specific package using
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:
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:
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
:
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 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:
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 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:
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):
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 then executed 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 this directory - 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:
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:
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.