バージョン: 3.13

Helm Charts をはじめよう (TLS を使用した ScalarDB Cluster)

このドキュメントでは、Kubernetes クラスター上の Helm Chart をテスト環境として使用して、TLS 構成で ScalarDB Cluster を開始する方法について説明します。ここでは、テスト用の Mac または Linux 環境がすでにあることを前提としています。このドキュメントでは minikube を使用しますが、これから説明する手順はどの Kubernetes クラスターでも機能するはずです。

要件

ScalarDB Cluster のライセンスキー (トライアルライセンスまたは商用ライセンス) を取得する必要があります。ライセンスキーをお持ちでない場合は、お問い合わせしてください。
TLSをサポートするScalarDB Cluster v3.12以降を使用する必要があります。

作成するもの

次のように、次のコンポーネントを Kubernetes クラスターにデプロイします。

+----------------------------------------------------------------------------------------------------------------------------------------------------+
| [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  | ---+                        |
|                                          +-------+                                          +------------------------+                             |
|                                                                                                                                                    |
+----------------------------------------------------------------------------------------------------------------------------------------------------+

TLS 接続用に次の秘密鍵ファイルと証明書ファイルを作成します。

                                                        +-------------------------------+
                                                  +---> | 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          |
                                                        +-------------------------------+

各接続で TLS を有効にするために、各秘密鍵と証明書ファイルを次のように設定します。

+--------------------------------+                            +-----------------------------------------+      +-----------------------------------------+
| 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)          |
                                                              +-----------------------------------------+      +-----------------------------------------+

ScalarDB Cluster 関連コンポーネント間には、次の接続があります。

クライアント - ScalarDB Cluster の Envoy: 一部のCRUD APIやSQL APIを実行すると、クライアントはEnvoy for ScalarDB Clusterにアクセスします。
ScalarDB Cluster の Envoy - ScalarDB Cluster: Envoy は、ScalarDB Cluster の前の L7 (gRPC) ロードバランサーとして機能します。
ScalarDB Cluster ノード - ScalarDB Cluster ノード: ScalarDB Cluster ノードから別の ScalarDB Cluster ノードにアクセスします。言い換えれば、すべての ScalarDB Cluster ノード間でクラスターの内部通信が行われます。

ステップ1. Kubernetes クラスターを開始する

Kubernetes クラスターを準備し、いくつかのツール (kubectl、helm、cfssl、および cfssljson) をインストールする必要があります。インストール方法の詳細については、Scalar Helm Charts をはじめようを参照してください。

ステップ2. PostgreSQL コンテナーを開始する

ScalarDB Cluster は、バックエンドデータベースとして何らかのデータベースシステムを使用する必要があります。このチュートリアルでは、PostgreSQL を使用します。

次のようにして、Kubernetes クラスターに PostgreSQL をデプロイできます。

Bitnami Helm リポジトリを追加します。

helm repo add bitnami https://charts.bitnami.com/bitnami

ScalarDB Cluster 用の PostgreSQL をデプロイします。

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

PostgreSQL コンテナが実行されているかどうかを確認します。

kubectl get pod -n default

[コマンド実行結果]

NAME                            READY   STATUS    RESTARTS   AGE
postgresql-scalardb-cluster-0   1/1     Running   0          34s

ステップ3. 作業ディレクトリを作成する

いくつかの構成ファイルと秘密鍵および証明書ファイルをローカルに作成します。したがって、それらの作業ディレクトリを作成します。

作業ディレクトリを作成します。

mkdir -p ${HOME}/scalardb-cluster-test/certs/

ステップ4. 秘密鍵および証明書ファイルを作成する

秘密鍵と証明書ファイルを作成します。

作業ディレクトリを ${HOME}/scalardb-cluster-test/certs/ ディレクトリに変更します。
```
cd ${HOME}/scalardb-cluster-test/certs/
```

CA の情報を含む JSON ファイルを作成します。

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

CA の秘密鍵/証明書ファイルを作成します。
```
cfssl gencert -initca ca.json | cfssljson -bare ca
```

CA 構成を含む JSON ファイルを作成します。

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

