Upgrading

telark is shipped as a Helm chart that pins each of the three service deployments — discovery, exporter, auth — plus the CRD definitions to a single chart version. Upgrade is a helm upgrade against the same release.

Before you upgrade

A small checklist:

Read the changelog for the target version. Anything called out as a CRD migration or a breaking config change is the first thing to plan for.
Snapshot the cluster. Run a Velero backup (or your equivalent) so the PVC and the telark CRDs are captured in a restorable state. See Operations → Backups.
Drain in-flight rollbacks. The rollback controller will not pick up new pending entries during the restart window. Wait for any current in-progress rollbacks to finish or fail.
Pause active plan changes. Plan phase transitions resume on the next controller tick after the new pods are ready.

The upgrade itself

A plain Helm upgrade against the existing release. The exact command will be documented under Reference → Helm values once the public install path lands.

What happens, in order:

Helm renders the new chart with the current values (overlay any --values you pass).
Helm applies the new CRD definitions. New fields land first; removed fields stay until the old CRD version is removed.
Helm rolls the three Deployments in parallel:
- exporter picks up the new image and re-mounts the PVC.
- discovery picks up the new image; the new leader wins the Redis election after the old one terminates.
- auth picks up the new image; sessions persisted in Redis survive the restart.
Readiness probes gate traffic onto the new pods.
The plan controller resumes its tick on the new leader; the rollback controller resumes its informer loop.

Total downtime for the API surface is typically the readiness window of the slowest pod — usually under a minute.

CRD migrations

When a telark version adds fields to a CRD, the new fields are populated lazily — discovery and exporter handle the absence of new fields by treating them as their default.

When a telark version removes or renames fields, the release notes will call out the migration. The supported pattern is:

Upgrade to the version that introduces the new field. telark writes both old and new fields.
Run an idle period (a few cycles, depending on the field).
Upgrade to the version that drops the old field.

If a future version requires a one-off backfill (cmd/backfill in auth-service is the existing precedent), the changelog will call it out and the chart will ship a Job manifest gated by a values flag.

Rolling back the upgrade

If the upgrade fails:

helm rollback <release> returns to the previous chart version. The Deployments re-roll with the old images.
The telark CRDs are not downgraded by Helm — they remain at the new version. This is usually safe because CRD changes are additive. If a release explicitly required a destructive CRD change, the rollback path will be in its changelog.
The snapshot PVC is unchanged by the upgrade; no restore needed unless the upgrade corrupted it (it should not).

Zero-downtime considerations

The chart sets sensible maxUnavailable / maxSurge defaults so each Deployment rolls one pod at a time. Concretely:

exporter can be safely scaled past 1 replica for zero-downtime upgrades (writes are serialised on the CRD's resource version + retry).
discovery is leader-elected; only one pod runs the cycle. During a roll, the new pod may race to become leader before the old one drains — the protection-plan controller will pause for one tick during the transition.
auth is stateless; rolls without coordination.

After the upgrade

Verify:

The /healthz and /readyz endpoints for each pod return 200.
The Prometheus telark_*_up style gauges are 1 on every pod.
The dashboard loads, plans render with the correct phase, and recent rollbacks still show in the list.
Trigger a small test action (force-sync on one application, for instance) and confirm it completes within one tick.