Skip to content
fzymgc-house Cluster Docs

Sign nas-otel GHCR image with keyless cosign

Date: 2026-06-28 Status: Accepted Decision: hl-2vsw Deciders: Sean Brandt

Context

Section titled “Context”

The nas-otel custom image (derived otelcol-contrib with journalctl for the journald receiver) is the first signed image in the fzymgc-house selfhosted-cluster repo. No existing build-* workflow signs its output. The image bundles systemd + journalctl into the cluster’s telemetry path, so supply-chain provenance matters: a tampered or misbuilt image would sit on the TrueNAS host shipping (or dropping) all nas logs and metrics to ClickStack.

Decision

Section titled “Decision”

Sign ghcr.io/fzymgc-house/nas-otel keyless with cosign in .github/workflows/build-nas-otel.yml (via sigstore/cosign-installer + cosign sign --yes, using the GitHub OIDC token — no key material stored). Emit SLSA provenance + SBOM via docker/build-push-action (provenance: true, sbom: true). Verify at deploy time with:

cosign verify <image> \
  --certificate-identity-regexp 'https://github.com/fzymgc-house/selfhosted-cluster/.github/workflows/build-nas-otel.yml@refs/heads/main' \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com

Scope signing to this image only; retrofitting signing onto the other 6 build-* workflows is deferred to a separate repo-wide hardening task.

Rationale

Section titled “Rationale”
  • First signed image — the trust anchor (workflow-path-bound OIDC identity) becomes the template for every future signed image.
  • Keyless removes Vault key-management overhead while fail-closed verification rejects images built by any other workflow (e.g. a future staging workflow publishing to the same package).
  • Scoping to one image keeps the change intentional and reviewable; a blanket retrofit would couple an unproven pattern to 6 working pipelines.

Alternatives Considered

Section titled “Alternatives Considered”
  • Keyless cosign on this image only (chosen): no key material to manage; OIDC-bound to the exact workflow path+ref; free under buildkit+keyless cosign; sets a scoped, intentional precedent.
  • No image signing (rejected): no supply-chain provenance for the telemetry image; unverifiable at deploy; no precedent for future hardening.
  • Retrofit signing onto all 6 build workflows now (rejected): out of scope for the bead; large blast radius; pattern unproven on this cluster first; flagged as a separate follow-up.

Consequences

Section titled “Consequences”
  • Positive: verifiable provenance for the telemetry image; reusable trust-identity pattern for future signing.
  • Negative: inconsistency — 6 existing build workflows remain unsigned until a separate hardening task.
  • Neutral: requires id-token: write permission on the workflow; cosign-installer action must be SHA-pinned and maintained.