Envoy 情報を含む JSON ファイルを作成します。

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

ScalarDB Cluster 情報を含む JSON ファイルを作成します。

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

Envoy の秘密鍵および証明書ファイルを作成します。

cfssl gencert -ca ca.pem -ca-key ca-key.pem -config ca-config.json -profile scalar-test-ca envoy.json | cfssljson -bare envoy

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

秘密鍵および証明書ファイルが作成されたことを確認します。

ls -1

[コマンド実行結果]

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

ステップ5. Helm Charts を使用して Kubernetes クラスターに ScalarDB Cluster をデプロイする

Scalar helm リポジトリを追加します。

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

ライセンスキーと証明書を環境変数に設定します。ライセンスキーをお持ちでない場合は、お問い合わせしてください。<CERT_PEM_FOR_YOUR_LICENSE_KEY> の値の詳細については、ライセンスキーの設定方法を参照してください。
```
SCALAR_DB_CLUSTER_LICENSE_KEY='<YOUR_LICENSE_KEY>'
SCALAR_DB_CLUSTER_LICENSE_CHECK_CERT_PEM='<CERT_PEM_FOR_YOUR_LICENSE_KEY>'
```

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

ライセンスキーと証明書を環境変数に設定します。ライセンスキーをお持ちでない場合は、お問い合わせしてください。
```
SCALAR_DB_CLUSTER_LICENSE_KEY=<YOUR_LICENSE_KEY>
SCALAR_DB_CLUSTER_LICENSE_CHECK_CERT_PEM=<CERT_PEM_FOR_YOUR_LICENSE_KEY>
```

資格情報とライセンスキーを含むシークレットリソース「scalardb-credentials-secret」を作成します。

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-literal=SCALAR_DB_CLUSTER_LICENSE_CHECK_CERT_PEM=${SCALAR_DB_CLUSTER_LICENSE_CHECK_CERT_PEM} \
  -n default

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

ScalarDB Cluster の秘密鍵、証明書、CA 証明書ファイルを含むシークレットリソースを作成します。

kubectl create secret generic scalardb-cluster-tls-ca --from-file=ca.crt=${HOME}/scalardb-cluster-test/certs/ca.pem -n default
kubectl create secret generic scalardb-cluster-tls-cert --from-file=tls.crt=${HOME}/scalardb-cluster-test/certs/scalardb-cluster.pem -n default
kubectl create secret generic scalardb-cluster-tls-key --from-file=tls.key=${HOME}/scalardb-cluster-test/certs/scalardb-cluster-key.pem -n default

ScalarDB Cluster のチャートのバージョンを設定します。

SCALAR_DB_CLUSTER_VERSION=3.12.2
SCALAR_DB_CLUSTER_CHART_VERSION=$(helm search repo scalar-labs/scalardb-cluster -l | grep -F "${SCALAR_DB_CLUSTER_VERSION}" | awk '{print $2}' | sort --version-sort -r | head -n 1)

ScalarDB Cluster をデプロイします。

helm install scalardb-cluster scalar-labs/scalardb-cluster -f ${HOME}/scalardb-cluster-test/scalardb-cluster-custom-values.yaml --version ${SCALAR_DB_CLUSTER_CHART_VERSION} -n default

ScalarDB Cluster ポッドがデプロイされているかどうかを確認します。

kubectl get pod -n default

[コマンド実行結果]

NAME                                     READY   STATUS    RESTARTS   AGE
postgresql-scalardb-cluster-0            1/1     Running   0          4m30s
scalardb-cluster-envoy-7cc948dfb-4rb8l   1/1     Running   0          18s
scalardb-cluster-envoy-7cc948dfb-hwt96   1/1     Running   0          18s
scalardb-cluster-envoy-7cc948dfb-rzbrx   1/1     Running   0          18s
scalardb-cluster-node-7c6959c79d-445kj   1/1     Running   0          18s
scalardb-cluster-node-7c6959c79d-4z54q   1/1     Running   0          18s
scalardb-cluster-node-7c6959c79d-vcv96   1/1     Running   0          18s

