## モジュール 1：TiDB Cloud ファイルシステムに慣れよう

`ti` は TiDB Cloud CLI のコマンド名です。これにより TiDB Cloud の様々なサービス管理を統一されたコマンドラインから行うことができます。管理対象には TiDB Cloud Filesystem および TiDB Cloud Starter が含まれます。

```mermaid
---
title: モジュール環境の概要
---
flowchart LR
  subgraph region["リージョン aws-${LAB:REGION_CODE}"]
    style region stroke-dasharray: 5 5
    USER["演習ユーザー"] --> TI["ti CLI"]
    TI -->|APIキーで管理| API["TiDB Cloud Filesystem"]
    TI -->|FSトークンでマウント・利用| API["TiDB Cloud Filesystem"]
  end
```

このモジュールは TiDB Cloud CLI「`ti`」コマンドへ慣れることを目的としています。`ti` のインストール、TiDB Cloud APIキーの設定、接続確認、CLIヘルプや出力制御について学びます。hermes-agent は次のモジュールからワークフローに参加します。

### 手順 1: TiDB Cloud CLI のインストール

- **[ターミナル 1](ssh://monitor1-ssh#1)** をクリックします。本モジュールの全コマンドは、このシェル上で `ubuntu` ユーザーとして実行します。
- TiDB Cloud CLI「`ti`」をダウンロード・インストールします。

```bash
curl -fsSL https://github.com/tidbcloud/ti-cli/releases/latest/download/install.sh | sh
export PATH="$HOME/.ti/bin:$PATH"
```

```output
...
  Docs: https://github.com/tidbcloud/ti-cli
```

- シェルプロファイルに `ti` コマンドを追加し、今後再度ターミナルを開いた際にも `ti` が使えるようにします。

```bash
grep -qxF 'export PATH="$HOME/.ti/bin:$PATH"' "$HOME/.bashrc" || \
  echo 'export PATH="$HOME/.ti/bin:$PATH"' >> "$HOME/.bashrc"
```

- TiDB Cloud CLI のバージョンを確認します。インストールしたバージョンはサンプル出力のものより新しい場合があります。

```bash
ti --version
```

```output
ti 0.2.1 (6b5d3f48e5b852d13906a592f64cac03b614eca9, 2026-08-11T09:07:43Z, linux/amd64)
```

### 手順 2: TiDB Cloud API キー（ペア）の取得

> [!IMPORTANT]
> このステップでは TiDB Cloud アカウントへのアクセスが必要です。組織の本番用アカウントではなく、ご自身のパーソナル TiDB Cloud アカウントの利用を推奨します。本演習で実施する作業は全て TiDB Cloud の無料枠内で完結します。

- [TiDB Cloud API Keys](https://tidbcloud.com/org-settings/api-keys) をクリックし、TiDB Cloud の Webコンソールを新しいタブで開きます。（**API Keys** ページでない場合は、**Organization Settings** 配下から見つけてください。）
- 右上の **Create API Key** をクリックします。
- **Description** に `lab-test` と入力し、**Generate API Key** をクリックするとAPIキーのペアが発行されます。
- このページは開いたままで次のステップに進みます。

### 手順 3: TiDB Cloud CLI の設定・基本操作を確認

- **[ターミナル 1](ssh://monitor1-ssh#1)** で以下のコマンドを実行します。リージョンは `aws-${LAB:REGION_CODE}` を指定済みです。プロンプトに従ってパブリックキー・プライベートキーをそれぞれ貼り付けます。

> [!TIP]
> プライベートキー貼り付け時、ターミナルには何も表示されませんが正常な挙動です。

```bash
ti configure --region-code aws-${LAB:REGION_CODE}
```

```output
{
  "profile": "default",
  "region_code": "aws-${LAB:REGION_CODE}",
  "credentials_stored": true
}
```

- この時点で `ti` CLI のデフォルト設定は次の通りになっています：
  - デフォルトリージョン: aws-${LAB:REGION_CODE}
  - TiDB Cloud サービス管理用の認証情報

> [!NOTE]
> 今後コマンドを実行する際も --region パラメータで明示的にリージョン指定を行います（意図明確化のため）。

- 指定リージョン内の全ファイルシステム一覧を表示してみましょう。ファイルシステムが無い場合も空リストで正常です。

```bash
ti fs list-file-systems --region aws-${LAB:REGION_CODE}
```

```output
{
  "region_code": "aws-${LAB:REGION_CODE}",
  "file_systems": []
}
```

- `ti` のオンラインヘルプを活用し、軽く探索してみましょう。次の例ですべての `ti` ヘルプ形式を網羅しています。`ti` のサブコマンド構造は最大2階層までです。

```bash
# TiDB Cloud CLI 全体ヘルプ
ti

# 利用できるサービスとグローバルパラメータ確認
ti help

# TiDB Cloud Filesystem の機能一覧
ti fs help

# TiDB Cloud Database の機能一覧
ti db help

# TiDB Cloud ファイルシステム作成方法のヘルプ
ti fs create-file-system help
```

- 先ほどは対話的に設定しましたが、非対話的に行うこともできます。次のコマンドを試し、出力を観察してください。

```bash
ti configure help | grep -i 'non-interactive'
```

```output
[--non-interactive]
  --non-interactive                   Use this option to avoid being prompted for configuration values. You must provide at least three configuration values (--tidb-cloud-public-key, --tidb-cloud-private-key, and --region-code) when using this option. This is useful when running ti in a script or automated environment.
```

- リソースを変更するコマンドで `--dry-run` をサポートしている場合、実際に作成・変更せずにプランや検証のみを行います。次のコマンド例はプレビュー用で、実際にファイルシステムは作成されません。

```bash
ti fs create-file-system \
  --display-name lab-workspace \
  --dry-run --region aws-${LAB:REGION_CODE}
```

```output
{
  "dry_run": true,
  "command": "ti fs create-file-system",
  "operation": "create_file_system",
  .
  .
  .
    {
      "name": "remote_mutation",
      "status": "skipped",
      "message": "dry-run stopped before sending a mutating remote request"
    }
  ]
}
```

### 手順 4: ファイルシステムの作成

- `ti fs create-file-system` を使い、新しいファイルシステムを作成します。
- リソース作成系コマンドはすべて `--wait` フラグを持ち、直後の処理を開始する前にサービス利用可能状態まで待機できるため、オーケストレーションに適しています。この後のステップで利用します。
- また、`ti` は標準でJSON形式出力ですが、JMESPathによる `--query` で任意のフィールド抽出ができ、`--output text` で人間が見やすい形にも変更可能です。
- 新ファイルシステムの `fs_token` と `file_system_id` を取得し変数に保存します。`fs_token`（`LAB_FS_TOKEN`）はファイルシステムの「一意識別子」であり利用認証情報も兼ねます。`file_system_id`（`LAB_FS_ID`）は一意識別子ですが認証情報は含みません。

> [!TIP]
> ファイルシステム初作成時は最大約1分かかる場合があります。しばらくお待ちください。

```bash
read LAB_FS_ID LAB_FS_TOKEN <<< "$(ti fs create-file-system \
  --display-name lab-workspace \
  --region aws-${LAB:REGION_CODE} \
  --wait \
  --query "join(' ', [file_system_id, fs_token])" \
  --output text \
  )"
```

- コマンド実行後、新しく作成したファイルシステムの `fs_token` を確認しましょう。皆さんの環境では、出力例と異なる値になります。

```bash
echo $LAB_FS_TOKEN
```

```output
drive9_ZXlKaGJHY2lPaUpJV
.
.
.
SzBmUXNtT19rbEZvTjlwZm15
```

- 同様に `file_system_id` の値も確認します。こちらも出力例とは異なる値になります。

```bash
echo $LAB_FS_ID
```

```output
cd06d327-06ca-4355-9ce5-4bf3cac76bed
```

### 手順 5: ファイルシステムをマウントする

- マウント用に空ディレクトリを作成します。

```bash
mkdir ~/mnt-module1
```

- `fs_token` があれば対応するファイルシステムにアクセス可能です。`--fs-token` パラメータで先ほど保存した `$LAB_FS_TOKEN` を指定しマウントします。

```bash
# マウント時、fs_token をパラメータ指定
ti fs mount --region aws-${LAB:REGION_CODE} --mount-path ~/mnt-module1 \
  --fs-token $LAB_FS_TOKEN
```

```output
{
  "status": "mounted",
...
  },
  "write_back_cache": true
}
```

- アンマウントは `ti fs umount` で実行できます。実際に試しましょう。

```bash
ti fs umount --mount-path ~/mnt-module1 
```

```output
{
  "status": "unmounted",
  "mount_path": "/home/ubuntu/mnt-module1"
}
```

- 次は `$TI_FS_TOKEN` 変数を使って再度マウントします。この場合 `--fs-token` パラメータは不要です（`ti` コマンドが `$TI_FS_TOKEN` 変数名を自動認識します）。

```bash
# 環境変数 TI_FS_TOKEN にセットすれば --fs-token の指定は不要
export TI_FS_TOKEN=$LAB_FS_TOKEN
ti fs mount --region aws-${LAB:REGION_CODE} --mount-path ~/mnt-module1
```

```output
{
  "status": "mounted",
...
  },
  "write_back_cache": true
}
```

- マウント済みディレクトリは通常のディレクトリ同様に利用できます。例としてテキストファイルを保存します。

```bash
echo "Hello TiDB Cloud FS" > ~/mnt-module1/hello-world.txt
cat ~/mnt-module1/hello-world.txt
```

```output
Hello TiDB Cloud FS
```

- もう一度アンマウントします。

```bash
# ディレクトリのアンマウント
ti fs umount --mount-path ~/mnt-module1
```

```output
{
  "status": "unmounted",
  "mount_path": "/home/ubuntu/mnt-module1"
}
```

### 手順 6: Hermes Agent 環境向けファイルシステム認証情報の準備

<!-- markdownlint-disable MD032 -->
> [!IMPORTANT]
> - `ti fs mount` コマンドが必要とするのはファイルシステムのトークンだけです。`ti` CLI に API キー設定がなくても、対象ファイルシステムのトークンとリージョン情報があればマウントできます。
> - こうした限定環境では Filesystem の管理はできませんが、Filesystem を利用できます。実際によくある例は agent のサンドボックスでの利用などです。

- `$TI_FS_TOKEN` 変数と `$TI_REGION_CODE` だけを Hermes 環境に渡せばOKです。次のコマンドで設定します。

```bash
echo TI_REGION_CODE=aws-${LAB:REGION_CODE} >> ~/.hermes/.env
echo TI_FS_TOKEN="$LAB_FS_TOKEN" >> ~/.hermes/.env
```

- `.hermes/.env` ファイルに正しく `TI_` 変数が入っているか確認します。

```bash
grep TI_.*= ~/.hermes/.env
```

```output
TI_REGION_CODE=aws-${LAB:REGION_CODE}
TI_FS_TOKEN=XXXXXXXXXXXXXXXXXXXXX
```

- もう不要となった環境変数をクリーンアップしましょう。

```bash
unset LAB_FS_TOKEN LAB_FS_ID TI_FS_TOKEN
```

### 手順 7: モジュールまとめ

- TiDB Cloud CLI「`ti`」の使い方を一通り習得できました。
- 新規ファイルシステムを作成し、その利用資格情報を Hermes Agent の環境変数ファイルに設定しました。
- 今後、既存ファイルシステムの `fs_token` を紛失した場合も、`ti fs generate-file-system-token` で再発行でき、「有効化・無効化・削除」は `ti fs enable-/disable-/delete-file-system-token` で可能です。ファイルシステムごとに複数トークンを持てます。
- 次モジュールでは Agent も「`ti`」CLI を瞬時に使いこなせるようになります。

次のモジュールにお進みください。