Standard Database upgrade

Upgrade your Aerospike Database cluster to gain access to the latest features and bug fixes. A rolling upgrade, the standard cluster upgrade process, involves upgrading one server node at a time and results in no downtime for the cluster. See Special upgrades and downgrades for important upgrade information relevant to specific versions.

Mixed versions

Aerospike supports mixed-version clusters for rolling upgrades. However, we do not recommend long term use of clusters with nodes running different versions of the Aerospike database.

Download the server package

• Manually download the server package from the Aerospike Downloads page.

• Read the release notes for the version you are downloading.

• You can automate server version downloads from the artifact repository. See the FAQ on downloads for details.

• Base URL:

  https://download.aerospike.com/artifacts/aerospike-server-VERSION/SERVER-VERSION/

Download the server package and transfer it to the node. The name of the server package varies by version.

Note

Linux distributions that use Red Hat packages must use the appropriate Red Hat Enterprise Linux compatible version. See Install Aerospike on Linux.

Database 6.2 and later

Starting with Database 6.2, which introduced support for ARM64, the server packages use the following naming convention:

aerospike-server-EDITION_VERSION_tools-TOOLS-VERSION_DISTRO_ARCHITECTURE.tgz

edition: community, enterprise, federal

version: 6.2.0.0

distro: debian10, debian11, debian12, ubuntu18.04, ubuntu20.04, ubuntu24.04,el7, el8, el9, amzn2023

architecture: x86_64, aarch64 based on uname -m

Database earlier than 6.2

In Database versions earlier than 6.2, Aerospike was intended to run only on Linux distributions and the x86_64 architecture.

aerospike-server-EDITION-VERSION-DISTRO.tgz

edition: community, enterprise, federal

version: 6.1.0.3

distro: debian10, debian11, ubuntu18.04, ubuntu20.04, ubuntu24.04, el7, el8

---

Stop the Aerospike service

Tip

It is good practice to quiesce a node prior to shutting it down or removing it from an Aerospike Enterprise cluster. See Quiesce a node for details.

Stop the Aerospike service as follows:

# On systemd Linux distributions
sudo systemctl stop aerospike

# On System V Linux distributions
sudo /etc/init.d/aerospike stop

Caution

If your server contains any in-memory namespaces without persistence (storage-engine memory), you must wait for migrations to complete before continuing to the next node to prevent data loss. See Monitoring migrations for more information.

Extract the server and tools package

To extract the contents of the package, run the following:

tar -xvf aerospike.tgz

You may need to delete the older version of Aerospike if you upgrade from a version prior to 3.3.x. To remove the packages, search for the old versions of aerospike-VERSION-server and aerospike-VERSION-tools.

For RPMs:

sudo rpm -qa | grep aerospike
sudo rpm -e RPM_NAME

For Debian packages:

sudo dpkg -l | grep aerospike
sudo dpkg -r DPKG_NAME

Install the new packages

Database 6.2 and later

Debian format

aerospike-server-EDITION_VERSION-1DISTRO_ARCHITECTURE.deb
aerospike-tools_VERSION-[commit]DISTRO_ARCHITECTURE.deb

edition: community, enterprise, federal

version: 6.2.0.0

distro: debian10, debian11, ubuntu18.04, ubuntu20.04

architecture: amd64, arm64 based on dpkg-architecture -qDEB_HOST_ARCH

sudo dpkg -i aerospike-server-enterprise_6.2.0.0-1ubuntu20.04_arm64.deb
sudo dpkg -i aerospike-tools_8.1.0-ubuntu20.04_arm64.deb

RPM format

aerospike-server-VERSION-1.RHEL.ARCHITECTURE.rpm
aerospike-tools-VERSION-1.RHEL.ARCHITECTURE.rpm

edition: community, enterprise, federal

version: 6.2.0.0

RHEL: el7, el8

architecture: x86_64, aarch64

sudo rpm -Uvh aerospike-server-enterprise-6.2.0.0-1.el7.aarch64.rpm
sudo rpm -Uvh aerospike-tools-7.4.0-1.el7.aarch64.rpm

Database earlier than 6.2

Debian format

