Cilium 容器镜像构建实战从开发镜像到官方发布镜像的完整机制解析【免费下载链接】ciliumeBPF-based Networking, Security, and Observability项目地址: https://gitcode.com/GitHub_Trending/ci/cilium本文围绕 Cilium 官方开发文档《Building Container Images》Documentation/contributing/development/images.rst展开系统讲解如何在本地基于当前检出的代码分支构建 cilium-agent 与 cilium-operator 的开发者镜像、如何构建官方发布镜像以及 cilium-builder/cilium-runtime 两个基础镜像的完整更新流程。读完本文你将能够独立完成 Cilium 容器镜像的本地构建、推送并深入理解镜像仓库划分、多平台构建、镜像摘要钉扎digest pinning与 CI 镜像生命周期管理的源码级实现细节。一、Cilium 官方镜像仓库体系Cilium 团队的镜像仓库遵循统一的构建与发布规范所有镜像均通过 GitHub Actions 从对应的 GitHub 仓库自动构建且全部是多平台镜像multi-platform同时支持linux/amd64与linux/arm64两种架构。各 GitHub 仓库与镜像仓库的对应关系如下继承自官方文档GitHub 仓库Dockerfile容器镜像仓库github.com/cilium/ciliumimages/builder/Dockerfilequay.io/cilium/cilium-builderimages/cilium/Dockerfile[quay|docker].io/cilium/ciliumimages/clustermesh-apiserver/Dockerfile[quay|docker].io/cilium/clustermesh-apiserverimages/hubble-relay/Dockerfile[quay|docker].io/cilium/hubble-relayimages/operator/Dockerfile[quay|docker].io/cilium/operator[quay|docker].io/cilium/operator-alibabacloud[quay|docker].io/cilium/operator-aws[quay|docker].io/cilium/operator-azure[quay|docker].io/cilium/operator-genericimages/runtime/Dockerfilequay.io/cilium/cilium-runtimegithub.com/cilium/cilium-cliDockerfilequay.io/cilium/cilium-cligithub.com/cilium/image-toolsimages/bpftool/Dockerfilequay.io/cilium/cilium-bpftoolimages/compilers/Dockerfilequay.io/cilium/image-compilersimages/llvm/Dockerfilequay.io/cilium/cilium-llvmimages/maker/Dockerfilequay.io/cilium/image-makerimages/startup-script/Dockerfilequay.io/cilium/startup-scriptgithub.com/cilium/proxyDockerfile.builderquay.io/cilium/cilium-envoy-builderDockerfilequay.io/cilium/cilium-envoy其中 builder、runtime、cilium、operator、hubble-relay 这几个核心镜像的定义文件与说明文档就在本仓库中各镜像的职责描述见 images/README.mdbuilder 镜像基于 Ubuntu提供protoc及插件、Go 工具链、交叉编译工具链以及用于编译 BPF 数据面的clang编译器来自 cilium-llvm 镜像runtime 镜像提供cilium-agent运行所需的全部用户态依赖——网络工具iproute2、iptables、ipset、kmod、clang/llc工具链、bpftool两者均来自 cilium/image-tools以及 CNI loopback 插件另含gops与 Ubuntu 用户态环境用于排障cilium 镜像包含cilium-agent及其他二进制cilium-dbg、envoy、cilium-health、hubble-cli基于 runtime 镜像operator 镜像只包含cilium-operator二进制与 CA 证书不引入其他二进制或库。同一个 Dockerfile 依据OPERATOR_VARIANT构建参数的取值构建 alibabacloud、aws、azure、generic 等变体hubble-relay 镜像只包含hubble-relay二进制与 CA 证书。镜像依赖树镜像之间并非彼此独立官方文档给出了清晰的依赖结构cilium/cilium ├── cilium/cilium-builder │ └── cilium/cilium-llvm └── cilium/cilium-runtime ├── cilium/cilium-bpftool └── cilium/cilium-llvm cilium/cilium-envoy └── cilium/cilium-envoy-builder cilium/operator └── cilium/cilium-builder └── cilium/cilium-llvm也就是说最终的cilium/cilium与cilium/operator应用镜像分别依赖cilium-builder与cilium-runtime两个底座镜像而这两个底座又共享cilium-llvm、cilium-bpftool等更底层的工具链镜像。理解这棵依赖树是理解后续更新基础镜像流程的关键。二、构建本地开发者镜像Developer Images仓库提供了两个 make 目标可以基于本地检出的分支自动构建包含你本地改动的容器镜像。构建 cilium-agent 镜像运行make dev-docker-image构建包含本地变更的 cilium-agent Docker 镜像ARCHamd64 DOCKER_DEV_ACCOUNTquay.io/myaccount DOCKER_IMAGE_TAGjane-developer-my-fix make dev-docker-image构建 cilium-operator 镜像运行make docker-operator-generic-image或对应的docker-operator-aws-image、docker-operator-azure-image构建 cilium-operator Docker 镜像ARCHamd64 DOCKER_DEV_ACCOUNTquay.io/myaccount DOCKER_IMAGE_TAGjane-developer-my-fix make docker-operator-generic-image以上命令假定你在quay.io上的用户名是myaccount。环境变量在源码中的解析逻辑这些环境变量的处理逻辑可以直接在 Makefile.docker 中找到DOCKER_REGISTRY ? quay.io ifeq ($(findstring /,$(DOCKER_DEV_ACCOUNT)),/) # DOCKER_DEV_ACCOUNT already contains /, assume it specifies a registry IMAGE_REPOSITORY : $(DOCKER_DEV_ACCOUNT) else IMAGE_REPOSITORY : $(DOCKER_REGISTRY)/$(DOCKER_DEV_ACCOUNT) endifDOCKER_DEV_ACCOUNT若值中包含/则被整体视为registry/用户名形式的镜像仓库前缀否则自动拼接默认 registryquay.io。这就是为什么示例中要写成quay.io/myaccountDOCKER_IMAGE_TAG镜像 tag示例中的jane-developer-my-fix便于区分不同开发者的构建ARCH控制构建平台。当指定ARCH时Makefile.docker 会走 docker buildx 的多平台路径ifdef ARCH # Default to multi-arch builds, always create the builder for all the platforms we support DOCKER_PLATFORMS : linux/arm64,linux/amd64 ... # Override default for a single platform ifneq ($(ARCH),multi) DOCKER_PLATFORMS : linux/$(ARCH) endif DOCKER_FLAGS --push --platform $(DOCKER_PLATFORMS)即指定ARCHamd64只构建 amd64 单平台并推送ARCHmulti或配合支持双平台的 builder则同时构建linux/arm64,linux/amd64不指定ARCH时构建回落到--load模式——只在本机加载镜像、不推送模拟普通docker build的行为。每个镜像目标由统一的模板DOCKER_IMAGE_TEMPLATE生成模板会注入以下构建参数CILIUM_SHA当前 git 版本MODIFIERS把NOSTRIP、NOOPT、LOCKDEBUG、RACE、V等构建修饰符透传给容器内的 makeOPERATOR_VARIANToperator 镜像的变体标识--targetrelease 或 debug 两种构建目标见下文 cilium 镜像的 debug 阶段。模板还定义了-unstripped变体NOSTRIP1-unstripped后缀用于保留完整调试符号的镜像例如dev-docker-image-unstripped。重定向基础镜像的拉取源设置BASE_IMAGE_REGISTRY可以重定向基础镜像cilium-builder、cilium-runtime、cilium-envoy的拉取地址。这样既能保持 Dockerfile 中的 tag/digest 钉扎不变又可以在构建时使用自定义 registry$(if $(BASE_IMAGE),--build-arg BASE_IMAGE$(BASE_IMAGE),)带竞态检测的镜像若需要构建开启 Go 竞态检测的镜像参考官方文档中 compile Cilium with race detection 一节的做法通过构建修饰符传入RACE1即可与源码make RACE1等价。三、构建官方发布镜像Official Release Images任何人都可以使用下面的 make 目标构建官方发布镜像DOCKER_IMAGE_TAGv1.4.0 make docker-images-all从 Makefile.docker 可以看到docker-images-all实际展开为docker-images-all: docker-cilium-image docker-hubble-relay-image \ docker-clustermesh-apiserver-image docker-operator-images-all \ docker-standalone-dns-proxy-image docker-operator-images-all: docker-operator-image docker-operator-aws-image \ docker-operator-azure-image docker-operator-alibabacloud-image \ docker-operator-generic-image也就是说docker-images-all一次性覆盖 cilium、hubble-relay、clustermesh-apiserver、standalone-dns-proxy 以及全部 5 个 operator 变体这正是 CI 使用的目标注释标明docker-*-all targets are mainly used from the CI。四、核心 Dockerfile 的多平台构建机制cilium 镜像builder 增量构建 调试符号分离images/cilium/Dockerfile 开头钉扎了三个基础镜像tag 与 sha256 digest 同时锁定ARG CILIUM_BUILDER_IMAGEquay.io/cilium/cilium-builder:be12da3a...sha256:969449d0bc... ARG CILIUM_RUNTIME_IMAGEquay.io/cilium/cilium-runtime:c9cad76d...sha256:d05d3500fc... ARG CILIUM_ENVOY_IMAGEquay.io/cilium/cilium-envoy:v1.38.4-...sha256:1b958363...构建流程分为几个关键阶段builder 阶段FROM --platform${BUILDPLATFORM}在构建机本征平台上挂载仓库源码与 BuildKit 缓存执行make GOARCH${TARGETARCH} ... build-container install-container-binary实现一次构建、跨架构安装调试符号提取所有可执行文件先用objcopy --only-keep-debug抽取.debug符号文件到/tmp/debug随后在NOSTRIP未设置时执行--strip-all并回写--add-gnu-debuglinkrelease 阶段FROM ${CILIUM_RUNTIME_IMAGE}从 builder 拷贝安装产物设置HUBBLE_SERVERunix:///var/run/cilium/hubble.sock容器内 Hubble CLI 走本地 unix socket 而非 RelayCMD为cilium-dbgdebug 阶段在 release 镜像之上安装 delve并用debug-wrapper脚本包装cilium-agent在专用端口自动挂载调试器供dev-docker-image-debug等-debug目标使用。runtime 镜像用户态依赖的最小完整集images/runtime/Dockerfile 基于 Ubuntu 26.04 与 golang 1.27.1从cilium-llvm:21.1.8与cilium-bpftool:7.7.0镜像中提取编译器与 bpftoolENV FORCE_BUILD4 # Change the number to force the generation of a new git-tree SHA. Useful when # we want to re-run apt-get upgrade for stale images.其中FORCE_BUILD变量值得注意runtime 镜像以目录的git tree hash作为 tag目录内容不变时 tree hash 也不变、缓存不会失效。当需要强制重新执行apt-get upgrade刷新过时的系统包时只需手工修改FORCE_BUILD的数值使 tree hash 变化即可触发全量重建。此外该镜像还构建了gops、CNI loopback 插件与iptables-wrapper首次调用时自动探测宿主机的 legacy/nft iptables 后端并重置符号链接。builder 镜像编译工具链的全家桶images/builder/Dockerfile 安装了 amd64/arm64 双向交叉编译工具链、Go 工具链、protoc及插件、delve并从 cilium-llvm 镜像只拷贝clang、llvm-objcopy、llvm-strip注释说明 BPF 构建是 clang-onlyverifier 测试从 cilium-llvm 镜像提取工具链而非此镜像。镜像构建还接入了container-structure-testtest阶段做结构校验测试清单见 images/builder/test/spec.yaml。五、更新 cilium-builder 与 cilium-runtime 镜像的标准流程这是官方文档中操作性最强的章节完整继承其七步流程并补充源码层面的机制说明。前提流程的起点是一个更新镜像版本号的本地提交即把新镜像的 tag/digest 写入各 Dockerfile完成下述步骤后会生成第二个提交包含所有随镜像更新需要联动的代码库变更。官方明确要求两个提交必须保持分离以便日后 backport。若只是想让这两个镜像内的软件包升级可以手工修改 images/runtime/Dockerfile 中的FORCE_BUILD变量为不同的值然后按相同步骤走。提交变更并在 cilium/cilium 上创建 PR$ git commit -sam images: update cilium-{runtime,builder}请 team/build 成员批准PR 提交后GitHub Actions 的 Base Image Release Build 工作流会自动构建基础镜像需要该团队成员批准。等待构建完成若 PR 来自外部 fork构建在推送镜像时会失败——这是预期行为。外部 fork 场景本地回写镜像引用并重新推送$ make -C images/ update-runtime-image $ git commit -sam images: update cilium-{runtime,builder} --amend $ make -C images/ update-builder-image $ git commit -sam images: update cilium-{runtime,builder} --amend主仓库场景构建会自动生成一个提交并推送到你的分支包含仓库内所有文件的联动修改。运行完整 CI 并确保通过。合并 PR。更新脚本的源码机制上一步的update-runtime-image/update-builder-image目标定义在 images/Makefile 中update-runtime-image: scripts/update-cilium-runtime-image.sh $(RUNTIME_IMAGE) $(RUNTIME_DIRECTORY) update-builder-image: scripts/update-cilium-builder-image.sh以 runtime 为例images/scripts/update-cilium-runtime-image.sh 做了三件事通过make-image-tag.sh为images/runtime目录计算新的git tree hash作为 tag调用get-image-digest.sh从 registry 拉取该镜像的 sha256 摘要拼成image:tagsha256:...形式把完整的引用回写给 images/runtime/update-cilium-runtime-image.sh后者用sed批量替换所有引用CILIUM_RUNTIME_IMAGE的 Dockerfile 及 GitHub Actions 文件used_by($(git grep -l ${image}: .github/actions/; find . -type f -name Dockerfile* -print0 \ | xargs -0 git grep -l CILIUM_RUNTIME_IMAGE | sort -u)) for i in ${used_by[]} ; do sed -E s#${image}:.*#${image_full}# ${i} ${i}.sedtmp mv ${i}.sedtmp ${i} donebuilder 侧的 images/builder/update-cilium-builder-image.sh 同理额外覆盖.devcontainer/devcontainer.json中的镜像引用。tag 生成规则tree hash、-dev 与 -wipimages/scripts/make-image-tag.sh 实现了两套打标策略值得单独说明子目录镜像runtime、builder使用git ls-tree --full-tree HEAD -- dir得到的tree hash作为 tag。这样做的好处是——用git show tree-hash可以直接看到构建该镜像时的目录内容消除这个镜像到底用了什么输入构建的疑问全树镜像优先使用符合vX.Y.Z格式的版本 tag否则用短 commit hash。若当前提交不在origin/main祖先链上开发分支追加-dev后缀若工作区有未提交改动追加-wip后缀明确标识非权威构建。另外images/Makefile还提供check-runtime-image/check-builder-image目标CHECKtrue模式脚本会执行git diff --exit-code校验各 Dockerfile 中的引用是否与 registry 实际镜像一致不一致即报错提示参考本流程——这是 CI 中防止镜像引用漂移的守门检查。六、CI 中的镜像构建与生命周期管理所有镜像由 GitHub Actionbuild-images自动创建该 Action 对所有Pull Request 自动运行包括来自 fork 仓库的 PR构建产物推送到quay.io/cilium/*-ci命名空间这些 CI 镜像保留 1 周之后由ci-images-garbage-collect工作流清理镜像被清理后开发者必须重新推送 PR如 push 一个空提交以触发新的镜像构建。这套机制保证了评审过程中任何时刻使用的镜像都是PR 当时代码对应的产物且不会无限占用 registry 空间。七、本地直接构建底座镜像images 子目录除了顶层make dev-docker-image也可以在images/子目录内直接构建与推送底座镜像其目标是独立的一套见 images/Makefile 与 images/README.md# 构建 runtime 镜像linux/amd64 linux/arm64 make -C images runtime-image # 推送到指定 registry make -C images runtime-image PUSHtrue REGISTRIESdocker.io/usernamemake -C images all-images会依次完成 lint、runtime-image、builder-image、cilium-image、operator-image、hubble-relay-image 的全量构建。需要注意新构建的 runtime/builder 镜像若要被 cilium 镜像消费必须按第五节的流程把 images/cilium/Dockerfile 中的CILIUM_RUNTIME_IMAGE/CILIUM_BUILDER_IMAGE引用更新为新 tagdigest或借助 update 脚本自动完成。八、小结Cilium 的容器镜像体系可以归纳为三层底座层cilium-llvm、cilium-bpftool来自 cilium/image-tools 仓库提供编译工具链平台层cilium-builder编译环境与cilium-runtime运行依赖以 git tree hash 打标、digest 钉扎通过 update 脚本与CHECKtrue校验保证全仓库引用一致应用层cilium、cilium/operator*、hubble-relay、clustermesh-apiserver、standalone-dns-proxy由 Makefile.docker 的统一模板驱动支持多平台构建、release/debug 双目标与竞态检测等构建修饰符。掌握这套机制后无论是日常开发中的make dev-docker-image、发布流程中的DOCKER_IMAGE_TAGvX.Y.Z make docker-images-all还是基础镜像的例行升级都有了清晰可操作的命令入口与源码级依据。【免费下载链接】ciliumeBPF-based Networking, Security, and Observability项目地址: https://gitcode.com/GitHub_Trending/ci/cilium创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考