Public Repository

Last pushed: 2 months ago
Short Description
NuoDB Community Edition
Full Description

Supported tags

  • [3.3.0, 3.3, latest]
  • [3.2.2, 3.2]

Quick reference

What is NuoDB?

NuoDB is an elastic SQL database for hybrid cloud applications that scales-out on-demand; ensures continuous availability; and provides standard database interfaces, operations and guarantees of consistency and durability. The database is accessed by clients through an ANSI SQL interface as a single logical database, even across data centers or Amazon availability zones.

A NuoDB database consists of 3 separate layers:

  • Admin for operational tasks;
  • TE for (ACID) SQL and caching;
  • SM for storage.

The TE and SM layers form a distributed, peer-to-peer mesh of process nodes which provides independent and highly available handling of the SQL, caching, and storage processing. This allows the database operator to elastically scale out and scale in each layer independently, and to provision appropriately to guarantee availabliity in the face of failures without any interruption to the database service.

Particularly well-suited to hybrid cloud, distributed and microservices architectures, container environments, and dynamic operational workloads, NuoDB also preserves the best of the traditional database world with its support of ANSI SQL and full ACID transactions.

For more information and related downloads for NuoDB and other NuoDB products, please visit www.nuodb.com.

How to use this image

The nuodb docker image is capable of running an Admin, SM, or TE process, in addition to executing CLI commands.
The normal topology is that each Admin, SM and TE process runs in a dedicated container.

At a minimum, a NuoDB database requires 1 each of an Admin, SM and TE process - although typically there are multiple instances of each process type to ensure HA.

For multi-database deployments, multiple databases can share a single set of Admin containers.

The following steps guide you through the total database lifecycle, inclusive of creating a database,
backup the database, simulate a failure, then restore the database.

create a network for nuodb

$ docker network create nuodb-net
445bfd1f94ca844e9c906ac17113639145e6276a5e6107d46f78574edb8cbf58

start an administration process

$ docker run -d --name ad1 --rm \
    --hostname ad1 \
    --net nuodb-net \
    -p 8888:8888 \
    -p 48004:48004 \
    -p 48005:48005 \
    -e "NUODB_DOMAIN_ENTRYPOINT=ad1" \
    ${IMG_NAME} nuoadmin
$ docker logs ad1
...
NuoAdmin Server running
...

create volumes for the archive and backup

$ mkdir vol1
$ chmod a+rw vol1
$ mkdir vol2
$ chmod a+rw vol2

start a storage manager

$ docker run -d --name sm1 --hostname sm1 --rm \
    --volume $(pwd)/vol1:/var/opt/nuodb/backup \
    --volume $(pwd)/vol2:/var/opt/nuodb/archive \
    --net nuodb-net ${IMG_NAME} nuodocker \
    --api-server ad1:8888 start sm \
    --db-name test --server-id ad1 \
    --dba-user dba --dba-password dba \
    --labels "zone east node localhost" \
    --archive-dir /var/opt/nuodb/archive
$ docker logs sm1
...
2018-08-15T19:14:48.395+0000 [14] (test node -1) Node state transition from Unknown to Running
...

start a transaction engine

$ docker run -d --name te1 --hostname te1 --rm \
    --net nuodb-net ${IMG_NAME} nuodocker \
    --api-server ad1:8888 start te \
    --db-name test --server-id ad1

show domain summary

$ docker run -it --net nuodb-net ${IMG_NAME} \
    nuocmd --api-server ad1:8888 show domain

server version: 3.3.master-5770-17ebc8a0ae, server license: Enterprise
server time: 2018-08-15T19:33:39.134000, client token: 190b8e7a7d6cdf65ca2d27b61e70bc25bd6c228c
Servers:
  [nuoadmin0] nuoadmin0:48005 (LEADER, Leader=nuoadmin0) ACTIVE:Connected *
