|
| 1 | +# Cilium Dependency Packaging |
| 2 | + |
| 3 | +This repository contains build definitions for a number of images that are components of the official and development images of Cilium. |
| 4 | + |
| 5 | +The builds are currently hosted in GitHub Actions, but can be ported to any other container-based CI system. |
| 6 | + |
| 7 | +## Images |
| 8 | + |
| 9 | +### [`images/maker`](images/maker/Dockerfile) |
| 10 | + |
| 11 | +This image consists of core tools used for building all other images, which include `bash`, `make` and `docker` (with [`buildx`](https://github.com/docker/buildx)) |
| 12 | +and [`crane`](https://github.com/google/go-containerregistry/blob/master/cmd/crane). |
| 13 | +This image enables using latest BuildKit features without depending on whatever Docker daemon/client CI host provides. |
| 14 | +Since `buildx` runs a BuildKit daemon inside a container, it's largely independent of what version of Docker daemon it runs on. |
| 15 | + |
| 16 | +This image also includes a secure credentials helper - [`docker-credential-env`](http://github.com/errordeveloper/docker-credential-env), |
| 17 | +which prevents having to use `docker login` which stores a plain text token in `${DOCKER_CONFIG}/config.json`. |
| 18 | + |
| 19 | +### [`images/compiler`](images/compilers/Dockerfile) |
| 20 | + |
| 21 | +This image consists of compilers and libraries needed to build other images for `amd64` and `arm64`. |
| 22 | + |
| 23 | +### [`images/bpftool`](images/bpftool/Dockerfile) |
| 24 | + |
| 25 | +This image builds `bpftool` binary for `amd64` and `arm64` using a cross-compiler. The resulting image has only one file - |
| 26 | +`/bin/bpftool`, it is a proper multi-platform image. The binary is dynamically linked to Ubuntu 20.04 glibc and other dependencies. |
| 27 | + |
| 28 | +This image is uses a recent version of `bpftool` from `bpf-next` Linux kernel tree. |
| 29 | + |
| 30 | +### [`images/iproute2`](images/iproute2/Dockerfile) |
| 31 | + |
| 32 | +This image builds `ip` and `tc` binaries for `amd64` and `arm64` using a cross-compiler. The resulting image has only two files - |
| 33 | +`/bin/ip` and `/bin/tc`, it is a proper multi-platform image. The binaries are dynamically linked to Ubuntu 20.04 glibc and other |
| 34 | +dependencies. |
| 35 | + |
| 36 | +This image is uses [a fork of `iproute2`](https://github.com/cilium/iproute2), it has features that Cilium relies on. |
| 37 | + |
| 38 | +### [`images/llvm`](images/llvm/Dockerfile) |
| 39 | + |
| 40 | +This image builds `llc` and `clang` binaries for `amd64` and `arm64` using a cross-compiler. The resulting image has only two |
| 41 | +files - `/bin/llc` and `/bin/clang`, it is a proper multi-platform image. The binaries are dynamically linked to Ubuntu 20.04 glibc |
| 42 | +and other dependencies. |
| 43 | + |
| 44 | +This image is a custom BPF-only distribution of LLVM. |
| 45 | + |
| 46 | +## Usage |
| 47 | + |
| 48 | +### Making changes |
| 49 | + |
| 50 | +All images get automatic tags based on checked-in contents of image subdirectory. At any point in git history of a subdirectory |
| 51 | +there exists a unique [git tree object hash](https://git-scm.com/book/en/v2/Git-Internals-Git-Objects), that is what's used for |
| 52 | +image tags. |
| 53 | + |
| 54 | +As the result of this, following stands: |
| 55 | + |
| 56 | +- image build definitions can be obtained with `git show <tag>` |
| 57 | +- image build is defined by contents of a directory |
| 58 | +- when changes are committed to image directory, new tag is generated |
| 59 | + - if there is a new tag, image is rebuilt and pushed with that new tag |
| 60 | + |
| 61 | +This does not cater for reproducible builds, however it serves as basis for reliable builds, especially when following rules |
| 62 | +are also applied to any build definitions: |
| 63 | + |
| 64 | +- all `FROM` statements use digests (use `scripts/get-image-digest.sh`) |
| 65 | +- any system packages are installed in a separate image that is references by a digests (that's how `images/compilers` is designed) |
| 66 | + - pining system packages can be quite laborious, especially because most of the time what you want is latest that the distribution offers, |
| 67 | + so what's much easier to let the package manager get the latest and then pin down the result by digest, so every time there is a change |
| 68 | + in underlying system packages, that is explicitly recorded by change of digest in each image that uses the base image |
| 69 | + |
| 70 | +Be sure to use `make lint`, which will run [`shellcheck`](https://github.com/koalaman/shellcheck) and [`hadolint`](https://github.com/hadolint/hadolint). |
| 71 | + |
| 72 | +For details of how this works, see the following: |
| 73 | + |
| 74 | +- [`Makefile`](Makefile) |
| 75 | +- [`scripts/build-image.sh`](`scripts/build-image.sh`) |
| 76 | +- [`scripts/make-image-tag.sh`](scripts/make-image-tag.sh). |
| 77 | +- [`images/maker`](images/maker/Dockerfile) |
| 78 | +- [`images/compilers`](images/compilers/Dockerfile) |
| 79 | + |
| 80 | +### Building Locally |
| 81 | + |
| 82 | +One should be able to build images locally as long as they have Docker installed with [`buildx` plug-in](https://docs.docker.com/buildx/working-with-buildx/). |
| 83 | + |
| 84 | +#### `images/{maker,compilers}` |
| 85 | + |
| 86 | +When you have dependencies that need to be added to these image before using them in one of the other images, e.g. if you need to add a system |
| 87 | +library in `compilers` image that will be used for compiling something else, you should make a PR to update `compilers` first. |
| 88 | +However, that's only required for full integration, and you can build images locally if you prefer, you can also push them to your own Docker Hub |
| 89 | +account or whatever is your preferred registry. |
| 90 | + |
| 91 | +When changes to these images are merged into master, builds should run and push new images to each of the registries. |
| 92 | +Once new images are out, a PR will be required to update all dependent images, please use the following commands to |
| 93 | +make updates and commit the resulting changes: |
| 94 | + |
| 95 | +> NOTE: You can only use the `update-*-image` make targets when you are _not building localy_. For example, if you have built a new `compilers` |
| 96 | +> locally, or perahps even pushed it your Docker Hyb account, and you want to consume this new version to build new `llvm` image - you need to uptade |
| 97 | +> `images/llvm/Dockerfile` manually, as the `scripts/update-*-images.sh` is not capable of handling this. |
| 98 | +
|
| 99 | +- `make update-maker-image` |
| 100 | +- `make update-compilers-image` |
0 commit comments