> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cartesia.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# NATS Pools

> ワーカーを専用の NATS サーバーにシャードすることで、1 台のサーバーがダウンしてもデプロイメント全体が停止しないようにします。

デフォルトでは、すべてのワーカーが 1 つの NATS サーバーを共有します。プールを宣言すると、特定のワーカー群に専用の NATS サーバーが割り当てられ、1 台のサーバーがダウンしても影響を受けるのはそのサーバーに接続されたワーカーだけになります。

```yaml theme={null}
nats:
  pools:
    - name: default
      transport: grpc
    - name: tts
      transport: grpc

workers:
  - name: tts-worker-a
    natsPool: tts
    # ...
  - name: tts-worker-b
    # natsPool を指定しない場合はデフォルトプールを使用
```

プール名は固定で、`default`、`stt`、`tts`、`agent` のいずれかです。`default` プールは常に存在するため、設定を上書きしたい場合にのみ宣言します。それ以外の宣言されたプールには、それぞれ `nats-server-<name>` の Deployment と Service が用意されます。宣言されていないプールを参照するワーカーがあると、`helm upgrade` はレンダリング時に失敗し、宣言すべきプール名を出力します。

## プールのフィールド

| フィールド               | デフォルト                            | 説明                                              |
| ------------------- | -------------------------------- | ----------------------------------------------- |
| `name`              | —                                | `default`、`stt`、`tts`、`agent` のいずれか             |
| `transport`         | `nats`                           | `nats` または `grpc`                               |
| `outputConnections` | `8`                              | ジョブ出力用の専用 NATS 接続数。`grpc` プールでは無視されます           |
| `resources`         | `nats.resources`、次に 1 CPU / 32Gi | このプールのサーバー Pod に対する Kubernetes の resources ブロック |

<Warning>
  プールのトポロジー、トランスポート、または出力接続数を変更すると、`helm upgrade` で API が自動的にロールされます。プールを導入するアップグレードでは、API のロールアウトが 1 回発生することを想定してください。
</Warning>

## プール間でワーカーをシャードする

ワーカーを 2 つのプールに分散しておくと、NATS Pod がクラッシュしてもデプロイメントは稼働を続けます。もう一方のプール側でリクエストは処理され続けます。この状態では利用可能な容量がおおむね半分になるため、Pod が復旧するまではレイテンシーの増加やキューイングが発生することが想定されます。

TTS の場合、API は `tts` プールと `default` プールに対して、それぞれの利用可能なワーカー容量に応じてリクエストを分配します。そのため通常運用ではどちらのプールも負荷を分担します。この動作にはリリースタグ `sonic-20260713` 以降が必要です。それより前のタグでは `tts` プールがプライマリで、`default` はフォールバックとなります。STT および agent のプールは常に、専用プールをプライマリ、`default` をフォールバックとして扱います。

## トランスポート

プールはデフォルトで、タスクごとのストリーミング I/O を NATS 上で伝送します。`transport: grpc` を設定すると、そのトラフィックはワーカーから API へのポート `50051` の直接 gRPC 接続に切り替わり、TTFA と RTF が改善します。NATS はそのままタスクの割り当てとハートビートを伝送します。宣言するすべてのプールで設定してください。

## Terraform

Terraform モジュールは、フィールド名を snake\_case にした形で Helm チャートのスキーマをそのまま反映します。`natsPool` を設定するワーカーには、対応する `nats_pools` エントリが必要です。

```hcl theme={null}
nats_pools = [
  { name = "default", transport = "grpc" },
  { name = "tts", transport = "grpc" },
]

workers = [
  {
    name     = "tts-worker-a"
    natsPool = "tts"
    # ...
  },
  {
    name = "tts-worker-b"
    # natsPool を省略した場合はデフォルトプールを使用
    # ...
  },
]
```

`natsPool` を未設定にするとデフォルトプールが使用されます。`"default"` を明示的に設定することは拒否されます。