Helm Charts をはじめよう (ScalarDL Ledger / Ledger のみ)

注記

このページは英語版のページが機械翻訳されたものです。英語版との間に矛盾または不一致がある場合は、英語版を正としてください。

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

要件

以下のコンテナイメージを入手するには、AWS Marketplace または Azure Marketplace でScalarDL Ledgerを購読する必要があります。

• AWS Marketplace
  • scalar-ledger
  • scalar-ledger-envoy
  • scalardl-schema-loader-ledger
• Azure Marketplace
  • scalar-ledger
  • scalardl-envoy
  • scalardl-schema-loader

詳細については、以下のドキュメントを参照してください。

• How to install Scalar products through AWS Marketplace
• How to install Scalar products through Azure Marketplace

私たちが作るもの

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

+--------------------------------------------------------------------------------------------------------------------------------------+
| [Kubernetes クラスター]                                                                                                                 |
|                                                                                                                                      |
|    [ポッド]                                [ポッド]                                                  [ポッド]                     [ポッド]       |
|                                                                                                                                      |
|                                       +-------+                                         +-----------------+                          |
|                                 +---> | Envoy | ---+                              +---> | ScalarDL Ledger | ---+                     |
|                                 |     +-------+    |                              |     +-----------------+    |                     |
|                                 |                  |                              |                            |                     |
|  +--------+      +---------+    |     +-------+    |     +-------------------+    |     +-----------------+    |     +------------+  |
|  | クライアント | ---> | サービス | ---+---> | Envoy | ---+---> |      サービス      | ---+---> | ScalarDL Ledger | ---+---> | PostgreSQL |  |
|  +--------+      | (Envoy) |    |     +-------+    |     | (ScalarDL Ledger) |    |     +-----------------+    |     +------------+  |
|                  +---------+    |                  |     +-------------------+    |                            |                     |
|                                 |     +-------+    |                              |     +-----------------+    |                     |
|                                 +---> | Envoy | ---+                              +---> | ScalarDL Ledger | ---+                     |
|                                       +-------+                                         +-----------------+                          |
|                                                                                                                                      |
+--------------------------------------------------------------------------------------------------------------------------------------+

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

まず、Kubernetes クラスターを準備する必要があります。minikube 環境を使用する場合は、Scalar Helm Charts をはじめようを参照してください。すでに Kubernetes クラスターを開始している場合は、この手順をスキップできます。

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

ScalarDL Ledger は、バックエンドデータベースとして何らかのデータベースシステムを使用します。このドキュメントでは PostgreSQL を使用します。

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

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

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

2. PostgreSQLをデプロイします。

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

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

   kubectl get pod

   【コマンド実行結果】

   NAME                  READY   STATUS    RESTARTS   AGE
   postgresql-ledger-0   1/1     Running   0          11s

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

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

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

   mkdir -p ~/scalardl-test/certs/

ステップ4. キー/証明書ファイルを作成する

注記：このガイドでは、テストに自己署名証明書を使用します。ただし、これらの証明書を運用環境では使用しないことを強くお勧めします。

1. 作業ディレクトリを ~/scalardl-test/certs/ ディレクトリに変更します。

   cd ~/scalardl-test/certs/

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

   cat << 'EOF' > ~/scalardl-test/certs/ledger.json
   {
       "CN": "ledger",
       "hosts": ["example.com","*.example.com"],
       "key": {
           "algo": "ecdsa",
           "size": 256
       },
       "names": [
           {
               "O": "ledger",
               "OU": "test team",
               "L": "Shinjuku",
               "ST": "Tokyo",
               "C": "JP"
           }
       ]
   }
   EOF

3. クライアント情報を含む JSON ファイルを作成します。

   cat << 'EOF' > ~/scalardl-test/certs/client.json
   {
       "CN": "client",
       "hosts": ["example.com","*.example.com"],
       "key": {
           "algo": "ecdsa",
           "size": 256
       },
       "names": [
           {
               "O": "client",
               "OU": "test team",
               "L": "Shinjuku",
               "ST": "Tokyo",
               "C": "JP"
           }
       ]
   }
   EOF

4. Ledger のキー/証明書ファイルを作成します。

   cfssl selfsign "" ./ledger.json | cfssljson -bare ledger

