ko — Build and Deploy Go Containers Without Dockerfiles

Introduction

ko is a container image builder for Go applications that skips the Dockerfile entirely. It compiles your Go binary and layers it on top of a minimal distroless base image, producing small, secure, and reproducible containers. Designed for Kubernetes-native workflows, ko can resolve image references inside YAML manifests and push images to any OCI registry in one step.

What ko Does

• Builds Go applications into OCI container images without a Dockerfile
• Produces minimal distroless images that are small and free of OS-level vulnerabilities
• Resolves ko:// image references in Kubernetes YAML and replaces them with real image digests
• Pushes images to any OCI-compliant registry (Docker Hub, GHCR, ECR, GCR)
• Supports multi-platform builds for linux/amd64, linux/arm64, and more

Architecture Overview

ko works by running go build to compile a static binary, then constructing a container image programmatically using the go-containerregistry library. The base image defaults to gcr.io/distroless/static but is configurable. ko never invokes Docker or any container daemon — it builds and pushes images entirely in user space. For Kubernetes deployment, ko scans YAML files for ko:// prefixed image references, builds each referenced Go package, pushes the resulting images, and rewrites the manifests with the resolved digests.

Self-Hosting & Configuration

• Set KO_DOCKER_REPO to your target registry (e.g., ghcr.io/org or my-registry.com/project)
• Configure base images and build settings in .ko.yaml at the project root
• Use --platform linux/amd64,linux/arm64 for multi-architecture builds
• Integrate with GitHub Actions using the official ko-build/setup-ko action
• Use ko build --local to load images directly into a local Docker daemon or kind cluster

Key Features

• No Docker daemon required — builds images entirely in user space
• Produces images with only the Go binary on a distroless base (typically under 20MB)
• SBOM generation built in for supply-chain security compliance
• Reproducible builds with content-addressable image digests
• Fast incremental builds leveraging Go module caching

Comparison with Similar Tools

• Docker — general purpose but requires a daemon and produces larger images
• Buildpacks — auto-detect language but slower and less predictable for Go
• Kaniko — builds Dockerfiles in Kubernetes but still requires a Dockerfile
• Jib — similar concept for Java but does not support Go

FAQ

Q: Does ko work with non-Go projects? A: No, ko is specifically designed for Go. For other languages, consider Docker or Buildpacks.

Q: Can I use a custom base image instead of distroless? A: Yes, set the defaultBaseImage in .ko.yaml or use --base-image on the command line.

Q: Does ko support private registries with authentication? A: Yes, ko uses your Docker config credentials or cloud provider helpers for registry authentication.

Q: How does ko compare to Docker build speed? A: ko is typically faster because it skips the Docker daemon overhead and builds only the Go binary layer incrementally.

Sources

• https://github.com/ko-build/ko
• https://ko.build