Upgrades

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.

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

4. Upgrade, passing every values file every time:

   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.

   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); the cache starts empty.
0.26.0	Remove services.analytics from your values before upgrading; the chart refuses to render while it is present.