Upgrading Aerospike
By upgrading your Aerospike Database cluster you will gain access to the latest features and bug fixes. The cluster upgrade process involves upgrading one server node at a time, which results in no downtime for the cluster.
Aerospike supports mixed-version clusters for rolling upgrades. However, Aerospike does not recommend long term use of clusters with nodes running different versions of the Aerospike database.
Refer to the Special Upgrade instructions page for important information relevant to specific versions.
Download the server package to the node
You can download the Aerospike Database server manually from the Download page. Make sure to read the release notes of the version you are downloading. Alternatively, you can automate downloading versions of the server from the artifact repository. See the FAQ on downloads for details.
Base URL
https://download.aerospike.com/artifacts/aerospike-server-<edition>/<server-version>/
Download the server package and transfer it to the node. The name of the server package varies by version.
Linux distributions (distros) that use Red Hat packages must use the appropriate Red Hat Enterprise Linux compatible version. See Install on Red Hat Enterprise Linux.
Server version 6.2 and newer
Support for Debian 10 ARM64 was removed from server 6.3.
Starting with server version 6.2 where support for ARM64 is introduced, the server package follows the following naming convention:
aerospike-server-<edition>_<version>_tools-<tools-version>_<distro>_<architecture>.tgz
edition: community, enterprise, federal
version: 6.2.0.0, and so on
distro: debian10, debian11, ubuntu18.04, ubuntu20.04, el7, el8, el9, amzn2023, and so on
architecture: x86_64, aarch64 based on uname -m
Prior to server version 6.2
Prior to version 6.2, Aerospike Database servers were all intended to run only on Linux distros and the x86_64 architecture.
aerospike-server-<edition>-<version>-<distro>.tgz
edition: community, enterprise, federal
version: 6.1.0.3, and so on
distro: debian10, debian11, ubuntu18.04, ubuntu20.04, el7, el8, and so on
See server version 6.1.
Stop the Aerospike service
It is a good practice to quiesce a node prior to shutting it down or removing it from a cluster. Refer to the Quiesce Node page for details (Enterprise Edition).
To stop the Aerospike service
# On systemd Linux distros
sudo systemctl stop aerospike
# On System V Linux distros
sudo /etc/init.d/aerospike stop
If you have namespaces which are configured to be only in-memory with no persistence (storage-engine memory),
it is required to wait for migrations to be completed before moving on to the next node to avoid data loss.
Refer to Monitoring Migrations.
Unpack the server package
Uncompress the package to get the RPM or Debian packages of the server and tools.
You may need to delete the older version, if upgrading from Aerospike version
prior to 3.3.x.
To remove the packages look for the old versions of aerospike-<edition>-server
and aerospike-<edition>-tools.
# For RRMs
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
Server version 6.2 and later
Debian Format
aerospike-server-<edition>_<version>-1<distro>_<architecture>.deb
aerospike-tools_<version>-<[commit]distro>_<architecture>.deb
edition: community, enterprise, federal
version: 6.2.0.0, and so on
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-<edition>-<version>-1.<RHEL>.<architecture>.rpm
aerospike-tools-<version>-1.<RHEL>.<architecture>.rpm
edition: community, enterprise, federal
version: 6.2.0.0, and so on
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
Prior to server version 6.2
Debian Format
aerospike-server-<edition>-<version>.<distro>.x86_64.deb
aerospike-tools-<edition>-<version>.<distro>.x86_64.deb
edition: community, enterprise, federal
version: 6.0.0.7, 6.1.0.3, and so on
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-<edition>-<version>-1.<RHEL>.x86_64.rpm
aerospike-tools-<version>-1.<RHEL>.x86_64.rpm
edition: community, enterprise, federal
version: 6.1.0.3, and so on
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 distros
sudo systemctl start aerospike
# On System V Linux distros
sudo /etc/init.d/aerospike start
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 to controls these migrations. Refer to 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 performing these steps:
- Cluster key is uniform across the cluster, see
cluster_key - Cluster is of the expected size, see
cluster_size
This can be checked through asadm, asinfo or by tailing the logs.
In some situations, it may require waiting for migrations to complete prior to moving on and stopping the next node.
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 completed following a reclustering event (across all nodes in a cluster):
migrate_allowedistruemigrate_partitions_remainingis0
In order to programmatically check whether the cluster is at a stable state and migrations have finished, the following should be observed:
- Wait until
cluster_keyis uniform, thecluster_sizeis of expected size andmigrate_allowedis set totrue - Wait for
migrate_partitions_remainingto be0 - Check the
cluster_keyis still the same as it was in step 1 and that thecluster_sizedid not change. Should these be different, loop over to step 1 and check again.
Situations requiring a wait for migrations between nodes to complete include the following:
- namespaces which are configured to be in-memory only (no persistence,
storage-engine memory) - specific version upgrades requiring 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)
On completing the upgrade across all nodes in the cluster, you can confirm from the output of asadm -e "info network" if 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
service ready: soon there will be cake! will be logged once a node is available. The logs can be tailed for "cake" to check for this line:
# On systemd Linux distros
journalctl -u aerospike -a -o cat -f | grep "cake"
# On System V Linux distros
sudo tail -f /var/log/aerospike/aerospike.log | grep "cake"