Helm Chart をはじめよう (cert-manager を使用した TLS 対応 ScalarDB Cluster)
このチュートリアルでは、テスト環境の Kubernetes クラスターで Helm Charts と cert-manager を使用して、TLS 構成の ScalarDB Cluster を開始する方法 について説明します。開始する前に、テスト用の Mac または Linux 環境がすでに用意されている必要があります。また、このチュートリアルでは minikube の使用について説明していますが、説明されている手順はどの Kubernetes クラスターでも機能するはずです。
要件
- ScalarDB Cluster のライセンスキー (試用ライセンスまたは商用ライセンス) が必要です。ライセンスキーをお持ちでない場合は、お問い合わせください。
- TLS をサポートする ScalarDB Cluster 3.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 | ---+ |
| +-------+ +------------------------+ |
| |
| +----------------------------------------------------------------------------------+ +---------------------+ |
| | cert-manager (create private key and certificate for Envoy and ScalarDB Cluster) | | Issuer (Private CA) | |
| +----------------------------------------------------------------------------------+ +---------------------+ |
| |
+----------------------------------------------------------------------------------------------------------------------------------------------------+
cert-manager は、TLS 接続用に次の秘密鍵と証明書ファイルを自動的に作成します。
+----------------------+
+---> | For Scalar Envoy |
| +----------------------+
| | tls.key |
| | tls.crt |
+-------------------------+ | +----------------------+
| Issuer (Self-signed CA) | ---(Sign certificates)---+
+-------------------------+ | +----------------------+
| tls.key | +---> | For ScalarDB Cluster |
| tls.crt | +----------------------+
| ca.crt | | tls.key |
+-------------------------+ | tls.crt |
+----------------------+
Scalar Helm Charts は、Envoy および ScalarDB Cluster の各秘密鍵と証明書ファイルを次のように自動的にマウントし、各接続で TLS を有効にします。ルート CA 証明書ファイルはクライアントに手動でマウントします。
+-------------------------------------+ +------------------------------------------------+ +--------------------------------+
| Client | ---(CRUD/SQL requests)---> | Envoy for ScalarDB Cluster | ---> | ScalarDB Cluster nodes |
+-------------------------------------+ +------------------------------------------------+ +--------------------------------+
| ca.crt (to verify tls.crt of Envoy) | | tls.key | | tls.key |
+-------------------------------------+ | tls.crt | | tls.crt |
| ca.crt (to verify tls.crt of ScalarDB Cluster) | | ca.crt (to check health) |
+------------------------------------------------+ +--------------------------------+
ScalarDB Cluster 関連コンポーネント間には、次の接続が存在します。
クライアント - ScalarDB Cluster の Envoy: CRUD API または SQL API 関数を実行すると、クライアントは ScalarDB Cluster の Envoy にアクセスします。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/
ステップ4. cert-manager と issuer リソースをデプロイする
このチュートリアルでは、cert-manager を使用して秘密鍵と証明書を発行および管理します。次のようにして、Kubernetes クラスターに cert-manager をデプロイできます。
-
Jetstack helm リポジトリを追加します。
helm repo add jetstack https://charts.jetstack.io -
cert-manager をデプロイします。
helm install cert-manager jetstack/cert-manager \
--create-namespace \
--set installCRDs=true \
-n cert-manager -
cert-manager コンテナが実行されているかどうかを確認します。
kubectl get pod -n cert-manager[コマンド実行結果]
NAME READY STATUS RESTARTS AGE
cert-manager-6dc66985d4-6lvtt 1/1 Running 0 26s
cert-manager-cainjector-c7d4dbdd9-xlrpn 1/1 Running 0 26s
cert-manager-webhook-847d7676c9-ckcz2 1/1 Running 0 26s -
作業ディレクトリを
${HOME}/scalardb-cluster-test/に変更します。cd ${HOME}/scalardb-cluster-test/ -
プライベート CA のカスタム値ファイル (
private-ca-custom-values.yaml) を作成します。cat << 'EOF' > ${HOME}/scalardb-cluster-test/private-ca-custom-values.yaml
apiVersion: cert-manager.io/v1
kind: Issuer
metadata:
name: self-signed-issuer
spec:
selfSigned: {}
---
apiVersion: cert-manager.io/v1
kind: Certificate
metadata:
name: self-signed-ca-cert
spec:
isCA: true
commonName: self-signed-ca
secretName: self-signed-ca-cert-secret
privateKey:
algorithm: ECDSA
size: 256
issuerRef:
name: self-signed-issuer
kind: Issuer
group: cert-manager.io
---
apiVersion: cert-manager.io/v1
kind: Issuer
metadata:
name: self-signed-ca
spec:
ca:
secretName: self-signed-ca-cert-secret
EOF -
自己署名 CA を展開します。
kubectl apply -f ./private-ca-custom-values.yaml -
発行者リソースが
Trueであるかどうかを確認します。kubectl get issuer[コマンド実行結果]
NAME READY AGE
self-signed-ca True 6s
self-signed-issuer True 6s
ステップ5. Helm Charts を使用して Kubernetes クラスターに ScalarDB Cluster をデプロイする
-
Scalar Helm Charts リポジトリを追加します。
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
certManager:
enabled: true
issuerRef:
name: self-signed-ca
dnsNames:
- envoy.scalar.example.com
upstream:
enabled: true
overrideAuthority: "cluster.scalardb.example.com"
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"
certManager:
enabled: true
issuerRef:
name: self-signed-ca
dnsNames:
- cluster.scalardb.example.com
secretName: "scalardb-credentials-secret"
EOF -
資格情報とライセンスキーを含む
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-file=SCALAR_DB_CLUSTER_LICENSE_CHECK_CERT_PEM=<(echo ${SCALAR_DB_CLUSTER_LICENSE_CHECK_CERT_PEM} | sed 's/\\n/\
/g') \
-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 18sScalarDB Cluster ポッドが適切にデプロイされている場合、それらのポッドの
STATUS列にはRunningと表示されます。 -
ScalarDB Cluster サービスがデプロイされているかどうかを確認します。
kubectl get svc -n default[コマンド実行結果]
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 40sScalarDB 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=ca.crt=<(kubectl get secret self-signed-ca-cert-secret -o "jsonpath={.data['ca\.crt']}" | base64 -d) -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/"
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 を実行する
-
クライアントコンテナーで bash を実行します。
kubectl exec -it scalardb-cluster-client -n default -- bash次の手順のコマンドは、クライアントコンテナーで実行する必要があります。
-
リリースから ScalarDB Cluster SQL CLI をダウンロードします。
curl -OL https://github.com/scalar-labs/scalardb/releases/download/v${SCALAR_DB_CLUSTER_VERSION}/scalardb-cluster-sql-cli-${SCALAR_DB_CLUSTER_VERSION}-all.jar -
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.crt
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) -
ScalarDB Cluster SQL CLI を終了するには、
Ctrl + Dを押します。^D -
クライアントコンテナーを終了します。
exit
ステップ8. すべてのリソースを削除する
Kubernetes クラスターで ScalarDB Cluster テストを完了したら、すべてのリソースを削除します。
-
ScalarDB Cluster と PostgreSQL をアンインストールします。
helm uninstall -n default scalardb-cluster postgresql-scalardb-cluster -
自己署名 CA を削除します。
kubectl delete -f ./private-ca-custom-values.yaml -
cert-manager をアンインストールします。
helm uninstall -n cert-manager cert-manager -
クライアントコンテナを削除します。
kubectl delete pod scalardb-cluster-client --grace-period 0 -n default -
シークレットリソースを削除 します。
kubectl delete secrets scalardb-credentials-secret self-signed-ca-cert-secret scalardb-cluster-envoy-tls-cert scalardb-cluster-tls-cert client-ca-cert -
ネームスペース
cert-managerを削除します。kubectl delete ns cert-manager -
作業ディレクトリとサンプル構成ファイルを削除します。
cd ${HOME}rm -rf ${HOME}/scalardb-cluster-test/
参考文献
Scalar 製品の監視またはログ記録を開始する方法については、次のチュートリアルを参照してください。