Kubernetes

Quick Start Guide

NuoDB works with Kubernetes locally or in the cloud. To get started with NuoDB in Kubernetes you will need to have a running Kubernetes cluster in either environment.

Cloud

NuoDB is supported for production use in a wide range of Kubernetes environments, including:

Red Hat OpenShift
Google Anthos GKE or Google Cloud GKE
Amazon EKS
Azure AKS

Local

For test, development, and evaluation purposes, the following can also be used:

Docker Desktop Kubernetes
Rancher’s k3d
Canonical’s Microk8s

Note	For more information on running Kubernetes locally on your desktop or laptop refer to Appendix A - Running Kubernetes Locally.

Prerequisites

Important

A running Kubernetes cluster.
kubectl installed and able to access your cluster.
Helm installed.

Recommended: Sufficient familiarity with Kubernetes to use kubectl get events and kubectl logs to diagnose problems.

Installing NuoDB

Setup Kubernetes

Create a Kubernetes namespace for your NuoDB installation and make it the default.

$> kubectl create namespace nuodb
$> kubectl config set-context --current --namespace=nuodb

Setup NuoDB Helm charts

$> helm repo add nuodb https://storage.googleapis.com/nuodb-charts

Look at the available Helm charts

$> helm search repo
NAME                        CHART VERSION   APP VERSION DESCRIPTION
nuodb/admin                 3.1.0           4.0.0       Administration tier for NuoDB.
nuodb/database              3.1.0           4.0.0       NuoDB distributed SQL database.
nuodb/restore               3.1.0           4.0.0       On-demand restore a NuoDB SQL database.
nuodb/storage-class         3.1.0           4.0.0       Storage classes for NuoDB.
nuodb/transparent-hugepage  3.1.0           4.0.0       Disable disables transparent_hugepage on Linux ...

Disable transparent huge pages

$> helm install thp nuodb/transparent-hugepage

Helm returns immediately but in the background it takes a short while to run. Check by running:

$> kubectl get all

You should see one or more pods running (depending on the number of nodes in your cluster) and a daemon set called thp-transparent-hugepage.

Setting storage class

Note	If you have a default storage class, skip this step.

We need a persistent storage so the Helm charts will make persistent volume claims. A default storage class is expected. To find the storage class, run:

$> kubectl get storageclass
NAME                   PROVISIONER             RECLAIMPOLICY   VOLUMEBINDINGMODE      ALLOWVOLUMEEXPANSION   AGE
local-path (default)   rancher.io/local-path   Delete          WaitForFirstConsumer   false                  97m

Note that the local-path storage class is marked as default. Your storage class(es) may have different names and/or you may have more than one storage class, but there needs to be one marked as default.

If a default storage class is not set: If you are running locally, consult the documentation for your Kubernetes installation on how to set the default storage class. If you are running in the cloud, use our storage chart to set up the default, where xxx is amazon, google or azure.

$> helm install nuodb/storage-class storage --set cloud.provider=xxx

Setup of the admin layer

There are many options to configure the NuoDB Admin Processes (APs) but this command uses all the defaults.

$> helm install admin nuodb/admin

It will download the latest NuoDB container and run a single AP. Wait until admin pod is RUNNING; watch by running kubectl get all periodically. Eventually you should see an admin pod called admin-nuodb-cluster0-0 marked as RUNNING.
Check your NuoDB domain by running nuocmd inside the admin pod:

$> kubectl exec admin-nuodb-cluster0-0 -- nuocmd show domain
server version: 4.1.2-2-019a14f800, server license: Community
server time: 2020-04-19T16:34:45.368, client token: ...
Servers:
  [admin-nuodb-cluster0-0] admin-nuodb-cluster0-0.nuodb.default.svc.cluster.local:48005
    [last_ack = 0.95] [member = ADDED] [raft_state = ACTIVE]
    (LEADER, Leader=admin-nuodb-cluster0-0, log=0/2/2) Connected *
Databases:

Database setup

We need to override some of the default configuration:

Set the database name.
Set DBA "root" username and password.
Enable external access to the processes inside the cluster.
Reduce the disk used for storing the database data (what NuoDB calls its archive) to 5G.
Disable Hot Copy (online) backup, not needed for this quick start but enabled by default. Enable an Storage Manager (SM) that does not run backups instead.
Reduce the very large defaults for CPU and memory resources.

