Upgrades and migrations

A new release of Labtagon AI OS is a new version of the chart with new images. You roll it out with helm upgrade; the controller brings the database along.

Before you upgrade

1. Back up. Make sure a recent Postgres backup exists and the keys are safe (Backups and restore).

2. Read the release notes and the chart’s README for values that were renamed or deprecated. The chart keeps a deprecated value working for one release and says so in its notes; for example keycloak.harnessClients, which keycloak.agentClients replaces.

3. Render first:

   helm lint deploy/helm/ai-os -f values.yaml
   helm template ai-os deploy/helm/ai-os -n ai-os-system -f values.yaml > /dev/null

   The chart refuses values that contradict each other, such as a digest that is not sha256: with 64 hex digits, some components pinned and others not, or an idle default longer than the longest allowed.

Rolling it out

helm upgrade ai-os deploy/helm/ai-os -n ai-os-system -f values.yaml

• Roll all components together. They are released as one version. The chart notes one case explicitly: rolling the egress gateway back past the release that brought API rules turns those rules into host-level access.
• Pinned images: set the new digests of every component, the bundle fetcher and the checks image together.
• Runtimes of tool servers are pinned by digest per release (runtimes.*). A new runtime digest means new builds of the servers that use it.

Database migrations

• The controller applies the migrations in db/migrations itself when it starts (--migrate-dir), in name order, each once and in a transaction of its own. Which ran is recorded in the table schema_migrations.
• An advisory lock in Postgres makes sure only one controller migrates when several start together.
• A migration that fails is rolled back and the controller does not start; the error names the file. Fix the cause and let the pod start again.
• Migrations only go forward; there are no down migrations. To go back, restore the database from the backup you took before.

Postgres versions

postgres.imageName pins the PostgreSQL image of the CloudNativePG cluster (PostgreSQL 18.6 in the current chart). A cluster that already runs another major version needs its own image here: a different major version is a major upgrade, which CloudNativePG does in its own way (and a downgrade it refuses).

After the upgrade

• Under Administration → Platform, check that every component is ready and runs the new version, and that build checks are on.
• Sign in, open a chat, and call a tool from a client.
• Changing global.mirror means new approvals for companions on a runtime and new builds, unless the runtimes were already pinned to the same references.