Volt Operator for Kubernetes


VoltDB Home » Documentation » Volt Operator for Kubernetes

Volt Operator for Kubernetes


June 28, 2024


The Volt Operator for Kubernetes and its accompanying Helm chart manage the creation, configuration, and operation of VoltDB databases within the Kubernetes environment. You do not interact with the Operator directly; instead, you specify the desired state for the database through Helm properties, as explained in the Volt Kubernetes Administrator's Guide. This document provides additional information concerning the Operator, including:

Volt Operator Release Notes

This section describes changes and improvements made to the Volt Operator and accompanying Helm charts in each release, starting with version 3.0.0. Users of Volt Active Data on Kubernetes should take note of the following changes that might impact their existing applications.

1. Release V3.2.1 (June 28, 2024)



The following limitation in previous versions has been resolved:

  • During an in-service upgrade, if a pod took too long to shut down, the operator stopped the pod without letting the database shut down completely, then attempted to continue with the upgrade process, which would ultimately fail. Now if the pod shut down times out, the operator aborts the in-service upgrade. At which point you must manually rollback to the previous software version.

2. Release V3.2.0 (June 24, 2024)


Updating the configuration on XDCR clusters

There is a Helm property, cluster.clusterSpec.allowRestartDuringUpdate, that lets Helm automatically stop and restart the cluster if you update a configuration property that cannot be changed while the database is running. This property is very useful for updating a single cluster. However, it should never be set to true for an XDCR cluster, because the cluster will not be able to rejoin the XDCR mesh when it restarts. Unfortunately, in previous releases, not only would the cluster fail to restart properly, but the Volt Operator would hang and fail to respond to any further Helm commands, including commands to reset the failed cluster.

The issue with the operator has been resolved. It no longer hangs if the property is accidentally used on an XDCR cluster. The documentation will be updated in the upcoming release to warn against setting the .allowRestartDuringUpdate property for XDCR clusters.


Upcoming improvements to DR timeout configuration

There is an undocumented setting (DR_RECV_TIMEOUT) that changes the timeout period for a cluster waiting for a response to its initial connection request to another XDCR cluster, which was settable through the VOLTDB_OPTS environment variable (cluster.clusterSpec.env.VOLTDB_OPTS). This undocumented setting is being replaced by two official configuration controls in Volt Active Data V13.3.0. In support of that release, the corresponding Helm properties, cluster.config.deployment.dr.connection.source.receivetimeout and cluster.config.deployment.dr.connection.source.connectiontimeout, have been added to the Volt Helm chart.

Note that the use of DR_RECV_TIMEOUT in VOLTDB_OPTS is now deprecated and will be ignored in a future release. However, until then, the VOLTDB_OPTS setting will take precedence so as not to alter current behavior.



The following limitation in previous versions has been resolved:

  • Previously, if an XDCR cluster is paused but cannot drain its DR queues, the operator could hang and become unresponsive. This issue has been resolved and operations that might stall due to DR not draining will now timeout after two minutes, by default. You can adjust the timeout period using the cluster.clusterSpec.adminOperationTimeout property, specifying the timeout period in seconds.

3. Release V3.1.0 (June 5, 2024)


Improved handling of Kubernetes secrets

Previously, the Volt Operator supported an undocumented property, cluster.clusterSpec.clusterInit.initSecretRefName, that could be used specify a Kubernetes secret for storing the deployment, license, and logging configuration files. There are two new properties for naming separate secrets for storing the license and logging configuration, respectively:


At the same time, the original .initSecretRefName property is being deprecated. Although it is still possible to use this property to reference a Kubernetes secret holding the deployment file, that method for configuring the database is not recommended and support for the property may be removed in a future release. The correct method for configuring the database is through the individual cluster.config.deployment.* properties.


Support for configuring the XDCR connection and receive timeouts

The XDCR connection and receive timeouts have been added as settings in the Volt XML configuration file. The following Helm properties have been added so these timeouts can be set in Kubernetes as well:



Preparations for the next Long-Term Support (LTS) release

In addition to the enhancements listed above, other changes and additions have been made in preparation for the the upcoming Long-Term Support (LTS) release of Volt Active Data.



