Docker Compose 一键上 Kubernetes：docker-ce 中 Compose on Kubernetes 完整实战指南

• 容器运行时
• 云原生

本文围绕 docker-ce 仓库中 vendored 的 Compose on Kubernetes 组件（README），系统讲解如何用docker stack deploy直接把 Docker Compose 文件部署到 Kubernetes 集群。你将掌握安装检查、stack 部署/删除、底层 Stack 自定义资源（CRD）与 API 版本机制、调试构建流程，以及在生产集群（AKS/GKE/Microk8s/Minikube）上的部署思路。

什么是 Compose on Kubernetes

Compose on Kubernetes 是 Docker 官方提供的一个 Kubernetes 组件，其核心能力正如其 README 开篇所述：允许你直接使用 Docker Compose 文件在 Kubernetes 集群上部署应用栈（Stack）。

在 docker-ce 仓库中，它作为 CLI 的 vendored 依赖存在于components/cli/vendor/github.com/docker/compose-on-kubernetes/目录下，其中包含两大部分：

• API 定义（api/目录）：Stack 这一自定义资源的类型定义、注册逻辑、客户端 clientset/informer/lister，以及分组compose.docker.com下的多个 API 版本；
• 文档（README.md）：面向用户和开发者的使用与调试指南，即本文展开的核心内容。

该组件随 Docker Desktop 和 Docker Enterprise 内置分发。使用场景很明确：团队里已经有成熟的docker-compose.yml，又想迁移到 Kubernetes 平台时，无需重写为 Deployment/Service 等一大堆 YAML，直接用 Docker 原生的 stack 命令就能完成部署。

说明：当前 docker-ce 仓库对该组件的角色是"随 CLI 一并分发、供docker stack deploy --orchestrator=kubernetes调用"，本仓库并未包含 compose-on-kubernetes 的 controller 实现源码，controller 侧运行于 Docker Desktop/Enterprise 的 Kubernetes 集群内。

快速开始：在 Docker Desktop 上启用与部署

1. 环境准备与启用

Compose on Kubernetes 预装在 Docker Desktop 与 Docker Enterprise 中。在 Docker Desktop 上，你需要在设置中激活 Kubernetes才能使用该功能。

2. 检查组件是否已安装

组件是否可用，可以通过查询 API 是否暴露来判断。执行：

$ kubectl api-versions | grep compose compose.docker.com/v1beta1 compose.docker.com/v1beta2

compose.docker.com就是 Compose on Kubernetes 注册的 API 分组（group）。当前仓库的 API 注册代码中，该分组名定义为GroupName = "compose.docker.com"，见 register.go，版本包括v1beta1、v1beta2，此外 API 目录下还有较新的v1alpha3版本。

3. 部署一个 Stack

准备一个 Compose 文件（README 中的完整示例，定义了三服务应用hellokube）：

version: '3.3' services: db: build: db image: dockersamples/k8s-wordsmith-db words: build: words image: dockersamples/k8s-wordsmith-api deploy: replicas: 5 web: build: web image: dockersamples/k8s-wordsmith-web ports: - "33000:80"

用 Docker CLI 指定 Kubernetes 编排器部署：

$ docker stack deploy --orchestrator=kubernetes -c docker-compose.yml hellokube

这里的关键参数是--orchestrator=kubernetes，它告诉 Docker CLI 本次 stack 操作走 Kubernetes 路径。示例中words服务通过deploy.replicas: 5声明 5 个副本，web服务通过ports将容器 80 端口发布到宿主机的 33000 端口——这些 Compose 语义都会在部署时被映射为 Kubernetes 的 Deployment、Service 等对象。

部署完成后 CLI 会输出 "Waiting for the stack to be stable and running..."，并通过 watch 机制持续跟踪状态（详见下文"部署状态监控"一节）。

4. 移除 Stack

删除整个 stack（连同其 Kubernetes 资源）：

$ docker stack rm --orchestrator=kubernetes hellokube

删除时，Stack 对象的子资源（由 Compose 的 file-based secrets/configs 生成的 Secret/ConfigMap 等）会通过 Kubernetes 的 OwnerReference 级联清理，其实现见 stack.go 中的configMapChildResource/secretChildResource类型。

从源码看实现原理

docker-ce 仓库中保留了完整的 CLI 集成源码，可以帮你理解"Compose 文件是如何变成 Kubernetes 资源的"。

