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 all the database and environment configuration with Helm properties rather than as separate YAML properties, 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[3] of Volt Active Data, you can start the cluster with just four arguments to the helm install
command:
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.
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.
The VoltDB version — You must also specify the version of Volt Active Data you want to use. This is the server software version.
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:
Cluster configuration, including size of the cluster, available resources, and so on
Network configuration, including the assignment of ports and external mappings
Database initialization options, including administration username and password, schema, and class files
Database configuration, including the settings normally found in the YAML configuration files on non-Kubernetes installations
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.
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,\ 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).
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:
Documentation$ helm install mydb voltdb/voltdb \
--set-file cluster.config.licenseXMLFile=license.xmlAs 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.
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 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
[3] 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.