Root CA Certificates

To install a root certificate into your container built using ko, you can use one of the following methods.

incert

incert allows you to append CA certificates to an image and push the modified image to a specified registry.

incert can be run after ko build to build your Go application container image with custom root CA certificates.

Example

1. Build and push your Go application container image using ko build

   KO_DOCKER_REPO=mycompany/myimage:latest ko build .
   

2. Append the built image with your custom CA certificate(s) using incert

   incert -image-url=mycompany/myimage:latest -ca-certs-file=/path/to/cacerts.pem -dest-image-url=myregistry/myimage:latest
   

Custom Base Image

New root certificates can be installed into a custom image using standard OS packages. Then, this custom image can be used to override the base image for ko. Once the Go application container image is built using ko with the custom base image, the root certificates installed on the base image will be trusted by the Go application.

Example

1. Make a custom container image with your new root certificates

   # Dockerfile
   FROM alpine
   
   RUN apk update
   RUN apk add ca-certificates
   
   ADD new-root-ca.crt /usr/local/share/ca-certificates/new-root-ca.crt
   RUN chmod 644 /usr/local/share/ca-certificates/new-root-ca.crt
   RUN update-ca-certificates
   

2. Build and push the custom container image to a container registry

   docker build . -t docker.io/ko-build/image-with-new-root-certs
   docker push docker.io/ko-build/image-with-new-root-certs
   

3. Configure ko to override the default base image with the custom image

   # .ko.yaml
   defaultBaseImage: docker.io/ko-build/image-with-new-root-certs
   

   OR

   export KO_DEFAULTBASEIMAGE=docker.io/ko-build/image-with-new-root-certs
   

4. Build the Go app container image with ko

   ko build .
   

Static Assets

Alternatively, root certificates can be installed into the Go application container image using a combination of ko static assets and overriding the default system location for SSL certificates.

Using ko's support for static assets, root certificates can be stored in the <importpath>/kodata directory (either checked into the repository, or injected dynamically by a CI pipeline). After running ko build, the certificate files are then bundled into the built image at the path $KO_DATA_PATH.

To enable the Go application to trust the bundled certificate(s), the container runtime or orchestrator (Docker, Kubernetes, etc) must set the environment variable SSL_CERT_DIR to the same value as KO_DATA_PATH. Go uses SSL_CERT_DIR to determine the directory to check for SSL certificate files. Once this variable is set, the Go application will trust the bundled root certificates in $KO_DATA_PATH.

Example

1. Copy the root certificate(s) to the <importpath>/kodata/ directory

   # $(pwd) assumed to be at <importpath> for this example
   mkdir -p kodata
   cp $CERT_FILE_DIR/*.crt kodata/
   

2. Build the Go application container image

   KO_DOCKER_REPO=docker.io/ko-build/static-assets-certs ko build .
   

3. Run the Go application container image with SSL_CERT_DIR equal to /var/run/ko (the default value for $KO_DATA_PATH)

   docker run -e SSL_CERT_DIR=/var/run/ko docker.io/ko-build/static-assets-certs
   

A functional client-server example for this can be seen here.