Skip to main content
Version: 1.2

Upgrades

Upgrading a running Hub installation to a newer chart version applies schema migrations, which constrain how far you can roll back.

How releases work​

Hub releases as a single train. The hub umbrella chart pins matching versions of its components (hub-core, hub-auth, hub-connector, and hub-webui), and they are released together at the same chart version. You can install and manage each subchart separately, see the feature compatibility document to understand compatibility guarantees between versions.

Schema migrations are applied automatically as part of every chart upgrade. The chart runs the embedded migration tool in a dedicated Job named hub-core-migrate-<hash>. A single Job applies the schema change once, rather than every replica racing it during a rolling update. Each new hub-core Pod has an init-migrate init container that waits until the schema has every migration the release ships, so a new Pod never serves against an unmigrated schema.

Migrations are forward-only. The migration tool has no down-migrations. Once a newer chart version has run its migrations against your database, the schema reflects the newer version. There's no automated path back to the previous schema.

Plan an upgrade​

Before running helm upgrade, work through the following:

  1. Read the release notes. Each release publishes notes alongside the chart. Check them for breaking changes, required values updates, deprecations, and any per-upgrade migration warnings.
  2. Check your current chart version. Run helm list -n hub and confirm the version currently installed against the version you intend to install. If you are skipping multiple versions, read the notes for every intermediate release. Migrations from each are applied in order, and a step you skip may include a breaking values change you need to honor.
  3. Diff your values. If you keep your values.yaml in source control, compare it against the new chart's defaults. Run helm show values oci://xpkg.upbound.io/upbound/hub --version <new-version> to see the new defaults and check for renamed or removed keys.
  4. Stage the upgrade. Run the upgrade against a non-production installation first, ideally one that mirrors your production values and points at a copy of your production schema. Confirm the migration completes, the new Pods come up, and your existing connectors continue to register.
  5. Back up Postgres. Take a fresh backup of the Hub database immediately before the upgrade. Migrations are forward-only. If you need to revert to an older chart, you may need the backup to restore the previous schema. Use your database provider's native snapshot facility, such as an RDS snapshot.
  6. Plan the maintenance window. New hub-core Pods wait in their init-migrate container until the migration Job finishes. Your existing Pods keep serving while the migration runs. If the schema isn't current after 10 minutes, the init container fails and restarts. The window depends on the size of the migration; small upgrades typically take seconds, but a migration that rewrites a large table can take longer. Notify any clients of hub-core of the expected window.
warning

Database migrations can't be reversed automatically. Always take a backup of the Hub database before upgrading.

Upgrade procedure​

The upgrade is a standard helm upgrade against the hub chart.

  1. Run the upgrade with your existing values file:

    helm upgrade hub oci://xpkg.upbound.io/upbound/hub \
      --version <new-version> \
      --namespace hub \
      --values values.yaml

    Replace <new-version> with the chart version you are installing and values.yaml with the path to the values file you used for the original install.

  2. Watch the rollout:

    kubectl -n hub rollout status deployment/hub-core
    kubectl -n hub rollout status deployment/hub-auth
    kubectl -n hub rollout status deployment/hub-webui

    The hub-core rollout doesn't complete until the migration Job finishes, because each new Pod waits for the schema. To follow the migration, tail the Job from another terminal:

    kubectl -n hub logs -l app.kubernetes.io/component=api-migrate -c sql-migrate --follow

  3. Roll the connectors. Each hub-connector install is a separate Helm release in its host control plane. Upgrade each one to the same chart version using the same helm upgrade shape with its own values file.

  4. Verify:

    • The migration Job completed successfully and the hub-core Pods are Ready.
    • The Hub UI loads and you can authenticate.
    • Each hub-connector reconnects and continues reporting ControlPlane state.

Roll back​

Helm supports rolling the chart back with helm rollback, but Hub's database migrations are forward-only and Helm has no awareness of the schema. A naive rollback can leave your installation with an older binary running against a newer schema.

Before running helm rollback, check the release notes for the version range you are crossing. Two cases:

  • The release notes state the target version is schema-compatible with the schema currently in your database. This scenario is the common case for minor or patch rollbacks where no migration ran, or where the migrations between the two versions are additive only. In this case helm rollback is safe:

    helm rollback hub <previous-revision> --namespace hub

    Find <previous-revision> with helm history hub -n hub.

  • The release notes state the target version isn't schema-compatible with the current schema. A helm rollback alone doesn't work. You need to restore the database to a backup taken before the offending upgrade, then run helm rollback to align the chart. Plan for downtime; treat this as a database restore operation, not a Helm operation.

If the release notes don't state compatibility explicitly, assume the rollback is unsafe and contact support before proceeding.

warning

helm rollback doesn't reverse database migrations. Rolling the chart back without verifying schema compatibility can leave hub-core unable to start. It can also run with subtly inconsistent behavior against a schema it doesn't understand.

Next step​