5. クライアントのキー/証明書ファイルを作成します。

   cfssl selfsign "" ./client.json | cfssljson -bare client

6. キー/証明書ファイルが作成されたことを確認します。

   ls -1

   【コマンド実行結果】

   client-key.pem
   client.csr
   client.json
   client.pem
   ledger-key.pem
   ledger.csr
   ledger.json
   ledger.pem

ステップ5. Helm Charts を使用して ScalarDL Ledger の DB スキーマを作成する

Helm Charts を使用して、ScalarDL Schema Loader を Kubernetes クラスターにデプロイします。 ScalarDL Schema Loader は、PostgreSQL で ScalarDL Ledger の DB スキーマを作成します。

1. 作業ディレクトリを ~/scalardl-test/ に変更します。

   cd ~/scalardl-test/

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

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

3. AWS/Azure Marketplace から ScalarDL コンテナーイメージをプルするためのシークレットリソースを作成します。

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

   詳細については、以下のドキュメントを参照してください。

   • How to install Scalar products through AWS Marketplace
   • How to install Scalar products through Azure Marketplace

4. ScalarDL Schema Loader のカスタム値ファイル (schema-loader-ledger-custom-values.yaml) を作成します。

   • AWS Marketplace

     cat << 'EOF' > ~/scalardl-test/schema-loader-ledger-custom-values.yaml
     schemaLoading:
       schemaType: "ledger"
       image:
         repository: "709825985650.dkr.ecr.us-east-1.amazonaws.com/scalar/scalardl-schema-loader-ledger"
         version: "3.6.0"
       imagePullSecrets:
         - name: "reg-ecr-mp-secrets"
       databaseProperties: |
         scalar.db.contact_points=jdbc:postgresql://postgresql-ledger.default.svc.cluster.local:5432/postgres
         scalar.db.username={{ default .Env.SCALAR_DL_LEDGER_POSTGRES_USERNAME "" }}
         scalar.db.password={{ default .Env.SCALAR_DL_LEDGER_POSTGRES_PASSWORD "" }}
         scalar.db.storage=jdbc
       secretName: "ledger-credentials-secret"
     EOF

   • Azure Marketplace

     cat << 'EOF' > ~/scalardl-test/schema-loader-ledger-custom-values.yaml
     schemaLoading:
       schemaType: "ledger"
       image:
         repository: "<your private container registry>/scalarinc/scalardl-schema-loader"
         version: "3.6.0"
       imagePullSecrets:
         - name: "reg-acr-secrets"
       databaseProperties: |
         scalar.db.contact_points=jdbc:postgresql://postgresql-ledger.default.svc.cluster.local:5432/postgres
         scalar.db.username={{ default .Env.SCALAR_DL_LEDGER_POSTGRES_USERNAME "" }}
         scalar.db.password={{ default .Env.SCALAR_DL_LEDGER_POSTGRES_PASSWORD "" }}
         scalar.db.storage=jdbc
       secretName: "ledger-credentials-secret"
     EOF

5. PostgreSQL のユーザー名とパスワードを含むシークレットリソースを作成します。

   kubectl create secret generic ledger-credentials-secret \
     --from-literal=SCALAR_DL_LEDGER_POSTGRES_USERNAME=postgres \
     --from-literal=SCALAR_DL_LEDGER_POSTGRES_PASSWORD=postgres

6. ScalarDL Schema Loader をデプロイします。

   helm install schema-loader-ledger scalar-labs/schema-loading -f ./schema-loader-ledger-custom-values.yaml

7. ScalarDL Schema Loader ポッドがデプロイされ、完了しているかどうかを確認します。

   kubectl get pod

   【コマンド実行結果】

   NAME                                        READY   STATUS      RESTARTS   AGE
   postgresql-ledger-0                         1/1     Running     0          11m
   schema-loader-ledger-schema-loading-46rcr   0/1     Completed   0          3s

   ScalarDL Schema Loader ポッドが ContainerCreating または Running の場合は、プロセスが完了するまで待ちます (STATUS は Completed になります)。

ステップ6. Helm Charts を使用して Kubernetes クラスターに ScalarDL Ledger をデプロイする