ScalarDB Cluster ポッドが適切にデプロイされている場合は、ステータスが 実行中 であることがわかります。

ScalarDB Cluster サービスがデプロイされているかどうかを確認します。

kubectl get svc -n default

[Command execution result]

NAME                             TYPE        CLUSTER-IP      EXTERNAL-IP   PORT(S)     AGE
kubernetes                       ClusterIP   10.96.0.1       <none>        443/TCP     7h34m
postgresql-scalardb-cluster      ClusterIP   10.96.92.27     <none>        5432/TCP    4m52s
postgresql-scalardb-cluster-hl   ClusterIP   None            <none>        5432/TCP    4m52s
scalardb-cluster-envoy           ClusterIP   10.96.250.175   <none>        60053/TCP   40s
scalardb-cluster-envoy-metrics   ClusterIP   10.96.40.197    <none>        9001/TCP    40s
scalardb-cluster-headless        ClusterIP   None            <none>        60053/TCP   40s
scalardb-cluster-metrics         ClusterIP   10.96.199.135   <none>        9080/TCP    40s

ScalarDB Cluster サービスが適切にデプロイされている場合は、CLUSTER-IP 列にプライベート IP アドレスが表示されます。

注記

postgresql-scalardb-cluster-hl と scalardb-cluster-headless の CLUSTER-IP 値は、IP アドレスがないため None になります。

ステップ6. クライアントコンテナを開始する

クライアントコンテナでCAの証明書ファイルを使用します。そこで、シークレットリソースを作成し、クライアントコンテナにマウントします。

シークレットリソース client-ca-cert を作成します。

kubectl create secret generic client-ca-cert --from-file=certificate=${HOME}/scalardb-cluster-test/certs/ca.pem -n default

クライアントポッドのマニフェストファイル (scalardb-cluster-client-pod.yaml) を作成します。

cat << 'EOF' > ${HOME}/scalardb-cluster-test/scalardb-cluster-client-pod.yaml
apiVersion: v1
kind: Pod
metadata:
  name: "scalardb-cluster-client"
spec:
  containers:
    - name: scalardb-cluster-client
      image: eclipse-temurin:8-jre-jammy
      command: ['sleep']
      args: ['inf']
      env:
        - name: SCALAR_DB_CLUSTER_VERSION
          value: SCALAR_DB_CLUSTER_CLIENT_POD_SCALAR_DB_CLUSTER_VERSION
      volumeMounts:
        - name: "client-ca-cert"
          mountPath: "/certs/ca/ca.pem"
          subPath: certificate
          readOnly: true
  volumes:
    - name: "client-ca-cert"
      secret:
        secretName: "client-ca-cert"
  restartPolicy: Never
EOF

マニフェストファイルで ScalarDB Cluster のバージョンを設定します。

sed -i s/SCALAR_DB_CLUSTER_CLIENT_POD_SCALAR_DB_CLUSTER_VERSION/${SCALAR_DB_CLUSTER_VERSION}/ ${HOME}/scalardb-cluster-test/scalardb-cluster-client-pod.yaml

クライアントポッドをデプロイします。

kubectl apply -f ${HOME}/scalardb-cluster-test/scalardb-cluster-client-pod.yaml -n default

クライアントコンテナが実行されているかどうかを確認します。

kubectl get pod scalardb-cluster-client -n default

[コマンド実行結果]

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

ステップ7. ScalarDB Cluster SQL CLI をダウンロードしてクライアントコンテナにコピーします

ScalarDB Cluster SQL CLI をリリースからディレクトリ ${HOME}/scalardb-cluster-test/ の下にダウンロードします。

ScalarDB Cluster SQL CLI をクライアントコンテナにコピーします。

kubectl cp ${HOME}/scalardb-cluster-test/scalardb-cluster-sql-cli-${SCALAR_DB_CLUSTER_VERSION}-all.jar scalardb-cluster-client:/

ステップ8. クライアントコンテナで ScalarDB Cluster SQL CLI を実行する

クライアントコンテナで bash を実行します。
```
kubectl exec -it scalardb-cluster-client -n default -- bash
```
次の手順移行のコマンドは、クライアントコンテナ内で実行する必要があります。

