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.
ko makes building Go container images easy, fast, and secure by default.
ko is a simple, fast container image builder for Go applications.
It's ideal for use cases where your image contains a single Go application without many dependencies on the OS base image (e.g., no cgo, no OS package dependencies).
+ko builds images by executing go build on your local machine, and as such doesn't require docker to be installed.
+This can make it a good fit for lightweight CI/CD use cases.
ko makes multi-platform builds easy, produces SBOMs by default, and includes support for simple YAML templating which makes it a powerful tool for Kubernetes applications.
++🏃 Install
+koand get started!
ko is used and loved by these open source projects:
ko is a Cloud Native Computing Foundation Sandbox project.
$ VERSION=TODO # choose the latest version (without v prefix)
+$ OS=Linux # or Darwin
+$ ARCH=x86_64 # or arm64, i386, s390x
+We generate SLSA3 provenance using the OpenSSF's slsa-framework/slsa-github-generator. To verify our release, install the verification tool from slsa-framework/slsa-verifier#installation and verify as follows:
+$ curl -sSfL "https://github.com/ko-build/ko/releases/download/v${VERSION}/ko_${VERSION}_${OS}_${ARCH}.tar.gz" > ko.tar.gz
+$ curl -sSfL https://github.com/ko-build/ko/releases/download/v${VERSION}/attestation.intoto.jsonl > provenance.intoto.jsonl
+$ slsa-verifier -artifact-path ko.tar.gz -provenance provenance.intoto.jsonl -source github.com/google/ko -tag "v${VERSION}"
+ PASSED: Verified SLSA provenance
+$ tar xzf ko.tar.gz ko
+$ chmod +x ./ko
+brew install ko
+Installation on Alpine requires using the testing repository
echo https://dl-cdn.alpinelinux.org/alpine/edge/testing/ >> /etc/apk/repositories
+apk update
+apk add ko
+With Go 1.16+, build and install the latest released version:
+go install github.com/google/ko@latest
+You can use the setup-ko action to install ko and setup auth to GitHub Container Registry in a GitHub Action workflow:
+steps:
+- uses: imjasonh/setup-ko@v0.6
+Rapidly iterate with Go, Containers, and Kubernetes.
+ko [flags]
+ -h, --help help for ko
+ -v, --verbose Enable debug logs
+kubectl run that containerizes IMPORTPATH first.Apply the input files with image references resolved to built/pushed image digests.
+This sub-command finds import path references within the provided files, builds them into Go binaries, containerizes them, publishes them, and then feeds the resulting yaml into "kubectl apply".
+ko apply -f FILENAME [flags]
+
+ # Build and publish import path references to a Docker
+ # Registry as:
+ # ${KO_DOCKER_REPO}/<package name>-<hash of import path>
+ # Then, feed the resulting yaml into "kubectl apply".
+ # When KO_DOCKER_REPO is ko.local, it is the same as if
+ # --local was passed.
+ ko apply -f config/
+
+ # Build and publish import path references to a Docker
+ # Registry preserving import path names as:
+ # ${KO_DOCKER_REPO}/<import path>
+ # Then, feed the resulting yaml into "kubectl apply".
+ ko apply --preserve-import-paths -f config/
+
+ # Build and publish import path references to a Docker
+ # daemon as:
+ # ko.local/<import path>
+ # Then, feed the resulting yaml into "kubectl apply".
+ ko apply --local -f config/
+
+ # Apply from stdin:
+ cat config.yaml | ko apply -f -
+
+ # Any flags passed after '--' are passed to 'kubectl apply' directly:
+ ko apply -f config -- --namespace=foo --kubeconfig=cfg.yaml
+
+ --bare Whether to just use KO_DOCKER_REPO without additional context (may not work properly with --tags).
+ -B, --base-import-paths Whether to use the base path without MD5 hash after KO_DOCKER_REPO (may not work properly with --tags).
+ --disable-optimizations Disable optimizations when building Go code. Useful when you want to interactively debug the created container.
+ -f, --filename strings Filename, directory, or URL to files to use to create the resource
+ -h, --help help for apply
+ --image-label strings Which labels (key=value) to add to the image.
+ --image-refs string Path to file where a list of the published image references will be written.
+ --insecure-registry Whether to skip TLS verification on the registry
+ -j, --jobs int The maximum number of concurrent builds (default GOMAXPROCS)
+ -L, --local Load into images to local docker daemon.
+ --oci-layout-path string Path to save the OCI image layout of the built images
+ --platform strings Which platform to use when pulling a multi-platform base. Format: all | <os>[/<arch>[/<variant>]][,platform]*
+ -P, --preserve-import-paths Whether to preserve the full import path after KO_DOCKER_REPO.
+ --push Push images to KO_DOCKER_REPO (default true)
+ -R, --recursive Process the directory used in -f, --filename recursively. Useful when you want to manage related manifests organized within the same directory.
+ --sbom string The SBOM media type to use (none will disable SBOM synthesis and upload, also supports: spdx, cyclonedx, go.version-m). (default "spdx")
+ --sbom-dir string Path to file where the SBOM will be written.
+ -l, --selector string Selector (label query) to filter on, supports '=', '==', and '!='.(e.g. -l key1=value1,key2=value2)
+ --tag-only Include tags but not digests in resolved image references. Useful when digests are not preserved when images are repopulated.
+ -t, --tags strings Which tags to use for the produced image instead of the default 'latest' tag (may not work properly with --base-import-paths or --bare). (default [latest])
+ --tarball string File to save images tarballs
+ -v, --verbose Enable debug logs
+Build and publish container images from the given importpaths.
+This sub-command builds the provided import paths into Go binaries, containerizes them, and publishes them.
+ko build IMPORTPATH... [flags]
+
+ # Build and publish import path references to a Docker Registry as:
+ # ${KO_DOCKER_REPO}/<package name>-<hash of import path>
+ # When KO_DOCKER_REPO is ko.local, it is the same as if --local and
+ # --preserve-import-paths were passed.
+ # If the import path is not provided, the current working directory is the
+ # default.
+ ko build github.com/foo/bar/cmd/baz github.com/foo/bar/cmd/blah
+
+ # Build and publish a relative import path as:
+ # ${KO_DOCKER_REPO}/<package name>-<hash of import path>
+ # When KO_DOCKER_REPO is ko.local, it is the same as if --local and
+ # --preserve-import-paths were passed.
+ ko build ./cmd/blah
+
+ # Build and publish a relative import path as:
+ # ${KO_DOCKER_REPO}/<import path>
+ # When KO_DOCKER_REPO is ko.local, it is the same as if --local was passed.
+ ko build --preserve-import-paths ./cmd/blah
+
+ # Build and publish import path references to a Docker daemon as:
+ # ko.local/<import path>
+ # This always preserves import paths.
+ ko build --local github.com/foo/bar/cmd/baz github.com/foo/bar/cmd/blah
+ --bare Whether to just use KO_DOCKER_REPO without additional context (may not work properly with --tags).
+ -B, --base-import-paths Whether to use the base path without MD5 hash after KO_DOCKER_REPO (may not work properly with --tags).
+ --disable-optimizations Disable optimizations when building Go code. Useful when you want to interactively debug the created container.
+ -h, --help help for build
+ --image-label strings Which labels (key=value) to add to the image.
+ --image-refs string Path to file where a list of the published image references will be written.
+ --insecure-registry Whether to skip TLS verification on the registry
+ -j, --jobs int The maximum number of concurrent builds (default GOMAXPROCS)
+ -L, --local Load into images to local docker daemon.
+ --oci-layout-path string Path to save the OCI image layout of the built images
+ --platform strings Which platform to use when pulling a multi-platform base. Format: all | <os>[/<arch>[/<variant>]][,platform]*
+ -P, --preserve-import-paths Whether to preserve the full import path after KO_DOCKER_REPO.
+ --push Push images to KO_DOCKER_REPO (default true)
+ --sbom string The SBOM media type to use (none will disable SBOM synthesis and upload, also supports: spdx, cyclonedx, go.version-m). (default "spdx")
+ --sbom-dir string Path to file where the SBOM will be written.
+ --tag-only Include tags but not digests in resolved image references. Useful when digests are not preserved when images are repopulated.
+ -t, --tags strings Which tags to use for the produced image instead of the default 'latest' tag (may not work properly with --base-import-paths or --bare). (default [latest])
+ --tarball string File to save images tarballs
+ -v, --verbose Enable debug logs
+Create the input files with image references resolved to built/pushed image digests.
+This sub-command finds import path references within the provided files, builds them into Go binaries, containerizes them, publishes them, and then feeds the resulting yaml into "kubectl create".
+ko create -f FILENAME [flags]
+
+ # Build and publish import path references to a Docker
+ # Registry as:
+ # ${KO_DOCKER_REPO}/<package name>-<hash of import path>
+ # Then, feed the resulting yaml into "kubectl create".
+ # When KO_DOCKER_REPO is ko.local, it is the same as if
+ # --local was passed.
+ ko create -f config/
+
+ # Build and publish import path references to a Docker
+ # Registry preserving import path names as:
+ # ${KO_DOCKER_REPO}/<import path>
+ # Then, feed the resulting yaml into "kubectl create".
+ ko create --preserve-import-paths -f config/
+
+ # Build and publish import path references to a Docker
+ # daemon as:
+ # ko.local/<import path>
+ # Then, feed the resulting yaml into "kubectl create".
+ ko create --local -f config/
+
+ # Create from stdin:
+ cat config.yaml | ko create -f -
+
+ # Any flags passed after '--' are passed to 'kubectl apply' directly:
+ ko apply -f config -- --namespace=foo --kubeconfig=cfg.yaml
+
+ --bare Whether to just use KO_DOCKER_REPO without additional context (may not work properly with --tags).
+ -B, --base-import-paths Whether to use the base path without MD5 hash after KO_DOCKER_REPO (may not work properly with --tags).
+ --disable-optimizations Disable optimizations when building Go code. Useful when you want to interactively debug the created container.
+ -f, --filename strings Filename, directory, or URL to files to use to create the resource
+ -h, --help help for create
+ --image-label strings Which labels (key=value) to add to the image.
+ --image-refs string Path to file where a list of the published image references will be written.
+ --insecure-registry Whether to skip TLS verification on the registry
+ -j, --jobs int The maximum number of concurrent builds (default GOMAXPROCS)
+ -L, --local Load into images to local docker daemon.
+ --oci-layout-path string Path to save the OCI image layout of the built images
+ --platform strings Which platform to use when pulling a multi-platform base. Format: all | <os>[/<arch>[/<variant>]][,platform]*
+ -P, --preserve-import-paths Whether to preserve the full import path after KO_DOCKER_REPO.
+ --push Push images to KO_DOCKER_REPO (default true)
+ -R, --recursive Process the directory used in -f, --filename recursively. Useful when you want to manage related manifests organized within the same directory.
+ --sbom string The SBOM media type to use (none will disable SBOM synthesis and upload, also supports: spdx, cyclonedx, go.version-m). (default "spdx")
+ --sbom-dir string Path to file where the SBOM will be written.
+ -l, --selector string Selector (label query) to filter on, supports '=', '==', and '!='.(e.g. -l key1=value1,key2=value2)
+ --tag-only Include tags but not digests in resolved image references. Useful when digests are not preserved when images are repopulated.
+ -t, --tags strings Which tags to use for the produced image instead of the default 'latest' tag (may not work properly with --base-import-paths or --bare). (default [latest])
+ --tarball string File to save images tarballs
+ -v, --verbose Enable debug logs
+See "kubectl help delete" for detailed usage.
+ko delete [flags]
+ -h, --help help for delete
+ -v, --verbose Enable debug logs
+Log in to a registry
+ko login [OPTIONS] [SERVER] [flags]
+ # Log in to reg.example.com
+ ko login reg.example.com -u AzureDiamond -p hunter2
+ -h, --help help for login
+ -p, --password string Password
+ --password-stdin Take the password from stdin
+ -u, --username string Username
+ -v, --verbose Enable debug logs
+Print the input files with image references resolved to built/pushed image digests.
+This sub-command finds import path references within the provided files, builds them into Go binaries, containerizes them, publishes them, and prints the resulting yaml.
+ko resolve -f FILENAME [flags]
+
+ # Build and publish import path references to a Docker
+ # Registry as:
+ # ${KO_DOCKER_REPO}/<package name>-<hash of import path>
+ # When KO_DOCKER_REPO is ko.local, it is the same as if
+ # --local and --preserve-import-paths were passed.
+ ko resolve -f config/
+
+ # Build and publish import path references to a Docker
+ # Registry preserving import path names as:
+ # ${KO_DOCKER_REPO}/<import path>
+ # When KO_DOCKER_REPO is ko.local, it is the same as if
+ # --local was passed.
+ ko resolve --preserve-import-paths -f config/
+
+ # Build and publish import path references to a Docker
+ # daemon as:
+ # ko.local/<import path>
+ # This always preserves import paths.
+ ko resolve --local -f config/
+ --bare Whether to just use KO_DOCKER_REPO without additional context (may not work properly with --tags).
+ -B, --base-import-paths Whether to use the base path without MD5 hash after KO_DOCKER_REPO (may not work properly with --tags).
+ --disable-optimizations Disable optimizations when building Go code. Useful when you want to interactively debug the created container.
+ -f, --filename strings Filename, directory, or URL to files to use to create the resource
+ -h, --help help for resolve
+ --image-label strings Which labels (key=value) to add to the image.
+ --image-refs string Path to file where a list of the published image references will be written.
+ --insecure-registry Whether to skip TLS verification on the registry
+ -j, --jobs int The maximum number of concurrent builds (default GOMAXPROCS)
+ -L, --local Load into images to local docker daemon.
+ --oci-layout-path string Path to save the OCI image layout of the built images
+ --platform strings Which platform to use when pulling a multi-platform base. Format: all | <os>[/<arch>[/<variant>]][,platform]*
+ -P, --preserve-import-paths Whether to preserve the full import path after KO_DOCKER_REPO.
+ --push Push images to KO_DOCKER_REPO (default true)
+ -R, --recursive Process the directory used in -f, --filename recursively. Useful when you want to manage related manifests organized within the same directory.
+ --sbom string The SBOM media type to use (none will disable SBOM synthesis and upload, also supports: spdx, cyclonedx, go.version-m). (default "spdx")
+ --sbom-dir string Path to file where the SBOM will be written.
+ -l, --selector string Selector (label query) to filter on, supports '=', '==', and '!='.(e.g. -l key1=value1,key2=value2)
+ --tag-only Include tags but not digests in resolved image references. Useful when digests are not preserved when images are repopulated.
+ -t, --tags strings Which tags to use for the produced image instead of the default 'latest' tag (may not work properly with --base-import-paths or --bare). (default [latest])
+ --tarball string File to save images tarballs
+ -v, --verbose Enable debug logs
+A variant of kubectl run that containerizes IMPORTPATH first.
This sub-command combines "ko build" and "kubectl run" to support containerizing and running Go binaries on Kubernetes in a single command.
+ko run IMPORTPATH [flags]
+
+ # Publish the image and run it on Kubernetes as:
+ # ${KO_DOCKER_REPO}/<package name>-<hash of import path>
+ # When KO_DOCKER_REPO is ko.local, it is the same as if
+ # --local and --preserve-import-paths were passed.
+ ko run github.com/foo/bar/cmd/baz
+
+ # This supports relative import paths as well.
+ ko run ./cmd/baz
+
+ # You can also supply args and flags to the command.
+ ko run ./cmd/baz -- -v arg1 arg2 --yes
+ --bare Whether to just use KO_DOCKER_REPO without additional context (may not work properly with --tags).
+ -B, --base-import-paths Whether to use the base path without MD5 hash after KO_DOCKER_REPO (may not work properly with --tags).
+ --disable-optimizations Disable optimizations when building Go code. Useful when you want to interactively debug the created container.
+ -h, --help help for run
+ --image-label strings Which labels (key=value) to add to the image.
+ --image-refs string Path to file where a list of the published image references will be written.
+ --insecure-registry Whether to skip TLS verification on the registry
+ -j, --jobs int The maximum number of concurrent builds (default GOMAXPROCS)
+ -L, --local Load into images to local docker daemon.
+ --oci-layout-path string Path to save the OCI image layout of the built images
+ --platform strings Which platform to use when pulling a multi-platform base. Format: all | <os>[/<arch>[/<variant>]][,platform]*
+ -P, --preserve-import-paths Whether to preserve the full import path after KO_DOCKER_REPO.
+ --push Push images to KO_DOCKER_REPO (default true)
+ --sbom string The SBOM media type to use (none will disable SBOM synthesis and upload, also supports: spdx, cyclonedx, go.version-m). (default "spdx")
+ --sbom-dir string Path to file where the SBOM will be written.
+ --tag-only Include tags but not digests in resolved image references. Useful when digests are not preserved when images are repopulated.
+ -t, --tags strings Which tags to use for the produced image instead of the default 'latest' tag (may not work properly with --base-import-paths or --bare). (default [latest])
+ --tarball string File to save images tarballs
+ -v, --verbose Enable debug logs
+Print ko version.
+ko version [flags]
+ -h, --help help for version
+ -v, --verbose Enable debug logs
+ko makes building Go container images easy, fast, and secure by default.
ko is a simple, fast container image builder for Go applications.
It's ideal for use cases where your image contains a single Go application without many dependencies on the OS base image (e.g., no cgo, no OS package dependencies).
ko builds images by executing go build on your local machine, and as such doesn't require docker to be installed. This can make it a good fit for lightweight CI/CD use cases.
ko makes multi-platform builds easy, produces SBOMs by default, and includes support for simple YAML templating which makes it a powerful tool for Kubernetes applications.
\ud83c\udfc3 Install ko and get started!
ko is used and loved by these open source projects:
Add your project here!
ko is a Cloud Native Computing Foundation Sandbox project.
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.
"},{"location":"community/#slack","title":"Slack","text":"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\nYou 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 .\nbaseImageOverrides:\n github.com/my-user/my-repo/cmd/app: registry.example.com/base/for/app\n github.com/my-user/my-repo/cmd/foo: registry.example.com/base/for/foo\nBy 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:\n- id: foo\n dir: . # default is .\n main: ./foobar/foo\n env:\n - GOPRIVATE=git.internal.example.com,source.developers.google.com\n flags:\n - -tags\n - netgo\n ldflags:\n - -s -w\n - -extldflags \"-static\"\n - -X main.version={{.Env.VERSION}}\n- id: bar\n dir: ./bar\n main: . # default is .\n env:\n - GOCACHE=/workspace/.gocache\n ldflags:\n - -s\n - -w\nIf 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 [].
\ud83d\udca1 Note: Even though the configuration section is similar to the GoReleaser builds section, only the env, flags and ldflags fields 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:\n- linux/arm64\n- linux/amd64\nYou can also use the KO_DEFAULTPLATFORMS environment variable to set the default platforms, which overrides the YAML configuration:
KO_DEFAULTPLATFORMS=linux/arm64,linux/amd64\nFor ease of use, backward compatibility and advanced use cases, ko supports the following environment variables to influence the build process.
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)."},{"location":"configuration/#naming-images","title":"Naming Images","text":"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\nko 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 run","text":"To run the container locally:
docker run -p 8080:8080 $(ko build ./cmd/app)\ngcloud run deploy --image=$(ko build ./cmd/app)\n\ud83d\udca1 Note: The image must be pushed to Google Container Registry or Artifact Registry.
"},{"location":"deployment/#flyio","title":"fly.io","text":"flyctl launch --image=$(ko build ./cmd/app)\n\ud83d\udca1 Note: The image must be publicly available.
"},{"location":"deployment/#aws-lambda","title":"AWS Lambda","text":"aws lambda update-function-code \\\n --function-name=my-function-name \\\n --image-uri=$(ko build ./cmd/app)\n\ud83d\udca1 Note: The image must be pushed to ECR, based on the AWS provided base image, and use the aws-lambda-go framework. See official docs for more information.
az containerapp update \\\n --name my-container-app\n --resource-group my-resource-group\n --image $(ko build ./cmd/app)\n\ud83d\udca1 Note: The image must be pushed to ACR or other registry service. See official docs for more information.
"},{"location":"get-started/","title":"Get Started","text":""},{"location":"get-started/#setup","title":"Setup","text":"First, install ko.
ko depends on the authentication configured in your Docker config (typically ~/.docker/config.json).
\u2728 If you can push an image with docker push, you are already authenticated for ko! \u2728
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\n...\nregistry.example.com/my-project/app-099ba5bcefdead87f92606265fb99ac0@sha256:6e398316742b7aa4a93161dce4a23bc5c545700b862b43347b941000b112ec3e\n\ud83d\udca1 Note: Prior to v0.10, the command was called ko publish -- this is equivalent to ko 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.
$ VERSION=TODO # choose the latest version (without v prefix)\n$ OS=Linux # or Darwin\n$ ARCH=x86_64 # or arm64, i386, s390x\nWe generate SLSA3 provenance using the OpenSSF's slsa-framework/slsa-github-generator. To verify our release, install the verification tool from slsa-framework/slsa-verifier#installation and verify as follows:
$ curl -sSfL \"https://github.com/ko-build/ko/releases/download/v${VERSION}/ko_${VERSION}_${OS}_${ARCH}.tar.gz\" > ko.tar.gz\n$ curl -sSfL https://github.com/ko-build/ko/releases/download/v${VERSION}/attestation.intoto.jsonl > provenance.intoto.jsonl\n$ slsa-verifier -artifact-path ko.tar.gz -provenance provenance.intoto.jsonl -source github.com/google/ko -tag \"v${VERSION}\"\n PASSED: Verified SLSA provenance\n$ tar xzf ko.tar.gz ko\n$ chmod +x ./ko\nbrew install ko\nInstallation on Alpine requires using the testing repository
echo https://dl-cdn.alpinelinux.org/alpine/edge/testing/ >> /etc/apk/repositories\napk update\napk add ko\nWith Go 1.16+, build and install the latest released version:
go install github.com/google/ko@latest\nYou can use the setup-ko action to install ko and setup auth to GitHub Container Registry in a GitHub Action workflow:
steps:\n- uses: imjasonh/setup-ko@v0.6\nldflags?","text":"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 .\nCurrently, 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)\nor 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')\nYes, but support for Windows containers is new, experimental, and tenuous. Be prepared to file bugs. \ud83d\udc1b
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\nAnd build for windows/amd64.
ko build ./ --platform=windows/amd64\nkodata are ignored when building Windows images; only regular files and directories will be included in the Windows image.ko support autocompletion?","text":"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\nOr, you can source it directly:
source <(ko completion)\nko work with Kustomize?","text":"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 -\nko integrate with other build and development tools?","text":"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?","text":"Yes! Follow these steps:
$HOME/.docker/config.json:oc registry login --to=$HOME/.docker/config.json\nko-imagesKO_DOCKER_REPO to publish images to the internal registry.export KO_DOCKER_REPO=$(oc registry info --public)/ko-images\nko'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\n\n##\n## Build\n##\nFROM golang:1.16-buster AS build\n\nWORKDIR /app\n\nCOPY go.mod ./\nCOPY go.sum ./\nRUN go mod download\n\nCOPY *.go ./\n\nRUN go build -o /docker-gs-ping\n\n##\n## Deploy\n##\nFROM gcr.io/distroless/base-debian10\n\nWORKDIR /\n\nCOPY --from=build /docker-gs-ping /docker-gs-ping\n\nEXPOSE 8080\n\nUSER nonroot:nonroot\n\nENTRYPOINT [\"/docker-gs-ping\"]\nThis 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.
ko","text":"If your\u00a0Go 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.
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\nkind: Deployment\nmetadata:\n name: my-deployment\nspec:\n replicas: 3\n ...\n template:\n spec:\n containers:\n - name: my-app\n image: registry.example.com/my-app:v1.2.3\n...which you apply to your cluster with kubectl apply:
kubectl apply -f deployment.yaml\nWith ko, you can instead reference your Go binary by its importpath, prefixed with ko://:
...\n spec:\n containers:\n - name: my-app\n image: ko://github.com/my-user/my-repo/cmd/app\nko resolve","text":"With 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\nTaken 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 apply","text":"To apply the resulting resolved YAML config, you can redirect the output of ko resolve to kubectl apply:
ko resolve -f config/ | kubectl apply -f -\nSince this is a relatively common use case, the same functionality is available using ko apply:
ko apply -f config/\nAlso, 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\nNB: This requires that kubectl is available.
ko delete","text":"To teardown resources applied using ko apply, you can run ko delete:
ko delete -f config/\nThis 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/\n app/\n main.go\n kodata/\n favicon.ico\n index.html\nThen, in your main.go:
func main() {\n http.Handle(\"/\", http.FileServer(http.Dir(os.Getenv(\"KO_DATA_PATH\"))))\n log.Fatal(http.ListenAndServe(\":8080\", nil))\n}\nYou 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.
\ud83d\udca1 Tip: Symlinks in kodata are followed and included as well. For example, you can include Git commit information in your image with ln -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).
Rapidly iterate with Go, Containers, and Kubernetes.
ko [flags]\n -h, --help help for ko\n -v, --verbose Enable debug logs\nkubectl run that containerizes IMPORTPATH first.Apply the input files with image references resolved to built/pushed image digests.
"},{"location":"reference/ko_apply/#synopsis","title":"Synopsis","text":"This sub-command finds import path references within the provided files, builds them into Go binaries, containerizes them, publishes them, and then feeds the resulting yaml into \"kubectl apply\".
ko apply -f FILENAME [flags]\n\n # Build and publish import path references to a Docker\n # Registry as:\n # ${KO_DOCKER_REPO}/<package name>-<hash of import path>\n # Then, feed the resulting yaml into \"kubectl apply\".\n # When KO_DOCKER_REPO is ko.local, it is the same as if\n # --local was passed.\n ko apply -f config/\n\n # Build and publish import path references to a Docker\n # Registry preserving import path names as:\n # ${KO_DOCKER_REPO}/<import path>\n # Then, feed the resulting yaml into \"kubectl apply\".\n ko apply --preserve-import-paths -f config/\n\n # Build and publish import path references to a Docker\n # daemon as:\n # ko.local/<import path>\n # Then, feed the resulting yaml into \"kubectl apply\".\n ko apply --local -f config/\n\n # Apply from stdin:\n cat config.yaml | ko apply -f -\n\n # Any flags passed after '--' are passed to 'kubectl apply' directly:\n ko apply -f config -- --namespace=foo --kubeconfig=cfg.yaml\n\n --bare Whether to just use KO_DOCKER_REPO without additional context (may not work properly with --tags).\n -B, --base-import-paths Whether to use the base path without MD5 hash after KO_DOCKER_REPO (may not work properly with --tags).\n --disable-optimizations Disable optimizations when building Go code. Useful when you want to interactively debug the created container.\n -f, --filename strings Filename, directory, or URL to files to use to create the resource\n -h, --help help for apply\n --image-label strings Which labels (key=value) to add to the image.\n --image-refs string Path to file where a list of the published image references will be written.\n --insecure-registry Whether to skip TLS verification on the registry\n -j, --jobs int The maximum number of concurrent builds (default GOMAXPROCS)\n -L, --local Load into images to local docker daemon.\n --oci-layout-path string Path to save the OCI image layout of the built images\n --platform strings Which platform to use when pulling a multi-platform base. Format: all | <os>[/<arch>[/<variant>]][,platform]*\n -P, --preserve-import-paths Whether to preserve the full import path after KO_DOCKER_REPO.\n --push Push images to KO_DOCKER_REPO (default true)\n -R, --recursive Process the directory used in -f, --filename recursively. Useful when you want to manage related manifests organized within the same directory.\n --sbom string The SBOM media type to use (none will disable SBOM synthesis and upload, also supports: spdx, cyclonedx, go.version-m). (default \"spdx\")\n --sbom-dir string Path to file where the SBOM will be written.\n -l, --selector string Selector (label query) to filter on, supports '=', '==', and '!='.(e.g. -l key1=value1,key2=value2)\n --tag-only Include tags but not digests in resolved image references. Useful when digests are not preserved when images are repopulated.\n -t, --tags strings Which tags to use for the produced image instead of the default 'latest' tag (may not work properly with --base-import-paths or --bare). (default [latest])\n --tarball string File to save images tarballs\n -v, --verbose Enable debug logs\nBuild and publish container images from the given importpaths.
"},{"location":"reference/ko_build/#synopsis","title":"Synopsis","text":"This sub-command builds the provided import paths into Go binaries, containerizes them, and publishes them.
ko build IMPORTPATH... [flags]\n\n # Build and publish import path references to a Docker Registry as:\n # ${KO_DOCKER_REPO}/<package name>-<hash of import path>\n # When KO_DOCKER_REPO is ko.local, it is the same as if --local and\n # --preserve-import-paths were passed.\n # If the import path is not provided, the current working directory is the\n # default.\n ko build github.com/foo/bar/cmd/baz github.com/foo/bar/cmd/blah\n\n # Build and publish a relative import path as:\n # ${KO_DOCKER_REPO}/<package name>-<hash of import path>\n # When KO_DOCKER_REPO is ko.local, it is the same as if --local and\n # --preserve-import-paths were passed.\n ko build ./cmd/blah\n\n # Build and publish a relative import path as:\n # ${KO_DOCKER_REPO}/<import path>\n # When KO_DOCKER_REPO is ko.local, it is the same as if --local was passed.\n ko build --preserve-import-paths ./cmd/blah\n\n # Build and publish import path references to a Docker daemon as:\n # ko.local/<import path>\n # This always preserves import paths.\n ko build --local github.com/foo/bar/cmd/baz github.com/foo/bar/cmd/blah\n --bare Whether to just use KO_DOCKER_REPO without additional context (may not work properly with --tags).\n -B, --base-import-paths Whether to use the base path without MD5 hash after KO_DOCKER_REPO (may not work properly with --tags).\n --disable-optimizations Disable optimizations when building Go code. Useful when you want to interactively debug the created container.\n -h, --help help for build\n --image-label strings Which labels (key=value) to add to the image.\n --image-refs string Path to file where a list of the published image references will be written.\n --insecure-registry Whether to skip TLS verification on the registry\n -j, --jobs int The maximum number of concurrent builds (default GOMAXPROCS)\n -L, --local Load into images to local docker daemon.\n --oci-layout-path string Path to save the OCI image layout of the built images\n --platform strings Which platform to use when pulling a multi-platform base. Format: all | <os>[/<arch>[/<variant>]][,platform]*\n -P, --preserve-import-paths Whether to preserve the full import path after KO_DOCKER_REPO.\n --push Push images to KO_DOCKER_REPO (default true)\n --sbom string The SBOM media type to use (none will disable SBOM synthesis and upload, also supports: spdx, cyclonedx, go.version-m). (default \"spdx\")\n --sbom-dir string Path to file where the SBOM will be written.\n --tag-only Include tags but not digests in resolved image references. Useful when digests are not preserved when images are repopulated.\n -t, --tags strings Which tags to use for the produced image instead of the default 'latest' tag (may not work properly with --base-import-paths or --bare). (default [latest])\n --tarball string File to save images tarballs\n -v, --verbose Enable debug logs\nCreate the input files with image references resolved to built/pushed image digests.
"},{"location":"reference/ko_create/#synopsis","title":"Synopsis","text":"This sub-command finds import path references within the provided files, builds them into Go binaries, containerizes them, publishes them, and then feeds the resulting yaml into \"kubectl create\".
ko create -f FILENAME [flags]\n\n # Build and publish import path references to a Docker\n # Registry as:\n # ${KO_DOCKER_REPO}/<package name>-<hash of import path>\n # Then, feed the resulting yaml into \"kubectl create\".\n # When KO_DOCKER_REPO is ko.local, it is the same as if\n # --local was passed.\n ko create -f config/\n\n # Build and publish import path references to a Docker\n # Registry preserving import path names as:\n # ${KO_DOCKER_REPO}/<import path>\n # Then, feed the resulting yaml into \"kubectl create\".\n ko create --preserve-import-paths -f config/\n\n # Build and publish import path references to a Docker\n # daemon as:\n # ko.local/<import path>\n # Then, feed the resulting yaml into \"kubectl create\".\n ko create --local -f config/\n\n # Create from stdin:\n cat config.yaml | ko create -f -\n\n # Any flags passed after '--' are passed to 'kubectl apply' directly:\n ko apply -f config -- --namespace=foo --kubeconfig=cfg.yaml\n\n --bare Whether to just use KO_DOCKER_REPO without additional context (may not work properly with --tags).\n -B, --base-import-paths Whether to use the base path without MD5 hash after KO_DOCKER_REPO (may not work properly with --tags).\n --disable-optimizations Disable optimizations when building Go code. Useful when you want to interactively debug the created container.\n -f, --filename strings Filename, directory, or URL to files to use to create the resource\n -h, --help help for create\n --image-label strings Which labels (key=value) to add to the image.\n --image-refs string Path to file where a list of the published image references will be written.\n --insecure-registry Whether to skip TLS verification on the registry\n -j, --jobs int The maximum number of concurrent builds (default GOMAXPROCS)\n -L, --local Load into images to local docker daemon.\n --oci-layout-path string Path to save the OCI image layout of the built images\n --platform strings Which platform to use when pulling a multi-platform base. Format: all | <os>[/<arch>[/<variant>]][,platform]*\n -P, --preserve-import-paths Whether to preserve the full import path after KO_DOCKER_REPO.\n --push Push images to KO_DOCKER_REPO (default true)\n -R, --recursive Process the directory used in -f, --filename recursively. Useful when you want to manage related manifests organized within the same directory.\n --sbom string The SBOM media type to use (none will disable SBOM synthesis and upload, also supports: spdx, cyclonedx, go.version-m). (default \"spdx\")\n --sbom-dir string Path to file where the SBOM will be written.\n -l, --selector string Selector (label query) to filter on, supports '=', '==', and '!='.(e.g. -l key1=value1,key2=value2)\n --tag-only Include tags but not digests in resolved image references. Useful when digests are not preserved when images are repopulated.\n -t, --tags strings Which tags to use for the produced image instead of the default 'latest' tag (may not work properly with --base-import-paths or --bare). (default [latest])\n --tarball string File to save images tarballs\n -v, --verbose Enable debug logs\nSee \"kubectl help delete\" for detailed usage.
ko delete [flags]\n -h, --help help for delete\n -v, --verbose Enable debug logs\nLog in to a registry
ko login [OPTIONS] [SERVER] [flags]\n # Log in to reg.example.com\n ko login reg.example.com -u AzureDiamond -p hunter2\n -h, --help help for login\n -p, --password string Password\n --password-stdin Take the password from stdin\n -u, --username string Username\n -v, --verbose Enable debug logs\nPrint the input files with image references resolved to built/pushed image digests.
"},{"location":"reference/ko_resolve/#synopsis","title":"Synopsis","text":"This sub-command finds import path references within the provided files, builds them into Go binaries, containerizes them, publishes them, and prints the resulting yaml.
ko resolve -f FILENAME [flags]\n\n # Build and publish import path references to a Docker\n # Registry as:\n # ${KO_DOCKER_REPO}/<package name>-<hash of import path>\n # When KO_DOCKER_REPO is ko.local, it is the same as if\n # --local and --preserve-import-paths were passed.\n ko resolve -f config/\n\n # Build and publish import path references to a Docker\n # Registry preserving import path names as:\n # ${KO_DOCKER_REPO}/<import path>\n # When KO_DOCKER_REPO is ko.local, it is the same as if\n # --local was passed.\n ko resolve --preserve-import-paths -f config/\n\n # Build and publish import path references to a Docker\n # daemon as:\n # ko.local/<import path>\n # This always preserves import paths.\n ko resolve --local -f config/\n --bare Whether to just use KO_DOCKER_REPO without additional context (may not work properly with --tags).\n -B, --base-import-paths Whether to use the base path without MD5 hash after KO_DOCKER_REPO (may not work properly with --tags).\n --disable-optimizations Disable optimizations when building Go code. Useful when you want to interactively debug the created container.\n -f, --filename strings Filename, directory, or URL to files to use to create the resource\n -h, --help help for resolve\n --image-label strings Which labels (key=value) to add to the image.\n --image-refs string Path to file where a list of the published image references will be written.\n --insecure-registry Whether to skip TLS verification on the registry\n -j, --jobs int The maximum number of concurrent builds (default GOMAXPROCS)\n -L, --local Load into images to local docker daemon.\n --oci-layout-path string Path to save the OCI image layout of the built images\n --platform strings Which platform to use when pulling a multi-platform base. Format: all | <os>[/<arch>[/<variant>]][,platform]*\n -P, --preserve-import-paths Whether to preserve the full import path after KO_DOCKER_REPO.\n --push Push images to KO_DOCKER_REPO (default true)\n -R, --recursive Process the directory used in -f, --filename recursively. Useful when you want to manage related manifests organized within the same directory.\n --sbom string The SBOM media type to use (none will disable SBOM synthesis and upload, also supports: spdx, cyclonedx, go.version-m). (default \"spdx\")\n --sbom-dir string Path to file where the SBOM will be written.\n -l, --selector string Selector (label query) to filter on, supports '=', '==', and '!='.(e.g. -l key1=value1,key2=value2)\n --tag-only Include tags but not digests in resolved image references. Useful when digests are not preserved when images are repopulated.\n -t, --tags strings Which tags to use for the produced image instead of the default 'latest' tag (may not work properly with --base-import-paths or --bare). (default [latest])\n --tarball string File to save images tarballs\n -v, --verbose Enable debug logs\nA variant of kubectl run that containerizes IMPORTPATH first.
This sub-command combines \"ko build\" and \"kubectl run\" to support containerizing and running Go binaries on Kubernetes in a single command.
ko run IMPORTPATH [flags]\n\n # Publish the image and run it on Kubernetes as:\n # ${KO_DOCKER_REPO}/<package name>-<hash of import path>\n # When KO_DOCKER_REPO is ko.local, it is the same as if\n # --local and --preserve-import-paths were passed.\n ko run github.com/foo/bar/cmd/baz\n\n # This supports relative import paths as well.\n ko run ./cmd/baz\n\n # You can also supply args and flags to the command.\n ko run ./cmd/baz -- -v arg1 arg2 --yes\n --bare Whether to just use KO_DOCKER_REPO without additional context (may not work properly with --tags).\n -B, --base-import-paths Whether to use the base path without MD5 hash after KO_DOCKER_REPO (may not work properly with --tags).\n --disable-optimizations Disable optimizations when building Go code. Useful when you want to interactively debug the created container.\n -h, --help help for run\n --image-label strings Which labels (key=value) to add to the image.\n --image-refs string Path to file where a list of the published image references will be written.\n --insecure-registry Whether to skip TLS verification on the registry\n -j, --jobs int The maximum number of concurrent builds (default GOMAXPROCS)\n -L, --local Load into images to local docker daemon.\n --oci-layout-path string Path to save the OCI image layout of the built images\n --platform strings Which platform to use when pulling a multi-platform base. Format: all | <os>[/<arch>[/<variant>]][,platform]*\n -P, --preserve-import-paths Whether to preserve the full import path after KO_DOCKER_REPO.\n --push Push images to KO_DOCKER_REPO (default true)\n --sbom string The SBOM media type to use (none will disable SBOM synthesis and upload, also supports: spdx, cyclonedx, go.version-m). (default \"spdx\")\n --sbom-dir string Path to file where the SBOM will be written.\n --tag-only Include tags but not digests in resolved image references. Useful when digests are not preserved when images are repopulated.\n -t, --tags strings Which tags to use for the produced image instead of the default 'latest' tag (may not work properly with --base-import-paths or --bare). (default [latest])\n --tarball string File to save images tarballs\n -v, --verbose Enable debug logs\nPrint ko version.
ko version [flags]\n -h, --help help for version\n -v, --verbose Enable debug logs\n