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 a matching snapshot of the artifact PVC, 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, download an existing artifact, and start a workspace. In that conversation, verify r5dchat artifacts list succeeds and that a private file is not shared until explicitly pushed.
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 or artifact metadata change. 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 PostgreSQL and the artifact PVC from the same recovery point. 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 and matching artifact PVC snapshot 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 and artifact load
  • A workspace starts, runs a command, and can list its scoped artifacts
  • Existing workspace Deployments were rolled out if needed