Project: ko (App Definition and Development / Application Definition & Image Build)
File: configuration.md

Aside from certain environment variables (see ) like `KODOCKERREPO`, you can configure `ko`'s behavior using a `.ko.yaml` file. The location of this file can be overridden with `KOCONFIGPATH`. 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: ```yaml 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: ```shell KO_DEFAULTBASEIMAGE=registry.example.com/base/image ko build . ``` To override the base image for certain importpaths: ```yaml 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 influenced `builds` configuration section in your `.ko.yaml`. ```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 `[]`. The `ko` builds supports templating of `flags` and `ldflags`, similar to the . 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` | By default, `ko` builds images based on the platform it runs

If your target platform differs from your build platform you can specify the build platform: As a parameter See . In .ko.yaml Add this to your `.ko.yaml` file: ```yaml defaultPlatforms: linux/arm64 linux/amd64 ``` You can also use the `KO_DEFAULTPLATFORMS` environment variable to set the default platforms, which overrides the YAML configuration: ```shell KO_DEFAULTPLATFORMS=linux/arm64,linux/amd64 ``` By default, `ko` builds use the ambient environment from the system (i.e. `os.Environ()`). These values can be overridden globally or per-build (or both). ```yaml env: FOO=foo builds: id: foo dir: . main: ./foobar/foo env: FOO=bar # Overrides the global value. id: bar dir: ./bar main: . ``` For a given build, the environment variables are merged in the following order: System `os.Environ` (lowest precedence) Global `env` Build `env` (highest precedence) You can specify both `flags` and `ldflags` globally as well as per-build. ```yaml flags: -v ldflags: -s builds: id: foo dir: . main: ./foobar/foo flags: -trimpath # Build will use: -v -trimpath ldflags: -w # Build will use: -s -w id: bar dir: ./bar main: . ``` The values for each `build` will be appended to the global values when creating each build. Both global and per-build values may use . 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 | ||--|-| | `KODOCKERREPO` | (not set) | Container repository where to push images built with `ko` (required) | | `KOGOPATH` | `go` | `go` binary to use for builds, relative or absolute path, otherwise looked up via $PATH (optional) | | `KOCONFIGPATH` | `./.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 `KODOCKERREPO=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 `KODOCKERREPO`: `registry.example.com/repo` `ko` is normally used to publish images to container image registries, identified by `KODOCKERREPO`. `ko` can also load images to a local Docker daemon, if available, by setting `KODOCKERREPO=ko.local`, or by passing the `--local` (`-L`) flag. Local images can be used as a base image for other `ko` images: ```yaml defaultBaseImage: ko.local/example/base/image ``` `ko` can also load images into a local cluster, if available, by setting `KODOCKERREPO=kind.local`. By default this loads into the default KinD cluster name (`kind`). To load into another KinD cluster, set `KINDCLUSTERNAME=my-other-cluster`.