Configuration

Basic Configuration

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.

Overriding Base Images

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:

To override the base image for all images 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 .

To override the base image for certain importpaths:

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

Overriding Go build settings

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 [].

Templating support

The ko builds supports templating of flags and ldflags, similar to the GoReleaser builds section.

The table below lists the supported template parameters.

Template param	Description
`Env`	Map of environment variables used for the build
`GoEnv`	Map of `go env` environment variables used for the build
`Date`	The UTC build date in RFC 3339 format
`Timestamp`	The UTC build date as Unix epoc seconds
`Git.Branch`	The current git branch
`Git.Tag`	The current git tag
`Git.ShortCommit`	The git commit short hash
`Git.FullCommit`	The git commit full hash
`Git.CommitDate`	The UTC commit date in RFC 3339 format
`Git.CommitTimestamp`	The UTC commit date in Unix format
`Git.IsDirty`	Whether or not current git state is dirty
`Git.IsClean`	Whether or not current git state is clean.
`Git.TreeState`	Either `clean` or `dirty`

Setting default platforms

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

Setting build environment variables

By default, ko builds use the ambient environment from the system (i.e. os.Environ()). These values can be overridden for your build.

defaultEnv:
- FOO=foo
builds:
- id: foo
  dir: .
  main: ./foobar/foo
  env:
  - FOO=bar
- id: bar     # Will use defaultEnv.
  dir: ./bar
  main: .

For a given build, the environment variables are merged in the following order:

System os.Environ (lowest precedence)
Build variables: build.env if specified, otherwise defaultEnv (highest precedence)

Setting build flags and ldflags

You can specify both flags and ldflags globally as well as per-build.

defaultFlags:
- -v
defaultLdflags:
- -s
builds:
- id: foo
  dir: .
  main: ./foobar/foo
  flags:
  - -trimpath
  ldflags:
  - -w
- id: bar     # Will use defaultFlags and defaultLdflags.
  dir: ./bar
  main: .

The values for a build will be used if specified, otherwise their respective defaults will be used. Both default and per-build values may use template parameters.

Environment Variables (advanced)

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).

Naming Images

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-paths (-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/repo

Local Publishing Options

ko 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.