Tip	Overriding these many options using `--set` is very tedious, see Appendix B - Using a Configuration File for the alternative option of copying the configuration values to a `YAML` file and modifying them.

Start the database with its parameters:

Windows

$> helm upgrade demo nuodb/database --install --create-namespace --namespace nuodb ^
  --set database.name=demo ^
  --set database.rootUser=dba ^
  --set database.rootPassword=dba ^
  --set database.te.labels.external-address=localhost ^
  --set database.te.labels.external-port=48006 ^
  --set database.persistence.size=5Gi ^
  --set database.sm.hotCopy.replicas=0 ^
  --set database.sm.noHotCopy.replicas=1 ^
  --set database.sm.resources.requests.cpu=500m ^
  --set database.sm.resources.requests.memory=500M ^
  --set database.sm.resources.limits.cpu=500m ^
  --set database.sm.resources.limits.memory=500M ^
  --set database.te.resources.requests.cpu=500m ^
  --set database.te.resources.requests.memory=500M ^
  --set database.te.resources.limits.cpu=500m ^
  --set database.te.resources.limits.memory=500M

Linux/MacOS

$> helm upgrade demo nuodb/database --install --create-namespace --namespace nuodb \
  --set database.name=demo \
  --set database.rootUser=dba \
  --set database.rootPassword=dba \
  --set database.te.labels.external-address=localhost \
  --set database.te.labels.external-port=48006 \
  --set database.persistence.size=5Gi \
  --set database.sm.hotCopy.replicas=0 \
  --set database.sm.noHotCopy.replicas=1 \
  --set database.sm.resources.requests.cpu=500m \
  --set database.sm.resources.requests.memory=500M \
  --set database.sm.resources.limits.cpu=500m \
  --set database.sm.resources.limits.memory=500M \
  --set database.te.resources.requests.cpu=500m \
  --set database.te.resources.requests.memory=500M \
  --set database.te.resources.limits.cpu=500m \
  --set database.te.resources.limits.memory=500M

This takes a while to run. Monitor by running kubectl get all periodically. You should see two pods, sm-database-nuodb-cluster0-test-hotcopy-0 and te-database-nuodb-cluster0-test-xxxx (where xxxx is a random suffix chosen by Kubernetes). They should eventually come up and enter the RUNNING state.

Look at the domain again:

$> kubectl exec admin-nuodb-cluster0-0 -- nuocmd show domain
Defaulted container "admin" out of: admin, nuocollector, nuocollector-config, init-disk (init)
server version: 4.2.8.vee-1-4f2e2257bc, server license: Community
server time: 2023-01-27T19:41:19.754, client token: ....
Servers:
  [admin-nuodb-cluster0-0] admin-nuodb-cluster0-0.nuodb.nuodb.svc.cluster.local:48005
     [last_ack = 1.54] ACTIVE (LEADER, Leader=admin-nuodb-cluster0-0, log=10/74/74) Connected *
Databases:
  demo [state = RUNNING]
    [SM] sm-demo-nuodb-cluster0-demo-database-0/10.42.0.16:48006 [start_id = 12]
      [server_id = admin-nuodb-cluster0-1] [pid = 96] [node_id = 1] [last_ack =  3.45] MONITORED:RUNNING
    [TE] te-demo-nuodb-cluster0-demo-database-545f6b5d9c-4w46s/10.42.3.7:48006 [start_id = 13]
      [server_id = admin-nuodb-cluster0-2] [pid = 43] [node_id = 2] [last_ack =  9.41] MONITORED:RUNNING

What has Helm done for us? List the installed charts:

$> helm ls
NAME  NAMESPACE REVISION    UPDATED         STATUS      CHART                       APP VERSION
admin nuodb     2           2023-01-27 ...  deployed    admin-3.4.0                 4.2.1
demo  nuodb     1           2023-01-28 ...  deployed    database-3.4.0              4.2.1
thp   nuodb     1           2023-01-27 ...  deployed    transparent-hugepage-3.4.0  4.2.1

Access the Database

Port-forwarding

Use port-forwarding to map requests from your local machine to processes in the cluster:

Windows

Start two new cmd windows.
In the first, run kubectl port-forward svc/nuodb-clusterip 48004:48004 --namespace nuodb.
In the second run kubectl port-forward svc/demo-nuodb-cluster0-demo-database-clusterip 48006:48006 --namespace nuodb.
Return to your original window.

Linux/MacOS:

