Enabling TLS in Containerized Environments

To minimize the configuration required, the NuoDB Docker image is pre-configured with TLS enabled and defines a convention that must be adhered to when you provision TLS keys and certificates and expose them to containerized NuoDB processes.

All containerized NuoDB processes expect TLS keys and certificates to be located in $NUODB_CFGDIR/keys, which expands to /etc/nuodb/keys and includes the following files:

File Description

nuoadmin.p12

The default value of the keystore for the NuoDB Admin process (the keystore property in nuoadmin.conf). Contains only the admin key and certificate.

nuoadmin-truststore.p12

The default value of the truststore for the NuoDB Admin process (the truststore property in nuoadmin.conf). Contains the certificate used to verify admin certificates and the client certificate.

nuocmd.pem

The default value of the NUOCMD_CLIENT_KEY environment variable, which specifies the PEM file containing the key and certificate used by NuoDB Command (nuocmd) clients.

ca.cert

The default value of the NUOCMD_VERIFY_SERVER environment variable, which specifies the PEM file containing the certificate used to verify admin certificates.

The NuoDB Docker image is distributed with a set of files that follows this convention. To enable security, provision your own TLS keys and certificates, as described in Configuring NuoDB Admin TLS Encryption, using files as described, and expose them to containerized NuoDB processes using mechanisms such as Docker Volumes or Kubernetes Secrets.

Setting Environment Variables

When enabling TLS in containerized environments, you must set the following environment variables:

Variable Default Value Description

NUODB_KEYSTORE_PASSWORD

changeIt

The password used to encrypt the private key in the NuoDB Admin keystore.

NUODB_TRUSTSTORE_PASSWORD

changeIt

The password used to verify the integrity of the NuoDB Admin truststore.

NUOCMD_CLIENT_KEY

-

Used to specify the PEM file containing the key and certificate used by NuoDB Command (nuocmd) clients.

NUOCMD_VERIFY_SERVER

-

Used to specify the PEM file containing the certificate used to verify admin certificates.

A containerized NuoDB Admin process (AP) can be started with a custom set of TLS keys and certificates as follows:

docker run -d --cap-add SYS_PTRACE ... \
    -v "$KEYS_DIR:/etc/nuodb/keys" \
    -e "NUODB_KEYSTORE_PASSWORD=$PASSWD" \
    -e "NUODB_TRUSTSTORE_PASSWORD=$PASSWD" \
    -e "NUODB_BOOTSTRAP_SERVERID=admin-0" \
    -e "NUODB_DOMAIN_ENTRYPOINT=admin-0" \
    -e "NUOCMD_CLIENT_KEY=$KEYS_DIR/nuocmd.pem" \
    -e "NUOCMD_VERIFY_SERVER=$KEYS_DIR/$NUOCMD_VERIFY_SERVER" \
    nuodb:latest nuoadmin

In the above example, $KEYS_DIR is an environment variable used to set the directory on the host that has the provisioned key and certificate data for the AP. $PASSWD is the environment variable set for the keystore and truststore password environment variables.

$NUOCMD_VERIFY_SERVER is an environment variable set to the server certificate file name; the value is set based on which TLS trust model is used, shared admin key or unique admin key. For example, nuoadmin.cert for the Shared Admin Key trust model and ca.cert for the Unique Admin Key trust model.

Enabling TLS in OpenShift or Kubernetes

To enable TLS in OpenShift or Kubernetes, do the following:

1. Create a Kubernetes Secret template named nuodb-tls-secret.yaml with the following contents:

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

2. Inject the key material into the template file as follows:

export KEYSTORE_BASE64=$(cat nuoadmin.p12 | base64 | tr -d '\n')
export TRUSTSTORE_BASE64=$(cat nuoadmin-truststore.p12 | base64 | tr -d '\n')
export NUOCMD_PEM_BASE64=$(cat nuocmd.pem | base64 | tr -d '\n')
export CA_CERT_BASE64=$(cat ca.cert | base64 | tr -d '\n')
sed -i -e '/nuoadmin.p12:.*/ s|:.*|: '"${KEYSTORE_BASE64}"'|' nuodb-tls-secret.yaml
sed -i -e '/nuoadmin-truststore.p12:.*/ s|:.*|: '"${TRUSTSTORE_BASE64}"'|' nuodb-tls-secret.yaml
sed -i -e '/nuocmd.pem:.*/ s|:.*|: '"${NUOCMD_PEM_BASE64}"'|' nuodb-tls-secret.yaml
sed -i -e '/ca.cert:.*/ s|:.*|: '"${CA_CERT_BASE64}"'|' nuodb-tls-secret.yaml

3. Install the Kubernetes Secret before launching any admin:

kubectl create -f nuodb-tls-secret.yaml

For more information on distributing credentials securely, see kubernetes support.

Exposing the Keystore to Containerized Database Processes

If the NuoDB AP cannot act as a CA for database processes which it manages, database processes are passed the same certificate used by the nuoadmin process as opposed to a certificate signed by it.

In containerized deployments of NuoDB, the admin and database processes can only communicate via socket connections and there is no secure method for the AP to pass the database process its private key and certificate. In this scenario, it is necessary to specify the keystore file and keystore password for the entry-point script that forks the database process (nuodocker start sm/te).

This keystore can be mounted into the container using some mechanism such as Docker Volumes or Kubernetes Secrets. The keystore is specified using the --keystore argument of nuodocker start sm/te, while the keystore password is specified using the NUODOCKER_KEYSTORE_PASSWORD environment variable, which can be specified as a Kubernetes Secret (to avoid exposing the password with docker ps or kubectl describe pod).

Invoking a Containerized Database Process with a Keystore

The following example demonstrates how to use Docker to start a containerized database process with a keystore.

docker run -d --cap-add SYS_PTRACE ... -e NUODOCKER_KEYSTORE_PASSWORD="$PASSWD"
--volume /path/to/keys:/etc/nuodb/keys nuodb:latest \
nuodocker --api-server admin-0:8888 start te \
--db-name db --server-id admin-0 --keystore /etc/nuodb/keys/nuoadmin.p12