📣新登場！TiDB Cloud BYOC、TiDB Cloud Filesystem、PostgreSQL-compatible TiDB Cloud Starter がパブリックプレビュー中。このページは自動翻訳されたものです。原文はこちらからご覧ください。
AI
開発者
ベストプラクティス
API

マシン間でファイルシステムを共有する

TiDB Cloud Filesystem では、環境間でファイルをコピーすることなく、別のユーザー、マシン、CI ジョブ、またはエージェントとファイルを共有できます。受信者ごとに個別のスコープ付きトークンを発行することで、パスと操作ごとにアクセスを制限でき、他の受信者に影響を与えずに特定の受信者のアクセスだけを取り消せます。

このガイドでは、ディレクトリへの読み取り専用アクセスを 24 時間付与し、受信者の権限を確認してから、トークンを取り消す方法を説明します。

前提条件

開始する前に、以下を確認してください。

  • 既存のファイルシステム用のオーナートークンを持っており、そのリージョンを把握していること。
  • 所有者の環境と受信者の環境の両方に TiDB Cloud CLI (ti) をインストールしていること。
  • スコープ付きトークンを転送するための、シークレットマネージャーなどの安全なチャネルがあること。

Bash または Zsh を使用してください。チュートリアル全体を通して、2 つの別々のシェルを開いたままにします。1 つは信頼できるマシン上でトークンの作成と取り消しを行う 所有者シェル、もう 1 つはアクセスをテストするための 受信者シェル です。受信者はオーナートークンや TiDB Cloud API キーを持つ必要はありません。

CI またはエージェントでは、入力プロンプトを実行する代わりに、各環境の TI_FS_TOKEN に適切なトークンを注入してください。表示されているとおりにリージョンを設定し、TI_FS_FILE_SYSTEM_ID をクリアします。クリーンアップまで、両方の環境で share_path を、所有者の環境で reviewer_token_id を保持してください。

所有者シェルで、リージョンを設定し、プロンプトでオーナートークンを読み込みます。入力内容は表示されません。

unset TI_FS_FILE_SYSTEM_ID
export TI_REGION_CODE="<filesystem-region-code>"
printf 'Owner token: '
read -rs TI_FS_TOKEN && export TI_FS_TOKEN && printf '\n'

アクセスの取り消しが完了するまで、オーナートークンは TI_FS_TOKEN に保持してください。これはファイル操作とトークン管理の両方の認証に使用されます。その他の認証方法については、ファイルシステムトークンの管理 を参照してください。

特定のファイルへのアクセスを付与する

所有者シェルで、次の操作を行います。

  1. 一意のディレクトリを作成し、サンプルファイルをアップロードします。

    share_path="/sharing-example-$(date +%s)-$$"
ti fs create-directory --path "$share_path"
printf 'Shared review sample\n' | ti fs copy-file \
  --from-stdin --to-remote "$share_path/summary.txt"
ti fs read-file --path "$share_path/summary.txt"

    read-file の想定出力は Shared review sample です。エラーがある場合は、先に解消してから続行してください。

  2. このディレクトリに対する読み取りと一覧表示のみを許可するトークンを作成します。

    ti fs generate-file-system-scoped-token \
  --subject reviewer \
  --ttl 24h \
  --allow "$share_path:read,list"

    返された fs_token は安全に保存してください。これは発行時にのみ表示されます。取り消しのために、返された token_id も保存します。

    reviewer_token_id="<returned-token-id>"

  3. 安全なチャネルを通じて、スコープ付きトークン、リージョンコード、および share_path の正確な値を受信者に送信します。オーナートークンは非公開のままにしてください。マウント経由でファイルを更新した場合は、アクセス情報を送る前に、更新内容が共有可能な状態になっていることを確認してください。

受信者ごとに個別のスコープ付きトークンを作成すると、アクセスを個別に取り消せます。その他の権限の組み合わせについては、ファイルシステムトークンの管理 を参照してください。

別のマシンから共有ファイルにアクセスする

受信者シェルで、次の操作を行います。

  1. リージョンと共有パスを設定し、プロンプトでスコープ付きトークンを読み込みます。

    unset TI_FS_FILE_SYSTEM_ID
export TI_REGION_CODE="<filesystem-region-code>"
share_path="<shared-directory-path>"
printf 'Scoped token: '
read -rs TI_FS_TOKEN && export TI_FS_TOKEN && printf '\n'

    所有者から提供されたリージョンと正確なディレクトリパスを使用してください。トークンがファイルシステムを識別するため、ファイルシステム ID や CLI プロファイルをコピーする必要はありません。

  2. ディレクトリを一覧表示し、ファイルを読み取ります。

    ti fs list-files --path "$share_path"
