# Upgrades

> Upgrade a self-hosted ACOG installation safely: back up, read the new overlay, render, upgrade with every values file, and know what a rollback can undo.

Product: AI Cost Optimizer Gateway (ACOG). Web version: https://tessarac.com/docs/acog/self-hosted/upgrades. Last updated: 2026-10-16.

## Releases

A self-hosted release ships the same builds the hosted service runs. Releases are numbered `1.x.y` and published to `oci://docker.io/tessarac/ai-cost-optimizer`; each image is tagged with its version. Versions ending in `-beta.N` are pre-releases, never chosen unless you name them.

## Procedure

1. **Back up PostgreSQL.** Database migrations cannot be reversed.

   ```bash
   kubectl -n aco exec deploy/aco-postgres -- pg_dump -U aco -d aco -Fc > aco-$(date +%F).dump
   ```

2. **Read the new chart's `values-selfhost.yaml`.** It pins the images that go together for that version.

3. **Render and compare** with your current release, and confirm no operator custom resources appear (see [Install on Kubernetes](https://tessarac.com/docs/acog/self-hosted/kubernetes.md#3-render-and-check)).

4. **Upgrade, passing every values file every time:**

   ```bash
   helm upgrade aco oci://docker.io/tessarac/ai-cost-optimizer \
     --version <new version> -n aco \
     -f values-selfhost.yaml \
     -f my-install.yaml
   ```

   Do not use `--reuse-values`: it keeps old defaults and is how settings such as `ha.enabled: false` get lost. Keep `ha.enabled: false` and any datastore modes in your own overlay.

5. **Watch the control plane first.** It applies database migrations at start, one at a time, each in a transaction.

   ```bash
   kubectl -n aco rollout status deploy/aco-controlplane
   ```

6. **Check the rest**, and confirm the licence is still active under **Admin → Billing** (it is stored in PostgreSQL and survives upgrades).

The bundled datastores replace their pod when their specification changes, so a datastore is briefly unavailable during such an upgrade.

On an air-gapped installation, mirror the new version's images before step 4.

## Rolling back

`helm rollback aco <revision> -n aco` restores the previous images and configuration. It does not undo database migrations the newer version applied. If the rollback crosses a schema change, also restore the PostgreSQL backup from step 1.

## Datastore upgrades

Major-version upgrades of PostgreSQL, ClickHouse or Dragonfly that you run yourself are your own operation; the chart does not perform them.

## Version notes

Notes that need action, or change what you see, when you upgrade past a version:

| Upgrading past | Note |
|---|---|
| 1.26.46 | The semantic cache answers a request only from an answer in the same API format. Entries stored before the upgrade are not served, so the cache refills from new traffic. |
| 1.26.17 | Releases come only from plain versions such as `1.26.17`; `-beta.N` versions are pre-releases. |
| 1.26.16 | The version line moved from 0.x to 1.x (1.26.16 follows 0.26.15). Images are also tagged with the release version. |
| 0.26.11 | The default prompt-cache lifetime is five minutes. Connections and keys set to one hour are unchanged. |
| 0.26.10 | An auto mode saving is capped at what your default model would have cost. Upgrade metering before, or together with, the data plane. |
| 0.26.9 | Do not run 0.26.8's metering: it overstated auto mode savings. Contact support to correct rows recorded with it. |
| 0.26.8 | Auto mode measures its saving against your default model. Upgrade the control plane before, or together with, the web console. |
| 0.26.7 | One-hour cache writes and fast mode are priced as Anthropic bills them, so recorded costs rise for that traffic. Upgrade metering first. |
| 0.26.6 | The semantic cache no longer answers prompts longer than the embedder can read. |
| 0.26.5 | Every service restarts once during the upgrade. |
| 0.26.1 | With the semantic cache on, create the collection-naming key Secret before upgrading (see [Configuration](https://tessarac.com/docs/acog/self-hosted/configuration.md#semantic-cache)); the cache starts empty. |
| 0.26.0 | Remove `services.analytics` from your values before upgrading; the chart refuses to render while it is present. |