database.properties ファイルを作成します。

cat << 'EOF' > /database.properties
# ScalarDB Cluster configurations
scalar.db.sql.connection_mode=cluster
scalar.db.sql.cluster_mode.contact_points=indirect:scalardb-cluster-envoy.default.svc.cluster.local

# Auth configurations
scalar.db.cluster.auth.enabled=true
scalar.db.sql.cluster_mode.username=admin
scalar.db.sql.cluster_mode.password=admin

# TLS configurations
scalar.db.cluster.tls.enabled=true
scalar.db.cluster.tls.ca_root_cert_path=/certs/ca/ca.pem
scalar.db.cluster.tls.override_authority=envoy.scalar.example.com
EOF

ScalarDB Cluster SQL CLI を実行します。

java -jar /scalardb-cluster-sql-cli-${SCALAR_DB_CLUSTER_VERSION}-all.jar --config /database.properties

サンプル名前空間 ns を作成します。
```
CREATE NAMESPACE ns;
```

名前空間 ns の下にサンプルテーブル tbl を作成します。

CREATE TABLE ns.tbl (a INT, b INT, c INT, PRIMARY KEY(a, b));

サンプルレコードを挿入します。

INSERT INTO ns.tbl VALUES (1,2,3), (4,5,6), (7,8,9);

挿入したサンプルレコードを選択します。

SELECT * FROM ns.tbl;

[コマンド実行結果]

0: scalardb> SELECT * FROM ns.tbl;
+---+---+---+
| a | b | c |
+---+---+---+
| 7 | 8 | 9 |
| 1 | 2 | 3 |
| 4 | 5 | 6 |
+---+---+---+
3 rows selected (0.059 seconds)

ステップ9. すべてのリソースを削除する

Kubernetes クラスターで ScalarDB Cluster のテストが完了したら、すべてのリソースを削除します。

ScalarDB Cluster と PostgreSQL をアンインストールします。
```
helm uninstall -n default scalardb-cluster postgresql-scalardb-cluster
```

クライアントコンテナを削除します。

kubectl delete pod scalardb-cluster-client --grace-period 0 -n default

シークレットリソースを削除します。

kubectl delete secrets scalardb-credentials-secret scalardb-cluster-tls-key scalardb-cluster-tls-cert scalardb-cluster-tls-ca envoy-tls-key envoy-tls-cert client-ca-cert

作業ディレクトリとサンプルファイル (構成ファイル、秘密鍵、および証明書) を削除します。
```
cd ${HOME}
```
```
rm -rf ${HOME}/scalardb-cluster-test/
```

参考文献

Scalar 製品の監視またはログ記録を開始する方法については、次のドキュメントで説明しています。

要件​

作成するもの​

ステップ1. Kubernetes クラスターを開始する​

ステップ2. PostgreSQL コンテナーを開始する​

ステップ3. 作業ディレクトリを作成する​

ステップ4. 秘密鍵および証明書ファイルを作成する​

ステップ5. Helm Charts を使用して Kubernetes クラスターに ScalarDB Cluster をデプロイする​

ステップ6. クライアントコンテナを開始する​

ステップ7. ScalarDB Cluster SQL CLI をダウンロードしてクライアントコンテナにコピーします​

ステップ8. クライアントコンテナで ScalarDB Cluster SQL CLI を実行する​

ステップ9. すべてのリソースを削除する​

参考文献​

要件

作成するもの

ステップ1. Kubernetes クラスターを開始する

ステップ2. PostgreSQL コンテナーを開始する

ステップ3. 作業ディレクトリを作成する

ステップ4. 秘密鍵および証明書ファイルを作成する

ステップ5. Helm Charts を使用して Kubernetes クラスターに ScalarDB Cluster をデプロイする

ステップ6. クライアントコンテナを開始する

ステップ7. ScalarDB Cluster SQL CLI をダウンロードしてクライアントコンテナにコピーします

ステップ8. クライアントコンテナで ScalarDB Cluster SQL CLI を実行する

ステップ9. すべてのリソースを削除する

参考文献