Upgrading a Cluster

Riak KV nodes negotiate with each other to determine supported operating modes. This allows clusters containing mixed-versions of Riak KV to properly interoperate without special configuration, and simplifies rolling upgrades.

Before starting the rolling upgrade process on your cluster, check out the Upgrading Riak KV: Production Checklist page, which covers details and questions to consider while upgrading.

Debian/Ubuntu

The following example demonstrates upgrading a Riak KV node that has been installed with the Debian/Ubuntu packages provided by Basho.

1. Stop Riak KV:

riak stop

2. Back up the Riak KV node’s /etc and /data directories:

sudo tar -czf riak_backup.tar.gz /var/lib/riak /etc/riak

3. Upgrade Riak KV:

sudo dpkg -i <riak_package_name>.deb

4. Restart Riak KV:

riak start

5. Verify Riak KV is running the new version:

riak version

6. Wait for the riak_kv service to start:

riak-admin wait-for-service riak_kv »target_node«

• »target_node« is the node which you have just upgraded (e.g. riak@192.168.1.11)

7. Wait for any hinted handoff transfers to complete:

riak-admin transfers

• While the node was offline, other nodes may have accepted writes on its behalf. This data is transferred to the node when it becomes available.

8. Repeat the process for the remaining nodes in the cluster.

RHEL/CentOS

The following example demonstrates upgrading a Riak KV node that has been installed with the RHEL/CentOS packages provided by Basho.

1. Stop Riak KV:

riak stop

2. Back up Riak KV’s /etc and /data directories:

sudo tar -czf riak_backup.tar.gz /var/lib/riak /etc/riak

3. Upgrade Riak KV:

sudo rpm -Uvh <riak_package_name>.rpm

4. Restart Riak KV:

riak start

5. Verify that Riak KV is running the new version:

riak version

6. Wait for the riak_kv service to start:

riak-admin wait-for-service riak_kv »target_node«

• »target_node« is the node which you have just upgraded (e.g. riak@192.168.1.11)

7. Wait for any hinted handoff transfers to complete:

riak-admin transfers

• While the node was offline, other nodes may have accepted writes on its behalf. This data is transferred to the node when it becomes available.

8. Repeat the process for the remaining nodes in the cluster.

Solaris/OpenSolaris

The following example demonstrates upgrading a Riak KV node that has been installed with the Solaris/OpenSolaris packages provided by Basho.

1. Stop Riak KV:

riak stop

sudo svcadm disable riak

2. Back up Riak KV’s /etc and /data directories:

sudo gtar -czf riak_backup.tar.gz /opt/riak/data /opt/riak/etc

3. Uninstall Riak KV:

sudo pkgrm BASHOriak

4. Install the new version of Riak KV:

sudo pkgadd -d <riak_package_name>.pkg

4. Restart Riak KV:

riak start

sudo svcadm enable riak

5. Verify that Riak KV is running the new version:

riak version

6. Wait for the riak_kv service to start:

riak-admin wait-for-service riak_kv »target_node«

»target_node« is the node which you have just upgraded (e.g. riak@192.168.1.11)

7. Wait for any hinted handoff transfers to complete:

riak-admin transfers

While the node was offline, other nodes may have accepted writes on its behalf. This data is transferred to the node when it becomes available.

8. Repeat the process for the remaining nodes in the cluster.

Rolling Upgrade to Enterprise

If you would like to upgrade an existing Riak KV cluster to a commercially supported Riak KV Enterprise cluster with multi-datacenter replication, undertake the following steps:

1. Shut down the node you are going to upgrade.
2. Back up your etc (app.config and vm.args) and data directories.
3. Uninstall your Riak KV package.
4. Install the riak_ee package.
5. A standard package uninstall should not have removed your data directories. If it did, move your backup to where the data directory should be.
6. Copy any customizations from your backed-up vm.args to the riak_ee installed vm.args file, these files may be identical.
7. The app.config file from riak_ee will be significantly different from your backed-up file. While it will contain all of the same sections as your original, it will have many new ones. Copy the customizations from your original app.config file into the appropriate sections in the new one. Ensure that the following sections are present in app.config:
   • riak_core — the cluster_mgr setting must be present. See MDC v3 Configuration for more information.
   • riak_repl — See MDC v3 Configuration for more information.
   • riak_jmx — See JMX Monitoring for more information.
   • snmp — See SNMP for more information.
8. Start Riak KV on the upgraded node.

Basho Patches

After upgrading, you should ensure that any custom patches contained in the basho-patches directory are examined to determine their application to the upgraded version. If you find that patches no longer apply to the upgraded version, you should remove them from the basho-patches directory prior to operating the node in production.

The following lists locations of the basho-patches directory for each supported operating system:

• CentOS & RHEL Linux: /usr/lib64/riak/lib/basho-patches
• Debian & Ubuntu Linux: /usr/lib/riak/lib/basho-patches
• FreeBSD: /usr/local/lib/riak/lib/basho-patches
• SmartOS: /opt/local/lib/riak/lib/basho-patches
• Solaris 10: /opt/riak/lib/basho-patches

Riaknostic

It is a good idea to also verify some basic configuration and general health of the Riak KV node after upgrading by using Riak KV’s built-in diagnostic utility Riaknostic.

Ensure that Riak KV is running on the node, and issue the following command:

riak-admin diag

Make the recommended changes from the command output to ensure optimal node operation.