メインコンテンツまでスキップ
バージョン: 3.9
Features and pricing

ScalarDL Ledger と Auditor を介して ScalarDL アプリケーションを実行する

注記

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

このガイドでは、ScalarDL Ledger と Auditor を介して ScalarDL アプリケーションを実行する方法について説明します。このドキュメントでは、すでに ScalarDL Ledger をはじめようチュートリアルを試し、Java で ScalarDL アプリケーションを書くガイドを参考にして Client SDK を使用して ScalarDL を統合したアプリケーションを作成したことを前提としています。

ScalarDL Auditor とは何ですか？​

ScalarDL Auditor は、Ledger の同一の状態を管理し、クライアントがビザンチン故障を検出するのを支援するコンポーネントです。Auditor を使用すると、セキュリティの観点から有益ですが、追加の処理コストが必要になります。したがって、ユースケースに必要かどうかを慎重に検討してください。

注記

ビザンチン故障検出を適切に機能させるには、Ledger と Auditor を異なる管理ドメインに展開および管理する必要があります。ただし、このガイドでは簡単にするため、scalardl-samples 環境でのシンプルな設定を使用します。ここでは、Ledger と Auditor の両方が同じネットワーク上に配置され、同じ管理ドメイン内で管理されます。

設定する​

Ledger と Auditor を介して ScalarDL アプリケーションを実行する前に、まず Ledger、Auditor、および ScalarDL と相互作用するクライアントを設定する必要があります。

以下に説明するように、設定する必要がある重要なオプションと決定事項がいくつかあります。

Auditor を有効にする​

Ledger と Auditor を介してアプリケーションを実行するため、Auditor を有効にする必要があります。Auditor の有効化は、以下のようにクライアントと Ledger の設定で行う必要があります。

  • クライアントの設定で、scalar.dl.client.auditor.enabled を true に設定します。
  • Ledger の設定で、scalar.dl.ledger.auditor.enabled を true に設定します。

次に、ScalarDL は Asset Proof を使用して Ledger と Auditor 間の整合性をチェックするため、scalar.dl.ledger.proof.enabled を true に設定して Ledger 設定で Asset Proof を有効にする必要があります。また、認証方式を決定するセクションで選択した認証方式に応じて、Asset Proof に署名するために Ledger と Auditor の設定で適切な秘密鍵またはシークレットキーを設定する必要があります。

注記

scalardl-samples 環境を使用している場合は、対応するストレージの ledger.properties および auditor.properties ファイルを参照してください。

設定の詳細については、以下を参照してください:

認証方法を決定する​

クライアントの認証方式として、電子署名または HMAC のいずれかを選択する必要があります。電子署名方式は認証に加えて否認防止も提供しますが遅く、HMAC 方式は認証のみですが高速です。

認証方法は以下のように設定できます。クライアント、Ledger、および Auditor の全体で同じ方法 (digital-signature または hmac) を設定する必要があります。

  • クライアントの設定で scalar.dl.client.authentication.method を digital-signature または hmac に設定します。
  • Ledger の設定で scalar.dl.ledger.authentication.method を digital-signature または hmac に設定します。
  • Auditor の設定で scalar.dl.auditor.authentication.method を digital-signature または hmac に設定します。

また、秘密情報の準備も必要です。電子署名方式の場合は証明書と秘密鍵、HMAC 方式の場合はシークレットキーを用意してください。ScalarDL の認証について詳しくは ScalarDL 認証ガイドを参照してください。

設定の詳細については、以下を参照してください:

データベース設定を決定する​

Ledger と Auditor の両方が ScalarDB を使用してデータベースと相互作用するため、様々なデータベース上で ScalarDL を実行できます。そのため、アプリケーションの要件に基づいて ScalarDB がサポートするデータベースを決定し、いくつかの ScalarDB パラメータを設定する必要があります。

ScalarDB パラメータの詳細については、ScalarDB の設定も参照してください。

下位のデータベース​

