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

# アップグレードとロールバック

> セルフホストデプロイメントを新しいリリースタグに移行し、問題があれば元に戻します。

このページでは、既存の Cartesia セルフホストデプロイメントを新しいリリースに移行し、アップグレードに失敗した場合にロールバックする方法について説明します。初回デプロイについては [はじめに](/self-hosted/getting-started) を参照してください。

## リリースタグ

Cartesia の各リリースには `sonic-YYYYMMDD` 形式のタグが付与されます（例: `sonic-20260503`）。リリースタグは、チャート内のすべてのコンポーネントのイメージバージョンを固定します:

* `cartesia-api`
* `cartesia-license-proxy`
* すべてのワーカーイメージ（`cartesia-sonic-azure-disco`、`cartesia-sonic-rosy-dragon` など）

`cartesia-kube` 内の Helm チャートと Terraform コードはリリースタグとは独立して進化します。リリースをアップグレードする際に通常これらを更新する必要はありません。

タグは 1 か所でグローバルに設定します:

* **Helm:** `values.yaml` の `release.releaseTag`
* **Terraform:** `.tfvars` ファイルの `release_tag`

## アップグレード手順

タグ値を上げて再適用します。

<Tabs>
  <Tab title="Terraform">
    `.tfvars` ファイルを編集:

    ```hcl theme={null}
    release_tag = "sonic-20260503"   # new tag
    ```

    プラットフォームディレクトリから適用します:

    ```bash theme={null}
    cd infra/aws/cartesia-eks   # or infra/gcp/cartesia-gke
    terraform apply -var-file="../../../aws-terraform.tfvars" \
                    -var "cartesia_api_key=$CARTESIA_API_KEY" \
                    -var "service_account_json=$(cat /path/to/service-account.json)"
    ```
  </Tab>

  <Tab title="Helm">
    `values.yaml` を編集:

    ```yaml theme={null}
    release:
      releaseTag: sonic-20260503   # new tag
    ```

    アップグレードします:

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

再適用すると、Kubernetes は API、license-proxy、すべてのワーカーを並列にロールします。順序は決定論的ではなく、ロールアウト中の期間は混在したイメージの Pod が存在します。

チャートはすべてのワーカーに対してグローバルに `release.releaseTag` を使用します。ワーカーごとのタグオーバーライドはありません。全ワーカーをロールする前にワーカーごとに段階的な検証が必要な場合は、[support@cartesia.ai](mailto:support@cartesia.ai) までお問い合わせください。

### アップグレードの検証

マネージド Kubernetes ページの [検証](/self-hosted/managed-kubernetes#verify) チェックリストを実行してください。さらに、各デプロイメントのロールアウト完了を監視します:

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

すべての Pod が新しいイメージタグで動作していることを確認します:

```bash theme={null}
kubectl get pods -n cartesia -o jsonpath='{range .items[*]}{.metadata.name}{"\t"}{.spec.containers[*].image}{"\n"}{end}'
```

## ローリングアップデートの挙動

チャートは以下のローリングアップデート戦略を設定します:

| コンポーネント          | `maxSurge`            | `maxUnavailable`                    |
| ---------------- | --------------------- | ----------------------------------- |
| API サーバー         | `1`                   | `release.maxUnavailable`（デフォルト `0`） |
| ワーカー（各）          | `3`                   | `release.maxUnavailable`（デフォルト `0`） |
| Voice Clone ワーカー | `3`                   | `release.maxUnavailable`（デフォルト `0`） |
| License proxy    | Kubernetes デフォルト（25%） | Kubernetes デフォルト（25%）               |

デフォルトの `maxUnavailable: 0` では、Kubernetes は古い Pod を終了する前に新しい Pod を立ち上げます。アップグレード中、容量が望ましい数を下回ることはありません。一時的な容量低下と引き換えに高速なロールアウトを許容するには、`values.yaml` の `release.maxUnavailable` を上げてください。

<Note>
  `maxSurge: 3` および `maxUnavailable: 0` の場合、ロールアウト中にワーカーデプロイメントは一時的に **（望ましいレプリカ数 + 3）** 個の GPU を必要とします。クラスタが GPU 容量ぎりぎりで動作している場合、新しい Pod はクラスタオートスケーラーがノードを追加するまで Pending になります。あるいは、アップグレード前にデプロイメントをスケールダウンしてください。
</Note>

## ロールバック手順

アップグレードでリグレッションが発生した場合は、リリースタグを元に戻します。

<Tabs>
  <Tab title="Helm">
    過去のリリースを一覧表示:

    ```bash theme={null}
    helm history cartesia -n cartesia
    ```

    特定のリビジョンにロールバック:

    ```bash theme={null}
    helm rollback cartesia <revision> -n cartesia
    ```

    または直前のリビジョンに:

    ```bash theme={null}
    helm rollback cartesia 0 -n cartesia
    ```
  </Tab>

  <Tab title="Terraform">
    `.tfvars` ファイルの `release_tag` 値を元に戻します:

    ```hcl theme={null}
    release_tag = "sonic-20260417"   # previous tag
    ```

    そして適用します:

    ```bash theme={null}
    cd infra/aws/cartesia-eks   # or infra/gcp/cartesia-gke
    terraform apply -var-file="../../../aws-terraform.tfvars" \
                    -var "cartesia_api_key=$CARTESIA_API_KEY" \
                    -var "service_account_json=$(cat /path/to/service-account.json)"
    ```
  </Tab>
</Tabs>

ロールバックはアップグレードと同じローリングアップデート戦略を使用するため、入れ替え中も容量は維持されます。

### 初回デプロイの失敗

初回デプロイ中にクラスタが正常な状態に達しなかった場合は、再試行する前にデバッグしてください:

* Pod のイベントを確認: `kubectl describe pod <pod> -n cartesia`
* ログを確認: `kubectl logs <pod> -n cartesia`

完了前にデプロイメントを取り消す必要がある場合:

* **Helm:** `helm uninstall cartesia -n cartesia`
* **Terraform:** バージョン管理で変更を元に戻して `terraform apply` するか、完全にティアダウンするなら `terraform destroy`。

### ロールバックの検証

すべての Pod がロールバック後のタグで動作していることを確認し、[検証](/self-hosted/managed-kubernetes#verify) チェックリストを再実行します。

## ホットリロードのアーティファクトとロールバック

[add-voices](/self-hosted/managing-artifacts#adding-voices) および [add-pdict](/self-hosted/managing-artifacts#adding-pronunciation-dictionaries) で追加されたボイスマイグレーションと発音辞書は、顧客の GCS バケット（`gs://cartesia-{name}/migrations/v2/migrations/`）に保存され、ホットリロードで適用されます — [アーティファクトの管理](/self-hosted/managing-artifacts) を参照してください。

これらのアーティファクトは**リリースタグから独立しています**。`helm rollback` や `terraform apply` でリリースをロールバックしても、バケット内のボイスマイグレーションや発音辞書は**削除されません** — ロールバック後も引き続き利用可能です。

過去に追加したボイスや pdict を取り消すためのパブリック API は現在ありません。デプロイメントからアーティファクトを削除する必要がある場合は、[support@cartesia.ai](mailto:support@cartesia.ai) までお問い合わせください。