1. ScalarDL Ledger のカスタム値ファイル (scalardl-ledger-custom-values.yaml) を作成します。

   • AWS Marketplace

     cat << 'EOF' > ~/scalardl-test/scalardl-ledger-custom-values.yaml
     envoy:
       image:
         repository: "709825985650.dkr.ecr.us-east-1.amazonaws.com/scalar/scalar-ledger-envoy"
         version: "1.3.0"
       imagePullSecrets:
         - name: "reg-ecr-mp-secrets"
     
     ledger:
       image:
         repository: "709825985650.dkr.ecr.us-east-1.amazonaws.com/scalar/scalar-ledger"
         version: "3.6.0"
       imagePullSecrets:
         - name: "reg-ecr-mp-secrets"
       ledgerProperties: |
         scalar.db.contact_points=jdbc:postgresql://postgresql-ledger.default.svc.cluster.local:5432/postgres
         scalar.db.username={{ default .Env.SCALAR_DL_LEDGER_POSTGRES_USERNAME "" }}
         scalar.db.password={{ default .Env.SCALAR_DL_LEDGER_POSTGRES_PASSWORD "" }}
         scalar.db.storage=jdbc
         scalar.dl.ledger.proof.enabled=true
         scalar.dl.ledger.proof.private_key_path=/keys/private-key
       secretName: "ledger-credentials-secret"
       extraVolumes:
         - name: "ledger-keys"
           secret:
             secretName: "ledger-keys"
       extraVolumeMounts:
         - name: "ledger-keys"
           mountPath: "/keys"
           readOnly: true
     EOF

   • Azure Marketplace

     cat << 'EOF' > ~/scalardl-test/scalardl-ledger-custom-values.yaml
     envoy:
       image:
         repository: "<your private container registry>/scalarinc/scalardl-envoy"
         version: "1.3.0"
       imagePullSecrets:
         - name: "reg-acr-secrets"
     
     ledger:
       image:
         repository: "<your private container registry>/scalarinc/scalar-ledger"
         version: "3.6.0"
       imagePullSecrets:
         - name: "reg-acr-secrets"
       ledgerProperties: |
         scalar.db.contact_points=jdbc:postgresql://postgresql-ledger.default.svc.cluster.local:5432/postgres
         scalar.db.username={{ default .Env.SCALAR_DL_LEDGER_POSTGRES_USERNAME "" }}
         scalar.db.password={{ default .Env.SCALAR_DL_LEDGER_POSTGRES_PASSWORD "" }}
         scalar.db.storage=jdbc
         scalar.dl.ledger.proof.enabled=true
         scalar.dl.ledger.proof.private_key_path=/keys/private-key
       secretName: "ledger-credentials-secret"
       extraVolumes:
         - name: "ledger-keys"
           secret:
             secretName: "ledger-keys"
       extraVolumeMounts:
         - name: "ledger-keys"
           mountPath: "/keys"
           readOnly: true
     EOF

2. シークレットリソース ledger-keys を作成します。

   kubectl create secret generic ledger-keys --from-file=private-key=./certs/ledger-key.pem

3. ScalarDL Ledger をデプロイします。

   helm install scalardl-ledger scalar-labs/scalardl -f ./scalardl-ledger-custom-values.yaml

