5.3. Upgrading the VoltDB Software and Helm Charts

Documentation

VoltDB Home » Documentation » VoltDB Kubernetes Administrator's Guide

5.3. Upgrading the VoltDB Software and Helm Charts

When new versions of the VoltDB software are released they are accompanied by new versions of the Helm charts that support them. By default when you "install" a "release" of VoltDB with Helm, you get the latest version of the VoltDB software at that time. Your release will stay on its initial version of VoltDB as long as you don't update the charts and VoltDB Operator in use.

You can upgrade an existing database instance to a recent version using a combination of kubectl and helm commands to update the charts, the operator, and the VoltDB software. The steps to upgrade the VoltDB software in Kubernetes are:

  1. Update your copy of the VoltDB repository.

  2. Update the custom resource definition (CRD) for the VoltDB Operator.

  3. Upgrade the VoltDB Operator and software.

The following sections explain how to perform each step of this process, including a full example of the entire process in Example 5.1, “Process for Upgrading the VoltDB Software” However, when upgrading an XDCR cluster, there is an additional step required to ensure the cluster's schema is maintained during the upgrade process. Section 5.3.4, “Updating VoltDB for XDCR Clusters” explains the extra step necessary for XDCR clusters.

Note

To use the helm upgrade command to upgrade the VoltDB software, the starting version of VoltDB must be 10.1 or higher. See the VoltDB Release Notes for instructions when using Helm to upgrade earlier versions of VoltDB.

5.3.1. Updating Your Helm Repository

The first step when upgrading VoltDB is to make sure your local copy of the VoltDB Helm repository is up to date. You do this using the helm repo update command:

$ helm repo update

Once you update your local copy of the charts, you can determine which version — of both the charts and the software — you want to use by listing all available versions. You do this with the helm search repo command.

$ helm search repo voltdb/voltdb --versions
NAME           CHART VERSION  APP VERSION  DESCRIPTION            
voltdb/voltdb  1.3.0          10.2.0       A Helm chart for VoltDB
voltdb/voltdb  1.2.1          10.1.3       A Helm chart for VoltDB
voltdb/voltdb  1.2.0          10.1.2       A Helm chart for VoltDB
voltdb/voltdb  1.1.0          10.1.0       A Helm chart for VoltDB
voltdb/voltdb  1.0.2          10.0.0       A Helm chart for VoltDB

The display shows the available versions, including for each release a version number for the chart and one for the VoltDB software (app version). Make a note of the pair of version numbers who want to use because you will need them both to complete the following steps of the process. All of the examples in this document use the chart version 1.2.1 and the software version 10.1.3 for the purposes of demonstration.

5.3.2. Updating the Custom Resource Definition (CRD)

The second step is to update the custom resource definition (CRD) for the VoltDB Operator. This allows the Operator to be upgraded to the latest version.

To update the CRD, you must first save a copy of the latest chart, then extract the CRD from the resulting tar file. The helm pull command saves the chart as a gzipped tar file and the tar command lets you extract the CRD. For example:

$ helm pull voltdb/voltdb --version 1.2.1
$ tar --strip-components=2 -xzf voltdb-1.2.1.tgz  \
     voltdb/crds/voltdb.com_voltdbclusters_crd.yaml

Note that the file name of the resulting tar file includes the chart version number. Once you have extracted the CRD as a YAML file, you can apply it to Kubernetes:

$ kubectl apply -f voltdb.com_voltdbclusters_crd.yaml

5.3.3. Upgrading the VoltDB Operator and Software

Once you update the CRD, you are ready to upgrade VoltDB, including both the Operator and the server software. You do this using the helm upgrade command and specifying the version numbers for both items on the command line. As soon as you make this change, the Operator will pause the database, take a final snapshot, shutdown the database and then restart with the new version, restoring the snapshot in the process. For example:

$ helm upgrade mydb voltdb/voltdb --reuse-values \
   --set operator.image.tag=1.2.1 \
   --set cluster.clusterSpec.image.tag=10.1.3

Example 5.1, “Process for Upgrading the VoltDB Software” summarizes all of the commands needed to update a database release to VoltDB version 10.1.2.

Example 5.1. Process for Upgrading the VoltDB Software

$    # Update the local copy of the charts
$ helm repo update
$ helm search repo voltdb/voltdb --versions
NAME           CHART VERSION  APP VERSION  DESCRIPTION            
voltdb/voltdb  1.2.1          10.1.3       A Helm chart for VoltDB
voltdb/voltdb  1.2.0          10.1.2       A Helm chart for VoltDB
voltdb/voltdb  1.1.0          10.1.0       A Helm chart for VoltDB
voltdb/voltdb  1.0.2          10.0.0       A Helm chart for VoltDB
$
$
$    # Extract and update the CRD
$ helm pull voltdb/voltdb --version 1.2.1
$ tar --strip-components=2 -xzf voltdb-1.2.1.tgz  \
     voltdb/crds/voltdb.com_voltdbclusters_crd.yaml
$ kubectl apply -f voltdb.com_voltdbclusters_crd.yaml
$
$
$    # Upgrade the Operator and VoltDB software
$ helm upgrade mydb voltdb/voltdb --reuse-values \
   --set operator.image.tag=1.2.1 \
   --set cluster.clusterSpec.image.tag=10.1.3

5.3.4. Updating VoltDB for XDCR Clusters

When upgrading an XDCR cluster, there is one extra step you must pay attention to. Normally, during the upgrade, VoltDB saves and restores a snapshot between versions and so all data and schema information is maintained. When upgrading an XDCR cluster, the data and schema is deleted, since the cluster will need to reload the data from another cluster in the XDCR relationship once the upgrade is complete.

Loading the data is automatic. But loading the schema depends on the schema being stored properly before the upgrade begins.

If the schema was loaded through the YAML properties cluster.config.schemas and cluster.config.classes originally and has not changed, the schema and classes will be restored automatically. However, if the schema was loaded manually or has been changed since it was originally loaded, you must make sure a current copy of the schema and classes is available after the upgrade. There are two ways to do this.

For both methods, the first step is to save a copy of the schema and the classes. You can do this using the voltdb get schema and voltdb get classes commands. For example, using Kubernetes port forwarding you can save a copy of the schema and class JAR file to your local working directory:

$ kubectl port-forward mydb-voltdb-cluster-0 21212 &
$ voltdb get schema -o myschema.sql
$ voltdb get classes -o myclasses.jar

Once you have copies of the current schema and class files, you can either set them as the default schema and classes for your database release before you upgrade the software or you can set them in the same command as you upgrade the software. For example, the following commands set the default schema and classes first, then upgrade the Operator and server software. Alternately, you could put the two --set-file and two --set arguments in a single command.

$ helm upgrade mydb voltdb/voltdb --reuse-values \
   --set-file cluster.config.schemas=myschema.sql  \
   --set-file cluster.config.classes=myclasses.jar
$ helm upgrade mydb voltdb/voltdb --reuse-values \
   --set operator.image.tag=1.2.1 \
   --set cluster.clusterSpec.image.tag=10.1.3