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

# Upgrades and Rollback

> Move your self-hosted deployment to a new release tag, and revert if something goes wrong.

This page covers moving an existing Cartesia self-hosted deployment to a newer release, and rolling back if the upgrade fails. For initial deployments, see [Getting Started](/self-hosted/getting-started).

## Release tags

Each Cartesia release is tagged with the format `sonic-YYYYMMDD` (e.g., `sonic-20260503`). A release tag pins the image version for every component in the chart:

* `cartesia-api`
* `cartesia-license-proxy`
* Every worker image (`cartesia-sonic-azure-disco`, `cartesia-sonic-rosy-dragon`, etc.)

The Helm chart and Terraform code in `cartesia-kube` evolve independently from the release tag — you generally do not need to update them when upgrading the release.

Set the tag once globally:

* **Helm:** `release.releaseTag` in `values.yaml`
* **Terraform:** `release_tag` in your `.tfvars` file

## Upgrade Procedure

Bump the tag value and re-apply.

<Tabs>
  <Tab title="Terraform">
    Edit your `.tfvars` file:

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

    Then apply from the platform directory:

    ```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">
    Edit `values.yaml`:

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

    Then upgrade:

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

When you re-apply, Kubernetes rolls every deployment (API, license-proxy, all workers) in parallel. The order is not deterministic — expect mixed pod images during the rollout window.

The chart uses `release.releaseTag` globally for every worker — there is no per-worker tag override. If you need per-worker staged validation before rolling all workers, contact [support@cartesia.ai](mailto:support@cartesia.ai).

### Verifying the upgrade

Run the [Verify](/self-hosted/managed-kubernetes#verify) checklist from the Managed Kubernetes page. Additionally, watch each deployment's rollout complete:

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

Confirm every pod is running the new image tag:

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

## Rolling Update Behavior

The chart configures these rolling update strategies:

| Component          | `maxSurge`               | `maxUnavailable`                       |
| ------------------ | ------------------------ | -------------------------------------- |
| API server         | `1`                      | `release.maxUnavailable` (default `0`) |
| Workers (each)     | `3`                      | `release.maxUnavailable` (default `0`) |
| Voice Clone worker | `3`                      | `release.maxUnavailable` (default `0`) |
| License proxy      | Kubernetes default (25%) | Kubernetes default (25%)               |

With the default `maxUnavailable: 0`, Kubernetes brings new pods up before terminating old ones — capacity is never reduced below the desired count during an upgrade. To allow faster rollouts at the cost of temporary capacity loss, raise `release.maxUnavailable` in `values.yaml`.

<Note>
  With `maxSurge: 3` and `maxUnavailable: 0`, a worker deployment temporarily needs **(desired replicas + 3)** GPUs available during the rollout. If your cluster is at exact GPU capacity, the new pods will Pend until the cluster autoscaler adds nodes — or until you scale the deployment down before upgrading.
</Note>

## Rollback Procedure

If the upgrade introduces a regression, revert the release tag.

<Tabs>
  <Tab title="Helm">
    List previous releases:

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

    Roll back to a specific revision:

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

    Or to the immediately previous revision:

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

  <Tab title="Terraform">
    Revert the `release_tag` value in your `.tfvars` file:

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

    Then apply:

    ```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>

The rollback uses the same rolling update strategy as the upgrade — capacity is preserved during the swap.

### Initial deployment failures

If the cluster never reaches a healthy state during an initial deployment, debug before retrying:

* Inspect pod events: `kubectl describe pod <pod> -n cartesia`
* Inspect logs: `kubectl logs <pod> -n cartesia`

If the deployment must be reversed before completion:

* **Helm:** `helm uninstall cartesia -n cartesia`
* **Terraform:** revert the change in version control and `terraform apply`, or `terraform destroy` for a full teardown.

### Verifying the rollback

Confirm every pod is running the rolled-back tag and re-run the [Verify](/self-hosted/managed-kubernetes#verify) checklist.

## Hot-reload artifacts and rollback

Voice migrations and pronunciation dictionaries added via [add-voices](/self-hosted/managing-artifacts#adding-voices) and [add-pdict](/self-hosted/managing-artifacts#adding-pronunciation-dictionaries) are stored in the customer GCS bucket (`gs://cartesia-{name}/migrations/v2/migrations/`) and applied via hot reload — see [Managing Artifacts](/self-hosted/managing-artifacts).

These artifacts are **independent of the release tag**. Rolling back a release via `helm rollback` or `terraform apply` does **not** remove voice migrations or pronunciation dictionaries from the bucket — they remain available after rollback.

There is no public API today to revoke a previously-added voice or pdict. If you need to remove an artifact from your deployment, contact [support@cartesia.ai](mailto:support@cartesia.ai).