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

名前空間に制限付きでアクセスする

注記

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

警告

名前空間機能は現在パブリックプレビューです。この機能と関連ドキュメントは変更される可能性があります。

このドキュメントでは、ScalarDL のマルチテナント環境において、名前空間を制限付きで設定およびアクセスする方法について説明します。

名前空間への制限アクセスとは？​

名前空間へのアクセスを制限すると、単一の ScalarDL クラスター上で複数のテナントをホストしながら、テナント間での厳格なデータ分離を確保できます。各テナントは独自の名前空間内で動作し、その名前空間内のアセットのみにアクセスできます。

セキュリティモデル​

名前空間への制限アクセスは、ポートベースのアクセス制御に依存します:

  • 特権ポート: 管理者が名前空間管理と資格情報登録に使用します。管理者のみがこのポートにアクセスできる必要があります。
  • 非特権ポート: テナントクライアントがコントラクト登録と実行に使用します。テナントは、特定の名前空間に登録された資格情報を使用してこのポートにアクセスします。

テナントの資格情報は特定の名前空間に登録されているため、これらの資格情報で実行されるすべての操作は自動的にその名前空間にスコープされます。テナントは、割り当てられた名前空間外でコントラクトを登録したり操作を実行したりできません。

注記

このチュートリアルでは、簡単にするためデフォルトポートを使用し、特権および非特権ポートの両方が同じクライアントマシンからアクセス可能であることを前提としています。本番環境では、管理者のみが特権ポートにアクセスできるようにアクセスを制限し、テナントは非特権ポートのみを通じて接続するようにしてください。

前提条件​

ScalarDL サンプルリポジトリをクローンする​

ターミナルを開き、次のコマンドを実行して ScalarDL サンプルリポジトリをクローンします:

git clone https://github.com/scalar-labs/scalardl-samples

次に、以下のコマンドを実行して、サンプル設定を含むディレクトリに移動します:

cd scalardl-samples

お使いのデータベースで ScalarDL を起動する​

データベースを選択し、コマンドに従って ScalarDL Ledger をデプロイしてください。ScalarDL がサポートするデータベースの一覧については、データベースを参照してください。

ライセンスを設定する (Enterprise Edition のみ)

ScalarDL Enterprise Edition を使用している場合は、次のようにライセンスを設定します。Community Edition を使用している場合は、次のセクションに進んで ScalarDL を起動してください。

ライセンスの設定についてはこちらをご覧ください

  1. 次のように、mysql/docker-compose-ledger.yml ファイルで Enterprise Edition のコンテナイメージを有効にします。

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

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

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

      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 のライセンスキーを設定します。mysql/ledger.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 ファイルを次のように更新します。試用版ライセンスを使用している場合は、この手順をスキップしてください。

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

      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

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

      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

ScalarDL を起動する

以下の手順に従って、ScalarDL Ledger を開始できます。

  1. 次のコマンドを実行して、MySQL をローカルで実行します。

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

  2. 次のコマンドを実行して、ScalarDL Ledger のデータベーススキーマをロードします。

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

  3. 次のコマンドを実行して ScalarDL Ledger および依存するコンポーネントを起動します。

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

クライアントSDKをダウンロードする​

次に、ScalarDL クライアントツールとサンプルを使用して ScalarDL と対話します。

デプロイされた ScalarDL バージョンと同じバージョンを指定し、以下のコマンドを実行してツールをダウンロードするために使用します:

VERSION=$(grep SCALARDL_VERSION .env | awk -F= '{print $2}')

次に、以下のコマンドを実行してツールをダウンロードします:

curl -OL https://github.com/scalar-labs/scalardl/releases/download/v$VERSION/scalardl-java-client-sdk-$VERSION.zip
unzip scalardl-java-client-sdk-$VERSION.zip
mv scalardl-java-client-sdk-$VERSION client

テナント名前空間を設定する​

このセクションでは、新しいテナント名前空間を設定する手順について説明します。

管理者クライアントを設定する​

テナント名前空間と資格情報を管理するため、管理者用のクライアントプロパティを設定する必要があります。管理者クライアント用の最小必要プロパティを含む設定ファイルを作成するには、以下のコマンドを実行します:

cat << 'EOF' > admin.properties
# ScalarDL Ledger用のホスト名
scalar.dl.client.server.host=localhost

# エンティティID。各秘密鍵に対して設定する必要があり、名前空間内で一意でなければなりません。
scalar.dl.client.entity.id=admin

# 証明書ファイルへのパス
scalar.dl.client.entity.identity.digital_signature.cert_path=./fixture/client.pem

# 秘密鍵ファイルへのパス
scalar.dl.client.entity.identity.digital_signature.private_key_path=./fixture/client-key.pem
EOF

このチュートリアルでは、ScalarDL Ledger ホスト名に localhost を使用できます。秘密鍵と証明書については、scalardl-samples の fixture ディレクトリで提供されているもの (それぞれ client-key.pemとclient.pem) を使用できます。証明書保持者には、任意の一意の ID を指定できます。

警告

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

テナント名前空間を作成する​

管理者として、以下のコマンドを実行してテナント用の名前空間を作成します。この操作には特権ポートへのアクセスが必要です。

client/bin/scalardl create-namespace --properties admin.properties --namespace tenant_a

テナント資格情報を登録する​

以下のコマンドを実行して、新しく作成された名前空間にテナントの証明書を登録します。これにより、テナントの身元と名前空間が関連付けられます。

