feat(gke): auto-track preview backend image via ArgoCD Image Updater

[mikestankavich]

Summary

• Adds the upstream argocd-image-updater chart as a GKE-only ArgoCD-managed Application, watching ghcr.io/trakrf/backend:preview with digest update-strategy.
• Annotates the trakrf-backend-preview Application so the controller patches helm.parameters.image.tag with the resolved digest on every change; prod is intentionally never annotated (manual tag promotion stays the contract).
• Teaches the helm/trakrf-backend chart to render either a <repo>:<tag> or <repo>@<digest> image reference based on the shape of image.tag, so the same field accepts a human-pinned sha-<short> or a controller-written sha256:<hex>.
• Documents the design + implementation under docs/superpowers/.

Context

Platform side (independent repo) shipped two PRs that make this possible:

• trakrf/platform#408 — docker-build.yml now builds the preview branch on every sync-preview.yml rewrite, publishing ghcr.io/trakrf/{backend,ingester}:sha-<short>.
• trakrf/platform#409 — adds a floating :preview tag (priority 50, below sha-<short>'s 100) specifically so Image Updater's digest strategy has an unambiguous primitive to watch without racing main-branch builds.

The hand-off documented in #409 is the exact contract this PR fulfils.

Design highlights

1. argocd write-back, not git write-back. Patches the live Application's spec.source.helm.parameters. No GitHub credentials to manage. No commit churn on main every PR open/sync/close. values-gke.yaml.image.tag stays as the bootstrap value; the live tag lives on the Application.

2. GKE-only gating on the Image Updater Application, env-only gating on the annotations. The Image Updater chart only emits when cluster=gke. The annotations only emit when env=preview AND cluster=gke. When prod shares the GKE cluster post-cutover, prod stays a deliberate manual tag promotion by structure — the trakrf-backend-prod Application is structurally unannotated, and Image Updater is opt-in per Application via annotations.

3. Chart-level support for digest references. Image Updater's digest strategy writes sha256:<hex> into the image.tag helm parameter. The Docker reference for a digest uses @, not : — so the chart helper detects the sha256: prefix and switches separators. Both deployment and migration job use the helper.

See docs/superpowers/specs/2026-05-25-tra-483-gke-preview-image-updater-design.md for the full design walk-through (architecture, sub-decisions, risks).

What's NOT in this PR (by design)

• Prod auto-bump — prod stays a deliberate manual tag promotion.
• Cross-repo bot-PR or git-side-branch write-back — explicitly chose argocd write-back for simplicity.
• Ingester auto-track — trakrf-ingester runs the upstream Redpanda Connect image; no platform image to track.
• scripts/apply-root-app.sh run — this is a post-merge manual step (per repo convention).

Test plan

Pre-merge (already done, render-only):

• helm lint helm/trakrf-backend clean.
• Root chart renders 13 valid YAML docs on GKE; argocd-image-updater Application + 5 annotations on trakrf-backend-preview only.
• Root chart on AKS render: no argocd-image-updater Application, no Image Updater annotations on preview.
• trakrf-backend template renders <repo>:<tag> for sha-67f3dbc and <repo>@<digest> for sha256:....

Post-merge (manual, on GKE):

• scripts/apply-root-app.sh gke — re-render with the new templates.
• kubectl -n argocd get applications — argocd-image-updater Healthy + Synced.
• kubectl -n argocd describe app trakrf-backend-preview — annotations present.
• kubectl -n argocd describe app trakrf-backend-prod — no Image Updater annotations.
• Open or sync a non-draft PR on trakrf/platform; confirm preview env rolls within a few minutes and /version.json reports the new commit.

🤖 Generated with Claude Code