Chapter 2. Configuring the VoltDB Database Cluster


VoltDB Home » Documentation » VoltDB Kubernetes Administrator's Guide

Chapter 2. Configuring the VoltDB Database Cluster

The two major differences between creating a VoltDB database cluster in Kubernetes and starting a cluster using traditional servers are:

  • In Kubernetes, there is a single Helm command (install) that performs both the initialization and the startup of the database.

  • You specify the database configuration with properties rather than as an XML file, environment variables, or command line arguments.

In fact, all of the configuration — including the configuration of the virtual servers (or pods), the server processes, and the database — is accomplished using Helm properties. Helm simplifies the process by coordinating all the different components involved, including Kubernetes, Docker, and VoltDB. By using the provided Helm charts, it is possible to start a default VoltDB cluster with a single command:

$ helm install mydb voltdb/voltdb        \
   --set global.voltdbVersion=13.2.0     \
   --set-file cluster.config.licenseXMLFile=license.xml

For recent versions[2] of Volt Active Data, you can start the cluster with just four arguments to the helm install command:

  1. The release name — The release name (mydb in the example) identifies the cluster and is used as a prefix for the corresponding Kubernetes' artifacts (such as pod and service names) as well as in Helm commands when managing the cluster. You can use any name you like to identify the cluster.

  2. The name of the Helm chart — in the case of VoltDB, the chart name is the name you gave when you added the Volt chart repository to Helm followed by the chart name voltdb. Assuming you named the repository voltdb, the chart name is voltdb/voltdb.

  3. The VoltDB version — You must also specify the version of Volt Active Data you want to use. This is the server software version.

  4. Your Volt Active Data license — Finally, you must provide the Volt Active Data license file you received when you purchased Volt.

You specify the release and chart names as parameters to the command and you specify the VoltDB version and license file as values using command arguments such as --set and --set-file. All other properties — most notably the configuration properties — have default values that are used if not explicitly changed. For example, the default node (or replica) count for the cluster is three.


Although the global.voltdbVersion property is required, it is a Helm property and can be set like any other, individually on the command line or in a properties file with other database and cluster settings. For the purposes of demonstration, many of the examples in this book, assume that the software version is set in a properties file as part of the overall configuration

However, a default cluster of three nodes and no schema or configuration is not particularly useful. So VoltDB provides Helm properties to let you customize every aspect of the database and cluster configuration, including:

The following sections explain how to specify Helm properties in a properties file or on the command line, as well how to use those properties to make some of the most common customizations to your database. Later chapters explain how to configure specific features (such as security and XDCR). Appendix B, VoltDB Helm Properties provides a full list of the properties, including a brief description and the default value for each.

2.1. Using Helm Properties to Configure Your Database

First, it is useful to understand the different ways you can specify properties on the Helm command line. The following discussion is not intended as a complete description of Helm; only a summary to give you an idea of what they do and when to use them.

Helm offers three different ways to specify properties:


The --set flag lets you specify individual property values on the command line. You can use --set multiple times or separate multiple property/value pairs with commas. For example, the following two commands are equivalent:

$ helm install mydb voltdb/voltdb             \
   --set cluster.serviceSpec.clientPort=22222 \
   --set cluster.serviceSpec.adminPort=33333
$ helm install mydb voltdb/voltdb             \
   --set cluster.serviceSpec.clientPort=22222,\

The --set flag is useful for setting a few parameters that change frequently or for overriding parameters set earlier in the command line (such as in a YAML file).


The --set-file flag lets you specify the contents of a file as the value for a property. For example, the following command sets the contents of the file license.xml as the license for starting the VoltDB cluster:

$ helm install mydb voltdb/voltdb      \
   --set-file cluster.config.licenseXMLFile=license.xml

As with --set, You can use --set-file multiple times or separate multiple property/file pairs with commas. The --set-file flag is useful for setting parameters where the value is too complicated to set directly on the command line. For example, the contents of the VoltDB license file.

--values, -f

The --values flag lets you specify a file that contains multiple property definitions in YAML format. Whereas properties set on the command line with --set use dot notation to separate the property hierarchy, YAML puts each level of the hierarchy on a separate line, with indentation and followed by a colon. For example, the following YAML file and --values flag set the same two properties shown in the --set example above:

$ cat ports.yaml
      clientPort: 22222
      adminPort: 33333
$ helm install mydb voltdb/voltdb  \
   --values ports.yaml

YAML files are extremely useful for setting multiple properties with values that do not change frequently. You can also use them to group properties (such as port settings or security) that work together to configure aspects of the database environment.

You can use any of the preceding techniques for specifying properties for the VoltDB Helm charts. In fact, you can use each method multiple times on the command line and mixed in any order. For example, the following example uses --values to set the database configuration and ports, --set-file to identify the license, and --set to specify the number of nodes requested:

$ helm install mydb voltdb/voltdb                       \
   --values dbconf.yaml,dbports.yaml                    \
   --set-file cluster.config.licenseXMLFile=license.xml \
   --set cluster.clusterSpec.replicas=5

[2] Recent Volt versions (13.0.3, 12.3.4, 11.4.13, and 10.2.21 or later) use the simplified command for starting the database. For earlier versions, you must specify the specific chart and software versions to use. See the Volt Operator Release Notes for details.