Getting Started with Helm Charts (ScalarDB Cluster with TLS)
This tutorial explains how to get started with ScalarDB Cluster with TLS configurations by using Helm Charts on a Kubernetes cluster in a test environment. Before starting, you should already have a Mac or Linux environment for testing. In addition, although this tutorial mentions using minikube, the steps described should work in any Kubernetes cluster.
Requirements
- You need to have a license key (trial license or commercial license) for ScalarDB Cluster. If you don't have a license key, please contact us.
- You need to use ScalarDB Cluster 3.12 or later, which supports TLS.
What you'll create
In this tutorial, you'll deploy the following components on a Kubernetes cluster in the following way:
+----------------------------------------------------------------------------------------------------------------------------------------------------+
| [Kubernetes Cluster] |
| [Pod] [Pod] [Pod] |
| |
| +-------+ +------------------------+ |
| +---> | Envoy | ---+ +---> | ScalarDB Cluster node | ---+ |
| [Pod] | +-------+ | | +------------------------+ | |
| | | | | |
| +-----------+ +---------+ | +-------+ | +--------------------+ | +------------------------+ | +---------------+ |
| | Client | ---> | Service | ---+---> | Envoy | ---+---> | Service | ---+---> | ScalarDB Cluster node | ---+---> | PostgreSQL | |
| | (SQL CLI) | | (Envoy) | | +-------+ | | (ScalarDB Cluster) | | +------------------------+ | | (For Ledger) | |
| +-----------+ +---------+ | | +--------------------+ | | +---------------+ |
| | +-------+ | | +------------------------+ | |
| +---> | Envoy | ---+ +---> | ScalarDB Cluster node | ---+ |
| +-------+ +------------------------+ |
| |
+----------------------------------------------------------------------------------------------------------------------------------------------------+
You'll also create the following private key and certificate files for TLS connections.
+-------------------------------+
+---> | For Scalar Envoy |
| +-------------------------------+
| | envoy-key.pem |
| | envoy.pem |
+----------------------+ | +-------------------------------+
| Self-signed CA | ---(Sign certificates)---+
+----------------------+ | +-------------------------------+
| ca-key.pem | +---> | For ScalarDB Cluster |
| ca.pem | +-------------------------------+
+----------------------+ | scalardb-cluster-key.pem |
| scalardb-cluster.pem |
+-------------------------------+
You'll set each private key and certificate file as follows to enable TLS in each connection.
+--------------------------------+ +-----------------------------------------+ +-----------------------------------------+
| Client | ---(CRUD/SQL requests)---> | Envoy for ScalarDB Cluster | ---> | ScalarDB Cluster nodes |
+--------------------------------+ +-----------------------------------------+ +-----------------------------------------+
| ca.pem (to verify envoy.pem) | | envoy-key.pem | | scalardb-cluster-key.pem |
+--------------------------------+ | envoy.pem | | scalardb-cluster.pem |
| ca.pem (to verify scalardb-cluster.pem) | | ca.pem (used for health check) |
+-----------------------------------------+ +-----------------------------------------+
The following connections exist amongst the ScalarDB Cluster–related components:
Client - Envoy for ScalarDB Cluster
: When you execute a CRUD API or SQL API function, the client accesses Envoy for ScalarDB Cluster.Envoy for ScalarDB Cluster - ScalarDB Cluster
: Envoy works as an L7 (gRPC) load balancer in front of ScalarDB Cluster.ScalarDB Cluster node - ScalarDB Cluster node
: A ScalarDB Cluster node accesses other ScalarDB Cluster nodes. In other words, the cluster's internal communications exist amongst all ScalarDB Cluster nodes.
Step 1. Start a Kubernetes cluster and install tools
You need to prepare a Kubernetes cluster and install some tools (kubectl
, helm
, cfssl
, and cfssljson
). For more details on how to install them, see Getting Started with Scalar Helm Charts.
Step 2. Start the PostgreSQL containers
ScalarDB Cluster must use some type of database system as a backend database. In this tutorial, you'll use PostgreSQL.
You can deploy PostgreSQL on the Kubernetes cluster as follows:
-
Add the Bitnami helm repository.
helm repo add bitnami https://charts.bitnami.com/bitnami
-
Deploy PostgreSQL for ScalarDB Cluster.
helm install postgresql-scalardb-cluster bitnami/postgresql \
--set auth.postgresPassword=postgres \
--set primary.persistence.enabled=false \
-n default -
Check if the PostgreSQL containers are running.
kubectl get pod -n default
[Command execution result]
NAME READY STATUS RESTARTS AGE
postgresql-scalardb-cluster-0 1/1 Running 0 34s
Step 3. Create a working directory
You'll create some configuration files and private key and certificate files locally. Be sure to create a working directory for those files.
-
Create a working directory.
mkdir -p ${HOME}/scalardb-cluster-test/certs/
Step 4. Create private key and certificate files
You'll create private key and a certificate files.
-
Change the working directory to
${HOME}/scalardb-cluster-test/certs/
.cd ${HOME}/scalardb-cluster-test/certs/
-
Create a JSON file that includes CA information.
cat << 'EOF' > ${HOME}/scalardb-cluster-test/certs/ca.json
{
"CN": "scalar-test-ca",
"key": {
"algo": "ecdsa",
"size": 256
},
"names": [
{
"C": "JP",
"ST": "Tokyo",
"L": "Shinjuku",
"O": "Scalar Test CA"
}
]
}
EOF -
Create the CA private key and certificate files.
cfssl gencert -initca ca.json | cfssljson -bare ca
-
Create a JSON file that includes CA configurations.
cat << 'EOF' > ${HOME}/scalardb-cluster-test/certs/ca-config.json
{
"signing": {
"default": {
"expiry": "87600h"
},
"profiles": {
"scalar-test-ca": {
"expiry": "87600h",
"usages": [
"signing",
"key encipherment",
"server auth"
]
}
}
}
}
EOF -
Create a JSON file that includes Envoy information.
cat << 'EOF' > ${HOME}/scalardb-cluster-test/certs/envoy.json
{
"CN": "scalar-envoy",
"hosts": [
"envoy.scalar.example.com",
"localhost"
],
"key": {
"algo": "ecdsa",
"size": 256
},
"names": [
{
"C": "JP",
"ST": "Tokyo",
"L": "Shinjuku",
"O": "Scalar Envoy Test"
}
]
}
EOF -
Create a JSON file that includes ScalarDB Cluster information.
cat << 'EOF' > ${HOME}/scalardb-cluster-test/certs/scalardb-cluster.json
{
"CN": "scalardb-cluster",
"hosts": [
"cluster.scalardb.example.com",
"localhost"
],
"key": {
"algo": "ecdsa",
"size": 256
},
"names": [
{
"C": "JP",
"ST": "Tokyo",
"L": "Shinjuku",
"O": "ScalarDB Cluster Test"
}
]
}
EOF -
Create private key and certificate files for Envoy.
cfssl gencert -ca ca.pem -ca-key ca-key.pem -config ca-config.json -profile scalar-test-ca envoy.json | cfssljson -bare envoy
-
Create private key and certificate files for ScalarDB Cluster.
cfssl gencert -ca ca.pem -ca-key ca-key.pem -config ca-config.json -profile scalar-test-ca scalardb-cluster.json | cfssljson -bare scalardb-cluster
-
Confirm that the private key and certificate files were created.
ls -1
[Command execution result]
ca-config.json
ca-key.pem
ca.csr
ca.json
ca.pem
envoy-key.pem
envoy.csr
envoy.json
envoy.pem
scalardb-cluster-key.pem
scalardb-cluster.csr
scalardb-cluster.json
scalardb-cluster.pem
Step 5. Deploy ScalarDB Cluster on the Kubernetes cluster by using Helm Charts
-
Add the Scalar Helm Charts repository.
helm repo add scalar-labs https://scalar-labs.github.io/helm-charts
-
Set your license key and certificate as environment variables. If you don't have a license key, please contact us. For details about the value of
<CERT_PEM_FOR_YOUR_LICENSE_KEY>
, see How to Configure a Product License Key.SCALAR_DB_CLUSTER_LICENSE_KEY='<YOUR_LICENSE_KEY>'
SCALAR_DB_CLUSTER_LICENSE_CHECK_CERT_PEM='<CERT_PEM_FOR_YOUR_LICENSE_KEY>' -
Create a custom values file for ScalarDB Cluster (
scalardb-cluster-custom-values.yaml
).cat << 'EOF' > ${HOME}/scalardb-cluster-test/scalardb-cluster-custom-values.yaml
envoy:
enabled: true
tls:
downstream:
enabled: true
certChainSecret: "envoy-tls-cert"
privateKeySecret: "envoy-tls-key"
upstream:
enabled: true
overrideAuthority: "cluster.scalardb.example.com"
caRootCertSecret: "scalardb-cluster-tls-ca"
scalardbCluster:
image:
repository: "ghcr.io/scalar-labs/scalardb-cluster-node-byol-premium"
scalardbClusterNodeProperties: |
### Necessary configurations for deployment on Kuberetes
scalar.db.cluster.membership.type=KUBERNETES
scalar.db.cluster.membership.kubernetes.endpoint.namespace_name=${env:SCALAR_DB_CLUSTER_MEMBERSHIP_KUBERNETES_ENDPOINT_NAMESPACE_NAME}
scalar.db.cluster.membership.kubernetes.endpoint.name=${env:SCALAR_DB_CLUSTER_MEMBERSHIP_KUBERNETES_ENDPOINT_NAME}
### Storage configurations
scalar.db.contact_points=jdbc:postgresql://postgresql-scalardb-cluster.default.svc.cluster.local:5432/postgres
scalar.db.username=${env:SCALAR_DB_CLUSTER_POSTGRES_USERNAME}
scalar.db.password=${env:SCALAR_DB_CLUSTER_POSTGRES_PASSWORD}
scalar.db.storage=jdbc
### SQL configurations
scalar.db.sql.enabled=true
### Auth configurations
scalar.db.cluster.auth.enabled=true
scalar.db.cross_partition_scan.enabled=true
### TLS configurations
scalar.db.cluster.tls.enabled=true
scalar.db.cluster.tls.ca_root_cert_path=/tls/scalardb-cluster/certs/ca.crt
scalar.db.cluster.node.tls.cert_chain_path=/tls/scalardb-cluster/certs/tls.crt
scalar.db.cluster.node.tls.private_key_path=/tls/scalardb-cluster/certs/tls.key
scalar.db.cluster.tls.override_authority=cluster.scalardb.example.com
### License key configurations
scalar.db.cluster.node.licensing.license_key=${env:SCALAR_DB_CLUSTER_LICENSE_KEY}
scalar.db.cluster.node.licensing.license_check_cert_pem=${env:SCALAR_DB_CLUSTER_LICENSE_CHECK_CERT_PEM}
tls:
enabled: true
overrideAuthority: "cluster.scalardb.example.com"
caRootCertSecret: "scalardb-cluster-tls-ca"
certChainSecret: "scalardb-cluster-tls-cert"
privateKeySecret: "scalardb-cluster-tls-key"
secretName: "scalardb-credentials-secret"
EOF -
Create a secret resource named
scalardb-credentials-secret
that includes credentials and license keys.kubectl create secret generic scalardb-credentials-secret \
--from-literal=SCALAR_DB_CLUSTER_POSTGRES_USERNAME=postgres \
--from-literal=SCALAR_DB_CLUSTER_POSTGRES_PASSWORD=postgres \
--from-literal=SCALAR_DB_CLUSTER_LICENSE_KEY="${SCALAR_DB_CLUSTER_LICENSE_KEY}" \
--from-file=SCALAR_DB_CLUSTER_LICENSE_CHECK_CERT_PEM=<(echo ${SCALAR_DB_CLUSTER_LICENSE_CHECK_CERT_PEM} | sed 's/\\n/\
/g') \
-n default -
Create secret resources that include the private key and certificate files for Envoy.
kubectl create secret generic envoy-tls-cert --from-file=tls.crt=${HOME}/scalardb-cluster-test/certs/envoy.pem -n default
kubectl create secret generic envoy-tls-key --from-file=tls.key=${HOME}/scalardb-cluster-test/certs/envoy-key.pem -n default