Building Container Images

Two make targets exists to build container images automatically based on the locally checked out branch:

Developer images

Run make dev-docker-image to build a cilium-agent Docker image that contains your local changes.

ARCH=amd64 DOCKER_DEV_ACCOUNT=quay.io/myaccount DOCKER_IMAGE_TAG=jane-developer-my-fix make dev-docker-image

Run make docker-operator-generic-image (respectively, docker-operator-aws-image or docker-operator-azure-image) to build the cilium-operator Docker image:

ARCH=amd64 DOCKER_DEV_ACCOUNT=quay.io/myaccount DOCKER_IMAGE_TAG=jane-developer-my-fix make docker-operator-generic-image

The commands above assumes that your username for quay.io is myaccount.

Race detection

See section on compiling Cilium with race detection.

Official release images

Anyone can build official release images using the make target below.

DOCKER_IMAGE_TAG=v1.4.0 make docker-images-all

Experimental Docker BuildKit and Buildx support

Docker BuildKit allows build artifact caching between builds and generally results in faster builds for the developer. Support can be enabled by:

export DOCKER_BUILDKIT=1

Multi-arch image build support for arm64 (aka aarch64) and amd64 (aka x86-64) can be enabled by defining:

export DOCKER_BUILDX=1

Multi-arch images are built using a cross-compilation builder by default, which uses Go cross compilation for Go targets, and QEMU based emulation for other build steps. You can also define your own Buildx builder if you have access to both arm64 and amd64 machines. The “cross” builder will be defined and used if your current builder is “default”.

Buildx targets push images automatically, so you must also have DOCKER_REGISTRY and DOCKER_DEV_ACCOUNT defined, e.g.:

export DOCKER_REGISTRY=docker.io
export DOCKER_DEV_ACCOUNT=your-account

Currently the cilium-runtime and cilium-builder images are released for amd64 only (see the table below). This means that you have to build your own cilium-runtime and cilium-builder images:

make docker-image-runtime

After the build finishes update the runtime image references in other Dockerfiles (docker buildx imagetools inspect is useful for finding image information). Then proceed to build the cilium-builder:

make docker-image-builder

After the build finishes update the main Cilium Dockerfile with the new builder reference, then proceed to build Hubble from github.com/cilium/hubble. Hubble builds via buildx QEMU based emulation, unless you have an ARM machine added to your buildx builder:

export IMAGE_REPOSITORY=${DOCKER_REGISTRY}/${DOCKER_DEV_ACCOUNT}/hubble
CONTAINER_ENGINE="docker buildx" DOCKER_FLAGS="--push --platform=linux/arm64,linux/amd64" make image

Update the main Cilium Dockerfile with the new Hubble reference and build the multi-arch versions of the Cilium images:

make docker-images-all

Official Cilium repositories

The following table contains the main container image repositories managed by Cilium team. It is planned to convert the build process for all images based on GH actions.

Image dependency:

[docker|quay].io/cilium/cilium
 depends on:
  quay.io/cilium/cilium-builder
   depends on:
    quay.io/cilium/cilium-runtime
     depends on:
      docker.io/cilium/cilium-iproute2
      docker.io/cilium/cilium-bpftool
      docker.io/cilium/cilium-llvm
  quay.io/cilium/cilium-envoy
   depends on:
    quay.io/cilium/cilium-envoy-builder
     depends on:
      quay.io/cilium/cilium-builder
       depends on:
        quay.io/cilium/cilium-runtime
         depends on:
          docker.io/cilium/cilium-iproute2
          docker.io/cilium/cilium-bpftool
          docker.io/cilium/cilium-llvm

Update cilium-builder and cilium-runtime images

1. cilium-builder depends on cilium-runtime so one needs to update cilium-runtime first. Steps 4 and 7 will fetch the digest of the image built by GitHub actions.

   $ make -C images/ update-runtime-image

2. Commit your changes and create a PR in cilium/cilium.

   $ git commit -s -a -m "update cilium-{runtime,builder}"

3. Ping one of the members of team/build to approve the build that was created by GitHub Actions here. Note that at this step cilium-builder build failure is expected since we have yet to update the runtime digest.

4. Wait for cilium-runtime build to complete. Only after the image is available run:

   $ make -C images/ update-runtime-image update-builder-image

5. Commit your changes and re-push to the PR in cilium/cilium.

   $ git commit --amend -s -a

6. Ping one of the members of team/build to approve the build that was created by GitHub Actions here.

7. Wait for the build to complete. Only after the image is available run:

   $ make -C images/ update-runtime-image update-builder-image

8. Commit your changes and re-push to the PR in cilium/cilium.

   $ git commit --amend -s -a

9. Update the versions of the images that are pulled into the CI VMs.

• Open a PR against the Packer-CI-Build with an update to said image versions. Once your PR is merged, a new version of the VM will be ready for consumption in the CI.
• Update the SERVER_VERSION field in test/Vagrantfile to contain the new version, which is the build number from the Jenkins Job for the VMs. For example, build 119 from the pipeline would be the value to set for SERVER_VERSION.
• Open a pull request with this version change in the cilium repository.

Nightly Docker image

After each successful Nightly build, a cilium/nightly image is pushed to dockerhub.

To use latest nightly build, please use cilium/nightly:latest tag. Nightly images are stored on dockerhub tagged with following format: YYYYMMDD-<job number>. Job number is added to tag for the unlikely event of two consecutive nightly builds being built on the same date.

Image Building Process

Images are automatically created by a GitHub action: build-images. This action will automatically run for any Pull Request, including Pull Requests submitted from forked repositories, and push the images into quay.io/cilium/*-ci. They will be available there for 1 week before they are removed by the ci-images-garbage-collect workflow. Once they are removed, the developer must re-push the Pull Request into GitHub so that new images are created.