使用するデータベースの設定方法:

  • Ledger と Auditor の設定で、scalar.db.storage、scalar.db.contact_points、scalar.db.username、および scalar.db.password を利用するデータベースに合わせて設定します。

ScalarDB を介して ScalarDL でサポートされるデータベースとそのバージョンについては、要件を参照してください。

警告

アプリケーションが Function 機能を介してテーブルを読み書きし、そのテーブルが ScalarDB アプリケーションからも直接アクセスされる場合は、ここで選択したデータベースを適切に設定する必要があります。具体的には、一貫性を保証するために、ScalarDL アプリケーションと ScalarDB アプリケーションの両方が同じ Coordinator テーブルを参照する必要があります。

分離レベル​

Ledger は ScalarDB の Consensus Commit トランザクションマネージャを利用してトランザクションを管理します。トランザクションマネージャは、トランザクションの分離性を保証し、整合性・正確性を担保します。

Ledger の分離レベルは以下のように設定できます。どの分離レベルを使うべきかわからない場合は、SERIALIZABLE を使用してください。

  • Ledger の設定で scalar.db.consensus_commit.isolation_level に希望する分離レベルを設定します。デフォルト値は SNAPSHOT です。
注記

Auditor は Consensus Commit トランザクションマネージャを利用しないため、Auditor 用にトランザクションマネージャや分離レベルを設定する必要はありません。

制限事項​

ScalarDL は ScalarDB を活用していますが、以下の ScalarDB 機能は ScalarDL の一貫性保証メカニズムと互換性がありません。

その他の設定を決定する​

クライアント、Ledger、および Auditor には TLS や gRPC などの設定を追加で設定可能です。詳細は以下を参照してください。

Ledger と Auditor を起動する​

Ledger、Auditor、およびクライアントを設定した後、Ledger と Auditor を起動する必要があります。

このガイドでは、Ledger と Auditor をローカルで起動するために scalardl-samples のコンテナベース環境を使用します。リポジトリのクローンが完了していない場合は、前提条件とScalarDL サンプルリポジトリのクローンを作成するを参照してください。

ローカルまたはクラウドベースの Kubernetes 環境で Ledger と Auditor をローカルで起動する方法の詳細については、ローカル Kubernetes 環境に ScalarDL をデプロイするまたはクラウドベースの Kubernetes 環境に ScalarDL をデプロイするをそれぞれ参照してください。

データベースを選択する​

データベースを選択し、コマンドに従って ScalarDL Ledger と Auditor をデプロイしてください。

ライセンスを設定する