client/bin/scalardl register-cert --properties admin.properties --namespace tenant_a --entity-id foo --cert-path ./fixture/client.pem
注記

このサンプルでは、簡単にするため管理者クライアントと同じclient.pemを使用します。電子署名認証を使用する実際の本番環境では、テナントユーザーによって発行された証明書を使用すべきです。

テナント名前空間を使用する​

このセクションでは、テナントクライアントを設定して割り当てられた名前空間を操作する方法について説明します。

テナントクライアントを設定する​

割り当てられた名前空間でコントラクトを登録して実行したり、アセットを検証したりするため、テナント用のクライアントプロパティを設定する必要があります。テナントクライアント用の最小必要プロパティを含む設定ファイルを作成するには、以下のコマンドを実行します:

cat << 'EOF' > tenant.properties
# ScalarDL Ledger用のホスト名
scalar.dl.client.server.host=localhost

# エンティティID。前の手順で名前空間に登録されたエンティティIDと一致する必要があります。
scalar.dl.client.entity.id=foo

# クライアント要求が実行される名前空間
scalar.dl.client.context.namespace=tenant_a

# 証明書ファイルへのパス
scalar.dl.client.entity.identity.digital_signature.cert_path=./fixture/client.pem

# 秘密鍵ファイルへのパス
scalar.dl.client.entity.identity.digital_signature.private_key_path=./fixture/client-key.pem
EOF

コントラクトを登録して実行する​

テナントは、名前空間内でコントラクトを登録し実行できるようになりました。クライアントプロパティで設定された名前空間にすべての操作が自動的にスコープされるため、名前空間を意識することなく ScalarDL Ledger をはじめようで紹介された同じコントラクトを使用できます。

まず、以下のコマンドを実行してscalardl-samples内のコントラクトをコンパイルします:

./gradlew assemble

これにより build/classes/java/main/com/org1/contract/StateUpdater.class が生成されます。次に、以下のコマンドを実行してコントラクトを登録します:

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

以下のコマンドを実行してコントラクトを実行します:

client/bin/scalardl execute-contract --properties tenant.properties --contract-id StateUpdater --contract-argument '{"asset_id":"some_asset", "state":3}'

ファンクションを登録して実行する​

デフォルトでは、テナントは非特権ポートを通じてコントラクトを登録できますが、ファンクションは登録できません。テナントがファンクションを登録できるようにするには、管理者が以下の Ledger 設定オプションを有効にする必要があります:

  • scalar.dl.ledger.function.non_privileged_port_registration.enabled: true に設定すると、テナントが非特権ポートを通じてファンクションを登録できるようになります。デフォルトは false です。
  • scalar.dl.ledger.function.non_privileged_port_registration.overwrite.enabled: true に設定すると、テナントが非特権ポートを通じて既存のファンクションを上書きできるようになります。デフォルトは false です。

ファンクションの登録が有効になると、テナントはデフォルト名前空間と同じ方法で名前空間内のファンクションを登録して実行できます。

注記

ファンクションは、テナントのコンテキスト名前空間（scalar.dl.client.context.namespace で設定された名前空間）と同じ名前を持つ ScalarDB 名前空間、またはコンテキスト名前空間の後にアンダースコアが続く名前で始まる名前空間にのみアクセスできます。例えば、コンテキスト名前空間が tenant_a の場合、ファンクションは tenant_a、tenant_a_logs、tenant_a_2024 にアクセスできますが、tenant_ax や無関係な名前空間にはアクセスできません。ファンクションが Get、Scan、Put、Delete の各操作を実行する際、その操作で指定する名前空間はこれらのアクセス可能な名前空間のいずれかである必要があります。それ以外の名前空間を対象とする操作や、名前空間を指定しない操作は拒否されます。

ファンクションがアクセスする ScalarDB 名前空間は、テナントの名前空間をプレフィックスとして作成してください。このアクセスルールはプレフィックスベースであるため階層的です。短いコンテキスト名前空間は、そのプレフィックスを共有するより長い名前空間にアクセスできます（例えば、tenant_a は tenant_a_logs にアクセスできます）。テナント間の意図したアクセス境界がプレフィックスに反映されるよう、名前空間の命名を設計してください。なお、それらの名前空間内のテーブル名は任意です。

例えば、ファンクションを登録するには、以下のコマンドを実行します:

client/bin/scalardl register-function --properties tenant.properties --function-id test-function --function-binary-name com.example.function.TestFunction --function-class-file /path/to/TestFunction.class

ファンクションをコントラクトと一緒に実行するには、以下のコマンドを実行します:

client/bin/scalardl execute-contract --properties tenant.properties --contract-id StateUpdater --contract-argument '{"asset_id":"some_asset", "state":3}' --function-id test-function --function-argument '{}'

コントラクトとファンクションの更新の詳細については、コントラクトとファンクションのライフサイクルを管理するを参照してください。

アセットを検証する​

以下のコマンドを実行することで、デフォルト名前空間と同様に通常通りアセットを検証できます:

client/bin/scalardl validate-ledger --properties tenant.properties --asset-id="some_asset"

参照​

独自のコントラクトを記述するには、以下を参照してください:

Java アプリケーションで ScalarDL コンポーネントと対話するには、以下を参照してください:

名前空間とその管理方法について詳しく学ぶには、以下を参照してください:

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