Upgrading Starter Deployments

    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.

    The following four cases are possible:

    • You have installed via an installation package (e.g. a 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.

    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.

    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

    ( 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 from .

    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:

      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:

      When using a supervisor like SystemD, this will happens 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

      Run the following command for any of the starter endpoints (e.g. ) 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:

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

      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).

      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:

      The —starter.endpoint option can be set to the endpoint of anyof the starters. E.g. .

      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:

        The —starter.endpoint option can be set to the endpoint of anyof the starters. E.g. .