ScalarDL Auditor を使用するには商用ライセンスが必要です。以下の手順でライセンスを設定してください。

  1. mysql/docker-compose-ledger.yml ファイルで Enterprise エディションのコンテナイメージを有効にします:

    • イメージを変更する前 (デフォルト設定):

      # docker-compose-ledger.yml
      services:
        scalardl-ledger:
          image: ghcr.io/scalar-labs/scalardl-ledger:${SCALARDL_VERSION}
          # image: ghcr.io/scalar-labs/scalardl-ledger-byol:${SCALARDL_VERSION}

    • イメージを変更した後:

      # docker-compose-ledger.yml
      services:
        scalardl-ledger:
          # image: ghcr.io/scalar-labs/scalardl-ledger:${SCALARDL_VERSION}
          image: ghcr.io/scalar-labs/scalardl-ledger-byol:${SCALARDL_VERSION}

  2. ScalarDL Ledger と Auditor のライセンスキーを設定します。mysql/ledger.properties と mysql/auditor.properties ファイルで、<SET_YOUR_LICENSE_KEY> をライセンスキーに置き換えます。例:

    ##### PLEASE REPLACE THIS VALUE WITH YOUR LICENSE KEY (ENTERPRISE EDITION ONLY) #####
    scalar.dl.licensing.license_key={"organization_name":"XXXXXXXX","expiration_date_time":"YYYY-MM-DDTHH:mm:SS+TIMEZONE","product_name":"ScalarDL Ledger","product_version":N,"license_type":"trial","signature":"XXXXXXXX"}
    ##### PLEASE REPLACE THIS VALUE WITH YOUR LICENSE KEY (ENTERPRISE EDITION ONLY) #####

  3. 証明書を利用してライセンスを検証するには、mysql/docker-compose-ledger.yml と mysql/docker-compose-auditor.yml ファイルを以下のように更新します。試用ライセンスを使用している場合は、このステップをスキップしてください。

    • 証明書ファイルパスを変更する前 (デフォルト設定):

      # docker-compose-ledger.yml
      services:
        scalardl-ledger:
          volumes:
            - ./ledger.properties:/scalar/ledger/ledger.properties.tmpl
            - ../fixture/ledger-key.pem:/scalar/ledger-key.pem
            - ../fixture/trial-license-cert.pem:/scalar/license-cert.pem
            # If you have a commercial license key, you must use `commercial-license-cert.pem` instead of `trial-license-cert.pem`.
            # - ../fixture/commercial-license-cert.pem:/scalar/license-cert.pem
      # docker-compose-auditor.yml
      services:
        scalardl-auditor:
          volumes:
            - ./auditor.properties:/scalar/auditor/auditor.properties.tmpl
            - ../fixture/auditor-key.pem:/scalar/auditor-key.pem
            - ../fixture/trial-license-cert.pem:/scalar/license-cert.pem
            # If you have a commercial license key, you must use `commercial-license-cert.pem` instead of `trial-license-cert.pem`.
            # - ../fixture/commercial-license-cert.pem:/scalar/license-cert.pem

    • 証明書ファイルパスを変更した後:

      # docker-compose-ledger.yml
      services:
        scalardl-ledger:
          volumes:
            - ./ledger.properties:/scalar/ledger/ledger.properties.tmpl
            - ../fixture/ledger-key.pem:/scalar/ledger-key.pem
            # - ../fixture/trial-license-cert.pem:/scalar/license-cert.pem
            # If you have a commercial license key, you must use `commercial-license-cert.pem` instead of `trial-license-cert.pem`.
            - ../fixture/commercial-license-cert.pem:/scalar/license-cert.pem
      # docker-compose-auditor.yml
      services:
        scalardl-auditor:
          volumes:
            - ./auditor.properties:/scalar/auditor/auditor.properties.tmpl
            - ../fixture/auditor-key.pem:/scalar/auditor-key.pem
            # - ../fixture/trial-license-cert.pem:/scalar/license-cert.pem
            # If you have a commercial license key, you must use `commercial-license-cert.pem` instead of `trial-license-cert.pem`.
            - ../fixture/commercial-license-cert.pem:/scalar/license-cert.pem

ScalarDL を起動する

以下の手順に従って ScalarDL Ledger と Auditor の使用を開始できます:

  1. 以下のコマンドを実行して MySQL をローカルで実行します:

    docker compose -f mysql/docker-compose-auditor.yml up -d mysql

  2. 以下のコマンドを実行して ScalarDL Ledger と Auditor のデータベーススキーマを読み込みます:

    docker compose -f mysql/docker-compose-auditor.yml up -d scalardl-ledger-schema-loader
    docker compose -f mysql/docker-compose-auditor.yml up -d scalardl-auditor-schema-loader

  3. 以下のコマンドを実行して ScalarDL Ledger、Auditor、およびその依存コンポーネントを起動します:

    docker compose -f mysql/docker-compose-auditor.yml up -d

Client SDK をダウンロードする​

ScalarDL コマンドを実行する場合は Client SDK をダウンロードしてください。手順については、Client SDK のダウンロードを参照してください。

クライアントから証明書またはシークレットキーを登録する​

認証方式を決定するで選択した認証方法を選択し、コマンドに従って認証を設定してください。

