[Deprecated] Getting Started with Helm Charts (ScalarDB Server)

Note

ScalarDB Server is now deprecated. Please use ScalarDB Cluster instead.

This document explains how to get started with ScalarDB Server using Helm Chart on a Kubernetes cluster as a test environment. Here, we assume that you already have a Mac or Linux environment for testing. We use Minikube in this document, but the steps we will show should work in any Kubernetes cluster.

Requirement

You need to subscribe to ScalarDB in the AWS Marketplace or Azure Marketplace to get container images (scalardb-server and scalardb-envoy). Please refer to the following documents for more details.
- How to install Scalar products through AWS Marketplace
- How to install Scalar products through Azure Marketplace

What we create

We will deploy the following components on a Kubernetes cluster as follows.

+--------------------------------------------------------------------------------------------------------------------------------------+
| [Kubernetes Cluster]                                                                                                                 |
|                                                                                                                                      |
|    [Pod]                                [Pod]                                                  [Pod]                     [Pod]       |
|                                                                                                                                      |
|                                       +-------+                                         +-----------------+                          |
|                                 +---> | Envoy | ---+                              +---> | ScalarDB Server | ---+                     |
|                                 |     +-------+    |                              |     +-----------------+    |                     |
|                                 |                  |                              |                            |                     |
|  +--------+      +---------+    |     +-------+    |     +-------------------+    |     +-----------------+    |     +------------+  |
|  | Client | ---> | Service | ---+---> | Envoy | ---+---> |      Service      | ---+---> | ScalarDB Server | ---+---> | PostgreSQL |  |
|  +--------+      | (Envoy) |    |     +-------+    |     | (ScalarDB Server) |    |     +-----------------+    |     +------------+  |
|                  +---------+    |                  |     +-------------------+    |                            |                     |
|                                 |     +-------+    |                              |     +-----------------+    |                     |
|                                 +---> | Envoy | ---+                              +---> | ScalarDB Server | ---+                     |
|                                       +-------+                                         +-----------------+                          |
|                                                                                                                                      |
+--------------------------------------------------------------------------------------------------------------------------------------+

Step 1. Start a Kubernetes cluster

First, you need to prepare a Kubernetes cluster. If you use a minikube environment, please refer to the Getting Started with Scalar Helm Charts. If you have already started a Kubernetes cluster, you can skip this step.

Step 2. Start a PostgreSQL container

ScalarDB uses some kind of database system as a backend database. In this document, we 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.

helm install postgresql-scalardb bitnami/postgresql \
  --set auth.postgresPassword=postgres \
  --set primary.persistence.enabled=false

Check if the PostgreSQL container is running.

kubectl get pod

[Command execution result]

NAME                    READY   STATUS    RESTARTS   AGE
postgresql-scalardb-0   1/1     Running   0          2m42s

Step 3. Deploy ScalarDB Server on the Kubernetes cluster using Helm Charts

Add the Scalar helm repository.

helm repo add scalar-labs https://scalar-labs.github.io/helm-charts

Create a secret resource to pull the ScalarDB container images from AWS/Azure Marketplace.

AWS Marketplace

kubectl create secret docker-registry reg-ecr-mp-secrets \
  --docker-server=709825985650.dkr.ecr.us-east-1.amazonaws.com \
  --docker-username=AWS \
  --docker-password=$(aws ecr get-login-password --region us-east-1)

Azure Marketplace

kubectl create secret docker-registry reg-acr-secrets \
  --docker-server=<your private container registry login server> \
  --docker-username=<Service principal ID> \
  --docker-password=<Service principal password>

Please refer to the following documents for more details.

Create a custom values file for ScalarDB Server (scalardb-custom-values.yaml).

AWS Marketplace

cat << 'EOF' > scalardb-custom-values.yaml
envoy:
  image:
    repository: "709825985650.dkr.ecr.us-east-1.amazonaws.com/scalar/scalardb-envoy"
    version: "1.3.0"
  imagePullSecrets:
    - name: "reg-ecr-mp-secrets"
     