aerospike-server-VERSION.DISTRO.x86_64.deb
aerospike-tools-VERSION.DISTRO.x86_64.deb

edition: community, enterprise, federal

version: 6.0.0.7, 6.1.0.3

distro: debian10, debian11, ubuntu18.04, ubuntu20.04

For example

sudo dpkg -i aerospike-server-enterprise-6.0.0.7.ubuntu18.04.x86_64.deb
sudo dpkg -i aerospike-tools-7.3.1.ubuntu18.04.x86_64.deb

RPM format

aerospike-server-VERSION-1.RHEL.x86_64.rpm
aerospike-tools-VERSION-1.RHEL.x86_64.rpm

edition: community, enterprise, federal

version: 6.1.0.3

RHEL: el7, el8

sudo rpm -Uvh aerospike-server-enterprise-6.1.0.3-1.el8.x86_64.rpm
sudo rpm -Uvh aerospike-tools-7.3.1-1.el8.x86_64.rpm

---

Start the Aerospike service

Restart the server, and wait until the server confirms that the node is ready.

# On systemd Linux distributions
sudo systemctl start aerospike

# On System V Linux distributions
sudo /etc/init.d/aerospike start

Note

Stopping and starting the Aerospike service makes the node leave the cluster for a short time, which triggers data rebalancing (migrations). The migrate-fill-delay parameter controls these migrations. See the Delay Migrations page for further details.

Monitor the cluster state

Prior to upgrading another node, verify that the node has re-joined the cluster by checking the following items:

• The cluster key is uniform across the cluster, see cluster_key.
• The cluster is the expected size, see cluster_size.

This can be checked through asadm, asinfo or by tailing the logs.

Caution

Some scenarios may require that you wait for migrations to complete prior to moving on and stopping the next node. These scenarios include the following:

• in-memory namespaces without persistence (storage-engine memory)
• specific version upgrades that require persisted data to be deleted (for example, version 4.2)
• some use cases for clusters running the older cluster protocol (prior to version 3.13)

As of version 4.3, the cluster-stable info command can be used to easily determine whether a cluster is stable.

For versions not supporting the cluster-stable info command, the following conditions would guarantee that migrations have finished following a reclustering event across all nodes in a cluster:

• migrate_allowed is true
• migrate_partitions_remaining is 0

To programmatically check whether the cluster is stable and migrations have finished, the following should be observed:

• Wait until cluster_key is uniform, the cluster_size is of expected size and migrate_allowed is set to true
• Wait for migrate_partitions_remaining to be 0
• Check the cluster_key is still the same as it was in step 1 and that the cluster_size did not change. If these are different, loop over to step 1 and check again.

After completing the upgrade across all nodes in the cluster, run asadm -e "info network" to verify that all the nodes have successfully upgraded to the correct version and that the cluster size is correct. You can look at asadm -e "info node" to check other statistics.

Admin> info network
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~Network Information (2020-12-16 21:45:32 UTC)~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
         Node|         Node ID|             IP|    Build|Migrations|~~~~~~~~~~~~~~~~~~Cluster~~~~~~~~~~~~~~~~~~|Client|  Uptime
             |                |               |         |          |Size|         Key|Integrity|      Principal| Conns|
10.0.0.1:3000| BB9010016AE4202|  10.0.0.1:3000|C-5.3.0.1|   0.000  |   5|92DCF600367B|True     |BB9050016AE4202|     2|00:07:48
10.0.0.2:3000| BB9020016AE4202|  10.0.0.2:3000|C-5.3.0.1|   0.000  |   5|92DCF600367B|True     |BB9050016AE4202|     2|00:07:47
10.0.0.3:3000|*BB9030016AE4202|  10.0.0.3:3000|C-5.3.0.1|   0.000  |   5|92DCF600367B|True     |BB9050016AE4202|     2|00:07:46
Number of rows: 5

Note

service ready: soon there will be cake! is logged after a node is available. You can tail the logs and grep for “cake” to check for this line:

# On systemd Linux distributions
journalctl -u aerospike -a -o cat -f | grep "cake"

# On System V Linux distributions
sudo tail -f /var/log/aerospike/aerospike.log | grep "cake"