ko

ko is a container image builder designed specifically for Go applications. It simplifies the process of building images that are easy, fast, and secure by default.

Key Characteristics

• Go-Centric: It builds images by executing go build on your local machine.
• No Docker Required: Because it uses your local Go toolchain, it does not require a Docker daemon to be installed, making it ideal for lightweight CI/CD environments.
• Ideal Use Cases: It is best suited for images containing a single Go application with minimal OS dependencies (e.g., applications without cgo or complex OS package requirements).

Core Features

• Multi-platform builds: Easily target multiple architectures.
• SBOMs by default: Automatically produces Software Bill of Materials.
• Kubernetes Integration: Supports simple YAML templating to facilitate building images for Kubernetes applications.

When using ko apply, you can control how images are named in the registry and how they are published using the following flags:

• --preserve-import-paths (-P): Preserves the full import path after the registry URL (e.g., ${KO_DOCKER_REPO}/<import path>). By default, ko uses <package name>-<hash of import path>.
• --base-import-paths (-B): Uses the base path without the MD5 hash after the registry URL.
• --bare: Uses only the KO_DOCKER_REPO without additional context.
• --local (-L): Loads images into the local Docker daemon instead of pushing to a remote registry. When KO_DOCKER_REPO is set to ko.local, it behaves the same as using --local.
• --push: Determines whether to push images to the registry. This is true by default.
• --tags: Specifies custom tags for the produced images instead of the default [latest]. Note that using --tags may not work correctly with --base-import-paths or --bare.

# Example: Preserving import paths in the registry
ko apply --preserve-import-paths -f config/

# Example: Loading images to local docker daemon
ko apply --local -f config/

When using ko create, you can control how images are named in your registry using the following strategies:

1. Default Strategy: Images are published as ${KO_DOCKER_REPO}/<package name>-<hash of import path>.
2. Preserve Import Paths: Use the --preserve-import-paths (or -P) flag to publish images using their full import path: ${KO_DOCKER_REPO}/<import path>.
3. Local Development: Use the --local (or -L) flag to load images directly into your local Docker daemon as ko.local/<import path> instead of pushing to a remote registry.
4. Base Import Paths: Use --base-import-paths (or -B) to use the base path without the MD5 hash after the registry URL (note: this may conflict with --tags).

# Preserve full import paths in the registry
ko create --preserve-import-paths -f config/

# Load images to local docker daemon instead of pushing
ko create --local -f config/

To bundle static assets into your container image, place them in a directory named kodata/ located within your package's import path. ko will automatically include these files in the image.

Inside the container, the location of these assets is provided via the KO_DATA_PATH environment variable. You should use this variable in your application code to locate the files rather than hardcoding a path.

Key behaviors:

• Symlinks: ko follows symlinks within the kodata directory and includes the target files in the image.
• Timestamps: By default, ko does not embed timestamps, meaning http.FileServer will not serve Last-Modified headers. To enable timestamp support, set the KO_DATA_DATE_EPOCH environment variable during your build.

// Example directory structure:
// cmd/app/main.go
// cmd/app/kodata/index.html

func main() {
    // Use the KO_DATA_PATH environment variable to find bundled assets
    dataDir := os.Getenv("KO_DATA_PATH")
    http.Handle("/", http.FileServer(http.Dir(dataDir)))
    log.Fatal(http.ListenAndServe(":8080", nil))
}