$> kubectl port-forward svc/nuodb-clusterip 48004:48004 --namespace nuodb > /dev/null 2>&1 &
$> kubectl port-forward svc/demo-nuodb-cluster0-demo-database-clusterip 48006:48006 --namespace nuodb > /dev/null 2>&1 &

Ports 48004 and 48006 are the default ports for an AP and a TE respectively. You can now access database demo as if it was running locally on your machine.

Connect to the database

From your favorite SQL tool (such as DBeaver or DBVisualizer)

Host: localhost
Port: 48004
Database name: demo
Username: dba
Password: dba

OR

Running NuoDB’s command-line SQL tool nuosql from inside the AP pod

$> $ kubectl exec -it admin-nuodb-cluster0-0 -- bash
Defaulted container "admin" out of: admin, nuocollector, nuocollector-config, init-disk (init)
bash-4.4$ nuosql demo --user dba --password dba --connection-property PreferInternalAddress=true
SQL>

Use the SYSTEM.Nodes table to view the domain:

SQL> SELECT ID, STARTID, ADDRESS, PORT, STATE, TYPE, RELEASE_VER FROM SYSTEM.Nodes;
 ID  STARTID   ADDRESS   PORT   STATE     TYPE          RELEASE_VER
 --- -------- ---------- ----- ------- ----------- ----------------------
  1     12    10.42.0.16 48006 Running Storage     4.2.1.vee-3-c42866be32
  2     13    10.42.3.7  48006 Running Transaction 4.2.1.vee-3-c42866be32

Nodes table show two NuoDB processes (or nodes) running - a Storage Manager (SM) and a Transaction Engine (TE).

For full details of our Helm charts and their configuration, refer to https://github.com/nuodb/nuodb-helm-charts.

Import the Sample Ice Hockey Database

Open a bash shell session in the "admin-nuodb-cluster0-0" pod:

$> kubectl exec -it admin-nuodb-cluster0-0 -- bash

Use the following commands to import the sample ice hockey database schemas into the empty "demo" database:

$> nuosql demo --schema hockey --user dba --password dba --connection-property PreferInternalAddress=true </opt/nuodb/samples/quickstart/sql/create-db.sql

$> nuosql demo --schema hockey --user dba --password dba --connection-property PreferInternalAddress=true </opt/nuodb/samples/quickstart/sql/Players.sql

$> nuosql demo --schema hockey --user dba --password dba --connection-property PreferInternalAddress=true </opt/nuodb/samples/quickstart/sql/Scoring.sql

$> nuosql demo --schema hockey --user dba --password dba --connection-property PreferInternalAddress=true </opt/nuodb/samples/quickstart/sql/Teams.sql

Try Out NuoSQL

Invoke an interactive nuosql session using the name of the "demo" database. Try out some simple nuosql commands:

$> nuosql demo --schema hockey --user dbat --password dba --connection-property PreferInternalAddress=true

SQL> use hockey;
SQL> show tables;
Tables in schema HOCKEY
        HOCKEY
        PLAYERS
        SCORING
        TEAMS
        VW_PLAYER_STATS is a view

In the above example:

SQL> use hockey;

switches to using the "HOCKEY" schema from the default "USER" schema and:

SQL> show tables;

shows the tables in that schema.

Try out some more nuosql commands on the hockey database, such as:

SQL> select * from TEAMS where TEAMS.YEAR=2011;

Now try a more advanced query such as:

SQL> select p.lastName, p.firstName, s.year, s.teamID, s.gamesPlayed
from   players p, scoring s
where  p.birthCountry='Slovakia'
and    s.playerID = p.playerID order by p.lastName;

When you are finished, type quit to exit the interactive nuosql session.

Type exit to exit the bash shell in the "admin-nuodb-cluster0-0" container.

Appendix A - Running Kubernetes Locally

Three possible options are:

Docker Desktop has an option in its Settings to run up a Kubernetes cluster. Just tick the box, apply and wait a few minutes. It automatically installs kubectl and sets up kubeconfig to enable access the cluster.
Rancher’s k3d allows you to run their minimal Kubernetes (k3s) on top of Docker (so you still need a Docker installation). It is lighter weight than the one built into Docker Desktop.
Canonical’s Microk8s is a third option that does not require Docker. All three are available for Windows, MacOS and Linux. Helm is available at GitHub. There is an installer for each of the three platforms listed above, or use the appropriate package manager.
There is a binary install for most platforms, or use the package manager for your platform.
Windows users should download the installer zip, unpack it and copy helm.exe to C:\Windows\System32.