電子署名認証方式の場合、以下の証明書を登録する必要があります:

  • クライアントの証明書を Ledger と Auditor に登録する
  • Ledger の証明書を Auditor に登録する
  • Auditor の証明書を Ledger に登録する

これらの証明書は register-cert コマンドを使用して登録できます。このコマンドの詳細については、ScalarDL クライアントコマンドリファレンスを参照してください。

scalardl register-cert --properties <CLIENT_PROPERTIES_FILE>
scalardl register-cert --properties <LEDGER_AS_CLIENT_PROPERTIES_FILE>
scalardl register-cert --properties <AUDITOR_AS_CLIENT_PROPERTIES_FILE>

具体的には、scalardl-samples 環境では、../fixture/ にあるサンプルプロパティファイルを使用して client/bin/scalardl にあるコマンドを実行し、以下のように証明書を登録します。

client/bin/scalardl register-cert --properties ../fixture/client.properties
client/bin/scalardl register-cert --properties ../fixture/ledger.as.client.properties
client/bin/scalardl register-cert --properties ../fixture/auditor.as.client.properties
警告

本番環境では、サンプルの秘密鍵と証明書を使用しないでください。独自の証明書を取得する方法の詳細については、証明書の取得方法を参照してください。

ScalarDL Java Client SDK の ClientService を使用して証明書を登録することもできます。

クライアントからコントラクトとファンクションを登録する​

以下のコマンドでコントラクトを登録できます。このコマンドの詳細については、ScalarDL クライアントコマンドリファレンスを参照してください。

scalardl register-contract --properties <CLIENT_PROPERTIES_FILE> --contract-id <CONTRACT_ID> --contract-binary-name <CONTRACT_BINARY_NAME> --contract-class-file <CONTRACT_CLASS_FILE>

ファンクションは以下のコマンドで登録できます。このコマンドの詳細については、ScalarDL クライアントコマンドリファレンスを参照してください。

scalardl register-function --properties <CLIENT_PROPERTIES_FILE> --function-id <FUNCTION_ID> --function-binary-name <FUNCTION_BINARY_NAME> --function-class-file <FUNCTION_CLASS_FILE>

ScalarDL Java Client SDK の ClientService を使用してコントラクトとファンクションを登録することもできます。

アプリケーションを実行する​

クライアントからコントラクトとファンクションの登録が完了したら、ScalarDL アプリケーションを実行できます。

アプリケーションでデータを検証する​

データを検証するで説明されている ClientService API を使用するか、クライアント CLI コマンドを使用してデータを検証できます。どちらの場合も、ScalarDL Auditor を使用する際は内部的にコントラクト実行を使用するため、検証前に ValidateLedger コントラクトをビルドして登録する必要があります。

ScalarDL Java Client SDK リポジトリで以下のコマンドを実行して検証コントラクトをビルドできます。v3.11.0 などの特定のバージョンをチェックアウトしてください。

git clone https://github.com/scalar-labs/scalardl-java-client-sdk.git
cd scalardl-java-client-sdk/
git checkout <SCALARDL_VERSION>
./gradlew assemble

上記のコマンドを実行すると、build/classes/java/main/com/scalar/dl/client/contract/ValidateLedger.class が生成されます。その後、register-contract コマンドを使用して登録できます。validate-ledger は、クライアントが検証を行う際に指定するデフォルトのコントラクト ID です。これを変更したい場合は、クライアント設定で scalar.dl.client.auditor.linearizable_validation.contract_id を独自の検証コントラクト ID に設定してください。

scalardl register-contract --properties <CLIENT_PROPERTIES_FILE> --contract-id validate-ledger --contract-binary-name com.scalar.dl.client.contract.ValidateLedger --contract-class-file <PATH_TO_VALIDATE_LEDGER_CLASS>

validate-ledger コマンドを実行してデータを検証できます。このコマンドの詳細については、ScalarDL クライアントコマンドリファレンスを参照してください。

scalardl validate-ledger --properties <CLIENT_PROPERTIES_FILE> --asset-id="<ASSET_ID>"