The following limitations in the previous version have been resolved:

  • In previous releases, having a sidecar container running on a Volt server pod could interfere with the in-service upgrade (ISU) process. This issue has been resolved.

  • It was reported that certain third party applications — specifically ArgoCD — react badly if any of the properties under cluster.clusterSpec.clusterInit.* are listed without a value. Previously, if the user filled in one or more of these properties, the Volt Operator would automatically add null entries for the rest. The operator no longer adds empty property entries and will, in fact, remove empty entries to avoid this issue.

4. Release V3.0.1 (April 4, 2024)



The following limitation in the previous version has been resolved:

  • The global.voltdbVersion property is not supposed to have a default value; you must specify the software version you wish to use when creating a Helm release. However, in the initial Operator V3.0.0 release, a value used in testing was accidentally left in as the default. This would not affect anyone who sets the property to the software version to use. However, when using older versions by specifying only the image tag, the Operator would attempt to create a release using the older software but the most recent configuration semantics. In most cases, the pods would fail to start due to various configuration errors. This issue has been resolved.

5. Release V3.0.0 (March 29, 2024)


Volt Operator V3.0.0 and changes to the Helm commands

This release of Volt Operator for Kubernetes version 3.0.0 improves the management of Volt database applications in two ways. It allows the user to select the chart, operator, and Docker image by specifying just the software version of VoltDB. It also uses a single operator and chart for managing all current versions of VoltDB, rather than separate operator releases for each software release. These changes have two major benefits:

  • Ease of Use — You only need to specify the version of VoltDB to use, you no longer need to correlate which operator and chart versions are compatible with which software versions.

  • Reliability — There is a single operator for all currently supported versions of VoltDB; consequently, fixes to the operator itself automatically apply to all versions of the product.

The one noticeable change resulting from the transition to Operator V3.0.0 is that there is no longer a default version of VoltDB. In other words, you must explicitly identify the version of VoltDB you want to use when you start the database or upgrade the VoltDB version. For example:

$ helm install mydb voltdb/voltdb --set global.voltdbVersion=13.2.0

This applies to all helm commands, but especially helm install when you are first instantiating the cluster. Once the cluster is running, for other Helm commands (such as helm upgrade) you can use the --reuse-values qualifier to retain the current setting of the software version.


Volt Operator 3.0.0 supports Kubernetes versions 1.25 through 1.28

The current Operator requires a minimum of Kubernetes version 1.25 and has been tested and verified against versions through 1.28.


New value allowed for the vmc.enabled property.

Previously, the vmc.enabled property allowed the values "true" or "false" to specify whether VMC and the JSON API are run as a separate service (true) or as part of the database server process (false). However, depending on what version of VoltDB you are running, the default differs. For VoltDB V13.x, the default is true, for previous versions, the default is false. Therefore, the property now allows the value "default" to set the property to match the default behavior for the version of VoltDB being used.


New default TLS/SSL configuration for the VMC/JSON API service

If TLS/SSL is enabled for the cluster, the separate VMC service and Prometheus agent (if in use) must also be configured to use TLS to access the servers. Previously, it was necessary to configure this explicitly. Now, if TLS/SSL is enabled for the cluster but no TLS properties are defined for VMC, the operator will automatically configure these services (through the vmc.voltdb.ssl.* properties) to use the appropriate TLS settings when accessing the server. It will also enable and configure SSL for the VMC services outbound port (that is, the vmc.ssl.* properties).

This automatic propagation of TLS/SSL settings is done through a new property value for the properties metrics.ssl.enabled and vmc.ssl.enabled. Where previously these properties only supported "true" and "false", they now also support "auto" to let the operator configure their TLS /SSL settings, which is now the default. Note that any VMC or Prometheus Agent properties that are explicitly set will overide any automated settings from the ...enabled="auto" property.


Additional improvements

The following limitations in previous versions have been resolved:

  • Previously, if TLS/SSL was not enabled for the cluster, the Operator still created Kubernetes secrets for SSL information. Although these secrets were harmless because they were empty, they were also unnecessary. These secrets are no longer created if TLS/SSL is not enabled.