Stack 自定义资源（CRD）

Stack 是该方案的核心自定义资源。以v1beta2版本为例（stack.go），其结构为：

• StackSpec：包含Services（服务配置列表）、Secrets、Configs三个部分；
• StackStatus：记录部署阶段Phase与可读信息Message。

其中ServiceConfig几乎完整覆盖了 Compose 服务的常用字段：Image、Command、Entrypoint、Environment、Ports、Volumes、HealthCheck、Deploy（副本数/更新策略/资源限制/重启策略/放置约束）、Privileged、Tmpfs、WorkingDir等，见 stack.go。

Stack 的Status.Phase定义了四种生命周期状态（stack.go）：

此外v1beta2还定义了ComposeFile（保存 stack 原始 compose 文件内容）、Scale（服务期望/当前副本数映射）等辅助类型，见 composefile_stack_types.go 与 scale.go。

API 版本协商与自动选择

不同 Kubernetes 集群上安装的 compose 组件版本不同，CLI 需要先探测集群支持的 Stack API 版本。在 client.go 中，Factory.Stacks()通过 Kubernetes Discovery 客户端获取compose.docker.com组的 API 版本，然后按v1beta1 → v1beta2 → v1alpha3选择对应的客户端实现。三个版本的能力差异在 convert.go 中有明确定义：

• v1beta1：仅保存完整 Compose 文件文本（Spec.ComposeFile），compose 版本上限为3.5（见 parsing.go）；
• v1beta2：结构化存储StackSpec；
• v1alpha3：额外支持pull secrets（x-kubernetes.pull_secret）、pull policies（x-kubernetes.pull_policy）、stack 内负载均衡（x-kubernetes.internal_service_type）。

如果 Compose 文件使用了高版本特性而集群 API 版本过低，CLI 会直接报错提示"请使用 v1alpha3 或更高版本"。

版本化转换：从 Compose 到 Stack

fromComposeServiceConfig（convert.go）是"Compose 模型 → Stack API 模型"的核心转换函数，它完成的关键映射包括：

• Compose 的deploy.resources.limits/reservations→Resources（CPU 以 NanoCPUs、内存以字节表示）；
• Compose 的deploy.restart_policy→RestartPolicy；
• Compose 的deploy.placement.constraints→Placement，其中 Swarm 风格的约束（node.platform.os、node.platform.arch、node.hostname、node.labels.xxx）会被解析为 Kubernetes 的节点选择器（convert.go）；
• Compose 的ports、secrets、configs、volumes、healthcheck等均映射到对应的 Stack 结构。

值得注意的是x-kubernetes扩展字段：Compose 文件可以在 service 上声明x-kubernetes.pull_secret、x-kubernetes.pull_policy和x-kubernetes.internal_service_type（可选值为ClusterIP/Headless，空值表示自动），这些是 Compose on Kubernetes 特有的 Kubernetes 增强能力（convert.go）。

标签体系：如何识别 stack 与 service

Kubernetes 对象依靠 label selector 被关联回各自的 stack。仓库中定义的三个标签（labels.go）为：

SelectorForStack()会据此生成形如com.docker.stack.namespace=hellokube,com.docker.service.name in (words,web)的 label selector，用于按 stack 过滤 Pod、Service 等资源（labels.go）。

部署流程与冲突检测

RunDeploy（deploy.go）描述了docker stack deploy走 Kubernetes 路径的完整流程：

1. 创建 compose 客户端，从StackClient将 Compose 模型转换为 Stack 对象；
2. 将 file-based 的 Composeconfigs/secrets转换为 KubernetesConfigMap/Secret（见 stack.go）；
3. 冲突检测：检查 stack 中声明的服务名是否已存在于集群。若同名 Service 已存在但缺少com.docker.stack.namespace标签或标签值不同，则判定冲突并报错，避免误覆盖其他 stack 或手工创建的资源。该逻辑在 stackclient.go 的verify函数中实现；v1beta2及以上版本则由服务端处理，客户端无需检查；
4. 调用CreateOrUpdate创建或更新 Stack 对象，并通过 OwnerReference 将子资源挂到 Stack 名下（stackclient.go）；
5. 输出 "Waiting for the stack to be stable and running..." 并启动 watcher 等待就绪。

部署状态监控

部署后 CLI 会同时监听两类对象（watcher.go）：