4. ScalarDL Ledger ポッドがデプロイされているかどうかを確認します。

   kubectl get pod

   【コマンド実行結果】

   NAME                                        READY   STATUS      RESTARTS   AGE
   postgresql-ledger-0                         1/1     Running     0          14m
   scalardl-ledger-envoy-547bbf7546-6cn88      1/1     Running     0          52s
   scalardl-ledger-envoy-547bbf7546-rpg5p      1/1     Running     0          52s
   scalardl-ledger-envoy-547bbf7546-x2vlg      1/1     Running     0          52s
   scalardl-ledger-ledger-9bdf7f8bd-29bzm      1/1     Running     0          52s
   scalardl-ledger-ledger-9bdf7f8bd-9fklw      1/1     Running     0          52s
   scalardl-ledger-ledger-9bdf7f8bd-9tw5x      1/1     Running     0          52s
   schema-loader-ledger-schema-loading-46rcr   0/1     Completed   0          3m38s

   ScalarDL Ledger ポッドが適切にデプロイされている場合、STATUS が Running であることがわかります。

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

   kubectl get svc

   【コマンド実行結果】

   NAME                            TYPE        CLUSTER-IP       EXTERNAL-IP   PORT(S)                         AGE
   kubernetes                      ClusterIP   10.96.0.1        <none>        443/TCP                         47d
   postgresql-ledger               ClusterIP   10.109.253.150   <none>        5432/TCP                        15m
   postgresql-ledger-hl            ClusterIP   None             <none>        5432/TCP                        15m
   scalardl-ledger-envoy           ClusterIP   10.106.141.153   <none>        50051/TCP,50052/TCP             83s
   scalardl-ledger-envoy-metrics   ClusterIP   10.108.36.136    <none>        9001/TCP                        83s
   scalardl-ledger-headless        ClusterIP   None             <none>        50051/TCP,50053/TCP,50052/TCP   83s
   scalardl-ledger-metrics         ClusterIP   10.98.4.217      <none>        8080/TCP                        83s

   ScalarDL Ledger サービスが適切にデプロイされている場合は、CLUSTER-IP 列にプライベート IP アドレスが表示されます。(注記： scalardl-ledger-headless には CLUSTER-IP がありません。)

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

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

1. シークレットリソース client-keys を作成します。

   kubectl create secret generic client-keys --from-file=certificate=./certs/client.pem --from-file=private-key=./certs/client-key.pem

2. Kubernetes クラスター上でクライアントコンテナーを起動します。

   cat << 'EOF' | kubectl apply -f -
   apiVersion: v1
   kind: Pod
   metadata:
     name: "scalardl-client"
   spec:
     containers:
       - name: scalardl-client
         image: eclipse-temurin:8-jdk
         command: ['sleep']
         args: ['inf']
         volumeMounts:
           - name: "client-keys"
             mountPath: "/keys"
             readOnly: true
     volumes:
       - name: "client-keys"
         secret:
           secretName: "client-keys"
     restartPolicy: Never
   EOF

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

   kubectl get pod scalardl-client

   【コマンド実行結果】

   NAME              READY   STATUS    RESTARTS   AGE
   scalardl-client   1/1     Running   0          11s

ステップ8. クライアントコンテナで ScalarDL サンプルコントラクトを実行する

以下に最低限の手順を説明します。ScalarDL の詳細やコントラクトについて知りたい場合は、Getting Started with ScalarDL をご覧ください。

1. クライアントコンテナで bash を実行します。

   kubectl exec -it scalardl-client -- bash

   この手順の後、クライアントコンテナで各コマンドを実行します。

2. git、curl、および unzip コマンドをクライアントコンテナにインストールします。

   apt update && apt install -y git curl unzip

3. ScalarDL Java Client SDK git リポジトリのクローンを作成します。

   git clone https://github.com/scalar-labs/scalardl-java-client-sdk.git

4. ディレクトリを scalardl-java-client-sdk/ に変更します。

   cd scalardl-java-client-sdk/

   pwd

   【コマンド実行結果】

   
   /scalardl-java-client-sdk

5. ブランチを任意のバージョンに変更します。

   git checkout -b v3.6.0 refs/tags/v3.6.0

   git branch

   【コマンド実行結果】

     master
   * v3.6.0

   別のバージョンを使用する場合は、使用するバージョン (タグ) を指定してください。同じバージョンの ScalarDL Ledger と ScalarDL Java Client SDK を使用する必要があります。

6. サンプルコントラクトを作成します。

   ./gradlew assemble

7. ScalarDL の CLI ツールは ScalarDL Java Client SDK Releases からダウンロードしてください。

   curl -OL https://github.com/scalar-labs/scalardl-java-client-sdk/releases/download/v3.6.0/scalardl-java-client-sdk-3.6.0.zip

   同じバージョンの CLI ツールと ScalarDL Ledger を使用する必要があります。

8. scalardl-java-client-sdk-3.6.0.zip ファイルを解凍します。

   unzip ./scalardl-java-client-sdk-3.6.0.zip

9. Kubernetes クラスター上の ScalarDL Ledger にアクセスするための構成ファイル (client.properties) を作成します。

   cat << 'EOF' > client.properties
   scalar.dl.client.server.host=scalardl-ledger-envoy.default.svc.cluster.local
   scalar.dl.client.cert_holder_id=client
   scalar.dl.client.cert_path=/keys/certificate
   scalar.dl.client.private_key_path=/keys/private-key
   EOF

