Skip to main content
An upgrade has two distinct parts: the control plane, which Helm manages, and existing workspace Deployments, which Helm does not. Workspace pods are created by the controller at runtime, so a chart upgrade alone does not change them.

​
Before you upgrade

1

Back up

Take a database backup and confirm you hold SETTINGS_ENCRYPTION_KEY and BETTER_AUTH_SECRET. See Backup and restore.
2

Read the release notes

Check for breaking changes and required values between your current version and the target.
3

Capture your current values

This preserves settings that are not in your values file:

​
Upgrade the control plane

1

Update the repository

2

Render and dry-run the exact values

3

Upgrade

--atomic rolls the release back automatically if the upgrade fails.
4

Verify

Then sign in, confirm provider settings decrypt correctly, open an existing conversation, and start a workspace.
The control plane uses the Recreate strategy to stay within namespace pod quotas, so expect a brief interruption rather than a seamless rolling update.

​
Database migrations

Migrations run in an init container before the new application container starts, guarded by a PostgreSQL advisory lock so concurrent rollouts cannot race.
A Helm rollback does not reverse a database migration. If a release includes a schema change, rolling back the chart leaves the newer schema in place. The application must tolerate that, or you must restore the database from backup. Test upgrades in a staging namespace first.

​
Roll out existing workspaces

New workspaces use the new image automatically. Existing Deployments keep their current image until you update them explicitly.
1

Determine the new workspace image

2

Update every workspace Deployment

This replaces only the container image and preserves each Deployment’s current replica count, so idle workspaces stay scaled to zero.
3

Wait only for the running ones

Workspace Deployments use Recreate because each home volume is ReadWriteOnce. Active users see a short interruption while their pod restarts. The PVC and its contents are preserved. Never delete workspace PVCs as part of an image update.

​
Roll back

1

Find the revision

2

Roll back the release

3

Restore the previous workspace image

Only if you had already updated existing workspaces:
4

Verify the schema is compatible

If the failed upgrade applied a migration, confirm the older application still works against the current schema. Restore the database from backup if it does not.

​
Upgrade checklist

  • Database backup taken and verified
  • SETTINGS_ENCRYPTION_KEY and BETTER_AUTH_SECRET available
  • Current values exported
  • Release notes reviewed
  • Rendered manifests pass kubectl apply --dry-run=server
  • /api/health returns {"ok":true}
  • Control-plane logs are free of startup errors
  • Login works, including SSO if enabled
  • Provider settings still decrypt
  • An existing conversation loads
  • A workspace starts and runs a command
  • Existing workspace Deployments were rolled out if needed