Volt Operator for Kubernetes

Documentation

VoltDB Home » Documentation » Volt Operator for Kubernetes

Volt Operator for Kubernetes

V3.4.0

October 25, 2024

Introduction
Volt Operator Release Notes
Running Older Releases of VoltDB

Introduction

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.4.0 (October 25, 2024)

Note

It has been noticed that Helm has an issue handling large (six digits or more) integers in the YAML properties file. Rather than pass these integers as is, it converts large integers to scientific notation, which is often not acceptable to downstream systems, including the VoltDB configuration properties. The workaround is to make sure you quote any large integers in the Helm YAML properties file.

1.1.

Improvement

The following limitation in previous versions has been resolved:

  • There was an issue where an invalid URL could trigger a segmentation violation in the operator, causing the operator to restart. Unfortunately, since the cause of the problem was still present when the operator restarted, the error and restart sequence was repeated.

    This issue has been resolved. The error message now correctly identifies the cause of the problem as an invalid URL The operator stays up and available for managing the installed instance. It also continues trying to apply the problematic configuration and logging the error until the invalid URL is corrected.

2. Release V3.3.0 (October 2, 2024)

2.1.

Support for Volt Active Data V14.0

The Operator has integrated support for new V14 features, including the new get and set operations to optimize configuring the database. It also drops the ability to start the standalone Prometheus agent that has been removed from the product. For these reasons, although previous Operator releases can be used, Operator 3.3.0 is recommended for running Volt Active Data 14.0.0 or later in Kubernetes.

2.2.

Security updates

All known high and critical CVEs were resolved as of the date of this release, including:

CVE-2024-34156

2.3.

Improvement

The following limitation in previous versions has been resolved:

  • Previously, there were cases of the operator reporting a node failing to stop because the shutdown process was taking longer than the operator's fixed timeout for that event. The time limit has been extended to 30 seconds to avoid spurious errors due to shutdown taking longer than expected.

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

3.1.

Improvement

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.

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

4.1.

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.

4.2.

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.

4.3.

Improvement

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.

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

5.1.

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:

cluster.clusterSpec.clusterInit.licenseSecretRefName
cluster.clusterSpec.clusterInit.loggingConfigMapRefName

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.

5.2.

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:

cluster.config.deployment.dr.connection.connectiontimeout
cluster.config.deployment.dr.connection.receivetimeout

5.3.

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.

5.4.

Improvements

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.

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

6.1.

Improvements

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.

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

7.1.

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.

7.2.

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.

7.3.

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.

7.4.

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.

7.5.

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.

All recent releases of Volt Active Data — including the current major version and Long-Term Support (LTS) releases — use a single operator and Helm chart: Volt Operator V3.0.0 or later, chart V3.0.0 or later. The minimum versions of VoltDB that Operator V3 supports are: 10.2.21, 11.4.13, 12.3.4, and 13.0.3. All future major releases will be supported by Operator V3. When installing or upgrading Volt, you should use the most recent release of Operator V3 and Chart V3, since this is sure to support all available features of your chosen Volt version.

However, if you must use an older version of VoltDB, you must use an older version of the Operator as well. For versions of VoltDB prior to the releases listed above, or if you choose not to upgrade to Operator V3.0, you cannot use the global.voltdbVersion property. Instead, you must identify and use the appropriate an earlier version of the Operator itself, based on the table below:

Volt LTS versionOperator and Chart version
10.2.x1.3.x
11.4.x1.8.x
12.3.x2.1.x

Once you identify the correct Operator version, you include the --version qualifier on the commands you issue to Helm. For example, to start a Volt 12.3.0 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.