scalardb:
  image:
    repository: "709825985650.dkr.ecr.us-east-1.amazonaws.com/scalar/scalardb-server"
    tag: "3.7.0"
  imagePullSecrets:
    - name: "reg-ecr-mp-secrets"
  databaseProperties: |
    scalar.db.storage=jdbc
    scalar.db.contact_points=jdbc:postgresql://postgresql-scalardb.default.svc.cluster.local:5432/postgres
    scalar.db.username={{ default .Env.SCALAR_DB_POSTGRES_USERNAME "" }}
    scalar.db.password={{ default .Env.SCALAR_DB_POSTGRES_PASSWORD "" }}
  secretName: "scalardb-credentials-secret"
EOF

Azure Marketplace

cat << 'EOF' > scalardb-custom-values.yaml
envoy:
  image:
    repository: "<your private container registry>/scalarinc/scalardb-envoy"
    version: "1.3.0"
  imagePullSecrets:
    - name: "reg-acr-secrets"
     
scalardb:
  image:
    repository: "<your private container registry>/scalarinc/scalardb-server"
    tag: "3.7.0"
  imagePullSecrets:
    - name: "reg-acr-secrets"
  databaseProperties: |
    scalar.db.storage=jdbc
    scalar.db.contact_points=jdbc:postgresql://postgresql-scalardb.default.svc.cluster.local:5432/postgres
    scalar.db.username={{ default .Env.SCALAR_DB_POSTGRES_USERNAME "" }}
    scalar.db.password={{ default .Env.SCALAR_DB_POSTGRES_PASSWORD "" }}
  secretName: "scalardb-credentials-secret"
   EOF

Create a Secret resource that includes a username and password for PostgreSQL.

kubectl create secret generic scalardb-credentials-secret \
  --from-literal=SCALAR_DB_POSTGRES_USERNAME=postgres \
  --from-literal=SCALAR_DB_POSTGRES_PASSWORD=postgres

Deploy ScalarDB Server.

helm install scalardb scalar-labs/scalardb -f ./scalardb-custom-values.yaml

Check if the ScalarDB Server pods are deployed.

kubectl get pod

[Command execution result]

NAME                              READY   STATUS    RESTARTS   AGE
postgresql-scalardb-0             1/1     Running   0          9m48s
scalardb-765598848b-75csp         1/1     Running   0          6s
scalardb-765598848b-w864f         1/1     Running   0          6s
scalardb-765598848b-x8rqj         1/1     Running   0          6s
scalardb-envoy-84c475f77b-kpz2p   1/1     Running   0          6s
scalardb-envoy-84c475f77b-n74tk   1/1     Running   0          6s
scalardb-envoy-84c475f77b-zbrwz   1/1     Running   0          6s

If the ScalarDB Server Pods are deployed properly, you can see the STATUS are Running.

Check if the ScalarDB Server services are deployed.

kubectl get svc

[Command execution result]

NAME                     TYPE        CLUSTER-IP       EXTERNAL-IP   PORT(S)     AGE
kubernetes               ClusterIP   10.96.0.1        <none>        443/TCP     47d
postgresql-scalardb      ClusterIP   10.109.118.122   <none>        5432/TCP    10m
postgresql-scalardb-hl   ClusterIP   None             <none>        5432/TCP    10m
scalardb-envoy           ClusterIP   10.110.110.250   <none>        60051/TCP   41s
scalardb-envoy-metrics   ClusterIP   10.107.98.227    <none>        9001/TCP    41s
scalardb-headless        ClusterIP   None             <none>        60051/TCP   41s
scalardb-metrics         ClusterIP   10.108.188.10    <none>        8080/TCP    41s

If the ScalarDB Server services are deployed properly, you can see private IP addresses in the CLUSTER-IP column. (Note: scalardb-headless has no CLUSTER-IP.)

Step 4. Start a Client container

Start a Client container on the Kubernetes cluster.

kubectl run scalardb-client --image eclipse-temurin:8 --command sleep inf

Check if the Client container is running.

kubectl get pod scalardb-client

[Command execution result]

NAME              READY   STATUS    RESTARTS   AGE
scalardb-client   1/1     Running   0          23s

Step 5. Run ScalarDB sample applications in the Client container

The following explains the minimum steps. If you want to know more details about ScalarDB, please refer to the Getting Started with ScalarDB.

Run bash in the Client container.
```
kubectl exec -it scalardb-client -- bash
```
After this step, run each command in the Client container.
Install the git and curl commands in the Client container.
```
apt update && apt install -y git curl
```

Clone ScalarDB git repository.

git clone https://github.com/scalar-labs/scalardb.git

