マネージド Kubernetes

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

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

Terraform でのデプロイ

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

cartesia-kube を cartesia-kube のダウンロードの説明に従って GCS バケットからダウンロードしてください。

# 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)"

設定

AWS EKS
GCP GKE

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

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

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

ワーカーの設定

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

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 をインストールします:

# 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. シークレットの作成

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 の設定

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. デプロイ

cd cartesia-kube/cartesia
helm upgrade --install cartesia . \
  --values values.yaml \
  --namespace cartesia

検証

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

ロールアウトの監視

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

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 のアドレスが割り当てられている

kubectl get ingress -n cartesia

ADDRESS 列がロードバランサーのホスト名または IP で埋まっているはずです。 GKE では ManagedCertificate のステータスも確認します — チャートがリソースを作成し、GCP は DNS 検証後に非同期で証明書をプロビジョニングします:

kubectl describe managedcertificate cartesia-ssl-cert -n cartesia

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

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

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

kubectl port-forward -n monitoring svc/prometheus-operated 9090:9090

その後 http://localhost:9090 にアクセスして up{namespace="cartesia"} をクエリすると、すべてのコンポーネント Pod が 1 を返すはずです。検証後は、機能スモークテストとパフォーマンスベンチマークについてスモークテストとベンチマークを参照してください。

Ingress と TLS

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

AWS EKS
GCP GKE
Self-managed

チャートは 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 までお問い合わせください。
証明書: Terraform（certificate_arn）または Helm（ingress.certificateArn）で ACM ARN を明示的に渡してください。未設定の場合、チャートの certificate-manager: 'true' アノテーションにより AWS Load Balancer Controller がホスト名に一致する ACM 証明書を検索します。
HTTP リダイレクト: ポート 80 上の HTTP トラフィックはポート 443 の HTTPS にリダイレクトされます。

Terraform
Helm

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

ingress:
  enabled: true
  routes:
    - api.cartesia.yourdomain.com
  certificateArn: "arn:aws:acm:us-west-2:123456789:certificate/abc123"

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

チャートは 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 を参照してください。

Terraform
Helm

enable_ingress = true
ingress_route  = "api.cartesia.yourdomain.com"

ingress:
  enabled: true
  routes:
    - api.cartesia.yourdomain.com

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

ingress:
  enabled: false

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

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 を付けたものに置き換えてください。

オートスケーリング

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

Cluster Autoscaler

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

enable_cluster_autoscaler = true

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

Pod Autoscaler (KEDA)

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

enable_pod_autoscaler = true
enable_metrics = true  # Required for KEDA

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

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

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

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

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

または Helm の values.yaml で:

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

スケーリングの挙動

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

本番公開チェックリスト

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

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

​Terraform でのデプロイ

​設定

​ワーカーの設定

​Helm のみでのデプロイ

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

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

​3. values.yaml の設定

​4. デプロイ

​検証

​ロールアウトの監視

​Pod が Ready

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

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

​Ingress と TLS

​オートスケーリング

​Cluster Autoscaler

​Pod Autoscaler (KEDA)

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

​スケーリングの挙動

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

Terraform でのデプロイ

設定

ワーカーの設定

Helm のみでのデプロイ

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

2. シークレットの作成

3. values.yaml の設定

4. デプロイ

検証

ロールアウトの監視

Pod が Ready

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

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

Ingress と TLS

オートスケーリング

Cluster Autoscaler

Pod Autoscaler (KEDA)

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

スケーリングの挙動

本番公開チェックリスト