containerize

Containerize an Application

Build a small, non-root, reproducible OCI image and verify it before it ships. Pairs with k8s-local for the local dev loop and security-scan for image scanning.

Choose an Approach

1. Go → ko (default, no Dockerfile): builds a minimal, shell-less, multi-arch, reproducible image straight from a package path (base defaults to cgr.dev/chainguard/static, override with KO_DEFAULTBASEIMAGE). Pin it per project (go get -tool github.com/google/ko, then go tool ko) so builds stay reproducible even where a global toolchain already provides ko.

   export KO_DOCKER_REPO=registry.localhost:5050/<slug>   # or a real registry
   go tool ko build ./cmd/<slug> --bare --platform=linux/amd64,linux/arm64
   

2. Python (or any other language) → multi-stage Dockerfile on a distroless or minimal base (optimized with uv). Copy and customize the image digests and the <slug> console-script entry point:

   • Dockerfile
   • .dockerignore

   # Build locally for current platform
   docker build -t <registry>/<slug>:<tag> .
   
   # Build multi-platform using Buildx (recommended for multi-arch registries)
   docker buildx build --platform linux/amd64,linux/arm64 -t <registry>/<slug>:<tag> --push .
   

Verify Before Ship

1. Resolve the immutable digest emitted by the registry after the push. Use that digest for every scan, signature, SBOM, and deployment reference; never sign a mutable tag.
2. Scan the built image (fail on HIGH/CRITICAL — see security-scan):

   trivy --config trivy.yaml image <registry>/<slug>@<digest>
   

3. Sign and verify keyless with Sigstore (OIDC, no long-lived keys). Verification must bind the certificate to the expected workflow identity and OIDC issuer:

   cosign sign --yes <registry>/<slug>@<digest> # --yes is mandatory: cosign prompts by default and hangs any CI job or agent session
   cosign verify \
     --certificate-identity '<expected-certificate-identity>' \
     --certificate-oidc-issuer '<expected-oidc-issuer>' \
     <registry>/<slug>@<digest>
   

4. SBOM for a portable component inventory:

   trivy --config trivy.yaml image --format cyclonedx -o sbom.json <registry>/<slug>@<digest>