> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tembo.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Upgrade guide

> How to upgrade Tembo on Kubernetes, and what to change for each chart release.

Each chart release runs one Tembo release and one host controller release, so the chart version is the only thing you pin. To upgrade, move to a newer chart version. Before you do, read the notes below for every release after the one you run. Breaking changes are marked **Breaking**.

***

## Upgrading the chart

1. Find the chart version you run, in the `CHART` column:

   ```bash theme={null}
   helm list -n tembo
   ```

2. Read the notes below for every release between yours and the one you're moving to, and change your values as they say.

3. Upgrade with the same values files you installed with:

   ```bash theme={null}
   helm upgrade tembo oci://registry.tembo.io/tembo --version <version> \
     -n tembo -f tembo-aws.json -f values.yaml
   ```

The host controller then replaces agent hosts whose configuration changed (see [Apply changes](https://docs.tembo.io/features/self-hosted/kubernetes/configuration.md#apply-changes)).

> [!NOTE]
>
> Helm installs the chart's custom resource definitions but never upgrades them. When a release changes them, apply them before you upgrade:
>
> ```bash theme={null}
> helm show crds oci://registry.tembo.io/tembo --version <version> | kubectl apply --server-side -f -
> ```

***

## Upgrading to 1.0.0+

> [!WARNING]
>
> 1.0.0 moves every Ingress setting into one `ingress` map, and no longer reads the old keys. Update your values before you upgrade, or Tembo's load balancers lose their cloud settings.

* **Breaking:** the chart no longer adds the AWS Load Balancer Controller's annotations by default. On AWS, set `ingress.aws.enabled: true`. Without it, your ALBs lose their settings and health checks.

* **Breaking:** GKE's settings moved from `ingress.gke` to `ingress.gcp`, and previews' settings from `sandbar` to `ingress.previews`:

  | Before 1.0.0 | 1.0.0 |
  | - | - |
  | ALB annotations by default | `ingress.aws.enabled: true` |
  | `ingress.gke.enabled` | `ingress.gcp.enabled` |
  | `ingress.gke.redirectToHttps` | `ingress.gcp.redirectToHttps` |
  | `ingress.gke.backendTimeoutSec` | `ingress.gcp.timeoutSeconds` |
  | `ingress.gke.staticIpName` | A `kubernetes.io/ingress.global-static-ip-name` annotation in `ingress.annotations` (`regional-static-ip-name` for an internal Ingress) |
  | `ingress.gke.managedCertificate: false` | `ingress.gcp.certificates`, or `ingress.tls.secretName` |
  | `sandbar.domain` | `ingress.previews.domain` |
  | `sandbar.ingress.tlsSecretName`, `sandbar.ingress.annotations` | `ingress.previews.tlsSecretName`, `ingress.previews.annotations` |

* **Breaking:** health checks come from `ingress.aws` or `ingress.gcp`. Each Service's `alb.ingress.kubernetes.io/healthcheck-path` annotation is no longer set by default, so remove any you copied into `<component>.service.annotations`.

* `ingress.aws` and `ingress.gcp` take the same settings: `internal`, `redirectToHttps`, `timeoutSeconds` and `certificates`. See [Networking](https://docs.tembo.io/features/self-hosted/kubernetes/prerequisites/networking.md). `internal: true` replaces setting the `gce-internal` class or the ALB's `scheme: internal` annotation yourself, which still work.

* On AWS, the ALB's idle timeout is now 3600 seconds (`ingress.aws.timeoutSeconds`), so websockets stay open. A `load-balancer-attributes` annotation of your own replaces it.

* Newer releases of the Terraform modules turn on `ingress.aws` or `ingress.gcp` in their Helm values. Setting it in your values works with any module version.

***

## Upgrading to 0.6.0+

* Computer previews and `tembo service` URLs are served from your install, by Sandbar, on by default. The chart adds:
  * An Ingress, `tembo-previews`, for `*.previews.<ingress.host>`.
  * An internal load balancer, `tembo-sandbar-hosts`, at `sandbar.<ingress.host>`, which agent hosts reach on ports 9000 and 9001.
* Previews need DNS and a certificate for `*.previews.<ingress.host>`; see [Networking](https://docs.tembo.io/features/self-hosted/kubernetes/prerequisites/networking.md). Without the certificate, only previews fail. On GKE, the previews' Ingress serves the `tembo-previews-tls` Secret, which cert-manager can issue.
* Previews also need a Tembo release later than 0.2.892.
* To turn previews off, set `sandbar.enabled: false`.

***

## Upgrading to 0.5.0+

* Adds Sandbar, off by default, and generates the secret the API and Sandbar share (`previews.authSecret`, in `tembo-generated`). No changes needed.

***

## Upgrading to 0.4.0+

* Adds `podAnnotations`, set on every pod the chart runs. Every component runs one replica, so set your node autoscaler's opt-out to keep it from evicting them:
  * GKE and the Cluster Autoscaler: `cluster-autoscaler.kubernetes.io/safe-to-evict: "false"`.
  * Karpenter and EKS Auto Mode: `karpenter.sh/do-not-disrupt: "true"`.

***

## Upgrading to 0.3.4+

* Every component requests CPU and memory, about 1.3 vCPUs and 4.5 GiB in total, so node autoscalers size nodes for them. The API and LiteLLM get up to 5 minutes to start.
* Every pod restarts once on upgrade, including the bundled Postgres.

***

## Upgrading to 0.3.0+

* Runs the Tembo MCP server at `/mcp`, in the API pods, with a `tembo-mcp` Service and an `/mcp` path on the Ingress. Agents use it as their `tembo` MCP server. To turn it off, set `mcp.enabled: false`.

***

## Upgrading to 0.2.0+

* The chart runs the Tembo and host controller releases it was built with. Remove `api.image.tag`, `web.image.tag` and `compute.controller.image.tag` from your values, unless you mean to pin other versions.

***

## Need Help?

If you run into any issues, contact [support@tembo.io](mailto:support@tembo.io).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.