• Stack 对象：一旦 Stack 的Phase变为Failure，立即报错并携带Message；
• Pod 状态：统计每个服务下 Pod 的 ready / pending / failed / unknown 数量，实时刷新到终端。

输出分两种模式：终端交互模式下用 ANSI 控制码原地刷新每行状态；非终端（管道/CI）模式下只输出状态变化，格式如words: Ready [pod status: 3/5 ready, 0/5 pending, 2/5 failed]（deploy.go）。待全部服务就绪后输出Stack hellokube is stable and running。

命名空间与 kubeconfig

Kubernetes 集成支持--namespace与--kubeconfig两个 flag（见 cli.go），并兼容 Docker context 与 kubectl 上下文：当设置了 Docker 当前 context 时优先从 context 读取 Kubernetes 配置；否则回退到KUBECONFIG环境变量或默认的~/.kube/config（config.go）。stack ls还支持--all-namespaces列出所有命名空间下的 stack。

开发与调试 Compose on Kubernetes

如果要在 Docker Desktop 上对 compose 组件（API server 与 controller）做二次开发或调试，README 提供了完整流程。

前置条件

• make
• Docker Desktop（Mac 或 Windows），引擎版本18.09 及以上
• 设置环境变量DOCKER_BUILDKIT=1启用 BuildKit
• 在 Docker Desktop 设置中启用 Kubernetes
• 实时调试场景还需要支持Delve API version 2远程调试能力的调试器（GoLand 已预配置好 run-config）

安装调试版镜像（带调试符号）

$ make -f debug.Makefile install-debug-images

该命令会：

• 构建带调试符号的镜像
• 运行调试安装器：
  • 在docker命名空间中安装 API server 与 Compose controller 的调试版
  • 创建两个调试用LoadBalancer服务（此模式下不使用）

用 kubectl 验证安装结果：

$ kubectl get all -n docker NAME READY STATUS RESTARTS AGE pod/compose-7c4dfcff76-jgwst 1/1 Running 0 59s pod/compose-api-759f8dbb4b-2z5n2 2/2 Running 0 59s NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE service/compose-api ClusterIP 10.98.42.151 <none> 443/TCP 59s service/compose-api-server-remote-debug LoadBalancer 10.101.198.179 localhost 40001:31693/TCP 59s service/compose-controller-remote-debug LoadBalancer 10.101.158.160 localhost 40000:31167/TCP 59s NAME DESIRED CURRENT UP-TO-DATE AVAILABLE AGE deployment.apps/compose 1 1 1 1 59s deployment.apps/compose-api 1 1 1 1 59s NAME DESIRED CURRENT READY AGE replicaset.apps/compose-7c4dfcff76 1 1 1 59s replicaset.apps/compose-api-759f8dbb4b 1 1 1 59s

此时docker命名空间下有两个 Deployment：compose（controller）与compose-api（API server）。用kubectl describe deployment查看镜像，应能看到镜像名为*-debug:latest。

安装实时调试版（Live Debugging）

$ make -f debug.Makefile install-live-debug-images

与上一个命令的区别是：

• 构建带调试符号的镜像
• 将镜像 entrypoint 改为启动Delve server
• 运行调试安装器：
  • 在docker命名空间安装 API server 与 Compose controller 的调试版
  • 创建两个调试用LoadBalancer服务：
    • localhost:40000→ Compose controller
    • localhost:40001→ API server
• API server 与 Compose controller 只有在调试器 attach 之后才会启动

连接调试器有两种方式：

• 使用 GoLand：选择仓库.idea中的Debug all配置，打上断点后启动调试器；
• 使用任意兼容 Delve 的调试器，指向localhost:40000与localhost:40001。用终端的话，先执行dlv connect localhost:40000，然后输入continue并回车。

用kubectl get all -n docker可确认组件已安装。验证 API server 是否启动，查看其日志：

$ kubectl logs -f -n docker deployment.apps/compose-api compose API server listening at: [::]:40000 ERROR: logging before flag.Parse: I1207 15:25:13.760739 11 plugins.go:158] Loaded 2 mutating admission controller(s) successfully in the following order: NamespaceLifecycle,MutatingAdmissionWebhook. ERROR: logging before flag.Parse: I1207 15:25:13.763211 11 plugins.go:161] Loaded 1 validating admission controller(s) successfully in the following order: ValidatingAdmissionWebhook. ERROR: logging before flag.Parse: W1207 15:25:13.767429 11 client_config.go:552] Neither --kubeconfig nor --master was specified. Using the inClusterConfig. This might not work. ERROR: logging before flag.Parse: W1207 15:25:13.851500 11 genericapiserver.go:319] Skipping API compose.docker.com/storage because it has no resources. ERROR: logging before flag.Parse: I1207 15:25:13.998154 11 serve.go:116] Serving securely on [::]:9443