Change the directory to scalardb/.
```
cd scalardb/
```
```
pwd
```
[Command execution result]
```
/scalardb
```
Change branch to arbitrary version.
```
git checkout -b v3.7.0 refs/tags/v3.7.0
```
```
git branch
```
[Command execution result]
```
  master
* v3.7.0
```
If you want to use another version, please specify the version (tag) you want to use.
Change the directory to docs/getting-started/.
```
cd docs/getting-started/
```
```
pwd
```
[Command execution result]
```
/scalardb/docs/getting-started
```

Download Schema Loader from ScalarDB Releases.

curl -OL https://github.com/scalar-labs/scalardb/releases/download/v3.7.0/scalardb-schema-loader-3.7.0.jar

You need to use the same version of ScalarDB and Schema Loader.

Create a configuration file (scalardb.properties) to access ScalarDB Server on the Kubernetes cluster.

cat << 'EOF' > scalardb.properties
scalar.db.contact_points=scalardb-envoy.default.svc.cluster.local
scalar.db.contact_port=60051
scalar.db.storage=grpc
scalar.db.transaction_manager=grpc
EOF

Create a JSON file (emoney-transaction.json) that defines DB Schema for the sample applications.

cat << 'EOF' > emoney-transaction.json
{
  "emoney.account": {
    "transaction": true,
    "partition-key": [
      "id"
    ],
    "clustering-key": [],
    "columns": {
      "id": "TEXT",
      "balance": "INT"
    }
  }
}
EOF

Run Schema Loader (Create sample TABLE).

java -jar ./scalardb-schema-loader-3.7.0.jar --config ./scalardb.properties -f emoney-transaction.json --coordinator

Run the sample applications.

Charge 1000 to user1:

./gradlew run --args="-action charge -amount 1000 -to user1"

Charge 0 to merchant1 (Just create an account for merchant1):

./gradlew run --args="-action charge -amount 0 -to merchant1"

Pay 100 from user1 to merchant1:

./gradlew run --args="-action pay -amount 100 -from user1 -to merchant1"

Get the balance of user1:

./gradlew run --args="-action getBalance -id user1"

Get the balance of merchant1:

./gradlew run --args="-action getBalance -id merchant1"

(Optional) You can see the inserted and modified (INSERT/UPDATE) data through the sample applications using the following command. (This command needs to run on your localhost, not on the Client container.)

kubectl exec -it postgresql-scalardb-0 -- bash -c 'export PGPASSWORD=postgres && psql -U postgres -d postgres -c "SELECT * FROM emoney.account"'

[Command execution result]

    id     | balance |                tx_id                 | tx_state | tx_version | tx_prepared_at | tx_committed_at |             before_tx_id             | before_tx_state | before_tx_version | before_tx_prepared_at | before_tx_committed_at | before_balance
-----------+---------+--------------------------------------+----------+------------+----------------+-----------------+--------------------------------------+-----------------+-------------------+-----------------------+------------------------+----------------
 merchant1 |     100 | 65a90225-0846-4e97-b729-151f76f6ca2f |        3 |          2 |  1667361909634 |1667361909679    | 3633df99-a8ed-4301-a8b9-db1344807d7b |               3 |                 1 |         1667361902466 |          1667361902485 |              0
 user1     |     900 | 65a90225-0846-4e97-b729-151f76f6ca2f |        3 |          2 |  1667361909634 |1667361909679    | 5520cba4-625a-4886-b81f-6089bf846d18 |               3 |                 1 |         1667361897283 |          1667361897317 |           1000
(2 rows)

Note:
- Usually, you need to access data (records) through ScalarDB. The above command is used to explain and confirm the working of the sample applications.

Step 6. Delete all resources

After completing the ScalarDB Server tests on the Kubernetes cluster, remove all resources.

Uninstall ScalarDB Server and PostgreSQL.

helm uninstall scalardb postgresql-scalardb

Remove the Client container.

kubectl delete pod scalardb-client --force --grace-period 0

Requirement

What we create

Step 1. Start a Kubernetes cluster

Step 2. Start a PostgreSQL container

Step 3. Deploy ScalarDB Server on the Kubernetes cluster using Helm Charts

Step 4. Start a Client container

Step 5. Run ScalarDB sample applications in the Client container

Step 6. Delete all resources

Further reading