尧图网页设计 
Istio 示例镜像构建指南读懂 samples/builder 的 docker buildx bake 流水线【免费下载链接】istioConnect, secure, control, and observe services.项目地址: https://gitcode.com/GitHub_Trending/is/istioIstio 仓库的许多示例bookinfo、helloworld、tcp-echo 等都需要随发布流程打制成容器镜像。本指南聚焦 samples/builder/README.md 及其背后真正起作用的 samples/builder/docker-bake.hcl讲清这套集中式镜像构建逻辑如何运作、如何用一条docker buildx bake命令构建并推送全部或部分示例镜像、如何覆盖镜像仓库与目标平台以及官方镜像与示例镜像更新时应当遵守的版本维护流程。读完你既能直接在本地复现构建也能理解 HCL 矩阵配置与多阶段构建源码之间的配合关系。目录定位为什么需要一个集中的 sample builderIstio 仓库根目录下有大量示例应用目录每个示例自身通常带有 Dockerfile 与对应的 K8s YAML。长久以来镜像构建逻辑分散在各示例目录里容易重复、不一致。samples/builder目录的存在就是为了把各种示例的镜像构建逻辑集中起来consolidate things便于统一维护版本、统一打 multi-arch 标签并推送到统一的镜像仓库。需要留意 README 给出的两个边界条件仍有一些镜像使用各自目录内的构建配置因此samples/builder覆盖范围并不完整——例如多数传统示例仍使用各目录独立的镜像打包与 CI 流程本目录当前采用Docker Buildx BakeHCL作为唯一构建入口构建逻辑真正落在 docker-bake.hcl 这一个文件中README.md只是操作说明。构建配置核心读透 docker-bake.hcldocker-bake.hcl 全部 45 行定义了整套镜像矩阵从文件结构可以拆分出三个层次。1. 可变变量可在命令行覆盖variable HUB { default localhost:5000 } variable PLATFORMS { default linux/amd64,linux/arm64 }HUB镜像仓库地址前缀默认localhost:5000即默认推送到本机运行的 registryPLATFORMS目标平台列表默认同时构建linux/amd64与linux/arm64两种架构。两个变量在 bake 时都可以通过--set或环境方式覆盖详见下文构建与推送一节。2. 镜像清单 images当前清单包含三组镜像其中 helloworld 的 v1/v2 共享同一份源码../helloworld/src仅通过构建参数service_version区分images [ { name tcp-echo-server source ../tcp-echo/src tags [1.3, latest] }, { name examples-helloworld-v1 source ../helloworld/src args { service_version v1 } tags [1.0, latest] }, { name examples-helloworld-v2 source ../helloworld/src args { service_version v2 } tags [1.0, latest] }, ]每个条目包含四个字段其作用分别是字段含义当前取值示例name镜像名不含仓库前缀tcp-echo-server、examples-helloworld-v1/v2source构建上下文相对 docker-bake.hcl 的路径../tcp-echo/src、../helloworld/srcargs传给 Dockerfile 的ARG构建参数service_version v1tags版本标签列表除语义化版本外通常带latest[1.3, latest]source字段体现了本仓库真实的目录布局三个镜像的实际构建上下文分别指向 samples/tcp-echo/src 与 samples/helloworld/src说明 builder 目录本身只是编排层镜像源码仍留在各自的示例目录中。3. default target矩阵展开生成最终 targettarget default { matrix { item images } name item.name context ${item.source} tags [ for x in setproduct([HUB], item.tags) : join(/${item.name}:, x) ] args lookup(item, args, {}) platforms split(,, lookup(item, platforms, PLATFORMS)) }这段 HCL 的关键机制如下matrix.item images把上面的镜像清单作为矩阵输入Buildx 会为清单中每一项自动生成一个独立的 bake targettarget 名称即item.namecontext ${item.source}每个 target 使用各自声明的构建上下文目录标签的生成使用setproduct将[HUB]与该项的tags做笛卡尔积再用join(/${item.name}:, x)拼出完整标签例如默认HUB下 tcp-echo-server 会被打上localhost:5000/tcp-echo-server:1.3localhost:5000/tcp-echo-server:latestlookup(item, args, {})与lookup(item, platforms, PLATFORMS)表示当某个条目未显式声明对应字段时分别回落为无构建参数与全局PLATFORMS默认值。这一设计使后续新增镜像只需向images清单追加一个条目即可自动获得矩阵构建、多架构支持与统一打标签能力无需复制粘贴 target。镜像背后的源码两个示例的构建上下文集中构建并不代表镜像实现集中最终成果由各示例目录中的 Dockerfile 与程序源码决定理解它们有助于排查构建失败或按需裁剪镜像。helloworldPython 构建期参数区分版本samples/helloworld/src/Dockerfile 基于python:3.12.1-slim将app.py与固定哈希的requirements.txt拷贝进/opt/microservices安装依赖并额外装入curl作为可选的客户端工具。其中与 bake 矩阵对接的关键行ARG service_version ENV SERVICE_VERSION${service_version:-v1} CMD [gunicorn, -b, [::]:5000, app:app, -k, gevent]同一份源码通过service_version这一个 ARG 产出 v1/v2 两个镜像镜像运行后会根据该环境变量返回不同版本的响应——这正是 helloworld 示例用于演示金丝雀发布把流量在 v1/v2 间灰度切分的基础默认监听[::]:5000TCP6若在 K8s Pod 中需要强制 IPv4可在 Deployment 的 command 中覆盖为[gunicorn, -b, [0.0.0.0]:5000, app:app, -k, gevent]。tcp-echo多阶段构建产出精简静态镜像samples/tcp-echo/src/Dockerfile 使用经典的两阶段构建第一阶段基于golang:1.22编译第二阶段从scratch起步仅拷贝静态二进制FROM golang:1.22 AS builder WORKDIR /go/src/istio.io/tcp-echo-server/ COPY main.go . RUN CGO_ENABLED0 GOOSlinux go build -ldflags -extldflags -static -s -w -o tcp-echo main.go FROM scratch COPY --frombuilder /go/src/istio.io/tcp-echo-server/tcp-echo . ENTRYPOINT [ /bin/tcp-echo ] CMD [ 9000, hello ]CGO_ENABLED0关闭 CGO 并静态链接保证产物能在无 glibc 的scratch中运行镜像体积最小化从 samples/tcp-echo/src/main.go 可见程序逻辑通过命令行接收逗号分隔的端口列表与响应前缀每收到一行输入就回显prefix 原始数据Dockerfile 的默认CMD对应监听 9000 端口、前缀为 hello该行为与 tcp-echo 示例 YAML 的用途完全匹配——它是 Istio 官方向导中演示 TCP 流量路由v1/v2 端口分流的主要样例。构建与推送示例镜像本地测试README 中给出的核心命令是docker buildx bake --push该命令会构建全部镜像并推送。完整的行为由 docker-bake.hcl 决定包括默认推送目标为localhost:5000因此你需要在构建机上先运行一个本地 registry例如docker run -d -p 5000:5000 --name registry registry:2才能让--push成功默认同时构建linux/amd64,linux/arm64需要 docker buildx 已配置好支持多架构的 builder如docker-containerdriver否则会退回单平台或报错。两个默认值都可以覆盖# 推送到其它本地/私有仓库 HUBmyregistry.example.com:5000 docker buildx bake --push # 仅构建单一架构加快本地迭代 HUBlocalhost:5000 PLATFORMSlinux/amd64 docker buildx bake --push从 docker-bake.hcl 的实现看HUB与PLATFORMS是通过 HCL 变量注入的tags展开时引用[HUB]platforms展开时把PLATFORMS按逗号切分因此在 bake 命令前以VARvalue形式赋值即可覆盖 HCL 中的 default。只构建部分镜像并非每次都需要全量构建可以显式点名部分 targetdocker buildx bake --push examples-helloworld-v1 tcp-echo-server由于defaulttarget 采用矩阵展开target 名就等于 images 清单里的name字段因此上例只构建并推送 helloworld v1 与 tcp-echo-server 两个镜像适合在修改了某个示例源码后做定向验证避免把整个矩阵重新跑一遍。更新示例镜像版本的流程当示例源码或依赖发生变化、需要发布新镜像时README 明确了两个动作二者缺一不可在 docker-bake.hcl 的tags配置中递增版本。以 tcp-echo-server 为例当前标签为[1.3, latest]若本次要发新版本应改为[1.4, latest]这类新版本号同时保持latest指向最新构建同步更新引用该镜像的示例 YAML。仓库中 Deployment 等编排文件里硬编码了镜像地址与 tag例如 samples/helloworld/helloworld.yaml 中写有image: registry.istio.io/release/examples-helloworld-v1:1.0第 36 行与 v2 对应的:1.0第 65 行。这些 tag 必须与 docker-bake.hcl 中声明的 tag 保持一致否则发布到镜像仓库的新版本不会被示例默认引用。本质上tags列表与 K8s YAML 的image:字段共同构成镜像发布约定二者需要成对更新这也是 README 特别提醒更新镜像时还要更新示例 YAML的原因。构建官方发布镜像的注意事项官方发布流程与本地测试流程的唯一差别是仓库前缀HUBregistry.istio.io/release docker buildx bake --push此时所有镜像将被推送至 Istio 官方发布仓库例如 helloworld v1 会被打上registry.istio.io/release/examples-helloworld-v1:1.0之类的完整标签与上面提到的示例 YAML 引用地址对应。README 特别强调了一个操作纪律每个镜像最好只在官方仓库发布一次以避免意外覆盖已经存在的既有镜像。原因在于一旦某个 tag尤其latest被发布后续任何非预期的重新构建都可能向该 tag 推送内容不同、无法追溯的镜像破坏可复现性与供应链可审计性。因此执行官方构建前应仔细核对tags确认版本号确实需要新增/变更再对目标镜像执行一次构建。局限性与适用前提在使用这套构建方案时请记住以下事实约束均来自仓库现状samples/builder目前管理的镜像只有 helloworldv1/v2与 tcp-echo-server 三类bookinfo、httpbin、sleep 等其它示例镜像仍由各自目录内的 Dockerfile 与构建脚本维护不在本 bake 矩阵内全部构建逻辑基于 Docker Buildx BakeHCL因此环境需要具备较新的 Docker 与 buildx 插件且--push依赖已运行的 registry若在离线或受限网络环境构建需要注意 helloworld 基础镜像与 pip 依赖的拉取requirements.txt 采用--require-hashes固定哈希安装tcp-echo 则依赖 Go 工具链镜像。相关文件速查构建编排入口samples/builder/README.md、samples/builder/docker-bake.hclhelloworld 镜像上下文samples/helloworld/src/Dockerfile、samples/helloworld/src/app.py、samples/helloworld/helloworld.yamltcp-echo 镜像上下文samples/tcp-echo/src/Dockerfile、samples/tcp-echo/src/main.go、samples/tcp-echo/tcp-echo.yaml掌握 samples/builder/docker-bake.hcl 的矩阵写法后为仓库新增一个示例镜像的成本极低只需向images清单追加一条带name、source、tags的记录如需版本差异化再加argsdefaulttarget 就会自动完成多架构构建、仓库前缀拼接与打标签工作再用文中命令执行构建推送、并按版本 示例 YAML成对更新的流程完成发布即可。【免费下载链接】istioConnect, secure, control, and observe services.项目地址: https://gitcode.com/GitHub_Trending/is/istio创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Istio 示例镜像构建指南：读懂 samples/builder 的 docker buildx bake 流水线
Istio 示例镜像构建指南读懂 samples/builder 的 docker buildx bake 流水线【免费下载链接】istioConnect, secure, control, and observe services.项目地址: https://gitcode.com/GitHub_Trending/is/istioIstio 仓库的许多示例bookinfo、helloworld、tcp-echo 等都需要随发布流程打制成容器镜像。本指南聚焦 samples/builder/README.md 及其背后真正起作用的 samples/builder/docker-bake.hcl讲清这套集中式镜像构建逻辑如何运作、如何用一条docker buildx bake命令构建并推送全部或部分示例镜像、如何覆盖镜像仓库与目标平台以及官方镜像与示例镜像更新时应当遵守的版本维护流程。读完你既能直接在本地复现构建也能理解 HCL 矩阵配置与多阶段构建源码之间的配合关系。目录定位为什么需要一个集中的 sample builderIstio 仓库根目录下有大量示例应用目录每个示例自身通常带有 Dockerfile 与对应的 K8s YAML。长久以来镜像构建逻辑分散在各示例目录里容易重复、不一致。samples/builder目录的存在就是为了把各种示例的镜像构建逻辑集中起来consolidate things便于统一维护版本、统一打 multi-arch 标签并推送到统一的镜像仓库。需要留意 README 给出的两个边界条件仍有一些镜像使用各自目录内的构建配置因此samples/builder覆盖范围并不完整——例如多数传统示例仍使用各目录独立的镜像打包与 CI 流程本目录当前采用Docker Buildx BakeHCL作为唯一构建入口构建逻辑真正落在 docker-bake.hcl 这一个文件中README.md只是操作说明。构建配置核心读透 docker-bake.hcldocker-bake.hcl 全部 45 行定义了整套镜像矩阵从文件结构可以拆分出三个层次。1. 可变变量可在命令行覆盖variable HUB { default localhost:5000 } variable PLATFORMS { default linux/amd64,linux/arm64 }HUB镜像仓库地址前缀默认localhost:5000即默认推送到本机运行的 registryPLATFORMS目标平台列表默认同时构建linux/amd64与linux/arm64两种架构。两个变量在 bake 时都可以通过--set或环境方式覆盖详见下文构建与推送一节。2. 镜像清单 images当前清单包含三组镜像其中 helloworld 的 v1/v2 共享同一份源码../helloworld/src仅通过构建参数service_version区分images [ { name tcp-echo-server source ../tcp-echo/src tags [1.3, latest] }, { name examples-helloworld-v1 source ../helloworld/src args { service_version v1 } tags [1.0, latest] }, { name examples-helloworld-v2 source ../helloworld/src args { service_version v2 } tags [1.0, latest] }, ]每个条目包含四个字段其作用分别是字段含义当前取值示例name镜像名不含仓库前缀tcp-echo-server、examples-helloworld-v1/v2source构建上下文相对 docker-bake.hcl 的路径../tcp-echo/src、../helloworld/srcargs传给 Dockerfile 的ARG构建参数service_version v1tags版本标签列表除语义化版本外通常带latest[1.3, latest]source字段体现了本仓库真实的目录布局三个镜像的实际构建上下文分别指向 samples/tcp-echo/src 与 samples/helloworld/src说明 builder 目录本身只是编排层镜像源码仍留在各自的示例目录中。3. default target矩阵展开生成最终 targettarget default { matrix { item images } name item.name context ${item.source} tags [ for x in setproduct([HUB], item.tags) : join(/${item.name}:, x) ] args lookup(item, args, {}) platforms split(,, lookup(item, platforms, PLATFORMS)) }这段 HCL 的关键机制如下matrix.item images把上面的镜像清单作为矩阵输入Buildx 会为清单中每一项自动生成一个独立的 bake targettarget 名称即item.namecontext ${item.source}每个 target 使用各自声明的构建上下文目录标签的生成使用setproduct将[HUB]与该项的tags做笛卡尔积再用join(/${item.name}:, x)拼出完整标签例如默认HUB下 tcp-echo-server 会被打上localhost:5000/tcp-echo-server:1.3localhost:5000/tcp-echo-server:latestlookup(item, args, {})与lookup(item, platforms, PLATFORMS)表示当某个条目未显式声明对应字段时分别回落为无构建参数与全局PLATFORMS默认值。这一设计使后续新增镜像只需向images清单追加一个条目即可自动获得矩阵构建、多架构支持与统一打标签能力无需复制粘贴 target。镜像背后的源码两个示例的构建上下文集中构建并不代表镜像实现集中最终成果由各示例目录中的 Dockerfile 与程序源码决定理解它们有助于排查构建失败或按需裁剪镜像。helloworldPython 构建期参数区分版本samples/helloworld/src/Dockerfile 基于python:3.12.1-slim将app.py与固定哈希的requirements.txt拷贝进/opt/microservices安装依赖并额外装入curl作为可选的客户端工具。其中与 bake 矩阵对接的关键行ARG service_version ENV SERVICE_VERSION${service_version:-v1} CMD [gunicorn, -b, [::]:5000, app:app, -k, gevent]同一份源码通过service_version这一个 ARG 产出 v1/v2 两个镜像镜像运行后会根据该环境变量返回不同版本的响应——这正是 helloworld 示例用于演示金丝雀发布把流量在 v1/v2 间灰度切分的基础默认监听[::]:5000TCP6若在 K8s Pod 中需要强制 IPv4可在 Deployment 的 command 中覆盖为[gunicorn, -b, [0.0.0.0]:5000, app:app, -k, gevent]。tcp-echo多阶段构建产出精简静态镜像samples/tcp-echo/src/Dockerfile 使用经典的两阶段构建第一阶段基于golang:1.22编译第二阶段从scratch起步仅拷贝静态二进制FROM golang:1.22 AS builder WORKDIR /go/src/istio.io/tcp-echo-server/ COPY main.go . RUN CGO_ENABLED0 GOOSlinux go build -ldflags -extldflags -static -s -w -o tcp-echo main.go FROM scratch COPY --frombuilder /go/src/istio.io/tcp-echo-server/tcp-echo . ENTRYPOINT [ /bin/tcp-echo ] CMD [ 9000, hello ]CGO_ENABLED0关闭 CGO 并静态链接保证产物能在无 glibc 的scratch中运行镜像体积最小化从 samples/tcp-echo/src/main.go 可见程序逻辑通过命令行接收逗号分隔的端口列表与响应前缀每收到一行输入就回显prefix 原始数据Dockerfile 的默认CMD对应监听 9000 端口、前缀为 hello该行为与 tcp-echo 示例 YAML 的用途完全匹配——它是 Istio 官方向导中演示 TCP 流量路由v1/v2 端口分流的主要样例。构建与推送示例镜像本地测试README 中给出的核心命令是docker buildx bake --push该命令会构建全部镜像并推送。完整的行为由 docker-bake.hcl 决定包括默认推送目标为localhost:5000因此你需要在构建机上先运行一个本地 registry例如docker run -d -p 5000:5000 --name registry registry:2才能让--push成功默认同时构建linux/amd64,linux/arm64需要 docker buildx 已配置好支持多架构的 builder如docker-containerdriver否则会退回单平台或报错。两个默认值都可以覆盖# 推送到其它本地/私有仓库 HUBmyregistry.example.com:5000 docker buildx bake --push # 仅构建单一架构加快本地迭代 HUBlocalhost:5000 PLATFORMSlinux/amd64 docker buildx bake --push从 docker-bake.hcl 的实现看HUB与PLATFORMS是通过 HCL 变量注入的tags展开时引用[HUB]platforms展开时把PLATFORMS按逗号切分因此在 bake 命令前以VARvalue形式赋值即可覆盖 HCL 中的 default。只构建部分镜像并非每次都需要全量构建可以显式点名部分 targetdocker buildx bake --push examples-helloworld-v1 tcp-echo-server由于defaulttarget 采用矩阵展开target 名就等于 images 清单里的name字段因此上例只构建并推送 helloworld v1 与 tcp-echo-server 两个镜像适合在修改了某个示例源码后做定向验证避免把整个矩阵重新跑一遍。更新示例镜像版本的流程当示例源码或依赖发生变化、需要发布新镜像时README 明确了两个动作二者缺一不可在 docker-bake.hcl 的tags配置中递增版本。以 tcp-echo-server 为例当前标签为[1.3, latest]若本次要发新版本应改为[1.4, latest]这类新版本号同时保持latest指向最新构建同步更新引用该镜像的示例 YAML。仓库中 Deployment 等编排文件里硬编码了镜像地址与 tag例如 samples/helloworld/helloworld.yaml 中写有image: registry.istio.io/release/examples-helloworld-v1:1.0第 36 行与 v2 对应的:1.0第 65 行。这些 tag 必须与 docker-bake.hcl 中声明的 tag 保持一致否则发布到镜像仓库的新版本不会被示例默认引用。本质上tags列表与 K8s YAML 的image:字段共同构成镜像发布约定二者需要成对更新这也是 README 特别提醒更新镜像时还要更新示例 YAML的原因。构建官方发布镜像的注意事项官方发布流程与本地测试流程的唯一差别是仓库前缀HUBregistry.istio.io/release docker buildx bake --push此时所有镜像将被推送至 Istio 官方发布仓库例如 helloworld v1 会被打上registry.istio.io/release/examples-helloworld-v1:1.0之类的完整标签与上面提到的示例 YAML 引用地址对应。README 特别强调了一个操作纪律每个镜像最好只在官方仓库发布一次以避免意外覆盖已经存在的既有镜像。原因在于一旦某个 tag尤其latest被发布后续任何非预期的重新构建都可能向该 tag 推送内容不同、无法追溯的镜像破坏可复现性与供应链可审计性。因此执行官方构建前应仔细核对tags确认版本号确实需要新增/变更再对目标镜像执行一次构建。局限性与适用前提在使用这套构建方案时请记住以下事实约束均来自仓库现状samples/builder目前管理的镜像只有 helloworldv1/v2与 tcp-echo-server 三类bookinfo、httpbin、sleep 等其它示例镜像仍由各自目录内的 Dockerfile 与构建脚本维护不在本 bake 矩阵内全部构建逻辑基于 Docker Buildx BakeHCL因此环境需要具备较新的 Docker 与 buildx 插件且--push依赖已运行的 registry若在离线或受限网络环境构建需要注意 helloworld 基础镜像与 pip 依赖的拉取requirements.txt 采用--require-hashes固定哈希安装tcp-echo 则依赖 Go 工具链镜像。相关文件速查构建编排入口samples/builder/README.md、samples/builder/docker-bake.hclhelloworld 镜像上下文samples/helloworld/src/Dockerfile、samples/helloworld/src/app.py、samples/helloworld/helloworld.yamltcp-echo 镜像上下文samples/tcp-echo/src/Dockerfile、samples/tcp-echo/src/main.go、samples/tcp-echo/tcp-echo.yaml掌握 samples/builder/docker-bake.hcl 的矩阵写法后为仓库新增一个示例镜像的成本极低只需向images清单追加一条带name、source、tags的记录如需版本差异化再加argsdefaulttarget 就会自动完成多架构构建、仓库前缀拼接与打标签工作再用文中命令执行构建推送、并按版本 示例 YAML成对更新的流程完成发布即可。【免费下载链接】istioConnect, secure, control, and observe services.项目地址: https://gitcode.com/GitHub_Trending/is/istio创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考