Skip to content
Build and deploy Go applications on Kubernetes
Branch: master
Clone or download
Harwayne and jonjohnsonjr Add --disable-optimizations flag to make debugging easier. (#24)
* Ignore GoLand files.

* Add --disable-optimizations flag to make debugging easier.

* Fix unit test (by ignoring the new functionality).
Latest commit b0a1702 Apr 18, 2019
Type Name Latest commit message Commit time
Failed to load latest commit information.
cmd/ko Add --disable-optimizations flag to make debugging easier. (#24) Apr 18, 2019
pkg Add --disable-optimizations flag to make debugging easier. (#24) Apr 18, 2019
vendor Drop name.WeakValidation Mar 22, 2019
.gitignore Add --disable-optimizations flag to make debugging easier. (#24) Apr 18, 2019
Gopkg.lock Drop name.WeakValidation Mar 22, 2019
Gopkg.toml Initial commit Mar 14, 2019
LICENSE Initial commit Mar 14, 2019 move ko to cmd/ko from cmd/ Mar 21, 2019


ko is a tool for building and deploying Golang applications to Kubernetes.

Build Status GoDoc Go Report Card


ko can be installed via:

go get

To update your installation:

go get -u

The ko Model

ko is built around a very simple extension to Go's model for expressing dependencies using import paths.

In Go, dependencies are expressed via blocks like:

import (

Similarly (as you can see above), Go binaries can be referenced via import paths like

One of the goals of ko is to make containers invisible infrastructure. Simply replace image references in your Kubernetes yaml with the import path for your Go binary, and ko will handle containerizing and publishing that container image as needed.

For example, you might use the following in a Kubernetes Deployment resource:

apiVersion: apps/v1beta1
kind: Deployment
  name: hello-world
      foo: bar
  replicas: 1
        foo: bar
      - name: hello-world
        # This is the import path for the Go binary to build and run.
        - containerPort: 8080

Determining supported import paths

Similar to other tooling in the Go ecosystem, ko expects to execute in the context of your $GOPATH. This is used to determine what package(s) ko is expected to build.

Suppose GOPATH is ~/gopath and the current directory is ~/gopath/src/ ko will deduce the base import path to be, and any references to subpackages of this will be built, containerized and published.

For example, any of the following would be matched:



Employing this convention enables ko to have effectively zero configuration and enable very fast development iteration. For warm-image, ko is able to build, containerize, and redeploy a non-trivial Kubernetes controller app in seconds (dominated by two go builds).

$ ko apply -f config/
2018/07/19 14:56:41 Using base for
2018/07/19 14:56:42 Publishing
2018/07/19 14:56:43 mounted blob: sha256:57752e7f9593cbfb7101af994b136a369ecc8174332866622db32a264f3fbefd
2018/07/19 14:56:43 mounted blob: sha256:59df9d5b488aea2753ab7774ae41a9a3e96903f87ac699f3505960e744f36f7d
2018/07/19 14:56:43 mounted blob: sha256:739b3deec2edb17c512f507894c55c2681f9724191d820cdc01f668330724ca7
2018/07/19 14:56:44 digest: sha256:6c7b96a294cad3ce613aac23c8aca5f9dd12a894354ab276c157fb5c1c2e3326 size: 592
2018/07/19 14:56:44 Published
2018/07/19 14:56:45 Using base for
2018/07/19 14:56:46 Publishing
2018/07/19 14:56:46 mounted blob: sha256:007782ba6738188a59bf21b4d8e974f218615ee948c6357535d07e7248b2a560
2018/07/19 14:56:46 mounted blob: sha256:57752e7f9593cbfb7101af994b136a369ecc8174332866622db32a264f3fbefd
2018/07/19 14:56:46 mounted blob: sha256:7fec050f965d7fba3de4bd19739746dce5a5125331b7845bf02185ff5d4cc374
2018/07/19 14:56:47 digest: sha256:5a81029bb0cfd519c321aeeea2bc1b7dc6488b6c72003d3613442b4d5e4ed14d size: 593
2018/07/19 14:56:47 Published
namespace/warmimage-system configured configured
deployment.apps/warmimage-controller unchanged
serviceaccount/warmimage-controller unchanged configured


ko has four commands, most of which build and publish images as part of their execution. By default, ko publishes images to a Docker Registry specified via KO_DOCKER_REPO.

However, these same commands can be directed to operate locally as well via the --local or -L command (or setting KO_DOCKER_REPO=ko.local). See the minikube section for more detail.

ko publish

ko publish simply builds and publishes images for each import path passed as an argument. It prints the images' published digests after each image is published.

$ ko publish
2018/07/19 14:57:34 Using base for
2018/07/19 14:57:35 Publishing
2018/07/19 14:57:35 mounted blob: sha256:739b3deec2edb17c512f507894c55c2681f9724191d820cdc01f668330724ca7
2018/07/19 14:57:35 mounted blob: sha256:57752e7f9593cbfb7101af994b136a369ecc8174332866622db32a264f3fbefd
2018/07/19 14:57:35 mounted blob: sha256:59df9d5b488aea2753ab7774ae41a9a3e96903f87ac699f3505960e744f36f7d
2018/07/19 14:57:36 digest: sha256:6c7b96a294cad3ce613aac23c8aca5f9dd12a894354ab276c157fb5c1c2e3326 size: 592
2018/07/19 14:57:36 Published

ko publish also supports relative import paths, when in the context of a repo on GOPATH.

$ ko publish ./cmd/sleeper
2018/07/19 14:58:16 Using base for
2018/07/19 14:58:16 Publishing
2018/07/19 14:58:17 mounted blob: sha256:59df9d5b488aea2753ab7774ae41a9a3e96903f87ac699f3505960e744f36f7d
2018/07/19 14:58:17 mounted blob: sha256:739b3deec2edb17c512f507894c55c2681f9724191d820cdc01f668330724ca7
2018/07/19 14:58:17 mounted blob: sha256:57752e7f9593cbfb7101af994b136a369ecc8174332866622db32a264f3fbefd
2018/07/19 14:58:18 digest: sha256:6c7b96a294cad3ce613aac23c8aca5f9dd12a894354ab276c157fb5c1c2e3326 size: 592
2018/07/19 14:58:18 Published

ko resolve

ko resolve takes Kubernetes yaml files in the style of kubectl apply and (based on the model above) determines the set of Go import paths to build, containerize, and publish.

The output of ko resolve is the concatenated yaml with import paths replaced with published image digests. Following the example above, this would be:

# Command
export PROJECT_ID=$(gcloud config get-value core/project)
ko resolve -f deployment.yaml

# Output
apiVersion: apps/v1beta1
kind: Deployment
  name: hello-world
  replicas: 1
      - name: hello-world
        # This is the digest of the published image containing the go binary.
        - containerPort: 8080

Some Docker Registries (e.g. support multi-level repository names. For these registries, it is often useful for discoverability and provenance to preserve the full import path, for this we expose --preserve-import-paths, or -P for short.

# Command
export PROJECT_ID=$(gcloud config get-value core/project)
ko resolve -P -f deployment.yaml

# Output
apiVersion: apps/v1beta1
kind: Deployment
  name: hello-world
  replicas: 1
      - name: hello-world
        # This is the digest of the published image containing the go binary
        # at the embedded import path.
        - containerPort: 8080

It is notable that this is not the default (anymore) because certain popular registries (including Docker Hub) do not support multi-level repository names.

ko apply

ko apply is intended to parallel kubectl apply, but acts on the same resolved output as ko resolve emits. It is expected that ko apply will act as the vehicle for rapid iteration during development. As changes are made to a particular application, you can run: ko apply -f unit.yaml to rapidly rebuild, repush, and redeploy their changes.

ko apply will invoke kubectl apply under the covers, and therefore apply to whatever kubectl context is active.

ko apply --watch (EXPERIMENTAL)

The --watch flag (-W for short) does an initial apply as above, but as it does, it builds up a dependency graph of your program and starts to continuously monitor the filesystem for changes. When a file changes, it re-applies any yamls that are affected.

For example, if I edit, the tool sees that the package has changed, and perhaps both and consume that library and were referenced by config/one-deploy.yaml and config/two-deploy.yaml. The edit would effectively result in a re-application of:

ko apply -f config/one-deploy.yaml -f config/two-deploy.yaml

This flag is still experimental, and feedback is very welcome.

ko delete

ko delete simply passes through to kubectl delete. It is exposed purely out of convenience for cleaning up resources created through ko apply.

With minikube

You can use ko with minikube via a Docker Registry, but this involves publishing images only to pull them back down to your machine again. To avoid this, ko exposes --local or -L options to instead publish the images to the local machine's Docker daemon.

This would look something like:

# Use the minikube docker daemon.
eval $(minikube docker-env)

# Make sure minikube is the current kubectl context.
kubectl config use-context minikube

# Deploy to minikube w/o registry.
ko apply -L -f config/

# This is the same as above.
KO_DOCKER_REPO=ko.local ko apply -f config/

A caveat of this approach is that it will not work if your container is configured with imagePullPolicy: Always because despite having the image locally, a pull is performed to ensure we have the latest version, it still exists, and that access hasn't been revoked. A workaround for this is to use imagePullPolicy: IfNotPresent, which should work well with ko in all contexts.

Images will appear in the Docker daemon as ko.local/ With --local import paths are always preserved (see --preserve-import-paths).

Configuration via .ko.yaml

While ko aims to have zero configuration, there are certain scenarios where you will want to override ko's default behavior. This is done via .ko.yaml.

.ko.yaml is put into the directory from which ko will be invoked. One can override the directory with the KO_CONFIG_PATH environment variable.

If neither is present, then ko will rely on its default behaviors.

Overriding the default base image

By default, ko makes use of as the base image for containers. There are a wide array of scenarios in which overriding this makes sense, for example:

  1. Pinning to a particular digest of this image for repeatable builds,
  2. Replacing this streamlined base image with another with better debugging tools (e.g. a shell, like

The default base image ko uses can be changed by simply adding the following line to .ko.yaml:


Overriding the base for particular imports

Some of your binaries may have requirements that are a more unique, and you may want to direct ko to use a particular base image for just those binaries.

The base image ko uses can be changed by adding the following to .ko.yaml:


Why isn't KO_DOCKER_REPO part of .ko.yaml?

Once introduced to .ko.yaml, you may find yourself wondering: Why does it not hold the value of $KO_DOCKER_REPO?

The answer is that .ko.yaml is expected to sit in the root of a repository, and get checked in and versioned alongside your source code. This also means that the configured values will be shared across developers on a project, which for KO_DOCKER_REPO is actually undesireable because each developer is (likely) using their own docker repository and cluster.

Including static assets

A question that often comes up after using ko for a while is: "How do I include static assets in images produced with ko?".

For this, ko builds around an idiom similar to go test and testdata/. ko will include all of the data under <import path>/kodata/... in the images it produces.

These files are placed under /var/run/ko/..., but the appropriate mechanism for referencing them should be through the KO_DATA_PATH environment variable. The intent of this is to enable users to test things outside of ko as follows:

KO_DATA_PATH=$PWD/cmd/ko/test/kodata go run ./cmd/ko/test/*.go
2018/07/19 23:35:20 Hello there

This produces identical output to being run within the container locally:

ko publish -L ./cmd/test
2018/07/19 23:36:11 Using base for
2018/07/19 23:36:12 Loading ko.local/
2018/07/19 23:36:13 Loaded ko.local/

docker run -ti --rm ko.local/
2018/07/19 23:36:25 Hello there

... or on cluster:

ko apply -f cmd/ko/test/test.yaml
2018/07/19 23:38:24 Using base for
2018/07/19 23:38:25 Publishing
2018/07/19 23:38:26 mounted blob: sha256:988abcba36b5948da8baa1e3616b94c0b56da814b8f6ff3ae3ac316e375e093a
2018/07/19 23:38:26 mounted blob: sha256:57752e7f9593cbfb7101af994b136a369ecc8174332866622db32a264f3fbefd
2018/07/19 23:38:26 mounted blob: sha256:f24d43c24e22298ed99ea125af6c1b828ae07716968f78cb6d09d4291a13f2d3
2018/07/19 23:38:26 mounted blob: sha256:7a7bafbc2ae1bf844c47b33025dd459913a3fece0a94b1f3ced860675be2b79c
2018/07/19 23:38:27 digest: sha256:703c205bf2f405af520b40536b87aafadcf181562b8faa6690fd2992084c8577 size: 751
2018/07/19 23:38:27 Published
pod/kodata created

kubectl logs kodata
2018/07/19 23:38:29 Hello there

Relevance to Release Management

ko is also useful for helping manage releases. For example, if your project periodically releases a set of images and configuration to launch those images on a Kubernetes cluster, release binaries may be published and the configuration generated via:

ko resolve -f config/ > release.yaml

Note that in this context it is recommended that you also provide -P, if supported by your Docker registry. This improves users' ability to tie release binaries back to their source.

This will publish all of the binary components as container images to and create a release.yaml file containing all of the configuration for your application with inlined image references.

This resulting configuration may then be installed onto Kubernetes clusters via:

kubectl apply -f release.yaml


This work is based heavily on learnings from having built the Docker and Kubernetes support for Bazel. That work was presented here.

You can’t perform that action at this time.