Production Adoption Guide

Production Adoption Guide

This is the consumer-facing path from evaluation to a controlled production deployment.

1. Define the supported payload

Prefer a static Linux binary:

CGO_ENABLED=0 GOOS=linux GOARCH=amd64 \
  go build -trimpath -ldflags='-s -w' -o service ./cmd/your-service
scripts/ci/verify-elf.sh service amd64

If static compilation is impossible, package the ELF interpreter and every shared library with -extra-file, then test on the exact target architecture. Never embed credentials, private keys, or environment-specific CA bundles in the executable or layer.

2. Build and verify

go run ./cmd/oci-builder \
  -binary ./service -output ./oci-image -arch amd64 \
  -image example/service -tag 1.0.0 \
  -created 1970-01-01T00:00:00Z
python3 scripts/ci/verify-oci-layout.py ./oci-image

Treat the printed manifest digest and blob checksums as build evidence. Build into a new path; existing outputs are deliberately not overwritten.

3. Turn the layout into a registry image

Place oci-image/ beside the repository Dockerfile:

docker build --pull=false -t ghcr.io/example/service:1.0.0 .
docker push ghcr.io/example/service:1.0.0
docker inspect --format='{{index .RepoDigests 0}}' \
  ghcr.io/example/service:1.0.0

Record and deploy the returned @sha256:... reference. Tags are discovery labels, not deployment identities.

4. Sign and verify

In CI, grant id-token: write only to the signing job:

cosign sign --yes ghcr.io/example/service@sha256:<digest>
cosign verify \
  --certificate-identity \
  'https://github.com/example/service/.github/workflows/release.yml@refs/tags/v1.0.0' \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com \
  ghcr.io/example/service@sha256:<digest>

Use an exact workflow/ref identity where possible. If a regex is necessary, anchor both ends and code-review it as a security boundary.

5. Enforce admission and runtime hardening

The cluster should admit only immutable digests with an approved signer. The E2E demonstration provides a tested policy-controller flow.

Minimum container contract:

automountServiceAccountToken: false
securityContext:
  seccompProfile:
    type: RuntimeDefault
containers:
  - name: service
    image: ghcr.io/example/service@sha256:<digest>
    securityContext:
      runAsNonRoot: true
      runAsUser: 65532
      runAsGroup: 65532
      allowPrivilegeEscalation: false
      readOnlyRootFilesystem: true
      capabilities:
        drop: ["ALL"]
    resources:
      requests: {cpu: 10m, memory: 32Mi}
      limits: {cpu: 250m, memory: 128Mi}

Mount only required configuration/secrets and use a size-limited emptyDir for writable paths. Add NetworkPolicy, PodDisruptionBudget, topology, probes, and workload-specific resource values.

6. Promotion and rollback

Promote the same digest between environments; never rebuild for production. Store layout checksums, SBOM, provenance, signature verification, security scan, compatibility result, approval, and deployed digest. Rollback means redeploying a previously admitted digest, not moving a tag.

7. Operational readiness

• Monitor crash loops, OOM, throttling, readiness, admission denials, webhook latency/availability, certificate transparency access, and registry errors.
• Use structured stdout/stderr logs; there is no shell in the image.
• Debug with an approved ephemeral container or nsenter, with access audited.
• Scan every application release even though the base filesystem is minimal.
• Patch by rebuilding and promoting a new digest; immutable images are not repaired in place.
• Test disaster recovery when GHCR, Fulcio/Rekor, or admission is unavailable.

Production acceptance checklist

• threat model reviewed and residual risks owned;
• protected release environment and two-person review configured;
• workflow permissions minimized and actions pinned;
• reproducibility, vulnerability, compatibility, and benchmark evidence reviewed;
• digest signed and independently verified;
• fail-closed admission enforced in all production namespaces;
• runtime security context and resource limits enforced by policy;
• secrets are external and workload identity is least privilege;
• monitoring, rollback, evidence retention, and emergency procedures tested.

For limitations, see Threat Model and Residual Risks, OCI Compatibility, and Troubleshooting.