Appendix B - Using a Configuration File

As an alternative to using --set, it is typically easier to copy and modify the database Helm chart’s configuration. Especially if you wish to make further changes later. Moreover, the file can be kept under version control. The following sets up the same configuration you used above.

Get the db-values.yaml configuration file for the chart:

$> helm inspect values nuodb/database > db-values.yaml

Make the following changes in db-values.yaml:

Seach for name: demo, you should see this section. This is where you can change the database name and set the root DBA user name and password.

database:
  ## Provide a name in place of the chart name for `app:` labels
  ##
  #nameOverride: ""
  ## Provide a name to substitute for the full names of resources
  ##
  #fullnameOverride: ""
  # name
  # NuoDB Database name.  must consist of lowercase alphanumeric
  #characters '[a-z0-9]+'
  name: demo
  # rootUser
  # Name of Database user
  rootUser: dba
  # rootPassword
  # Database password
  rootPassword: secret

Scroll down a short way and set persistence size to 5G as shown (the default of 20G is unnecessary):

  ## Import Environment Variables from one or more configMaps
  # Ex: configMapRef: [ myConfigMap, myOtherConfigMap ]
  ##
  envFrom:
    configMapRef: []
  persistence:
    size: 5Gi
    accessModes:
      - ReadWriteOnce
    # storageClass: "-"

Search for hotCopy: (note the colon) and disable hotcopy (online) backups by setting replicas to 0:

    # Settings for storage manager (SM) nodes with hotcopy enabled.
    # Total SM Limit is 1 in CE version of NuoDB
    # These SMs have hotcopy backup enabled. To start SMs without hotcopy use
    # database.sm.noHotCopy.replicas
    # All time values are in seconds unless the unit is included in the name.
    hotCopy:
      enablePod: true
      enableBackups: true
      replicas: 0

Search for noHotCopy: (note the colon) and enable an SM that does not perform backups by setting replicas to 1:

    # Number of storage manager (SM) nodes that do not have hotcopy backup enabled.
    # SM Limit is 1 in CE version of NuoDB
    # These SMs do not have hotcopy enabled, to start SMs with hotcopy use
    # database.sm.HotCopy.replicas
    noHotCopy:
      enablePod: true
      replicas: 1

Search for resources: (note the colon) and modify it to match the following. The default values are set for a reasonably sized production database and are too big for what we are doing today. These set the resources the SM will use.

    ## resources
    # k8s resource min (request) and max (limit)
    # min is also used for the target maximum memory used by the cache (NuoDB --mem option)
    resources:
      limits:
        cpu: 500m
        memory: 500M
      requests:
        cpu: 500m
        memory: 500M

Search for resources: again and make the same changes. These are the TE resources.

Just below you should see a labels section, modify to add two labels as shown to enable database access from outside the cluster. Don’t forget to remove the curly brackets after labels:

    ## Affinity, selector, and tolerations
    # There are expanded as YAML, and can include variable and template references
    affinity: {}
    # nodeSelector: {}
    # tolerations: []
    # labels
    # Additional Labels given to the TEs started
    labels:
     external-address: localhost
     external-port: 48006

Save your changes. Since you might deploy more than one database, make the name of Helm deployment the same as the name of your database. Deploy the chart by running:

$> helm install <db-name> nuodb/database --values db-values.yaml

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

tutorial.adoc

tutorial.adoc

Kubernetes

Quick Start Guide

Prerequisites

Installing NuoDB

Setup Kubernetes

Setup NuoDB Helm charts

Disable transparent huge pages

Setting storage class

Setup of the admin layer

Database setup

Access the Database

Port-forwarding

Connect to the database

Import the Sample Ice Hockey Database

Try Out NuoSQL

Appendix A - Running Kubernetes Locally

Appendix B - Using a Configuration File

Files

tutorial.adoc

Latest commit

History

tutorial.adoc

File metadata and controls

Kubernetes

Quick Start Guide

Prerequisites

Installing NuoDB

Setup Kubernetes

Setup NuoDB Helm charts

Disable transparent huge pages

Setting storage class

Setup of the admin layer

Database setup

Access the Database

Port-forwarding

Connect to the database

Import the Sample Ice Hockey Database

Try Out NuoSQL

Appendix A - Running Kubernetes Locally

Appendix B - Using a Configuration File