Running Older Releases of VoltDB

You should always run the latest point release of the LTS version of Volt you are using. This ensures you have the most reliable software, free of all known bugs and/or security vulnerabilities. However, if you must use an older point release, you must also use an older version of the Operator as well.

The Volt Operator version 3.0.0 and later manages the operation of recent releases of all supported versions of VoltDB, including:

  • Volt Active Data V13.0.3 and later

  • Volt Active Data V12.3.4 and later (LTS)

  • Volt Active Data V11.4.13 and later (LTS)

  • Volt Active Data V10.2.21 and later (LTS)

For these versions of Volt, you use Helm with the global.voltdbVersion property specifying the software version to use, as described in the Volt Kubernetes Administrator's Guide. If you need to use a version of VoltDB prior to the releases listed above, you cannot use the global.voltdbVersion property. Instead, you must identify and use the appropriate earlier version of the Operator itself. You can do this by looking it up on the compatibility chart or by having Helm list the available versions. For example, let's say you need to run VoltDB V12.3.0, first you list the older Operator versions with the helm search repo command:

helm search repo voltdb/voltdb --versions
      . . .           
voltdb/voltdb  2.1.1          12.3.1                    The Helm chart for VoltDB
voltdb/voltdb  2.1.0          12.3.0                    The Helm chart for VoltDB
voltdb/voltdb  2.0.2          12.2.2                    The Helm chart for VoltDB
      . . .

Once you identify the correct Operator version (in this case, 2.1.0), you include the --version qualifier on the commands you issue to Helm. For example, to start the database you include --version=2.1.0 on the helm install command:

$ helm install mydb voltdb/voltdb \
     --version=2.1.0              \ 
     --values myconfig.yaml       \
     --set cluster.clusterSpec.replicas=5

You must include the --version qualifier for all Helm commands related to this cluster, except when upgrading to a newer release supported by Operator V3 or later.

Compatibility for Older Versions of the Volt Operator

All recent releases of Volt Active Data — including the current major version and Long-Term Support (LTS) releases —use a single operator : Volt Operator V3.0.0 or later. If you must run an older release of Volt, you must use the appropriate older version of the Volt Operator as well. The following tables map older Volt versions to the compatible Operator and chart version.

* Long-Term Support releases are highlighted in bold.

Table 1. Volt Active Data V13.x Compatibility Chart

VoltDBKubernetesVoltDB OperatorHelm Chart

Table 2. Volt Active Data V12.x Compatibility Chart

VoltDBKubernetesVoltDB OperatorHelm Chart
12.3.3 *1.23-
12.3.2 *1.23-
12.3.1 *1.21-
12.3.0 *1.21-

Table 3. Volt Active Data V11.x Compatibility Chart

VoltDBKubernetesVoltDB OperatorHelm Chart
11.4.12 *1.21-
11.4.11 *1.21-
11.4.10 *1.21-
11.4.9 *1.21-
11.4.8 *1.16-
11.4.5, 11.4.6, 11.4.7 *1.16-
11.4.4 *1.16-
11.4.3 *1.16-
11.4.1, 11.4.2 *1.16-
11.4.0 *1.16-,, 1.8.1,, 1.7.5
11.31.16-,, 1.6.9
11.21.16-,, 1.6.2

Table 4. Volt Active Data V10.x Compatibility Chart

VoltDBKubernetesVoltDB OperatorHelm Chart
10.2.20 *1.21-
10.2.19 *1.21-
10.2.18 *1.21-
10.2.17 *1.16-
10.2.16 *1.16-
10.2.15 *1.16-
10.2.14 *1.16-
10.2.13 *1.16-
10.2.12 *1.16-
10.2.11 *1.16-
10.2.10 *1.16-
10.2.9 *1.16-
10.2.8 *1.16-
10.2.7 *1.16-
10.2.6 *1.16-
10.2.5 *1.16-
10.2.4 *1.16-
10.2.3 *1.16-
10.2.2 *1.16-
10.2.1 *1.16-
10.1.0,, 1.1.1 to 1.0.2