github.com/cilium/cilium@v1.16.2/Documentation/contributing/development/images.rst (about) 1 .. only:: not (epub or latex or html) 2 3 WARNING: You are looking at unreleased Cilium documentation. 4 Please use the official rendered version released here: 5 https://docs.cilium.io 6 7 .. _container_images: 8 9 Building Container Images 10 ========================= 11 12 Two make targets exists to build container images automatically based on the 13 locally checked out branch: 14 15 Developer images 16 ~~~~~~~~~~~~~~~~ 17 18 Run ``make dev-docker-image`` to build a cilium-agent Docker image that 19 contains your local changes. 20 21 .. code-block:: shell-session 22 23 ARCH=amd64 DOCKER_DEV_ACCOUNT=quay.io/myaccount DOCKER_IMAGE_TAG=jane-developer-my-fix make dev-docker-image 24 25 Run ``make docker-operator-generic-image`` (respectively, 26 ``docker-operator-aws-image`` or ``docker-operator-azure-image``) to build the 27 cilium-operator Docker image: 28 29 .. code-block:: shell-session 30 31 ARCH=amd64 DOCKER_DEV_ACCOUNT=quay.io/myaccount DOCKER_IMAGE_TAG=jane-developer-my-fix make docker-operator-generic-image 32 33 The commands above assumes that your username for ``quay.io`` is ``myaccount``. 34 35 ~~~~~~~~~~~~~~ 36 Race detection 37 ~~~~~~~~~~~~~~ 38 39 See section on :ref:`compiling Cilium with race detection 40 <compile-cilium-with-race-detection>`. 41 42 Official release images 43 ~~~~~~~~~~~~~~~~~~~~~~~ 44 45 Anyone can build official release images using the make target below. 46 47 .. code-block:: shell-session 48 49 DOCKER_IMAGE_TAG=v1.4.0 make docker-images-all 50 51 Experimental Docker BuildKit and Buildx support 52 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 53 54 Docker BuildKit allows build artifact caching between builds and 55 generally results in faster builds for the developer. Support can be 56 enabled by: 57 58 .. code-block:: shell-session 59 60 export DOCKER_BUILDKIT=1 61 62 Multi-arch image build support for arm64 (aka aarch64) and amd64 (aka 63 x86-64) can be enabled by defining: 64 65 .. code-block:: shell-session 66 67 export DOCKER_BUILDX=1 68 69 Multi-arch images are built using a cross-compilation builder by 70 default, which uses Go cross compilation for Go targets, and QEMU 71 based emulation for other build steps. You can also define your own 72 Buildx builder if you have access to both arm64 and amd64 machines. 73 The "cross" builder will be defined and used if your current builder 74 is "default". 75 76 Buildx targets push images automatically, so you must also have 77 DOCKER_REGISTRY and DOCKER_DEV_ACCOUNT defined, e.g.: 78 79 .. code-block:: shell-session 80 81 export DOCKER_REGISTRY=docker.io 82 export DOCKER_DEV_ACCOUNT=your-account 83 84 Currently the cilium-runtime and cilium-builder images are released 85 for amd64 only (see the table below). This means that you have to 86 build your own cilium-runtime and cilium-builder images: 87 88 .. code-block:: shell-session 89 90 make -C images runtime-image 91 92 After the build finishes update the runtime image references in other 93 Dockerfiles (``docker buildx imagetools inspect`` is useful for finding 94 image information). Then proceed to build the cilium-builder: 95 96 .. code-block:: shell-session 97 98 make -C images builder-image 99 100 After the build finishes update the main Cilium Dockerfile with the 101 new builder reference, then proceed to build Hubble from 102 github.com/cilium/hubble. Hubble builds via buildx QEMU based 103 emulation, unless you have an ARM machine added to your buildx 104 builder: 105 106 .. code-block:: shell-session 107 108 export IMAGE_REPOSITORY=${DOCKER_REGISTRY}/${DOCKER_DEV_ACCOUNT}/hubble 109 CONTAINER_ENGINE="docker buildx" DOCKER_FLAGS="--push --platform=linux/arm64,linux/amd64" make image 110 111 Update the main Cilium Dockerfile with the new Hubble reference and 112 build the multi-arch versions of the Cilium images: 113 114 .. code-block:: shell-session 115 116 make docker-images-all 117 118 Official Cilium repositories 119 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 120 121 The following table contains the main container image repositories managed by 122 Cilium team. It is planned to convert the build process for all images based 123 on GH actions. 124 125 +-------------------------------+---------------------------------------------+-----------------------------------------------+-------------------------+-------------------+ 126 | **Github Repository** | **Dockerfile** | **container image repository** | **Architectures** | **Build process** | 127 | | | +-----------+-------------+ | 128 | | | | **amd64** | **aarch64** | | 129 +-------------------------------+---------------------------------------------+-----------------------------------------------+-----------+-------------+-------------------+ 130 | github.com/cilium/cilium | images/runtime/Dockerfile | quay.io/cilium/cilium-runtime | Y | Y | GH Action | 131 | +---------------------------------------------+-----------------------------------------------+-----------+-------------+-------------------+ 132 | | images/builder/Dockerfile | quay.io/cilium/cilium-builder | Y | Y | GH Action | 133 | +---------------------------------------------+-----------------------------------------------+-----------+-------------+-------------------+ 134 | | images/cilium/Dockerfile | [docker|quay].io/cilium/cilium | Y | Y | GH Action | 135 | +---------------------------------------------+-----------------------------------------------+-----------+-------------+-------------------+ 136 | | images/cilium-docker-plugin/Dockerfile | [docker|quay].io/cilium/docker-plugin | Y | Y | GH Action | 137 | +---------------------------------------------+-----------------------------------------------+-----------+-------------+-------------------+ 138 | | images/hubble-relay/Dockerfile | [docker|quay].io/cilium/hubble-relay | Y | Y | GH Action | 139 | +---------------------------------------------+-----------------------------------------------+-----------+-------------+-------------------+ 140 | | images/operator/Dockerfile | [docker|quay].io/cilium/operator | Y | Y | GH Action | 141 | +---------------------------------------------+-----------------------------------------------+-----------+-------------+-------------------+ 142 | | images/operator-aws/Dockerfile | [docker|quay].io/cilium/operator-aws | Y | Y | GH Action | 143 | +---------------------------------------------+-----------------------------------------------+-----------+-------------+-------------------+ 144 | | images/operator-azure/Dockerfile | [docker|quay].io/cilium/operator-azure | Y | Y | GH Action | 145 | +---------------------------------------------+-----------------------------------------------+-----------+-------------+-------------------+ 146 | | images/operator-generic/Dockerfile | [docker|quay].io/cilium/operator-generic | Y | Y | GH Action | 147 | +---------------------------------------------+-----------------------------------------------+-----------+-------------+-------------------+ 148 | | images/clustermesh-apiserver/Dockerfile | [docker|quay].io/cilium/clustermesh-apiserver | Y | Y | GH Action | 149 +-------------------------------+---------------------------------------------+-----------------------------------------------+-----------+-------------+-------------------+ 150 | github.com/cilium/proxy | Dockerfile.builder | quay.io/cilium/cilium-envoy-builder | Y | Y | GH Action | 151 | +---------------------------------------------+-----------------------------------------------+-----------+-------------+-------------------+ 152 | | Dockerfile | quay.io/cilium/cilium-envoy | Y | Y | GH Action | 153 +-------------------------------+---------------------------------------------+-----------------------------------------------+-----------+-------------+-------------------+ 154 | | images/bpftool/Dockerfile | docker.io/cilium/cilium-bpftool | Y | Y | GH Action | 155 | +---------------------------------------------+-----------------------------------------------+-----------+-------------+-------------------+ 156 | | images/llvm/Dockerfile | docker.io/cilium/cilium-llvm | Y | Y | GH Action | 157 | github.com/cilium/image-tools +---------------------------------------------+-----------------------------------------------+-----------+-------------+-------------------+ 158 | | images/compilers/Dockerfile | docker.io/cilium/image-compilers | Y | Y | GH Action | 159 | +---------------------------------------------+-----------------------------------------------+-----------+-------------+-------------------+ 160 | | images/maker/Dockerfile | docker.io/cilium/image-maker | Y | Y | GH Action | 161 | +---------------------------------------------+-----------------------------------------------+-----------+-------------+-------------------+ 162 | | images/startup-script/Dockerfile | docker.io/cilium/startup-script | Y | Y | GH Action | 163 +-------------------------------+---------------------------------------------+-----------------------------------------------+-----------+-------------+-------------------+ 164 165 Image dependency: 166 167 :: 168 169 [docker|quay].io/cilium/cilium 170 depends on: 171 quay.io/cilium/cilium-builder 172 depends on: 173 quay.io/cilium/cilium-runtime 174 depends on: 175 docker.io/cilium/cilium-bpftool 176 docker.io/cilium/cilium-llvm 177 quay.io/cilium/cilium-envoy 178 depends on: 179 quay.io/cilium/cilium-envoy-builder 180 depends on: 181 quay.io/cilium/cilium-builder 182 depends on: 183 quay.io/cilium/cilium-runtime 184 depends on: 185 docker.io/cilium/cilium-bpftool 186 docker.io/cilium/cilium-llvm 187 188 189 190 .. _update_cilium_builder_runtime_images: 191 192 Update cilium-builder and cilium-runtime images 193 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 194 195 The steps described here, starting with a commit that updates the image 196 versions, build the necessary images and update all the appropriate 197 locations in the Cilium codebase. Hence, before executing the following steps, 198 the user should have such a commit (e.g., see 199 `this commit 200 <https://github.com/cilium/cilium/pull/17713/commits/b7a37ff80df8681d25a24fd5b464082d360fc6e2>`__) 201 in their local tree. After following the steps below, the result would be another 202 commit with the image updates (e.g,. see `this commit 203 <https://github.com/cilium/cilium/pull/17713/commits/bd3357704647117fa9ef4839b9f603cd0435b7cc>`__). 204 Please keep the two commits separate to ease backporting. 205 206 If you only wish to update the packages in these images, then you can manually 207 update the ``FORCE_BUILD`` variable in ``images/runtime/Dockerfile`` to have a 208 different value and then proceed with the steps below. 209 210 #. Commit your changes and create a PR in cilium/cilium. 211 212 .. code-block:: shell-session 213 214 $ git commit -sam "images: update cilium-{runtime,builder}" 215 216 #. Ping one of the members of `team/build <https://github.com/orgs/cilium/teams/build/members>`__ 217 to approve the build that was created by GitHub Actions `here <https://github.com/cilium/cilium/actions?query=workflow:%22Base+Image+Release+Build%22>`__. 218 Note that at this step cilium-builder build failure is expected since we have yet to update the runtime digest. 219 220 #. Wait for build to complete. If the PR was opened from an external fork the 221 build will fail while trying to push the changes, this is expected. 222 223 #. If the PR was opened from an external fork, run the following commands and 224 re-push the changes to your branch. Once this is done the CI can be executed. 225 226 .. code-block:: shell-session 227 228 $ make -C images/ update-runtime-image 229 $ git commit -sam "images: update cilium-{runtime,builder}" --amend 230 $ make -C images/ update-builder-image 231 $ git commit -sam "images: update cilium-{runtime,builder}" --amend 232 233 #. If the PR was opened from the main repository, the build will automatically 234 generate one commit and push it to your branch with all the necessary changes 235 across files in the repository. 236 237 #. Run the full CI and ensure that it passes. 238 239 #. Merge the PR. 240 241 Image Building Process 242 ~~~~~~~~~~~~~~~~~~~~~~ 243 244 Images are automatically created by a GitHub action: ``build-images``. This 245 action will automatically run for any Pull Request, including Pull Requests 246 submitted from forked repositories, and push the images into 247 ``quay.io/cilium/*-ci``. They will be available there for 1 week before they are 248 removed by the ``ci-images-garbage-collect`` workflow. Once they are removed, the 249 developer must re-push the Pull Request into GitHub so that new images are 250 created.