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

​
リリースタグ

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

​
アップグレード手順

タグ値を上げて再適用します。
.tfvars ファイルを編集:
release_tag = "sonic-20260503"   # new tag
プラットフォームディレクトリから適用します:
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)"
再適用すると、Kubernetes は API、license-proxy、すべてのワーカーを並列にロールします。順序は決定論的ではなく、ロールアウト中の期間は混在したイメージの Pod が存在します。 チャートはすべてのワーカーに対してグローバルに release.releaseTag を使用します。ワーカーごとのタグオーバーライドはありません。全ワーカーをロールする前にワーカーごとに段階的な検証が必要な場合は、support@cartesia.ai までお問い合わせください。

​
アップグレードの検証

マネージド Kubernetes ページの 検証 チェックリストを実行してください。さらに、各デプロイメントのロールアウト完了を監視します: 
kubectl rollout status deployment/cartesia-api -n cartesia
kubectl rollout status deployment/<worker-name> -n cartesia
すべての Pod が新しいイメージタグで動作していることを確認します: 
kubectl get pods -n cartesia -o jsonpath='{range .items[*]}{.metadata.name}{"\t"}{.spec.containers[*].image}{"\n"}{end}'

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

チャートは以下のローリングアップデート戦略を設定します:
コンポーネントmaxSurgemaxUnavailable
API サーバー1release.maxUnavailable（デフォルト 0）
ワーカー（各）3release.maxUnavailable（デフォルト 0）
Voice Clone ワーカー3release.maxUnavailable（デフォルト 0）
License proxyKubernetes デフォルト（25%）Kubernetes デフォルト（25%）
デフォルトの maxUnavailable: 0 では、Kubernetes は古い Pod を終了する前に新しい Pod を立ち上げます。アップグレード中、容量が望ましい数を下回ることはありません。一時的な容量低下と引き換えに高速なロールアウトを許容するには、values.yaml の release.maxUnavailable を上げてください。
maxSurge: 3 および maxUnavailable: 0 の場合、ロールアウト中にワーカーデプロイメントは一時的に （望ましいレプリカ数 + 3） 個の GPU を必要とします。クラスタが GPU 容量ぎりぎりで動作している場合、新しい Pod はクラスタオートスケーラーがノードを追加するまで Pending になります。あるいは、アップグレード前にデプロイメントをスケールダウンしてください。

​
ロールバック手順

アップグレードでリグレッションが発生した場合は、リリースタグを元に戻します。
過去のリリースを一覧表示:
helm history cartesia -n cartesia
特定のリビジョンにロールバック:
helm rollback cartesia <revision> -n cartesia
または直前のリビジョンに:
helm rollback cartesia 0 -n cartesia
ロールバックはアップグレードと同じローリングアップデート戦略を使用するため、入れ替え中も容量は維持されます。

​
初回デプロイの失敗

初回デプロイ中にクラスタが正常な状態に達しなかった場合は、再試行する前にデバッグしてください:
  • Pod のイベントを確認: kubectl describe pod <pod> -n cartesia
  • ログを確認: kubectl logs <pod> -n cartesia
完了前にデプロイメントを取り消す必要がある場合:
  • Helm: helm uninstall cartesia -n cartesia
  • Terraform: バージョン管理で変更を元に戻して terraform apply するか、完全にティアダウンするなら terraform destroy。

​
ロールバックの検証

すべての Pod がロールバック後のタグで動作していることを確認し、検証 チェックリストを再実行します。

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

add-voices および add-pdict で追加されたボイスマイグレーションと発音辞書は、顧客の GCS バケット（gs://cartesia-{name}/migrations/v2/migrations/）に保存され、ホットリロードで適用されます — アーティファクトの管理 を参照してください。 これらのアーティファクトはリリースタグから独立しています。helm rollback や terraform apply でリリースをロールバックしても、バケット内のボイスマイグレーションや発音辞書は削除されません — ロールバック後も引き続き利用可能です。 過去に追加したボイスや pdict を取り消すためのパブリック API は現在ありません。デプロイメントからアーティファクトを削除する必要がある場合は、support@cartesia.ai までお問い合わせください。