Docker Compose Bridge Transformations 命令完全指南：管理 compose 到 Kubernetes/Helm 的转换镜像
【免费下载链接】composeDefine and run multi-container applications with Docker项目地址: https://gitcode.com/GitHub_Trending/compose/compose
导读
docker compose bridge transformations是 Docker Compose CLI 中负责管理"转换器镜像（transformation images）"的命令组，它归属于 bridge 功能组，支撑着docker compose bridge convert将 Compose 项目转换为 Kubernetes manifests、Helm Chart 等其他部署模型的能力。读完本文，你将掌握 transformation 镜像的工作原理、list与create两个子命令的全部参数与用法，以及如何从仓库源码与端到端测试中验证这一机制的行为细节。
transformations 命令组在 bridge 体系中的定位
在 Compose 的 bridge 设计里，把compose.yaml转换成"另一个模型"的过程并不是写死在 CLI 二进制里的，而是交给一个个独立的转换器镜像去执行。CLI 只负责把 Compose 项目模型序列化并喂给镜像，再由镜像产出 Kubernetes/Helm 等目标产物。transformations子命令组正是围绕这批镜像的生命周期管理而存在。
从命令入口源码可以看到，transformations是一个仅用于归组的父命令，注册了如下两个子命令：
| 子命令 | 用途 |
|---|---|
list（别名ls） | 列出本地可用的 transformation 镜像 |
create | 基于已有 transformation 创建一份新的可定制副本 |
官方参考文档（compose_bridge_transformations.md）为命令组本身记录了唯一的选项：
| 选项 | 类型 | 默认 | 说明 |
|---|---|---|---|
--dry-run | bool | false | 以 dry-run 模式执行命令 |
其中--dry-run属于从父命令继承的选项（详见生成的 docker_compose_bridge_transformations.yaml），后续小节中list/create各自还能识别它。
先理解 transformation 镜像是什么：标签 + templates 目录
在动手执行list、create之前，有必要先弄清 CLI 是如何识别"一个镜像是不是 transformation"的。答案藏在pkg/bridge/transformers.go的常量定义里：
TransformerLabel = "com.docker.compose.bridge"：用于给镜像打标签的键；DefaultTransformerImage = "docker/compose-bridge-kubernetes"：默认的转换器镜像；templatesPath = "/templates"：转换模板在镜像内的固定目录。
也就是说，一个 transformation 镜像需要满足两点约定：
- 带有标签
com.docker.compose.bridge=transformation； - 镜像内包含
/templates目录，里面存放转换所用的模板文件。
而镜像真正被消费的地方在pkg/bridge/convert.go的convert函数中：CLI 会把序列化后的 Compose 项目（临时目录中的compose.yaml）以 bind mount 方式挂载为容器的/in，把输出目录挂载为/out，若用户显式传了--templates则再挂载到/templates，随后以LICENSE_AGREEMENT=true的环境变量启动该镜像并等待其运行完成，产物即被写入/out。这解释了为什么 transformation 镜像必须自带模板：转换逻辑本身运行在容器里，CLI 只负责把输入与输出目录接好。
列出已安装的转换器：transformations list
list（别名ls）用于枚举本机 Docker 中所有"已安装"的 transformation 镜像。其 CLI 定义见 cmd/compose/bridge.go，官方参数表如下（文档）：
| 选项 | 类型 | 默认 | 说明 |
|---|---|---|---|
--dry-run | bool | false | 以 dry-run 模式执行 |
--format | string | table | 输出格式，可选table或json |
-q,--quiet | bool | false | 仅显示 transformer 名称 |
底层实现：按标签过滤镜像
命令的完整形态有两种写法，二者等价：
docker compose bridge transformations list docker compose bridge transformations ls底层调用ListTransformers，其实质就是对 Docker daemon 执行一次带 label 过滤的ImageList查询：
docker image ls --filter label=com.docker.compose.bridge=transformation因此凡是带com.docker.compose.bridge=transformation标签的本地镜像都会被列出，无关镜像不会出现——这也是"可用 transformation"的唯一定义。
默认 table 输出与列含义
默认（--format table）输出包含四列（格式化逻辑见 cmd/compose/bridge.go）：
IMAGE ID：镜像 ID 的截断形式；REPO：仓库名（从 RepoTags 解析出的熟悉名称）；TAGS：镜像标签；SIZE：镜像大小（按人类可读格式展示）。
-q/--quiet则会退化为纯名称输出：优先打印RepoTags[0]，无标签时才打印镜像 ID。
机器可读输出
需要脚本消费时可切换为 JSON：
docker compose bridge transformations list --format json从 docker_compose_bridge_transformations_list.yaml 生成的默认值可以看到format的默认是table，仅在显式传入json时才切换。
一个典型的验证场景
仓库的端到端测试 pkg/e2e/bridge_test.go 展示了list的实战校验：在执行过转换后执行ls，断言标准输出中同时包含docker/compose-bridge-helm与docker/compose-bridge-kubernetes两个镜像名。这提示了 list 的最常见用途——确认本地是否已具备所需的转换器镜像，避免bridge convert时因镜像缺失触发不必要的网络拉取。
派生一份自定义转换器：transformations create
create用于"复制"一份现有的 transformation，生成一个可以修改的本地工程，便于你定制自己的转换模板。命令入口见 cmd/compose/bridge.go：
docker compose bridge transformations create [OPTION] PATH其中PATH是必填的位置参数（源码中通过cli.ExactArgs(1)强制恰好一个参数），它指向要生成的本地工程目录。参数表如下（文档）：
| 选项 | 类型 | 默认 | 说明 |
|---|---|---|---|
--dry-run | bool | false | 以 dry-run 模式执行 |
-f,--from | string | docker/compose-bridge-kubernetes | 要复制来源的已有 transformation 镜像 |
create 执行时实际发生什么
create的完整实现位于CreateTransformer，其行为可归纳为四个阶段：
- 解析来源镜像：若未传
--from，自动使用默认值docker/compose-bridge-kubernetes（见 transformers.go）； - 校验目标目录：目标路径会被转为绝对路径，且该目录必须不存在（
output folder %s already exists会直接报错），随后创建templates/子目录，并校验输出路径合法性； - 从来源镜像抽取模板：以来源镜像创建临时容器（结束后自动
ContainerRemove(Force: true)清理），再通过CopyFromContainer把容器内的/templates目录整体拷贝到本地目标目录； - 生成 Dockerfile：在目标目录写入一个默认 Dockerfile，内容为：
FROM docker/compose-bridge-transformer LABEL com.docker.compose.bridge=transformation COPY templates /templates这个 Dockerfile 恰好回应了前文所述的两条约定：基础镜像使用官方转换器运行时docker/compose-bridge-transformer，打上com.docker.compose.bridge=transformation标签，并把本地templates目录复制回镜像内的/templates。
create 之后你得到什么
假设执行：
docker compose bridge transformations create my-k8s-tweaks工作目录my-k8s-tweaks/下会出现：
templates/：从docker/compose-bridge-kubernetes拷贝来的模板目录，可在此按需修改；Dockerfile：上文展示的默认构建文件。
之后用docker build构建并打上标签，一个新 transformation 镜像便诞生了。不过要注意：create 本身不会自动帮你 build 镜像，它只负责生成可构建的工程骨架，最终仍需自行docker build -t <your-registry>/<name> .。
注意：
--dry-run需要 docker daemon 支持 dry-run 的客户端能力。从 docker_compose_bridge_transformations_create.yaml 可以看到from仅有string类型且默认值在帮助信息中说明，未传入时即回落到源码中的默认镜像。
把 transformations 接回完整的转换工作流
掌握了镜像管理之后，理解它们如何被使用才完整。docker compose bridge convert的-t/--transformation选项用于指定要应用的转换器，可重复传入多个（stringArray）；若完全不传，则默认使用docker/compose-bridge-kubernetes（默认值见 convert.go 与 compose_bridge_convert.md）。
仓库端到端测试 TestConvertAndTransformList 给出了一个完整可复现的工作流示例：
# 1. 转换为 Kubernetes manifests docker compose -f fixtures/bridge/compose.yaml --project-name bridge \ bridge convert --output out/kubernetes \ --transformation docker/compose-bridge-kubernetes:v0.0.3 # 2. 转换为 Helm chart docker compose -f fixtures/bridge/compose.yaml --project-name bridge \ bridge convert --output out/helm \ --transformation docker/compose-bridge-helm:v0.0.3 # 3. 核对本地已就绪的 transformation 镜像 docker compose --project-name bridge bridge transformations ls与之对应的样例 Compose 文件是 fixtures/bridge/compose.yaml，它同时使用了configs、secrets、internal网络与多网络服务，用以验证转换器的覆盖能力。转换结果可在仓库中直接比对：
- Kubernetes 输出：fixtures/bridge/expected-kubernetes（包含
base/的 namespace、configs、secrets、NetworkPolicy、Deployment、Service 与kustomization.yaml，以及overlays/desktop/覆盖层）； - Helm 输出：fixtures/bridge/expected-helm（
Chart.yaml、values.yaml与templates/下的各资源模板）。
观察这些预期产物可以看到：命名空间、Secret/ConfigMap、网络策略、Deployment、Service 等 Kubernetes 资源均由模板体系自动推导生成，这也是默认 transformationdocker/compose-bridge-kubernetes的功能边界。测试通过diff -r对转换输出与期望目录做全量比对，说明转换结果是确定性的。
使用注意事项与限制
结合源码，使用本命令组时有几点值得留意：
- 依赖本地 Docker daemon：
list与create都直接调用dockerCli.Client()（见 transformers.go），因此环境必须能访问 Docker Engine；create还需要能拉取或已存在--from指定的来源镜像。 - 镜像缺失时不会自动兜底：
create依赖本地镜像执行ContainerCreate+CopyFromContainer，来源镜像不存在时命令会直接失败，需要先docker pull。 - 目标目录必须不存在：
create PATH在目标已存在时会报output folder ... already exists，这是有意的保护，避免覆盖已有工程。 - Windows 与 Linux 行为差异：在
convert阶段，POSIX 系统会把容器以当前用户 UID 运行以保证输出文件归属正确，而 Windows 上引擎无法管理 SID，因此不会设置 User 字段（见 convert.go）。这一点对你编写、测试自定义模板时同样有影响。 --dry-run在文档与实现中的呈现：--dry-run在参考文档中作为（父命令继承的）选项出现，但本文所述三个命令的核心实现路径并未针对 dry-run 额外分支处理；它更接近 Compose CLI 对全局 dry-run 能力的统一标注（与 alpha dry-run 能力 对齐）。实际批量脚本中建议以真实执行 + 输出校验为准。
小结与延伸阅读
docker compose bridge transformations用"镜像即转换器"的方式把 Compose 到 Kubernetes/Helm 的转换逻辑与 CLI 解耦：list通过com.docker.compose.bridge=transformation标签发现已安装的转换器，create则从已有镜像抽取/templates生成可定制的转换工程。整体机制由 pkg/bridge/transformers.go 与 pkg/bridge/convert.go 共同实现，并被 pkg/e2e/bridge_test.go 端到端验证。
如果想继续深入，建议按以下顺序阅读仓库内容：
- 功能组总览：compose_bridge.md、compose_bridge_convert.md
- CLI 注册代码：cmd/compose/bridge.go
- 转换执行与资源预加载测试：pkg/bridge/convert_test.go
- 端到端样例工程：fixtures/bridge/
【免费下载链接】composeDefine and run multi-container applications with Docker项目地址: https://gitcode.com/GitHub_Trending/compose/compose
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
