2.2. Configuring the Cluster and Database


VoltDB Home » Documentation » VoltDB Kubernetes Administrator's Guide

2.2. Configuring the Cluster and Database

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

  • With Helm there is a single 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.

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. The following sections provide examples of some of the most common configuration settings when using Kubernetes. Appendix A, VoltDB Helm Properties gives a full list of all of the properties that are available for customization.

2.2.1. Configuring the Cluster

Many of the configuration options that are performed through hardware configuration, system commands or environment variables on traditional server platforms are now available through Helm properties. Most of these settings are listed in Section A.3, “Kubernetes Cluster Startup Options”.

Hardware Settings

Hardware settings, such as the number of processors and memory size, are defined as Kubernetes image resources through the Helm cluster.clusterSpec.resources property. Under resources, you can specify any of the YAML properties Kubernetes expects when configuring pods within a container. For example:

        cpu: 500m
        memory: 1000Mi
        cpu: 500m
        memory: 1000Mi
System Settings

System settings that control process limits that are normally defined through environment variables can be set with the cluster.clusterSpec.env properties. For example, the following YAML increases the Java maximum heap size and disables the collection of JVM statistics:

      VOLTDB_HEAPMAX: 3072
      VOLTDB_OPTS: -XX+PerfDisableSharedMem

One system setting that is not configurable through Kubernetes or Helm is whether the base platform has Transparent Huge Pages (THP) enabled or not. This is dependent of the memory management settings on the actual base hardware on which Kubernetes is hosted. Having THP enabled can cause problems with memory-intensive applications like VoltDB and it is strongly recommended that THP be disabled before starting your cluster. (See the section on Transparent Huge Pages in the VoltDB Administrator's Guide for an explanation of why this is an issue.)

If you are not managing the Kubernetes environment yourself or cannot get your provider to modify their environment, you will need to override VoltDB's warning about THP on startup by setting the cluster.clusterSpec.additionalArgs property to include the VoltDB start argument to disable the check for THP. For example:

      - "--ignore=thp"

2.2.2. Configuring the Database

In addition to configuring the environment VoltDB runs in, there are many different characteristics of the database itself you can control. These include mapping network interfaces and ports, selecting and configuring database features, and identifying the database schema, class files, and security settings.

The network settings are defined through the cluster.serviceSpec properties, where you can choose the individual ports and choose whether to expose them through the networking service (cluster.serviceSpec.type) you can also select. For example, the following YAML file disables exposure of the admin port and assigns the externalized client port to 31313:

    type: NodePort
      adminPortEnabled: false
      clientPortEnabled: true
      clientNodePort: 31313

The majority of the database configuration options for VoltDB are traditionally defined in an XML configuration file. When using Kubernetes, these options are declared using YAML and Helm properties.

In general, the Helm properties follow the same structure as the XML configuration, beginninging with "cluster.config". So, for example, where the number of sites per host is defined in XML as :

   <cluster sitesperhost="{n}"/>

It is defined in Kubernetes as:

        sitesperhost: {n}

The following sections give examples of defining common database configurations options using both XML and YAML. See Section A.6, “VoltDB Database Configuration Options” for a complete list of the Helm properties available for configuring the database. Command Logging

Command logging provides durability of the database content across failures. You can control the level of durability as well as the length of time required to recover the database by configuring the type of command logging and size of the logs themselves. In Kubernetes this is done with the cluster.config.deployment.commandlog properties. The following examples show the equivalent configuration in both XML and YAML:

XML Configuration FileYAML Configuration File
<commandlog enabled="true"
  <frequency time="300" 
        enabled: true
        synchronous: true
        logsize: 3072
          transactions 1000 Export

Export simplifies the integration of the VoltDB database with external databases and systems. You use the export configuration to define external "targets" the database can write to. In Kubernetes you define export targets using the cluster.config.deployment.export.configurations property. Note that the configurations property can accept multiple configuration definitions. In YAML, you specify a list by prefixing each list element with a hyphen, even if there is only one element. The following examples show the equivalent configuration in both XML and YAML for configuring a file export connector:

XML Configuration FileYAML Configuration File
           - target: eventlog
             type: file
                type: csv
                nonce: eventlog          Security and User Accounts

There are a number of options for securing a VoltDB database, including basic usernames and passwords in addition to industry network solutions such as Kerberos and SSL. Basic security is enabled in the configuration with the cluster.config.deployment.security.enabled property. You must also use the property and its children to define the actual usernames, passwords, and assigned roles. Again, the users property expects a list of sub-elements so you must prefix each set of properties with a hyphen.

Finally, if you do enable basic security, you must also tell the VoltDB operator which account to use when accessing the database. To do that, you define the cluster.config.auth properties, as shown below, which must specify an account with the built-in administrator role. The following examples show the equivalent configurations in both XML and YAML, including the assignment of an account to the VoltDB Operator:

XML Configuration FileYAML Configuration File
<security enabled="true"/>
  <user name="admin" 
  <user name="mitty" 
        enabled: true
        - name: admin
          password: superman
          roles: administrator
        - name: mitty
          password: thurber
          roles: user
      username: admin
      password: superman