Upgrading a Cluster
Riak KV upgrades are tested and supported for two feature release versions. For example, upgrades from 1.1.x to 1.3.x are tested and supported, while upgrades from 1.1.x to 1.4.x are not. When upgrading to a new version of Riak KV that is more than two feature releases ahead, we recommend first upgrading to an intermediate version. For example, in an upgrade from 1.1.x to 1.4.x, we recommend upgrading from 1.1.x to 1.3.x before upgrading to 1.4.x.
If you run Riak Control, you should disable it during the rolling upgrade process.
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 Riak.
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.
If you use Riak KV’s secondary indexes and are
upgrading from a version prior to Riak KV version 1.3.1, you need to
reformat the indexes using the riak-admin reformat-indexes
command. More details about reformatting indexes are available in the release notes.
RHEL/CentOS
The following example demonstrates upgrading a Riak KV node that has been installed with the RHEL/CentOS packages provided by Riak.
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.
If you use Riak KV’s secondary indexes and are
upgrading from a version prior to Riak KV version 1.3.1, you need to
reformat the indexes using the riak-admin reformat-indexes
command. More details about reformatting indexes are available in the release notes.
Solaris/OpenSolaris
The following example demonstrates upgrading a Riak KV node that has been installed with the Solaris/OpenSolaris packages provided by Riak.
1. Stop Riak KV:
riak stop
If you are using the service management facility (SMF) to manage Riak KV,
you will have to stop Riak KV via svcadm
instead of using 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
If you are using the service management facility (SMF) to manage Riak KV,
you will have to start Riak KV via svcadm
instead of using 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.
If you use Riak KV’s secondary indexes and are
upgrading from a version prior to Riak KV version 1.3.1, you need to
reformat the indexes using the riak-admin reformat-indexes
command. More details about reformatting indexes are available in the release notes.
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:
- Shut down the node you are going to upgrade.
- Back up your
etc
(app.config and vm.args) anddata
directories. - Uninstall your Riak KV package.
- Install the
riak_ee
package. - A standard package uninstall should not have removed your data directories. If it did, move your backup to where the data directory should be.
- Copy any customizations from your backed-up vm.args to the
riak_ee
installed vm.args file, these files may be identical. - 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
— thecluster_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.
- Start Riak KV on the upgraded node.
Riak 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.