（日志中的ERROR:前缀来自 kube-apiserver 组件在flag.Parse之前的标准输出行为，属于正常现象。）Skipping API compose.docker.com/storage表示该 group 下没有资源会被注册。最后一行Serving securely on [::]:9443表示 API server 已就绪。

验证 Compose controller 是否启动，查看其日志：

kubectl logs -f -n docker deployment.apps/compose API server listening at: [::]:40000 Version: v0.4.16-dirty Git commit: b2e3a6b-dirty OS/Arch: linux/amd64 Built: Fri Dec 7 15:18:13 2018 time="2018-12-07T15:25:19Z" level=info msg="Controller ready"

controller 打印版本、Git commit、构建信息，最后输出Controller ready表示调谐循环（reconcile loop）已就绪——从这一刻起，它开始监听 Stack 对象并驱动其下 Deployment/Service/Pod 的创建。

恢复默认版本

调试完成后，需要恢复默认的 Compose on Kubernetes：只需重启 Kubernetes 集群——在 Docker Desktop 设置中先停用再启用 Kubernetes，或直接重启 Docker Desktop。更多细节可参考原项目的 contributing 与 debugging 指南。

在云端与本地集群上部署

除 Docker Desktop 自带外，Compose on Kubernetes 也可以安装到其他 Kubernetes 发行版。原项目提供了四份部署指南（说明：本仓库仅 vendored 了 README，具体指南文件位于上游项目的 docs 目录，未随仓库分发）：

• Azure AKS：在 Azure 托管的 Kubernetes 服务上安装组件并启用 stack 部署；
• GKE：在 Google Kubernetes Engine 上安装；
• Microk8s：在轻量级、本地化的 Microk8s 上安装，适合开发与边缘场景；
• Minikube：在本地单节点 Minikube 上安装，适合无 Docker Desktop 环境（如 Linux）下的本地体验。

这些环境安装完 compose 组件后，使用方法与本篇一致：先kubectl api-versions | grep compose确认 API 就绪，再用docker stack deploy --orchestrator=kubernetes部署。

局限与适用范围

结合仓库源码，使用前应了解以下几点：

• 编排器选择是显式的：必须为 stack 命令显式指定--orchestrator=kubernetes（或通过配置全局设置）；若未指定，CLI 会报错"no orchestrator specified: use either kubernetes or swarm"（cmd.go）。当同时使用 swarm 与 Kubernetes 编排器时，CLI 还会校验 Docker daemon 主机与 Kubernetes API 主机是否匹配，避免在错误的集群上部署（cli.go）。
• Compose 功能子集：并非所有 Compose 指令都会被转换。CLI 会对不支持的字段给出告警；v1beta1版本仅接受 compose schema 3.5 及以下。高版本独有的 Kubernetes 增强（pull secret、pull policy、stack 内负载均衡）仅在v1alpha3可用。
• 文档对应版本：README 示例使用version: '3.3'与 Docker Desktop 18.09+ 环境；当前 docker-ce 仓库对应时代的 CLI 集成即基于上述源码实现，后续版本的功能差异请以你所使用的 Docker Desktop/Enterprise 版本为准。

参考资源

• 组件 README（本文依据）：components/cli/vendor/github.com/docker/compose-on-kubernetes/README.md
• Stack 类型定义（v1beta2）：api/compose/v1beta2/stack.go
• Stack 类型定义（v1alpha3，含x-kubernetes扩展）：api/compose/v1alpha3/stack.go
• 标签体系：api/labels/labels.go
• CLI 部署流程：cli/command/stack/kubernetes/deploy.go
• Compose → Stack 转换：cli/command/stack/kubernetes/convert.go
• Stack 客户端与冲突检测：cli/command/stack/kubernetes/stackclient.go
• 部署状态监控：cli/command/stack/kubernetes/watcher.go
• API 版本发现与选择：cli/command/stack/kubernetes/client.go

• 容器运行时
• 云原生