Skip to content

Build Prerequisites

In order to build EKS Distro, you will need to make sure several things are installed and configured.

Region Environment Variables

The build uses the new convention setting region with the AWS_REGION environment variable. Some older utilities such as v1 of the AWS CLI use the environment variable AWS_DEFAULT_REGION. To be safe, set and export both to the same value:

export AWS_REGION=us-west-2

Go Proxy Settings

If you are using an HTTP proxy like you might if you are on a corporate VPN, you may need to set and export GOPROXY:

export GOPROXY=direct

Amazon ECR

If you are building container images and uploading or downloading from ECR, you will need to configure buildctl to get registry credentials. While you could periodically use the AWS CLI and run aws ecr get-login to populate credentials into your ~/.docker/config.json, it is much easier to use the ECR Credential Helper. To get up and running easily, you can use the custom Docker config file provided in this repo. After installing the ECR credential helper, make sure you have AWS credentials configured in one the usual ways, and set the Docker config to the supplied example:

cat ./development/config.json
  "credsStore": "ecr-login"
# enables ecr push/pull
export DOCKER_CONFIG=$(pwd)/development

To create all the required ECR repositories for EKS Distro, run the /development/ecr/ create-all-private-repositories script.


In order to build and run multi-architecture containers, you will need to install Qemu. On AmazonLinux2, this can be installed with the qemu-user-static package, and then updating your host's binfmt_misc configuration.


If you are on a Mac, you will need to brew install coreutils to get GNU tar.

Build Options

The default target for make files uses buildkit to build containers. The alternative to this is building and pushing containers with Docker.


The default target for make files builds with buildkit. You can install the latest buildkit client from the GitHub releases page. To run a buildkit server locally, you can use docker-compose.

docker-compose -f development/buildkit-compose.yaml up -d
docker-compose -f development/buildkit-compose.yaml logs buildkitd
export BUILDKIT_HOST="tcp://"
buildctl debug workers

Note: If you notice that RUN commands in image builds that require network access are failing, your network may be blocking DNS lookups to Google DNS IPs ( and If you see the log message from the buildkit server:

"No non-localhost DNS nameservers are left in resolv.conf. Using default external servers: [nameserver nameserver]

Try adding your local nameservers and search domains to the development/buildkitd.toml file and the dns and dns_search, and volume sections of the development/buildkit-compose.yaml, and run docker-compose up -d. If you are on macOS, you can run the following command to find your nameservers and search domains.

scutil --dns

Build with Docker

If you don't want to use buildkit, you will need to install Docker to build containers. Use the docker target for make files.