ldflags?Using -ldflags is a common way to embed version info in go binaries (In fact, we do this for ko!).
+Unfortunately, because ko wraps go build, it's not possible to use this flag directly; however, you can use the GOFLAGS environment variable instead:
GOFLAGS="-ldflags=-X=main.version=1.2.3" ko build .
+Currently, there is a limitation that does not allow to set multiple arguments in ldflags using GOFLAGS.
+Using -ldflags multiple times also does not work.
+In this use case, it works best to use the builds section in the .ko.yaml file.
In order to support reproducible builds, ko doesn't embed timestamps in the images it produces by default.
However, ko does respect the SOURCE_DATE_EPOCH environment variable, which will set the container image's timestamp accordingly.
Similarly, the KO_DATA_DATE_EPOCH environment variable can be used to set the modtime timestamp of the files in KO_DATA_PATH.
For example, you can set the container image's timestamp to the current timestamp by executing:
+export SOURCE_DATE_EPOCH=$(date +%s)
+or set the timestamp of the files in KO_DATA_PATH to the latest git commit's timestamp with:
export KO_DATA_DATE_EPOCH=$(git log -1 --format='%ct')
+Yes, but support for Windows containers is new, experimental, and tenuous. Be prepared to file bugs. 🐛
+The default base image does not provide a Windows image.
+You can try out building a Windows container image by setting the base image to a Windows base image and building with --platform=windows/amd64 or --platform=all:
For example, to build a Windows container image, update your .ko.yaml to set the base image:
defaultBaseImage: mcr.microsoft.com/windows/nanoserver:ltsc2022
+And build for windows/amd64.
ko build ./ --platform=windows/amd64
+kodata are ignored when building Windows images; only regular files and directories will be included in the Windows image.ko support autocompletion?Yes! ko completion generates a Bash/Zsh/Fish/PowerShell completion script.
+You can get how to load it from help document.
ko completion [bash|zsh|fish|powershell] --help
+Or, you can source it directly:
+source <(ko completion)
+ko work with Kustomize?Yes! ko resolve -f - will read and process input from stdin, so you can have ko easily process the output of the kustomize command.
kustomize build config | ko resolve -f -
+ko integrate with other build and development tools?Oh, you betcha. Here's a partial list:
+ko support in Skaffoldko support for goreleaserko task in the Tekton catalogko support in Carvel's kbldko extension for Tiltko work with OpenShift Internal Registry?Yes! Follow these steps:
+$HOME/.docker/config.json:oc registry login --to=$HOME/.docker/config.json
+ko-imagesKO_DOCKER_REPO to publish images to the internal registry.export KO_DOCKER_REPO=$(oc registry info --public)/ko-images
+ko's functionality can be consumed as a library in a Go application.
To build an image, use pkg/build, and publish it with pkg/publish.
ko works best when your application has no dependencies on the underlying image.
This means ko is ideal when you don't require cgo, and builds are executed with CGO_ENABLED=0 by default.
To install other OS packages, make those available in your configured base image.
+ko only supports Go applications.
+For a similar tool targeting Java applications, try Jib.
+For other languages, try apko and melange.
If your Dockerfile looks like either of the examples in the official tutorial for writing a Dockerfile to containerize a Go application, you can easily migrate to use ko instead.
Let's review the best practice multi-stage Dockerfile in that tutorial first:
+# syntax=docker/dockerfile:1
+
+##
+## Build
+##
+FROM golang:1.16-buster AS build
+
+WORKDIR /app
+
+COPY go.mod ./
+COPY go.sum ./
+RUN go mod download
+
+COPY *.go ./
+
+RUN go build -o /docker-gs-ping
+
+##
+## Deploy
+##
+FROM gcr.io/distroless/base-debian10
+
+WORKDIR /
+
+COPY --from=build /docker-gs-ping /docker-gs-ping
+
+EXPOSE 8080
+
+USER nonroot:nonroot
+
+ENTRYPOINT ["/docker-gs-ping"]
+This Dockerfile:
golang:1.16 imageCOPYs your local source into the container environment (COPYing go.mod and go.sum first and running go mod download, to cache dependencies in the container environment)RUNs go build on your source, inside the container, to produce an executableCOPYs the executable built in the previous step into a new image, on top of a minimal distroless base image.The result is a Go application built on a minimal base image, with an optimally cached build sequence.
+After running docker build on this Dockerfile, don't forget to push that image to the registry so you can deploy it.
koIf your Go source is laid out as described in the tutorial, and you've installed and set up your environment, you can simply run ko build ./ to build and push the container image to your registry.
You're done. You can delete your Dockerfile and uninstall docker.
ko takes advantage of your local Go build cache without needing to be told to, and it sets the ENTRYPOINT and uses a nonroot distroless base image by default.
To build a multi-arch image, simply add --platform=all.
+Compare this to the equivalent Docker instructions.
We have a bi-weekly community meeting on Wednesdays at 1:00 AM US Eastern time, 10:00 AM US Western time. The main goal of these meetings is that we want to hear from you! We want to know what you're using ko for, what you'd like to see in ko, how we can make ko better for you. With any remaining time we can go through open issues and PRs.
We have a meeting agenda you can use to propose topics for discussion/ideas. You can also just show up and we'll figure out what to talk about.
+Come discuss ko with us in the #ko-build channel on the Kubernetes Slack!
+See you there!
Aside from certain environment variables (see below) like KO_DOCKER_REPO, you can
+configure ko's behavior using a .ko.yaml file. The location of this file can be overridden with KO_CONFIG_PATH.
By default, ko bases images on cgr.dev/chainguard/static. This is a
+small image that provides the bare necessities to run your Go binary.
You can override this base image in two ways:
+ko builds, add this line to your
+ .ko.yaml file:defaultBaseImage: registry.example.com/base/image
+You can also use the KO_DEFAULTBASEIMAGE environment variable to set the default base image, which overrides the YAML configuration:
KO_DEFAULTBASEIMAGE=registry.example.com/base/image ko build .
+baseImageOverrides:
+ github.com/my-user/my-repo/cmd/app: registry.example.com/base/for/app
+ github.com/my-user/my-repo/cmd/foo: registry.example.com/base/for/foo
+By default, ko builds the binary with no additional build flags other than
+-trimpath. You can replace the default build
+arguments by providing build flags and ldflags using a
+GoReleaser influenced builds
+configuration section in your .ko.yaml.
builds:
+- id: foo
+ dir: . # default is .
+ main: ./foobar/foo
+ env:
+ - GOPRIVATE=git.internal.example.com,source.developers.google.com
+ flags:
+ - -tags
+ - netgo
+ ldflags:
+ - -s -w
+ - -extldflags "-static"
+ - -X main.version={{.Env.VERSION}}
+- id: bar
+ dir: ./bar
+ main: . # default is .
+ env:
+ - GOCACHE=/workspace/.gocache
+ ldflags:
+ - -s
+ - -w
+If your repository contains multiple modules (multiple go.mod files in
+different directories), use the dir field to specify the directory where
+ko should run go build.
ko picks the entry from builds based on the import path you request. The
+import path is matched against the result of joining dir and main.
The paths specified in dir and main are relative to the working directory
+of the ko process.
The ldflags default value is [].
++💡 Note: Even though the configuration section is similar to the +GoReleaser
+buildssection, +only theenv,flagsandldflagsfields are currently supported. Also, the +templating support is currently limited to using environment variables only.
By default, ko builds images based on the platform it runs on. If your target platform differs from your build platform you can specify the build platform:
As a parameter +See Multi-Platform Images.
+In .ko.yaml
+Add this to your .ko.yaml file:
defaultPlatforms:
+- linux/arm64
+- linux/amd64
+You can also use the KO_DEFAULTPLATFORMS environment variable to set the default platforms, which overrides the YAML configuration:
KO_DEFAULTPLATFORMS=linux/arm64,linux/amd64
+For ease of use, backward compatibility and advanced use cases, ko supports the following environment variables to
+influence the build process.
| Variable | +Default Value | +Description | +
|---|---|---|
KO_DOCKER_REPO |
+(not set) | +Container repository where to push images built with ko (required) |
+
KO_GO_PATH |
+go |
+go binary to use for builds, relative or absolute path, otherwise looked up via $PATH (optional) |
+
KO_CONFIG_PATH |
+./ko.yaml |
+Path to ko configuration file (optional) |
+
KOCACHE |
+(not set) | +This tells ko to store a local mapping between the go build inputs to the image layer that they produce, so go build can be skipped entirely if the layer is already present in the image registry (optional). |
+
ko provides a few different strategies for naming the image it pushes, to
+workaround certain registry limitations and user preferences:
Given KO_DOCKER_REPO=registry.example.com/repo, by default,
+ko build ./cmd/app will produce an image named like
+registry.example.com/repo/app-<md5>, which includes the MD5 hash of the full
+import path, to avoid collisions.
--preserve-import-path (-P) will include the entire importpath:
+ registry.example.com/repo/github.com/my-user/my-repo/cmd/app--base-import-paths (-B) will omit the MD5 portion:
+ registry.example.com/repo/app--bare will only include the KO_DOCKER_REPO: registry.example.com/repoko is normally used to publish images to container image registries,
+identified by KO_DOCKER_REPO.
ko can also load images to a local Docker daemon, if available, by setting
+KO_DOCKER_REPO=ko.local, or by passing the --local (-L) flag.
Local images can be used as a base image for other ko images:
defaultBaseImage: ko.local/example/base/image
+ko can also load images into a local KinD
+cluster, if available, by setting KO_DOCKER_REPO=kind.local. By default this
+loads into the default KinD cluster name (kind). To load into another KinD
+cluster, set KIND_CLUSTER_NAME=my-other-cluster.
See Kubernetes Integration for information about deploying to Kubernetes.
+Because the output of ko build is an image reference, you can easily pass it to other tools that expect to take an image reference.
docker runTo run the container locally:
+docker run -p 8080:8080 $(ko build ./cmd/app)
+gcloud run deploy --image=$(ko build ./cmd/app)
+++💡 Note: The image must be pushed to Google Container Registry or Artifact Registry.
+
flyctl launch --image=$(ko build ./cmd/app)
+++💡 Note: The image must be publicly available.
+
aws lambda update-function-code \
+ --function-name=my-function-name \
+ --image-uri=$(ko build ./cmd/app)
+++💡 Note: The image must be pushed to ECR, based on the AWS provided base image, and use the
+aws-lambda-goframework. +See official docs for more information.
az containerapp update \
+ --name my-container-app
+ --resource-group my-resource-group
+ --image $(ko build ./cmd/app)
+++ + + + + + +💡 Note: The image must be pushed to ACR or other registry service. +See official docs for more information.
+
Because ko just runs go build in your normal development environment, it automatically reuses your go build cache from previous builds, making iterative development faster.
ko also avoids pushing blobs to the remote image registry if they're already present, making pushes faster.
You can make ko even faster by setting the KOCACHE environment variable.
+This tells ko to store a local mapping between the go build inputs to the image layer that they produce, so go build can be skipped entirely if the layer is already present in the image registry.
You could stop at just building and pushing images.
+But, because building images is so easy with ko, and because building with
+ko only requires a string importpath to identify the image, we can integrate
+this with YAML generation to make Kubernetes use cases much simpler.
Traditionally, you might have a Kubernetes deployment, defined in a YAML file, +that runs an image:
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+ name: my-deployment
+spec:
+ replicas: 3
+ ...
+ template:
+ spec:
+ containers:
+ - name: my-app
+ image: registry.example.com/my-app:v1.2.3
+...which you apply to your cluster with kubectl apply:
kubectl apply -f deployment.yaml
+With ko, you can instead reference your Go binary by its importpath, prefixed
+with ko://:
...
+ spec:
+ containers:
+ - name: my-app
+ image: ko://github.com/my-user/my-repo/cmd/app
+ko resolveWith this small change, running ko resolve -f deployment.yaml will instruct
+ko to:
ko:// prefix,ko://-prefixed string, execute ko build <importpath> to
+ build and push an image,ko://-prefixed string(s) in the input YAML with the fully-specified
+ image reference of the built image(s), as above.The result can be redirected to a file, to distribute to others:
+ko resolve -f config/ > release.yaml
+Taken together, ko resolve aims to make packaging, pushing, and referencing
+container images an invisible implementation detail of your Kubernetes
+deployment, and let you focus on writing code in Go.
ko applyTo apply the resulting resolved YAML config, you can redirect the output of
+ko resolve to kubectl apply:
ko resolve -f config/ | kubectl apply -f -
+Since this is a relatively common use case, the same functionality is available
+using ko apply:
ko apply -f config/
+Also, any flags passed after -- are passed to kubectl apply directly, for example to specify context and kubeconfig:
ko apply -f config -- --context=foo --kubeconfig=cfg.yaml
+NB: This requires that kubectl is available.
ko deleteTo teardown resources applied using ko apply, you can run ko delete:
ko delete -f config/
+This is purely a convenient alias for kubectl delete, and doesn't perform any
+builds, or delete any previously built images.
Because Go supports cross-compilation to other CPU architectures and operating systems, ko excels at producing multi-platform images.
To build and push an image for all platforms supported by the configured base image, simply add --platform=all.
+This will instruct ko to look up all the supported platforms in the base image, execute GOOS=<os> GOARCH=<arch> GOARM=<variant> go build for each platform, and produce a manifest list containing an image for each platform.
You can also select specific platforms, for example, --platform=linux/amd64,linux/arm64.
ko also has experimental support for building for Windows images.
+See FAQ.
A Software Bill of Materials (SBOM) is a list of software components that a software artifact depends on. +Having a list of dependencies can be helpful in determining whether any vulnerable components were used to build the software artifact.
+From v0.9+, ko generates and uploads an SBOM for every image it produces by default.
ko will generate an SBOM in the SPDX format by default, but you can select the CycloneDX format instead with the --sbom=cyclonedx flag. To disable SBOM generation, pass --sbom=none.
These SBOMs can be downloaded using the cosign download sbom command.
ko can also bundle static assets into the images it produces.
By convention, any contents of a directory named <importpath>/kodata/ will be
+bundled into the image, and the path where it's available in the image will be
+identified by the environment variable KO_DATA_PATH.
As an example, you can bundle and serve static contents in your image:
+cmd/
+ app/
+ main.go
+ kodata/
+ favicon.ico
+ index.html
+Then, in your main.go:
func main() {
+ http.Handle("/", http.FileServer(http.Dir(os.Getenv("KO_DATA_PATH"))))
+ log.Fatal(http.ListenAndServe(":8080", nil))
+}
+You can simulate ko's behavior outside of the container image by setting the
+KO_DATA_PATH environment variable yourself with KO_DATA_PATH=cmd/app/kodata/ go run ./cmd/app.
++💡 Tip: Symlinks in
+kodataare followed and included as well. For example, +you can include Git commit information in your image withln -s -r .git/HEAD ./cmd/app/kodata/
Also note that http.FileServer will not serve the Last-Modified header
+(or validate If-Modified-Since request headers) because ko does not embed
+timestamps by default.
This can be supported by manually setting the KO_DATA_DATE_EPOCH environment
+variable during build (See FAQ).
First, install ko.
ko depends on the authentication configured in your Docker config (typically ~/.docker/config.json).
✨ If you can push an image with docker push, you are already authenticated for ko! ✨
Since ko doesn't require docker, ko login also provides a surface for logging in to a container image registry with a username and password, similar to docker login.
Additionally, even if auth is not configured in the Docker config, ko includes built-in support for authenticating to the following container registries using credentials configured in the environment:
gcloud.GITHUB_TOKEN environment variableko depends on an environment variable, KO_DOCKER_REPO, to identify where it should push images that it builds. Typically this will be a remote registry, e.g.:
KO_DOCKER_REPO=gcr.io/my-project, orKO_DOCKER_REPO=ghcr.io/my-org/my-repo, orKO_DOCKER_REPO=my-dockerhub-userko build ./cmd/app builds and pushes a container image, and prints the resulting image digest to stdout.
In this example, ./cmd/app must be a package main that defines func main().
$ ko build ./cmd/app
+...
+registry.example.com/my-project/app-099ba5bcefdead87f92606265fb99ac0@sha256:6e398316742b7aa4a93161dce4a23bc5c545700b862b43347b941000b112ec3e
+++💡 Note: Prior to v0.10, the command was called
+ko publish-- this is equivalent toko build, and both commands will work and do the same thing.
The executable binary that was built from ./cmd/app is available in the image at /ko-app/app -- the binary name matches the base import path name -- and that binary is the image's entrypoint.