> ## Documentation Index
> Fetch the complete documentation index at: https://radarhq.io/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Upgrade

> Helm upgrade flow, migration safety, version-skew policy.

## The flow

```bash theme={null}
helm repo update
helm upgrade radar-hub skyhook/radar-hub \
  --namespace radar-hub
```

Omitting `--reuse-values` is deliberate. Because this command passes no new value overrides, Helm combines the new chart defaults with the release's existing user-supplied values instead of carrying forward defaults from the old chart. Commands below that add explicit overrides use `--reset-then-reuse-values` to perform the same merge before applying those overrides.

What happens:

1. Helm renders the new manifests from the new chart defaults plus your existing user-supplied values.
2. The `radar-hub` Deployment rolls (default rolling update; one new pod up + healthy before the old terminates). Each new pod's `migrate` initContainer applies any pending schema migrations against your Postgres before the main `hub` container starts.
3. The `radar-hub-web` Deployment rolls similarly.

Rolling-update strategy is deliberately conservative - the control plane is single-replica today, so the rollout briefly serves out of one new pod before the old terminates. Brief 503s during the cut are normal; the web app's auto-retry covers them.

## Pinning a specific release

```bash theme={null}
RADAR_HUB_CHART_VERSION="CHART_VERSION"
RADAR_HUB_RELEASE="MATCHING_RELEASE_TAG"
helm show chart skyhook/radar-hub --version "$RADAR_HUB_CHART_VERSION"
helm upgrade radar-hub skyhook/radar-hub \
  --namespace radar-hub \
  --reset-then-reuse-values \
  --version "$RADAR_HUB_CHART_VERSION" \
  --set-string image.hub.tag="$RADAR_HUB_RELEASE" \
  --set-string image.web.tag="$RADAR_HUB_RELEASE"
```

Replace `CHART_VERSION` with the selected `radar-hub` chart version and `MATCHING_RELEASE_TAG` with the `appVersion` shown by `helm show chart`, after confirming that tag is published for both Hub and Web. The chart and images ship as one release unit. Never mix a chart with images from another release, or mix Hub and Web release tags.

## Migration safety

All migrations land in `db/migrations/NNN_*.sql` and follow these rules:

* **Forward-only.** No down-migrations. Helm rollback does not undo schema changes; restore a database backup only when the previous binary cannot run against the migrated schema.
* **Additive-by-default.** New columns are nullable or safely defaulted and backfilled before constraints are enforced; new tables don't break existing reads.
* **Idempotent.** `IF NOT EXISTS`, `IF EXISTS`, `ON CONFLICT DO NOTHING`. A re-run never fails.
* **Tracked.** `schema_migrations` records every applied version; the runner skips applied ones.

Destructive migrations are called out in release notes with explicit downtime, backup, and rollback requirements. The 1.1.0 migration set is additive.

## Version-skew policy

* The chart and the images ship together. Use `helm upgrade` (which pins both via `appVersion`) rather than rolling images independently.
* The control plane speaks to in-cluster Radar via the tunnel protocol, which is **forward-compatible** by design - older Radar versions talk to newer control planes. We test 2 minor versions back. If you see protocol-level errors, check the Helm chart pinned in customer clusters: `radar` chart ≥ `1.5.4` is required for cloud-mode RBAC.
* The chart defaults Hub and Web to the same `appVersion`. Explicit image overrides can bypass that default; keep both tags identical because mixed versions are unsupported.

## Pre-upgrade checks

```bash theme={null}
# 1. Verify the chart is reachable + the new version is what you expect.
helm search repo skyhook/radar-hub

# 2. Lint the new chart against your live values.
helm get values radar-hub --namespace radar-hub > /tmp/live-values.yaml
helm template radar-hub skyhook/radar-hub \
  --namespace radar-hub \
  -f /tmp/live-values.yaml > /tmp/rendered.yaml

# 3. (Recommended) Take a backup of your Postgres.
pg_dump -h <host> -U radar radar_hub | gzip > radar-hub-pre-upgrade.sql.gz
```

## After upgrade

The first thing to check post-upgrade:

```bash theme={null}
kubectl -n radar-hub logs deploy/radar-hub-hub --tail=30
```

Look for:

* `radar-hub starting addr=:8080 mode=self_hosted ...` - the control plane booted.
* `license verified` - the new build is signed against the same Skyhook public key as the old.
* No `database schema not found` / `pg_query: relation "X" does not exist` - the `migrate` initContainer applied successfully before the main container started.

In the web app: hit `GET /api/config` and confirm `version.current` matches the chart's `appVersion`.

## Rollback

```bash theme={null}
helm rollback radar-hub <previous-revision> --namespace radar-hub
```

**Caveat:** Helm rollback rolls back the manifests, NOT the database. If the previous release had a different schema, the rolled-back control plane will fail against the migrated DB. We don't ship down-migrations. Practical guidance:

* For chart-template-only changes (annotations, resources, ingress): rollback is safe.
* For binary-version rollbacks within the same migration cohort: rollback is safe.
* For binary-version rollbacks across a destructive migration: restore from backup.

Tag releases that include destructive migrations clearly in our release notes so you know which rollbacks need a DB restore.

## Cadence

* **Patch (0.x.Y):** as needed, typically weekly. Bug fixes only. Minor or no migration.
* **Minor (0.X.0):** monthly. Feature work + migrations as needed.
* **Major (X.0.0):** breaking changes, e.g. cookie format change, mandatory new env var. We'll publish a migration guide ahead of these.

We support the current minor + the previous one. A 6-month-old version is out of support and may not get patches.