Chapter 2. Configuring the VoltDB Database Cluster

Documentation

VoltDB Home » Documentation » VoltDB Kubernetes Administrator's Guide
< previoustable of contentsnext >

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-file cluster.config.licenseXMLFile=license.xml

The name mydb specifies a name for the release you create, voltdb/voltdb specifies the Helm chart to install, and the --set-file argument specifies a new value for a property to customize the installation. In this case, --set-file specifies the location of the VoltDB license needed to start the database. The license is the only property you must specify; all other properties have default values that are used if not explicitly changed.

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:

--set

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,\
cluster.serviceSpec.adminPort=33333

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).

--set-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 show in the --set example above:

$ cat ports.yaml
cluster:
   serviceSpec:
      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
< previoustable of contentsnext >