[Deprecated] Getting Started with Helm Charts (ScalarDB Server)
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-serverandscalardb-envoy). Please refer to the following documents for more details.
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.
- AWS Marketplace
-
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 6sIf 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 41sIf the ScalarDB Server services are deployed properly, you can see private IP addresses in the CLUSTER-IP column. (Note:
scalardb-headlesshas 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 -- bashAfter 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.0git branch[Command execution result]
master
* v3.7.0If 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.jarYou 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
1000touser1:./gradlew run --args="-action charge -amount 1000 -to user1" - Charge
0tomerchant1(Just create an account formerchant1):./gradlew run --args="-action charge -amount 0 -to merchant1" - Pay
100fromuser1tomerchant1:./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"
- Charge
-
(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.
- Note:
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
Further reading
You can see how to get started with monitoring or logging for Scalar products in the following documents.