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

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

注記

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

このガイドでは、ScalarDL Ledger と Auditor を介して ScalarDL アプリケーションを実行する方法について説明します。このドキュメントでは、すでにクイックスタートチュートリアルのいずれかを試し、アプリケーションを書くガイドを参考にしてクライアント 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

Ledger と Auditor 間の認証を設定する (電子署名認証のみ)​

電子署名認証を使用する場合、Ledger の証明書と Auditor の証明書を互いに登録する必要があります。HMAC 認証を使用している場合は、この手順をスキップしてください。

Ledger と Auditor の証明書を登録するには、Client SDK に含まれるクライアントコマンドを実行する必要があります。Client SDK を取得するには、Client SDK をダウンロードするを参照してください。ダウンロード後、以下のコマンドを実行します:

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

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

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

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

HashStore、TableStore、または Ledger 抽象化のクライアントを設定する​

アプリケーションが基づく抽象化 (具体的には、HashStore、TableStore、または Ledger) に応じて、設定手順が異なります。抽象化を選択して、手順に従ってください。

HashStore クライアントをブートストラップする

アプリケーションで HashStoreClientService を作成する際、クライアント証明書またはシークレットキーと HashStore を使用するために必要なコントラクトが、ClientConfig の設定に基づいて自動的に登録されます。したがって、HashStore を手動でブートストラップする必要はありません。テスト目的などで手動で実行したい場合は、Client SDK をダウンロードするに従って HashStore Client SDK をダウンロードし、以下のコマンドを実行してください。

scalardl-hashstore bootstrap --properties <CLIENT_PROPERTIES_FILE>

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

必要な ID とコントラクトの登録が完了したら、ScalarDL を統合したアプリケーションを実行できます。

参照​

各コマンドの詳細については、以下のコマンドリファレンスを参照してください:

テクニカルサポートに問い合わせ
商用ライセンスをご契約のお客様のみご利用いただけます。
ドキュメントの問題を報告
このページについて何かお気づきの点がありましたら、こちらから報告いただけます。