Skip to content
fzymgc-house Cluster Docs

Use official GHCR Headroom images; do not build cluster-owned images

Date: 2026-06-23 Status: Accepted Decision: hl-8ycr Deciders: Sean Brandt

Context

Section titled “Context”

Headroom is a pre-1.0, single-vendor dependency with frequent releases. A decision was required on whether to build and own cluster images (full supply-chain control, patching) or consume the official ghcr.io/chopratejas/headroom images directly. During planning this decision reversed: an initial “build our own” assumption was overturned after verifying the official images exist.

Decision

Section titled “Decision”

Use the official ghcr.io/chopratejas/headroom images, digest-pinned at 0.27.0 (0.27.0-nonroot for apps, 0.27.0-code-nonroot for agents), tracked via Renovate for future version bumps. Do not build cluster-owned Headroom images.

Rationale

Section titled “Rationale”
  • The upstream image matrix directly serves deployment needs: code-nonroot includes tree-sitter for the agents instance; nonroot (debian-slim) retains a shell for /stats tuning on the apps instance.
  • Digest-pinning provides immutability without a cluster build pipeline.
  • Renovate converts the rapid pre-1.0 release cadence into reviewed PRs rather than silent drift.
  • Tag existence must be confirmed via a manifest HEAD probe, not the tags/list API (which paginates at 100/page and is unordered, producing false “tag missing” readings — this exact trap occurred during design).

Alternatives Considered

Section titled “Alternatives Considered”
  • Use official GHCR images, digest-pinned, Renovate-tracked (chosen): no build pipeline; tag matrix matches needs directly; Renovate surfaces bumps as reviewed changes; digest pin gives immutability without owning the build.
  • Build cluster-owned images (rejected): full supply-chain control and a patching path, but significant build/maintenance overhead for a third-party proxy, would have to replicate the nonroot/slim/code tag matrix, and adds no value since the upstream images are purpose-built and confirmed present.

Consequences

Section titled “Consequences”
  • Positive: no cluster build pipeline for Headroom; Renovate tracks upgrades automatically; digest pins prevent silent image mutation.
  • Negative: supply-chain trust is delegated to the upstream GHCR package with no cluster-side patching path; the env-var / flag surface must be re-verified against the pinned image at each bump (pre-1.0 instability risk).
  • Neutral: if the GHCR package is private, the existing cluster/ghcr/pull-secret is reused; the package was verified public, so no pull secret is needed.

Addenda

Section titled “Addenda”
  • Amended 2026-06-24 (hl-v9xz.11): No published official image carries the OpenTelemetry SDK (every variant is built [proxy], not [proxy,otel]; confirmed via manifest HEAD). A thin derived image ghcr.io/fzymgc-house/headroom-otel is therefore built to add only the OTel SDK + OTLP/HTTP exporter on top of the official code-nonroot base. This is a scoped exception, not a reversal: build a derived image only when the official matrix lacks a required capability extra unsupplied by config, and keep it minimal (no Headroom fork) so the upstream supply-chain trust is preserved.