10. クライアントの証明書ファイルを登録します。

    ./scalardl-java-client-sdk-3.6.0/bin/register-cert --properties ./client.properties

11. サンプルコントラクトStateUpdaterを登録します。

    ./scalardl-java-client-sdk-3.6.0/bin/register-contract --properties ./client.properties --contract-id StateUpdater --contract-binary-name com.org1.contract.StateUpdater --contract-class-file ./build/classes/java/main/com/org1/contract/StateUpdater.class

12. サンプルコントラクトStateReaderを登録します。

    ./scalardl-java-client-sdk-3.6.0/bin/register-contract --properties ./client.properties --contract-id StateReader --contract-binary-name com.org1.contract.StateReader --contract-class-file ./build/classes/java/main/com/org1/contract/StateReader.class

13. コントラクトStateUpdaterを実行します。

    ./scalardl-java-client-sdk-3.6.0/bin/execute-contract --properties ./client.properties --contract-id StateUpdater --contract-argument '{"asset_id": "test_asset", "state": 3}'

    このサンプルコントラクトは、test_asset という名前のアセットの state (値) を 3 に更新します。

14. コントラクト StateReader を実行します。

    ./scalardl-java-client-sdk-3.6.0/bin/execute-contract --properties ./client.properties --contract-id StateReader --contract-argument '{"asset_id": "test_asset"}'

    【コマンド実行結果】

    Contract result:
    {
      "id" : "test_asset",
      "age" : 0,
      "output" : {
        "state" : 3
      }
    }

15. アセットの検証リクエストを実行します。

    ./scalardl-java-client-sdk-3.6.0/bin/validate-ledger --properties ./client.properties --asset-id "test_asset"

    【コマンド実行結果】

    {
      "status_code" : "OK",
      "Ledger" : {
        "id" : "test_asset",
        "age" : 0,
        "nonce" : "f31599c6-e6b9-4b77-adc3-61cb5f119bd3",
        "hash" : "9ExfFl5Lg9IQwdXdW9b87Bi+PWccn3OSNRbhmI/dboo=",
        "signature" : "MEQCIG6Xa4WOWGMIIbA3PnCje4aAapYfCMerF54xRW0gaUuzAiBCA1nCAPoFWgxArB34/u9b+KeoxQBMALI/pOzMNoLExg=="
      },
      "Auditor" : null
    }
    • 参考情報
      • 資産データが改ざんされていない場合、検証リクエスト (validate-ledger コマンド) は結果として OK を返します。
      • 資産データが改ざんされている場合 (例: DB の state 値が改ざんされている場合)、検証リクエスト (validate-ledger コマンド) は結果として OK 以外の値 (例：INVALID_OUTPUT) を返します。以下のような。 【コマンド実行結果 (資産データが改ざんされた場合) 】

        {
          "status_code" : "INVALID_OUTPUT",
          "Ledger" : {
            "id" : "test_asset",
            "age" : 0,
            "nonce" : "f31599c6-e6b9-4b77-adc3-61cb5f119bd3",
            "hash" : "9ExfFl5Lg9IQwdXdW9b87Bi+PWccn3OSNRbhmI/dboo=",
            "signature" : "MEQCIGtJerW7N93c/bvIBy/7NXxoQwGFznHMmV6RzsgHQg0dAiBu+eBxkfmMQKJY2d9fLNvCH+4b+9rl7gZ3OXJ2NYeVsA=="
          },
          "Auditor" : null
        }
        • このようにして、ScalarDL Ledger はデータの改ざんを検出できます。

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

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

1. ScalarDL Ledger、ScalarDL Schema Loader、PostgreSQL をアンインストールします。

   helm uninstall scalardl-ledger schema-loader-ledger postgresql-ledger

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

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

3. 作業ディレクトリとサンプルファイル (構成ファイル、秘密鍵、証明書) を削除します。

   cd ~

   rm -rf ~/scalardl-test/

参考文献

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

• Helm Charts をはじめよう (Prometheus Operator を使用したモニタリング)
• Helm Charts をはじめよう (Loki スタックを使用したロギング)
• Helm Charts をはじめよう (Scalar Manager)