Upgrades & Rollback

This page covers moving a running self-hosted install between chart versions and undoing an upgrade. It assumes the canonical layout from Install on Kubernetes (Helm) — release name dynamiq in namespace dynamiq, values in values.yaml (plus a provider file like values-aws.yaml if you use one). Every upgrade re-runs the same schema validation and database migrations the install does, so the risk lives in schema changes and forward-only migrations — plan for both before you run anything.

Before you upgrade

An upgrade is the same helm upgrade --install you ran to install, pointed at a newer chart version. Prepare it deliberately:

• Pin the exact target version. Choose a specific --version — never latest. Image tags default to the chart's app version, so pinning the chart pins the matching images (Overview → Distribution).

• Read the release notes. Dynamiq publishes what changed between versions, including new required values and breaking migrations. Contact Dynamiq if you don't have them for your target version.

• Diff the default values. The chart is a private OCI artifact, so authenticate first, then compare the defaults of your current and target versions:

  helm registry login registry-1.docker.io \
    --username "$DYNAMIQ_REGISTRY_USER" \
    --password "$DYNAMIQ_REGISTRY_TOKEN"
  
  helm show values oci://registry-1.docker.io/dynamiqai/dynamiq --version 0.39.0 > current-defaults.yaml
  helm show values oci://registry-1.docker.io/dynamiqai/dynamiq --version <new> > new-defaults.yaml
  diff current-defaults.yaml new-defaults.yaml

• Check for new required keys. A newer chart can add keys to its values.schema.json. Those are validated the moment you upgrade, so a value that installed cleanly on the old version can be rejected by the new one — schema validation fails the upgrade before anything is applied to the cluster, so fix the values and re-run. Render the new version against your values file first to catch it dry:

  helm template dynamiq oci://registry-1.docker.io/dynamiqai/dynamiq \
    --version <new> -n dynamiq -f values.yaml > /dev/null

Upgrade

Run the same command as the install, with the new --version. Include every -f file you installed with — Helm does not remember files from previous releases:

helm upgrade --install dynamiq \
  oci://registry-1.docker.io/dynamiqai/dynamiq \
  --version <new> \
  --namespace dynamiq \
  -f values.yaml
  # add -f values-aws.yaml (or your provider file) if you used one

Helm validates values.yaml against the new chart's JSON schema, renders the manifests, and applies them. The Deployments roll to the new image tags — which follow the chart's app version unless you pinned a service to a specific tag with <svc>.image.tag:

nexus:
  image:
    tag: "0.39.0"

The database migration Job re-runs as a post-upgrade Helm hook, exactly as it does on install — it blocks the helm upgrade command until it finishes, and Helm deletes it on success. The semantics and how to watch it are identical to install Step 7; if the hook fails, the upgrade errors and the failed Job persists for inspection.

Roll back

List the release history, then roll back to a previous revision:

helm history dynamiq -n dynamiq
helm rollback dynamiq <revision> -n dynamiq

helm rollback restores the Kubernetes objects — Deployments, ConfigMaps, and the like — from the target revision, so the pods return to the previous image tags and configuration.

Because the failed-forward path can leave the database ahead of the code, the reliable recovery for a bad schema-migrating upgrade is: restore the database snapshot, then helm rollback (or re-upgrade) to the version that matches it. Restore order and the state that lives where are covered in Backup and restore.

Uninstall

Remove the release with:

helm uninstall dynamiq -n dynamiq

This deletes only what the chart created and still owns — the five Deployments, their Services, ConfigMaps, ingresses or routes, and any Helm-managed Secret. Several things deliberately survive:

• Secrets you pre-created — nexus, nexus-db, synapse, synapse-db, catalyst, catalyst-db, runtime, and the license Secret (install Step 4) are not owned by the release, so they remain. Delete them by hand if you're tearing down for good.
• The docker-registry pull Secret — remains if you created it with kubectl (install Step 2, Option B). It is deleted if you let the chart manage it via dynamiq.imageCredentials, since then it belongs to the release.
• Your external services — Postgres, NATS, and the S3 bucket are never managed by the chart, so uninstall does not touch them or your data. Feature-namespace workload state (inference and database pods nexus scheduled) lives outside the release too.
• The migration hook Job — already deleted after the last successful install or upgrade, so there is normally nothing to clean up. A Job left behind by a failed hook must be removed manually.

Next steps