> ## 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.

# マネージド Kubernetes

> AWS EKS および GCP GKE 上に Cartesia をデプロイする

Cartesia はインフラとアプリケーションの両方をデプロイする Terraform 構成を提供しています。既存のクラスタに Helm チャートを直接デプロイすることもできます。

<Note>完全な構成は、デプロイ時に Cartesia の担当者から提供されます。</Note>

## Terraform でのデプロイ

Terraform はクラスタ、ネットワーキング、GPU ドライバーを作成し、Helm 経由で Cartesia をデプロイします。
Cartesia のセルフホストを最も早く始められる方法です。

<Note>cartesia-kube を [cartesia-kube のダウンロード](/self-hosted/provisioned-resources#deployment-configurations) の説明に従って GCS バケットからダウンロードしてください。</Note>

```bash theme={null}
# Download and extract cartesia-kube from GCS (see Downloading cartesia-kube guide)
cd cartesia-kube

# Copy example config for your platform
cp aws-terraform.tfvars.example aws-terraform.tfvars  # or gcp-terraform.tfvars.example

# Deploy from the platform directory
cd infra/aws/cartesia-eks  # or infra/gcp/cartesia-gke
terraform init
terraform apply -var-file="../../../aws-terraform.tfvars" \
                -var "cartesia_api_key=$CARTESIA_API_KEY" \
                -var "service_account_json=$(cat /path/to/service-account.json)"
```

### 設定

<Tabs>
  <Tab title="AWS EKS">
    ```hcl theme={null}
    region = "us-west-2"
    name = "cartesia-production"

    eks_admin_users = ["arn:aws:iam::123456789:user/admin"]

    node_groups = {
      default = {
        ami_type = "AL2023_x86_64_STANDARD"
        instance_types = ["m7a.4xlarge"]
        min_size = 1
        max_size = 3
        desired_size = 1
      }
      gpu = {
        ami_type = "AL2023_x86_64_NVIDIA"
        instance_types = ["g5.2xlarge", "g5.4xlarge"]
        min_size = 1
        max_size = 5
        desired_size = 2
        disk_size = 100
        labels = { "nvidia.com/gpu.present" = "true" }
      }
    }

    # Ingress (optional)
    enable_ingress = true
    ingress_route = "api.cartesia.yourdomain.com"
    certificate_arn = "arn:aws:acm:us-west-2:123456789:certificate/abc123"

    # Hot reload (enabled by default)
    enable_hot_reload = true
    ```
  </Tab>

  <Tab title="GCP GKE">
    ```hcl theme={null}
    project_id = "your-gcp-project"
    region = "us-central1"
    zone = "us-central1-a"
    name = "cartesia-production"

    gke_admin_users = ["user@yourdomain.com"]

    node_pools = {
      default = {
        machine_type = "e2-standard-8"
        min_count = 1
        max_count = 3
        initial_node_count = 1
      }
      gpu = {
        machine_type = "g2-standard-8"
        accelerator_type = "nvidia-l4"
        accelerator_count = 1
        min_count = 1
        max_count = 5
        initial_node_count = 2
        disk_size_gb = 100
      }
    }

    # Ingress (optional)
    enable_ingress = true
    ingress_route = "api.cartesia.yourdomain.com"

    # Hot reload (enabled by default)
    enable_hot_reload = true
    ```
  </Tab>
</Tabs>

ホットリロードや、デプロイメントへのボイスや発音辞書の追加については [アーティファクトの管理](/self-hosted/managing-artifacts) を参照してください。

### ワーカーの設定

ワーカーは tfvars ファイル内で定義されます:

```hcl theme={null}
workers = [
  {
    name = "tts-worker"
    workerArgs = {
      model = "<model-name>"
      image = "cartesia-sonic-<model-name>"
      gpuType = "nvidia.com/gpu"
      capacity = 4
      operation = "TTS"
      useCB = true
      useLora = false
    }
    autoscaling = {
      enabled = true
      threshold = 0.6
      minReplicas = 1
      maxReplicas = 10
    }
  }
]
```

すべてのモデルワーカーは、`cartesia-sonic-` プレフィックスに具体的なモデル名を続けた名前のイメージを使用します。たとえば、sonic-3 は `cartesia-sonic-rosy-dragon` を使用します。

## Helm のみでのデプロイ

既存の Kubernetes クラスタに対しては、Helm チャートを直接デプロイします。

### 1. 前提条件のインストール

オートスケーリングとメトリクスを使用する場合は、先に KEDA と Prometheus をインストールします:

```bash theme={null}
# Prometheus
helm repo add prometheus-community https://prometheus-community.github.io/helm-charts
helm install prometheus prometheus-community/kube-prometheus-stack \
  --namespace monitoring \
  --create-namespace

# KEDA
helm repo add kedacore https://kedacore.github.io/charts
helm install keda kedacore/keda \
  --namespace keda \
  --create-namespace
```

### 2. シークレットの作成

```bash theme={null}
kubectl create namespace cartesia

kubectl create secret docker-registry gar-pull-secret \
  --namespace cartesia \
  --docker-server=us-docker.pkg.dev \
  --docker-username=_json_key \
  --docker-password="$(cat /path/to/service-account.json)"

kubectl create secret generic api-key-secret \
  --namespace cartesia \
  --from-literal=CONTAINER_KEY="$CARTESIA_API_KEY" \
  --from-literal=CARTESIA_API_KEY="$CARTESIA_API_KEY" \
  --from-literal=OPENAI_API_KEY="$OPENAI_API_KEY" \
  --from-literal=ANTHROPIC_API_KEY="$ANTHROPIC_API_KEY"

kubectl create secret generic gcs-access-secret \
  --namespace cartesia \
  --from-file=service-account.json=/path/to/service-account.json
```

### 3. values.yaml の設定

```yaml theme={null}
clusterName: cartesia-production

infra:
  provider: gcp  # or aws
  authenticate: true
  imageRegistry: us-docker.pkg.dev/cartesia-external/self-serve
  imagePullSecret: gar-pull-secret
  gcsSecretName: gar-pull-secret
  serviceAccount: cartesia-image-sa

release:
  version: "1.0.0"
  releaseTag: "sonic-20251118"

filesystem:
  storageClass:
    name: standard-rwo

ingress:
  enabled: true
  routes:
    - api.cartesia.yourdomain.com
  globalStaticIpName: cartesia-ingress-ip  # GKE only

metrics:
  enabled: true

legacyComponents:
  enabled: false

workers:
  - name: tts-worker
    workerArgs:
      model: <model-name>
      image: cartesia-sonic-<model-name>
      gpuType: nvidia.com/gpu
      capacity: 4
      operation: TTS
      useCB: true
      useLora: false
    autoscaling:
      enabled: true
      threshold: "0.6"
      minReplicas: 1
      maxReplicas: 10
```

### 4. デプロイ

```bash theme={null}
cd cartesia-kube/cartesia
helm upgrade --install cartesia . \
  --values values.yaml \
  --namespace cartesia
```

### 検証

トラフィックを流す前に、デプロイメントが正常であることを確認します。以下のコマンドは、これまでの例で使用したデフォルトの `cartesia` namespace とリリース名を前提としています。カスタマイズしている場合は適宜置き換えてください。

#### ロールアウトの監視

```bash theme={null}
kubectl rollout status deployment/cartesia-api -n cartesia
kubectl rollout status deployment/<worker-name> -n cartesia
```

ワーカー Pod は GPU メモリへのモデルロードがあるため、API より時間がかかります。`inferno_worker_capacity > 0` になるまで、ワーカーは `Running` のままで `Ready` にはなりません。

#### Pod が Ready

```bash theme={null}
kubectl get pods -n cartesia
```

すべての Pod が `Running` で、すべてのコンテナが `Ready` になっているはずです。プローブの挙動:

* **API Pod の Ready 化**: `GET /status` がポート 5000 で 200 を返した時点。
* **ワーカー Pod の Ready 化**: startup probe が満たされたとき — `/metrics` をポーリングし、`inferno_worker_capacity` が 0 より大きい値を報告するまで待ちます。モデルロード中は `Running` だが `Ready` ではない状態になります。
* **License-proxy と NATS**: チャート定義のヘルスプローブがなく、コンテナ起動直後に Ready になります。

#### Ingress のアドレスが割り当てられている

```bash theme={null}
kubectl get ingress -n cartesia
```

`ADDRESS` 列がロードバランサーのホスト名または IP で埋まっているはずです。

GKE では `ManagedCertificate` のステータスも確認します — チャートがリソースを作成し、GCP は DNS 検証後に非同期で証明書をプロビジョニングします:

```bash theme={null}
kubectl describe managedcertificate cartesia-ssl-cert -n cartesia
```

`Status: Active` を確認してください。GCP がプロビジョニング中の間、Ingress への HTTPS コールは証明書検証に失敗します。

#### メトリクススクレイプが動作している（オプション）

クラスタに Prometheus がインストールされている場合（通常は `kube-prometheus-stack` 経由）、チャートの `PodMonitor`（`cartesia-monitor`）は `release: prometheus` ラベルを通じて自動検出されます。Prometheus UI をポートフォワードして、各コンポーネントがスクレイプされていることを確認します:

```bash theme={null}
kubectl port-forward -n monitoring svc/prometheus-operated 9090:9090
```

その後 `http://localhost:9090` にアクセスして `up{namespace="cartesia"}` をクエリすると、すべてのコンポーネント Pod が `1` を返すはずです。

検証後は、機能スモークテストとパフォーマンスベンチマークについて [スモークテストとベンチマーク](/self-hosted/smoke-tests-and-benchmarking) を参照してください。

## Ingress と TLS

チャートは Kubernetes の `Ingress` リソースを通じて Cartesia API を外部に公開します。AWS EKS または GCP GKE 向けに Ingress を構成しアノテーションを付与します。他の Kubernetes ディストリビューション（AKS、OpenShift、Rancher、kubeadm）では、チャートの ingress を無効化して独自のものを作成してください。お使いのプラットフォームを以下から選択してください。

<Tabs>
  <Tab title="AWS EKS">
    チャートは AWS Load Balancer Controller（ALB）向けに Ingress を構成します。主な挙動:

    * **TLS 終端:** TLS は ALB で終端し、最小 TLS 1.2 です（`ssl-policy: ELBSecurityPolicy-TLS-1-2-2017-01`）。
    * **バックエンド側:** ALB と API Pod 間のトラフィックは平文の HTTP です（`backend-protocol: HTTP`）。エンドツーエンドの TLS については [support@cartesia.ai](mailto:support@cartesia.ai) までお問い合わせください。
    * **証明書:** Terraform（`certificate_arn`）または Helm（`ingress.certificateArn`）で ACM ARN を明示的に渡してください。未設定の場合、チャートの `certificate-manager: 'true'` アノテーションにより AWS Load Balancer Controller がホスト名に一致する ACM 証明書を検索します。
    * **HTTP リダイレクト:** ポート 80 上の HTTP トラフィックはポート 443 の HTTPS にリダイレクトされます。

    <Tabs>
      <Tab title="Terraform">
        ```hcl theme={null}
        enable_ingress  = true
        ingress_route   = "api.cartesia.yourdomain.com"
        certificate_arn = "arn:aws:acm:us-west-2:123456789:certificate/abc123"
        ```
      </Tab>

      <Tab title="Helm">
        ```yaml theme={null}
        ingress:
          enabled: true
          routes:
            - api.cartesia.yourdomain.com
          certificateArn: "arn:aws:acm:us-west-2:123456789:certificate/abc123"
        ```
      </Tab>
    </Tabs>

    チャートが Ingress に適用するアノテーションの全セットは `cartesia/templates/resources/ingress.yaml` を参照してください。
  </Tab>

  <Tab title="GCP GKE">
    チャートは GKE 組み込みの ingress コントローラー向けに Ingress を構成します。主な挙動:

    * **証明書:** チャートは `ingress.routes` の全ホスト名をカバーする `ManagedCertificate` リソース（`{release}-ssl-cert`）を作成します。GCP は DNS による所有権検証後に証明書をプロビジョニングするため、デプロイ前に DNS A レコードを ingress IP に向けてください。プロビジョニング時間は DNS 伝播に依存します。
    * **HTTP:** HTTP は HTTPS と並行して許可されます（`allow-http: true`）。チャートは HTTP-to-HTTPS リダイレクトを構成しないため、必要であれば別途追加してください。
    * **静的 IP（オプション）:** `ingress_static_ip_name` で global IP を予約します。このスタック外で管理される既存 IP を使う場合は、`ingress_use_existing_static_ip = true` も設定してください。詳細は `infra/gcp/cartesia-gke/variables.tf` を参照してください。

    <Tabs>
      <Tab title="Terraform">
        ```hcl theme={null}
        enable_ingress = true
        ingress_route  = "api.cartesia.yourdomain.com"
        ```
      </Tab>

      <Tab title="Helm">
        ```yaml theme={null}
        ingress:
          enabled: true
          routes:
            - api.cartesia.yourdomain.com
        ```
      </Tab>
    </Tabs>
  </Tab>

  <Tab title="Self-managed">
    チャートの Ingress リソースは `aws` または `gcp` プロバイダーに対してのみ有効なアノテーションを出力します。AKS、OpenShift、Rancher、kubeadm、その他の Kubernetes ディストリビューションでは、チャートの ingress を無効化して独自に作成します:

    ```yaml theme={null}
    ingress:
      enabled: false
    ```

    その後、クラスタの ingress コントローラー（NGINX、Traefik、AKS Application Gateway、HAProxy など）を使って、ポート 5000 の `{release}-api-server` サービスにルーティングする `Ingress` リソースを作成します。TLS は、Ingress の `spec.tls` から参照される標準の `kubernetes.io/tls` シークレットを使うか、[cert-manager](https://cert-manager.io/) を使って証明書発行を自動化してください。

    参考例（お使いの ingress コントローラーの慣例に合わせて調整してください）:

    ```yaml theme={null}
    apiVersion: networking.k8s.io/v1
    kind: Ingress
    metadata:
      name: cartesia-api-ingress
      namespace: cartesia
      annotations:
        kubernetes.io/ingress.class: nginx
    spec:
      tls:
        - hosts:
            - api.cartesia.yourdomain.com
          secretName: cartesia-tls
      rules:
        - host: api.cartesia.yourdomain.com
          http:
            paths:
              - path: /
                pathType: Prefix
                backend:
                  service:
                    name: cartesia-api-server
                    port:
                      number: 5000
    ```

    `cartesia-api-server` は、リリース名のあとに `-api-server` を付けたものに置き換えてください。
  </Tab>
</Tabs>

## オートスケーリング

Cartesia は Kubernetes デプロイメントに対して 2 レベルのオートスケーリングをサポートします。

### Cluster Autoscaler

Pending Pod に基づいてノードをスケールします。tfvars で有効化:

```hcl theme={null}
enable_cluster_autoscaler = true
```

ノードグループ／プールは、リソース不足で Pod がスケジュールできない場合、構成された `min_size`／`max_size` の範囲内でスケールします。

### Pod Autoscaler (KEDA)

ロードメトリクスに基づいてワーカー Pod をスケールします。tfvars で有効化:

```hcl theme={null}
enable_pod_autoscaler = true
enable_metrics = true  # Required for KEDA
```

KEDA は 2 つのスケーリングトリガーを使用します:

* **キューの深さ** — 処理不能なリクエストが蓄積したときにスケール
* **ワーカーロード** — GPU 使用率がしきい値を超えたときにスケール

### ワーカーごとのスケーリング

各ワーカーは個別のスケーリング構成を持てます:

```hcl theme={null}
workers = [
  {
    name = "tts-worker"
    workerArgs = { ... }
    autoscaling = {
      enabled = true
      threshold = 0.6      # Scale up when load > 60%
      minReplicas = 1
      maxReplicas = 10
    }
  }
]
```

または Helm の values.yaml で:

```yaml theme={null}
workers:
  - name: tts-worker
    workerArgs: { ... }
    autoscaling:
      enabled: true
      threshold: "0.6"
      minReplicas: 1
      maxReplicas: 10
```

### スケーリングの挙動

* **スケールアップ**: 30 秒の安定化ウィンドウ
* **スケールダウン**: フラッピングを避けるため 900 秒（15 分）の安定化ウィンドウ
* ワーカーは個々の負荷に基づいて独立してスケール

## 本番公開チェックリスト

本番トラフィックを開放する前の最終レビュー:

* すべての Pod が `Running` かつ `Ready`、すべてのイメージが対象リリースタグであること — [検証](#verify) を参照。
* Ingress が FQDN 上で HTTPS を介して到達可能であること — [検証](#verify) を参照。
* TLS 証明書がアクティブであること（EKS では ACM 証明書がアタッチ済み、GKE では ManagedCertificate が `Active`、セルフマネージドでは BYO 証明書がマウント済み） — [Ingress と TLS](#ingress-and-tls) を参照。
* スモークテストがパスすること — [スモークテストとベンチマーク](/self-hosted/smoke-tests-and-benchmarking) を参照。
* ベンチマーク結果がデプロイした GPU の期待範囲内であること — [GPU ごとのパフォーマンス](/self-hosted/hardware-selection#performance-per-gpu) を参照。
* メトリクススクレイプが動作していること（Prometheus をインストールしている場合） — [検証](#verify) を参照。
* ファイアウォールとネットワークポリシーがデプロイしたポスチャーと一致すること — [アウトバウンド egress (Connected モード)](/self-hosted/architecture#outbound-egress-connected-mode) を参照。
* （エアギャップのみ）ライセンスがロードされ、オフライン運用が確認できていること — [エアギャップデプロイメント](/self-hosted/air-gapped) を参照。
* オンコールのランブックに [アップグレードとロールバック](/self-hosted/upgrades-and-rollback) のロールバック手順がドキュメント化されていること。