1.2. Setting Up Your Kubernetes Environment

Documentation

VoltDB Home » Documentation » VoltDB Kubernetes Administrator's Guide

1.2. Setting Up Your Kubernetes Environment

Before you can run VoltDB in a containerized environment, you must be sure your host systems and client are configured with the right software and permissions to support VoltDB. The following sections outline:

  • What products are required on both the host environment and the local client you use to control Kubernetes and VoltDB

  • How to configure the host environment and user accounts to run the VoltDB components

  • How to configure your local client to control Kubernetes and the Helm charts

  • How to set permissions in Kubernetes and Docker to allow access to the VoltDB components

1.2.1. Product Requirements

Before you start, you must make sure you have the correct software products and versions installed on both the host system and your local client. The host environment is the set of servers where Kubernetes is installed, whether they are systems you set up yourself or hosted by a third-party cloud service, such as the Google Cloud Platform or Microsoft Azure. The local client environment is the system, such as a desktop or laptop, you use to access the services.

The following are the software requirements for running VoltDB in Kubernetes.

Host Environment

  • Kubernetes V1.23.x through V1.26.x

VoltDB on Kubernetes has been validated for the following cloud service providers:

  • AWS

  • Azure

  • Google Cloud

  • OpenShift

  • Tanzu

Client Environment

  • Kubectl V1.22 or later[1]

  • Helm V3.6.x or later

Optionally, you may want to install VoltDB on the client so you can use the voltadmin and sqlcmd command utilities to access the database remotely. If not, you can still use kubectl to create an interactive shell process on one of the server instances and run the utilities directly on the Kubernetes pods.

1.2.2. Configuring the Host Environment and Accounts

Once you have the necessary software installed, you must prepare the host environment to run VoltDB. This includes adding the appropriate Docker and chart repositories to Helm and configuring your host account with the permissions necessary to access those repositories.

First, you need accounts on the Kubernetes host environment and on the docker repository where the VoltDB images are stored, https://docker.io. To run the VoltDB Helm charts, your accounts must be set up with the following permissions:

  • Your Kubernetes host account must have sufficient permissions to allocate persistent volumes and claims and create and manage pods.

  • Your Docker repository account must have permission to access the VoltDB docker images. Access to the VoltDB docker images is assigned to VoltDB Enterprise customers on a per account basis. Contact VoltDB support for more information.

1.2.3. Configuring the Client

Next you must configure your client environment so you can communicate with and control Kubernetes and the Helm charts. First, install the Kubernetes and Helm command line interfaces, kubectl and helm. Next, configure the services to access the appropriate remote accounts and repositories.

The primary setup task for kubectl is creating the appropriate context for accessing the Kubernetes host you will be using. This is usually done as part of the installation or with a Kubconfig file and the kubectl config command. Once you have a context defined, you can use the kubectl cluster-info command to verify that your client is configured correctly.

For helm, you must add a link to the VoltDB docker repository, using the helm repo add command:

$ helm repo add voltdb \
     https://voltdb-kubernetes-charts.storage.googleapis.com

The first argument to the command ("voltdb") is a short name for referencing the repository in future commands. You can specify whatever name you like. The second argument is the location of the repository itself and must be entered as shown above.

Note

Helm first looks in local folders for charts you specify, then in the repositories. So if the short name you use matches a local directory, they can conflict and cause errors. In that case, you may want to choose a different name, such as "voltkube", to avoid any ambiguity. Then the chart locations you use in Helm commands would be "voltkube/voltdb" rather than "voltdb/voltdb" as shown in the examples.

1.2.4. Granting Kubernetes Access to the Docker Repository

Finally, you need to tell Kubernetes to access the Docker repository using the credentials for your Docker account. There are several ways to do this. You can specify your credentials on the helm command line each time you install a new VoltDB cluster. You can save the credentials in a YAML file with other parameters you pass to helm. Or you can set the credentials in a Kuerbernetes secret using kubectl.

The advantage of using a secret to store the credentials is that you only need to define them once and they are not easily discovered by others, since they are encrypted. To create a Kubernetes secret you use the kubectl create secret command, specifying the type of secret (docker-registry) and the name of the secret (which must be dockerio-registry), plus the individual credential elements as arguments:

$ kubectl create secret docker-registry dockerio-registry \
   --docker-username=johndoe          \
   --docker-password='ThisIsASecret'  \
   --docker-email="jdoe@anybody.org

Once you add the secret, you do not need to specify them again. If, on the other hand, you prefer to specify the credentials when you issue the helm commands to initialize the VoltDB cluster, you can supply them as the following helm properties using the methods described in Chapter 2, Configuring the VoltDB Database Cluster:

  • global.image.credentials.username

  • global.image.credentials.password



[1] Kubectl on the client must be within one minor version of Kubernetes in the host environment. For example, if Kubernetes is at version 1.23, Kubectl can be 1.22, 1.23, or 1.24. See the Kubernetes version skew documentation for further information.