ti fs read-file --path "$share_path/summary.txt"

    read-file の想定出力は Shared review sample です。

  3. 書き込みと、ディレクトリ外へのアクセスが拒否されることを確認します。

    printf 'This write must be rejected\n' | ti fs copy-file \
  --from-stdin --to-remote "$share_path/denied-write.txt"
ti fs list-files --path /

    各コマンドで認可エラーが返ることを想定しています。その他のエラーでは権限を確認したことにはなりません。いずれかの操作が成功した場合は、続行する前にトークンを取り消してください。

所有者シェルで、ti fs describe-file --path "$share_path/denied-write.txt" を実行し、ファイルが存在しないことが報告されることを確認します。

共有ディレクトリをマウントする（任意）

以下のコマンドは Linux FUSE または macFUSE を使用する macOS 向けです。macFUSE がない Mac では、--driver webdav を使用し、このコマンドから --read-only を省略してください。WebDAV はそのオプションを受け付けません。スコープ付きトークンにより、サービス側では引き続き読み取り専用アクセスが強制されます。マウントの前提条件 も参照してください。

受信者シェルで、共有ディレクトリをマウントします。

review_mount="$(mktemp -d "$HOME/ti-fs-review.XXXXXX")"
ti fs mount-file-system \
  --remote-path "$share_path" \
  --mount-path "$review_mount" \
  --driver fuse \
  --read-only

サンプルファイルを読み取ります。

cat "$review_mount/summary.txt"

想定出力は Shared review sample です。読み取りに 30 秒以上かかる場合は中断し、マウントのトラブルシューティング に従ってください。

スコープ付きトークンにより、サービス側で読み取り専用アクセスが強制されます。FUSE の --read-only オプションも、このローカルマウント経由の書き込みをブロックします。

更新内容が共有可能な状態になっていることを確認する

後続のワークフローでマウント経由の書き込みを行う場合は、別のユーザーに渡す前にファイルを閉じ、安全に書き込みを完了してください。FUSE の場合は、マウントを drain するか、正常にアンマウントしてください。WebDAV の場合は通常どおりアンマウントします。drain はサポートされていません。更新されたファイルは、直接 ti fs read-file リクエストで確認してください。

同じファイルへの同時書き込みは避けてください。変更は自動的にはマージされません。ユーザーごとに分離されたワークスペースが必要な場合は、レイヤーとチェックポイント を使用してください。

共有アクセスを停止する

以下の手順を順番に実行してください。

  1. 受信者: 共有ファイルを使用しているアプリケーションを停止します。ディレクトリをマウントしている場合は、アンマウントします。

    ti fs unmount-file-system --mount-path "$review_mount"

    手順 3 の確認のため、スコープ付きトークンは設定したままにしてください。

  2. 所有者: 元の所有者シェルで、作成時に保存した ID を使ってトークンを取り消します。

    ti fs delete-file-system-token --token-id "$reviewer_token_id"

    このコマンドは TiDB Cloud API 認証情報またはオーナートークンのいずれかを受け付けます。オーナートークンは TI_FS_TOKEN または --fs-token を通じて渡す必要があります。import-file-system-token によってローカル認証情報にのみ保存されたオーナートークンはここでは無視され、その場合 delete-file-system-token と list-file-system-tokens はどちらも API 認証情報を要求して終了コード 3 で終了します。トークンメタデータを確認するには、ti fs list-file-system-tokens --output text を使用してください。

  3. 受信者: 認証キャッシュが更新されるまで約 10 秒待ってから、同じスコープ付きトークンで再度読み取りを実行します。

    ti fs read-file --path "$share_path/summary.txt"

    認証エラーまたは認可エラーが返ることを想定しています。読み取りがまだ成功する場合は、取り消したトークン ID を確認し、キャッシュ間隔の後に再試行してください。ネットワークエラーでは取り消しを確認したことにはなりません。

    取り消しを確認したら、トークンをクリアします。

    unset TI_FS_TOKEN TI_REGION_CODE

    この例をマウントしていた場合は、rmdir "$review_mount" で空のローカルディレクトリを削除してください。

  4. 所有者: サンプルディレクトリを削除し、削除されたことを確認します。

    ti fs delete-file --path "${share_path:?Set the example directory first}" --recursive
ti fs describe-file --path "$share_path"

    describe-file では not-found エラーが返ることを想定しています。

取り消しによって、ファイルシステム本体や他のトークンはそのまま維持されます。受信者がすでにダウンロードまたはキャッシュしたファイルを消去できません。環境変数をクリアするだけでは、トークンは取り消されません。

次のステップ

このページは役に立ちましたか？