Databases:
  test [RUNNING]
    [SM] sm1/172.19.0.3:48006 (Default) [sid = 0] [server = nuoadmin0] MONITORED:RUNNING
    [TE] te1/172.19.0.4:48006 (Default) [sid = 1] [server = nuoadmin0] MONITORED:RUNNING

connect to it using nuosql

$ docker run --rm --net nuodb-net -it ${IMG_NAME} \
 nuosql test@ad1 --user dba --password dba

SQL> create table foo (id int);
SQL> insert into foo (id) values(1);
SQL> show tables;

    Tables in schema USER
        FOO

SQL> select * from foo;

 ID  
 ---

  1  

SQL> exit

initiate hot-copy backup

Make sure the backup directory is empty:

$ rm -fr vol1/*
...

Initiate the backup:

$ docker run -it \
    --net nuodb-net ${IMG_NAME} nuodocker \
    --api-server ad1:8888 hotcopy database --type full \
    --default-backup-dir /var/opt/nuodb/backup --db-name test

HotCopyResponse(coordinator_start_id=0, id=326bcda1-7975-4c0e-9b58-e9db69dfbdf7)

poll for completion of the backup

$ docker run -it \
    --net nuodb-net ${IMG_NAME} nuocmd \
    --api-server ad1:8888 get hotcopy-status \
    --coordinator-start-id 0 \
    --hotcopy-id 326bcda1-7975-4c0e-9b58-e9db69dfbdf7

HotCopyResponse(begin_timestamp=2018-08-30 20:19:08, coordinator_start_id=0, end_timestamp=2018-08-30 20:19:09, id=326bcda1-7975-4c0e-9b58-e9db69dfbdf7, message=Hot copy successfully completed, status=completed)

add another record

$ docker run --rm --net nuodb-net -it ${IMG_NAME} \
nuosql test@ad1 --user dba --password dba

SQL> insert into foo (id) values(2);
SQL> select * from foo;

ID  
---

 1  
 2  

SQL> exit

initiate an incremental backup

$ docker run -it \
    --net nuodb-net ${IMG_NAME} nuodocker \
    --api-server ad1:8888 hotcopy database --type incremental \
    --default-backup-dir /var/opt/nuodb/backup --db-name test

HotCopyResponse(coordinator_start_id=0, id=04f688e5-89e2-43e0-8ded-903854f01340)

poll for completion of the incremental backup

$ docker run -it \
    --net nuodb-net ${IMG_NAME} nuocmd \
    --api-server ad1:8888 get hotcopy-status \
    --coordinator-start-id 0 \
    --hotcopy-id 04f688e5-89e2-43e0-8ded-903854f01340

HotCopyResponse(begin_timestamp=2018-08-30 20:38:03, coordinator_start_id=0, end_timestamp=2018-08-30 20:38:03, id=04f688e5-89e2-43e0-8ded-903854f01340, message=Hot copy successfully completed, status=completed)

The results in the backup directory are:

$ ls -al vol1total 8
drwxrwxrwx   6 rbuck  staff  192 Aug 30 20:38 .
drwxr-xr-x  11 rbuck  staff  352 Aug 30 20:12 ..
drwxr-xr-x   4 rbuck  staff  128 Aug 30 20:38 1.inc
drwxr-xr-x   4 rbuck  staff  128 Aug 30 20:19 full
-rw-r--r--   1 rbuck  staff  409 Aug 30 20:19 state.xml
drwxr-xr-x   2 rbuck  staff   64 Aug 30 20:38 tmp

stop the database

$ docker stop te1
te1
$ docker stop sm1
sm1

delete the old archive

$ rm -fr vol2/*
...

restore the archive

First we need to restore the backup onto the archive directory using the following command:

$ docker run -d --name sm2 --hostname sm2 --rm \
    --volume $(pwd)/vol1:/var/opt/nuodb/backup \
    --volume $(pwd)/vol2:/var/opt/nuodb/archive \
    --net nuodb-net ${IMG_NAME} nuodocker \
    --api-server ad1:8888 restore archive \
    --origin-dir /var/opt/nuodb/backup \
    --restore-dir /var/opt/nuodb/archive \
    --db-name restored

start the restored database storage manager

Then we simply start the SM as before, but with a new database name:

$ docker run -d --name sm1 --hostname sm1 --rm \
    --volume $(pwd)/vol1:/var/opt/nuodb/backup \
    --volume $(pwd)/vol2:/var/opt/nuodb/archive \
    --net nuodb-net ${IMG_NAME} nuodocker \
    --api-server ad1:8888 start sm \
    --db-name restored --server-id ad1 \
    --dba-user dba --dba-password dba \
    --archive-dir /var/opt/nuodb/archive
$ docker logs sm1
...
2018-08-15T19:14:48.395+0000 [14] (test node -1) Node state transition from Unknown to Running
...

start the restored database transaction engine

$ docker run -d --name te1 --hostname te1 --rm \
    --net nuodb-net ${IMG_NAME} nuodocker \
    --api-server ad1:8888 start te \
    --db-name restored --server-id ad1
f4cb6ade4b069eadcd48de05b329fefc2c2a9b60d0369c2acc5f9fda51155b28

check SQL state

$ docker run --rm --net nuodb-net -it ${IMG_NAME} \
 nuosql restored@ad1 --user dba --password dba

SQL> show tables;

    Tables in schema USER
        FOO

SQL> select * from foo;

 ID  
 ---

  1  
  2  

SQL> exit

show domain summary

$ docker run -it --net nuodb-net ${IMG_NAME} \
    nuocmd --api-server ad1:8888 show domain

server version: 3.3.rel33dev-26-77f3f662ec, server license: Enterprise
server time: 2018-08-30T20:42:50.748000, client token: 1deb61c8b3f7758b84c1b76b247e247397c480ba
Servers:
  [ad1] ad1:48005 (LEADER, Leader=ad1) ACTIVE:Connected *
Databases:
  restored [RUNNING]
    [SM] sm1/172.18.0.3:48006 (Default) [sid = 2] [server = ad1] MONITORED:RUNNING
    [TE] te1/172.18.0.4:48006 (Default) [sid = 3] [server = ad1] MONITORED:RUNNING
  test [NOT_RUNNING]

Configuration

Paths

The nuodb image uses the standard paths for a rpm/deb install:

  • Configuration: /etc/nuodb (nuoadmin.conf, nuodb.config)
  • Runtime data: /var/opt/nuodb (raftlog, archive, journal)
  • Logging and cores: /var/log/nuodb (logfiles, heapdump, cores)

In general /var/opt/nuodb/ should be mounted to some performant, durable storage. We recomend mounting /var/log/nuodb to networked storage so debugging information can be gathered without having to restart the container.

Ports

The nuodb image exposes the following ports:

Port Purpose
8888 used to access the administration REST API
48004 port the admin process listens for incoming messages
48005 port used for storage manager and transaction engine
48006 port used for storage manager and transaction engine

Environment Variables

NUODB_HOME

Optional. Do NOT change. Default: /opt/nuodb

NUODB_ALTERNATIVE_ENTRYPOINT

Optional. If provided, Admin containers will ping this address and if the ping is successful the container will override NUODB_DOMAIN_ENTRYPOINT and set it to NUODB_ALTERNATIVE_ENTRYPOINT.

NUODB_SERVERID

Optional. Defaults to the hostname of the container unless otherwise specified. Used by the admin process to identify which server it is running on.

NUODB_JAVA_OPTS

Optional. The java options specified by this variable are used when running the admin process.

NUODB_ADMIN_PORT

Optional. Defaults to 48005.

NUOCMD_SERVER_FORMAT

Optional. Configures the nuocmd output format for servers.

NUOCMD_DB_FORMAT

Optional. Configures the nuocmd output format for database banner.

NUOCMD_PROCESS_FORMAT

Optional. Configures the nuocmd output format for process lists.

NUOCMD_ARCHIVE_FORMAT

Optional. Configures the nuocmd output format for archive lists.

Configuration Files

Users who wish to have more control over their nuodb configuration can supply their own configurations by mounting the /etc/nuodb on a directory that contains the desired configuration files.

For an Admin container, the host directory that is mounted in must contain the following files:

  • nuoadmin.conf
  • nuoadmin.rest.yml
  • nuoadmin.logback.xml

Enabling TLS

TLS is enabled by default with a default certificate. For production use users MUST provide an alternate PKCS#12 keystore.

For the purposes of illustration, we will show how to generate your own self-signed certificate, and then use that to start an admin process.

The following files are required:

  • ca.key CA private key
  • ca.cert - CA public certificate
  • client.key - CLI private key
  • client.csr - CLI certificate signing request
  • client.cert - CLI public certificate
  • client.pem - CLI private key and public certificate (catted in one file).
  • server.key - Server node private key for the domain.
  • server.csr - Server certificate signing request
  • server.cert - Server node public certificate for the domain.
  • server.p12 - Server node PKCS#12 keystore.

Every website seems to differ for file naming conventions of these; we use .cert
for the public portion, .key for the private portion, .pem for the combined,
and .p12 for keystores and truststores.

The following steps walk you through setting up TLS security:

  1. Write down the Common Name (CN) for your SSL Certificate.
    The CN is the fully qualified name for the system that uses the
    certificate. If you are using Dynamic DNS, your CN should have a
    wild-card, for example: *.api.com. Otherwise, use the hostname or
    IP address set in your Gateway Cluster (for example. 192.16.183.131
    or dp1.acme.com).

  2. Run the following OpenSSL command to generate your self-signed CA private and public key:

     $ openssl req -newkey rsa:2048 -nodes -x509 -days 365 \
         -subj '/C=US/ST=MA/L=Boston/CN=localhost/O=NuoDB/OU=Eng' \
         -keyout ca.key -out ca.cert
    
  3. Review the created CA certificate:

     $ openssl x509 -text -noout -in ca.cert
    
  4. Generate a client private key and CSR:

     $ openssl req -newkey rsa:2048 -nodes \
        -subj '/C=US/ST=MA/L=Boston/CN=localhost/O=NuoDB/OU=Eng' \
        -keyout client.key -out client.csr
    
  5. Generate a client certificate based upon the CA certificate:

     $ openssl x509 -req -in client.csr -CA ca.cert -CAkey ca.key \
         -CAcreateserial -days 1024 -sha256 -out client.cert 
    
  6. Generate a server private key and CSR:

     $ openssl req -newkey rsa:2048 -nodes \
        -subj '/C=US/ST=MA/L=Boston/CN=localhost/O=NuoDB/OU=Eng' \
        -keyout server.key -out server.csr
    
  7. Generate a server certificate based upon the CA certificate:

     $ openssl x509 -req -in server.csr -CA ca.cert -CAkey ca.key \
         -CAcreateserial -days 1024 -sha256 -out server.cert 
    
  8. Generate a Java truststore:

     $ export PASSWORD=changeIt
     $ keytool -importcert -file ca.cert -trustcacerts -alias ca-cert \
            -keystore truststore.p12 -storepass ${PASSWORD} -storetype pkcs12 -noprompt
     $ keytool -importcert -file server.cert -alias nuoadmin \
            -keystore truststore.p12 -storepass ${PASSWORD} -storetype PKCS12 -noprompt
     $ keytool -importcert -file client.cert -alias nuocmd \
            -keystore truststore.p12 -storepass ${PASSWORD} -storetype PKCS12 -noprompt
    
  9. Validate the truststore:

     $ export PASSWORD=changeIt
     $ keytool -list -keystore truststore.p12 -storepass ${PASSWORD} -storetype PKCS12
    
  10. Generate a server PKCS#12 keystore with the key and certificate:

    $ export PASSWORD=changeIt
    $ openssl pkcs12 -inkey server.key -in server.cert -export \
        -out server.p12 -passout pass:${PASSWORD}
    
  11. Validate your P12 file.

    $ openssl pkcs12 -in server.p12 -noout -info -passin pass:${PASSWORD}
    
     MAC Iteration 2048
     MAC verified OK
     PKCS7 Encrypted data: pbeWithSHA1And40BitRC2-CBC, Iteration 2048
     Certificate bag
     PKCS7 Data
     Shrouded Keybag: pbeWithSHA1And3-KeyTripleDES-CBC, Iteration 2048
    
  12. Volume mount the configuration file and PKCS#12 files when starting an admin node:

    $ cat client.cert > client.pem
    $ cat client.key >> client.pem
    $ docker run -d --name ad1 --rm \
        --hostname ad1 \
        --net nuodb-net \
        --volume $(pwd)/truststore.p12:/etc/nuodb/keys/nuoadmin-truststore.p12 \
        --volume $(pwd)/server.p12:/etc/nuodb/keys/nuoadmin.p12 \
        --volume $(pwd)/client.pem:/etc/nuodb/keys/nuocmd.pem \
        -p 8888:8888 \
        -p 48004:48004 \
        -p 48005:48005 \
        -e "NUODB_DOMAIN_ENTRYPOINT=ad1" \
        ${IMG_NAME} nuoadmin
    $ docker logs ad1
    ...
    NuoAdmin Server running
    ...
    
  13. Validate connectivity by issuing a show domain command:

    $ docker run -it --net nuodb-net \
        --volume $(pwd)/truststore.p12:/etc/nuodb/keys/nuoadmin-truststore.p12 \
        --volume $(pwd)/server.p12:/etc/nuodb/keys/nuoadmin.p12 \
        --volume $(pwd)/client.pem:/etc/nuodb/keys/nuocmd.pem \
        ${IMG_NAME} \
        nuocmd --api-server ad1:8888 show domain
    

    The remaining processes would also be started with the volume mounted certs and keystores.

Enabling TLS on Kubernetes

To enable TLS on Kubernetes/OpenShift we need to create a Secret containing the
key material.

Create a nuodb-tls.yaml file as follows:

apiVersion: v1
kind: Secret
metadata:
  name: mysecret
type: Opaque
data:
  nuoadmin-truststore.p12: replace
  nuocmd.pem: replace
  nuoadmin.p12: replace

n.b. One thing to note, the keys within the data element, above, become the filenames
when volume mounted, below.

Then inject the key material as follows:

$ export TRUSTSTORE_BASE64=$(cat truststore.p12 | base64 | tr -d '\n')
$ export NUOCMD_PEM_BASE64=$(cat client.pem | base64 | tr -d '\n')
$ export NUOADMIN_P12_BASE64=$(cat server.p12 | base64 | tr -d '\n')

$ sed -i -e '/nuoadmin-truststore.p12:.*/ s|:.*|: '"${TRUSTSTORE_BASE64}"'|' nuodb-tls.yaml
$ sed -i -e '/nuocmd.pem:.*/ s|:.*|: '"${NUOCMD_PEM_BASE64}"'|' nuodb-tls.yaml
$ sed -i -e '/nuoadmin.p12:.*/ s|:.*|: '"${NUOADMIN_P12_BASE64}"'|' nuodb-tls.yaml

Then install the secret before launching any admin:

$ kubectl create -f nuodb-tls.yaml

In each of the Pods related to Admin, TE, or SM processes, you must volume mount
these certificates as follows (noting the volumeMounts and volumes sections):

apiVersion: v1
kind: Pod
metadata:
  name: secret-test-pod
spec:
  containers:
    - name: test-container
      image: nginx
      volumeMounts:
          # name must match the volume name below
          - name: tls-keys
            mountPath: /etc/nuodb/keys
  # The secret data is exposed to Containers in the Pod through a Volume.
  volumes:
    - name: tls-keys
      secret:
        secretName: mysecret

More information:

Docker Pull Command
Owner
nuodb