从Docker Compose到Kubernetes：无缝迁移的完整实践指南

引言：告别复杂配置，拥抱容器编排新范式

你是否还在为Docker Compose项目迁移到Kubernetes而头疼？手动转换配置文件、学习复杂的Kubernetes概念、处理服务发现和网络问题——这些痛点是否让你望而却步？本文将带你探索如何利用Compose on Kubernetes工具，轻松实现Docker Compose到Kubernetes的无缝迁移，让你在保留熟悉的Compose语法的同时，充分享受Kubernetes强大的编排能力。

读完本文，你将能够：

• 理解Compose on Kubernetes的核心架构和工作原理
• 掌握在不同Kubernetes环境中安装Compose on Kubernetes的方法
• 熟练使用Docker CLI部署和管理Kubernetes上的Compose应用
• 深入了解Compose文件到Kubernetes资源的映射关系
• 解决迁移过程中可能遇到的常见问题

一、Compose on Kubernetes：架构解析与核心优势

1.1 什么是Compose on Kubernetes？

Compose on Kubernetes是一个开源工具，它允许你直接将Docker Compose文件部署到Kubernetes集群上。这意味着你可以继续使用熟悉的Compose语法来定义应用，同时利用Kubernetes的强大功能进行编排和管理。

1.2 核心架构

Compose on Kubernetes由两个主要的服务器组件和客户端工具构成：

flowchart TD
    Client[Docker CLI] -->|kubectl/API| K8sAPI[Kubernetes API Server]
    K8sAPI -->|Aggregation| ComposeAPI[Compose API Server]
    ComposeAPI -->|存储| Etcd[(etcd)]
    ComposeController[Compose Controller] -->|监听/协调| ComposeAPI
    ComposeController -->|管理资源| K8sAPI
    subgraph Kubernetes Cluster
        K8sAPI
        ComposeAPI
        ComposeController
        Etcd
    end

1.2.1 Compose API Server

Compose API Server通过API服务器聚合机制扩展了Kubernetes API，添加了用于创建和管理stack的路由。它负责：

• 接收和验证来自客户端的请求
• 将stack存储在etcd键值存储中
• 提供声明式REST API
• 处理不同版本Compose文件的转换（如v1beta1到v1beta2）

1.2.2 Compose Controller

Compose Controller是核心的协调组件，负责：

• 监视etcd中的stack对象变化
• 将stack分解为Kubernetes资源
• 协调当前集群状态与期望状态
• 聚合stack的整体状态

1.3 工作流程

sequenceDiagram
    participant 用户
    participant DockerCLI[Docker CLI]
    participant K8sAPI[Kubernetes API Server]
    participant ComposeAPI[Compose API Server]
    participant Etcd[etcd]
    participant Controller[Compose Controller]
    
    用户->>DockerCLI: docker stack deploy --orchestrator=kubernetes -c docker-compose.yml myapp
    DockerCLI->>K8sAPI: POST /apis/compose.docker.com/v1beta2/namespaces/default/stacks
    K8sAPI->>ComposeAPI: 转发请求
    ComposeAPI->>Etcd: 存储stack对象
    Etcd-->>ComposeAPI: 确认存储
    ComposeAPI-->>K8sAPI: 返回响应
    K8sAPI-->>DockerCLI: 部署成功
    Controller->>ComposeAPI: 监视stack变化
    ComposeAPI->>Controller: 推送stack更新
    loop 协调循环
        Controller->>K8sAPI: 创建/更新Kubernetes资源
        K8sAPI->>Controller: 返回资源状态
        Controller->>ComposeAPI: 更新stack状态
    end

1.4 核心优势

1. 降低学习曲线：无需学习复杂的Kubernetes YAML配置，继续使用熟悉的Compose语法
2. 声明式API：基于Kubernetes的声明式API模型，确保系统状态与期望状态一致
3. 无缝集成：与Kubernetes生态系统深度集成，支持所有标准Kubernetes功能
4. 简化部署流程：一条命令即可完成整个应用栈的部署和管理
5. 保留Docker CLI体验：使用熟悉的docker stack命令进行应用生命周期管理

二、环境准备与安装指南

2.1 支持的环境

Compose on Kubernetes可在多种Kubernetes环境中安装：

• Docker Desktop（推荐用于开发环境）
• Azure AKS
• Google GKE
• MicroK8s
• Minikube
• Kind

2.2 前置要求

• Kubernetes集群（1.14+推荐）
• kubectl命令行工具
• Docker CLI（18.09+）
• Helm（用于部署etcd）

2.3 在Docker Desktop上安装（推荐）

2.3.1 启用Kubernetes

1. 打开Docker Desktop设置
2. 导航到Kubernetes选项卡
3. 勾选"Enable Kubernetes"
4. 点击"Apply & Restart"

2.3.2 创建命名空间

kubectl create namespace compose

2.3.3 部署etcd

Compose on Kubernetes需要独立的etcd实例（不同于kube-system中的etcd）：

helm repo add stable https://charts.helm.sh/stable
helm install compose-etcd stable/etcd --namespace compose \
  --set replicaCount=1 \
  --set resources.requests.memory=128Mi \
  --set resources.limits.memory=256Mi \
  --set persistentVolume.enabled=false \
  --set service.type=ClusterIP

2.3.4 下载并运行安装程序

# 下载适合你系统的安装程序
# 对于Linux
curl -LO https://github.com/docker/compose-on-kubernetes/releases/download/v0.4.16/installer-linux
chmod +x installer-linux

# 对于macOS
curl -LO https://github.com/docker/compose-on-kubernetes/releases/download/v0.4.16/installer-darwin
chmod +x installer-darwin

# 运行安装程序
./installer-linux -namespace=compose -etcd-servers=http://compose-etcd-client:2379

2.3.5 验证安装

kubectl api-versions | grep compose

预期输出：

compose.docker.com/v1beta1
compose.docker.com/v1beta2

检查Pod状态：

kubectl get pods -n compose

2.4 在其他Kubernetes环境中安装

环境	安装指南	主要步骤
Azure AKS	install-on-aks.md	1. 创建AKS集群 2. 部署etcd 3. 安装Compose on Kubernetes
Google GKE	install-on-gke.md	1. 创建GKE集群 2. 配置RBAC 3. 部署etcd 4. 安装Compose on Kubernetes
MicroK8s	install-on-microk8s.md	1. 启用必要插件 2. 配置kubectl 3. 部署etcd 4. 安装Compose on Kubernetes
Minikube	install-on-minikube.md	1. 启动Minikube 2. 部署etcd 3. 安装Compose on Kubernetes
Kind	install-on-kind.md	1. 创建Kind集群 2. 部署etcd 3. 安装Compose on Kubernetes

三、实战指南：部署应用

3.1 准备Compose文件

以下是一个简单的多服务应用示例（保存为docker-compose.yml）：

version: '3.3'

services:
  db:
    image: dockersamples/k8s-wordsmith-db
    volumes:
      - db-data:/var/lib/postgresql/data

  words:
    image: dockersamples/k8s-wordsmith-api
    deploy:
      replicas: 5
    depends_on:
      - db

  web:
    image: dockersamples/k8s-wordsmith-web
    ports:
      - "33000:80"
    depends_on:
      - words

volumes:
  db-data:

3.2 部署应用栈

使用Docker CLI部署应用：

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

3.3 验证部署

3.3.1 检查stack状态

kubectl get stacks compose.docker.com

输出示例：

NAME       CREATED AT
hellokube  2023-05-15T10:30:00Z

3.3.2 查看stack详情

kubectl describe stack hellokube

3.3.3 检查创建的资源

kubectl get all -l com.docker.compose.stack=hellokube

输出示例：

NAME                           READY   STATUS    RESTARTS   AGE
pod/hellokube-db-0             1/1     Running   0          2m
pod/hellokube-words-7f9b4      1/1     Running   0          2m
pod/hellokube-words-8d2e7      1/1     Running   0          2m
pod/hellokube-words-9a3c5      1/1     Running   0          2m
pod/hellokube-words-b2d1f      1/1     Running   0          2m
pod/hellokube-words-c4e3g      1/1     Running   0          2m
pod/hellokube-web-6b8d7f9c8d   1/1     Running   0          2m

NAME                    TYPE           CLUSTER-IP      EXTERNAL-IP   PORT(S)          AGE
service/hellokube-db    ClusterIP      None            <none>        5432/TCP         2m
service/hellokube-web   LoadBalancer   10.100.200.201  <pending>     33000:30080/TCP  2m

NAME                      READY   UP-TO-DATE   AVAILABLE   AGE
deployment.apps/hellokube-web   1/1     1            1           2m

NAME                                 DESIRED   CURRENT   READY   AGE
replicaset.apps/hellokube-web-6b8d7f9c8d   1         1         1       2m

NAME                            READY   AGE
statefulset.apps/hellokube-db   1/1     2m
statefulset.apps/hellokube-words   5/5     2m

3.3.4 访问应用

如果使用的是Docker Desktop或有外部IP的环境：

curl http://localhost:33000

对于没有外部IP的环境（如Minikube），使用端口转发：

kubectl port-forward service/hellokube-web 33000:80

然后在浏览器中访问 http://localhost:33000

3.4 扩展服务

通过更新Compose文件中的deploy.replicas值，然后重新部署：

services:
  words:
    image: dockersamples/k8s-wordsmith-api
    deploy:
      replicas: 10  # 从5扩展到10

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

3.5 查看日志

# 查看web服务日志
kubectl logs -l com.docker.compose.service=web

# 查看特定pod日志
kubectl logs hellokube-web-6b8d7f9c8d-xyzabc

3.6 删除应用栈

docker stack rm --orchestrator=kubernetes hellokube

四、Compose到Kubernetes资源的映射

理解Compose文件如何映射到Kubernetes资源对于调试和优化应用非常重要。以下是主要的映射关系：

4.1 基本映射

Docker Compose概念	Kubernetes概念	说明
Stack	CustomResource (compose.docker.com/Stack)	整个应用栈的顶级资源
Service	Deployment/StatefulSet	根据是否有持久卷决定
Service (单实例)	StatefulSet (1副本)	带持久卷的单实例服务
Volume	PersistentVolumeClaim	持久化存储
Network	ClusterIP Service + DNS	服务发现
Port mapping	Service (NodePort/LoadBalancer)	外部访问
Deploy replicas	Deployment.spec.replicas	副本数量
Healthcheck	Liveness/Readiness Probe	健康检查

4.2 详细映射示例

以我们之前的docker-compose.yml为例：

Compose服务 -> Kubernetes资源

mindmap
  root((hellokube stack))
    db (db service)
      StatefulSet (hellokube-db)
      ClusterIP Service (hellokube-db)
      PersistentVolumeClaim (db-data)
    words (words service)
      StatefulSet (hellokube-words)
      ClusterIP Service (hellokube-words)
      5 Replicas
    web (web service)
      Deployment (hellokube-web)
      LoadBalancer Service (hellokube-web)
      NodePort 33000:80

标签和选择器

Compose on Kubernetes为所有创建的资源添加了标签，以便跟踪和管理：

标签	说明	示例值
com.docker.compose.stack	所属stack名称	hellokube
com.docker.compose.service	所属服务名称	web
com.docker.compose.project	项目名称（通常与stack相同）	hellokube
com.docker.compose.version	Compose版本	3.3

这些标签可用于查询相关资源：

# 查找属于hellokube stack的所有资源
kubectl get all -l com.docker.compose.stack=hellokube

# 查找web服务的所有pod
kubectl get pods -l com.docker.compose.service=web

五、高级配置与优化

5.1 资源限制

可以在Compose文件中为服务添加资源限制，这些将映射到Kubernetes的资源请求和限制：

services:
  web:
    image: dockersamples/k8s-wordsmith-web
    deploy:
      resources:
        limits:
          cpus: '0.5'
          memory: 512M
        reservations:
          cpus: '0.2'
          memory: 256M

映射到Kubernetes的：

resources:
  limits:
    cpu: 500m
    memory: 512Mi
  requests:
    cpu: 200m
    memory: 256Mi

5.2 健康检查

services:
  web:
    image: dockersamples/k8s-wordsmith-web
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost/health"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 40s

映射到Kubernetes的：

livenessProbe:
  httpGet:
    path: /health
    port: 80
  initialDelaySeconds: 40
  periodSeconds: 30
  timeoutSeconds: 10
  failureThreshold: 3
readinessProbe:
  httpGet:
    path: /health
    port: 80
  initialDelaySeconds: 40
  periodSeconds: 30
  timeoutSeconds: 10
  failureThreshold: 3

5.3 环境变量和配置

5.3.1 环境变量

services:
  web:
    image: dockersamples/k8s-wordsmith-web
    environment:
      - WORDS_API=http://words:8080
      - LOG_LEVEL=info
    env_file:
      - .env.production

5.3.2 配置文件

对于更复杂的配置，可以使用ConfigMap：

services:
  web:
    image: dockersamples/k8s-wordsmith-web
    volumes:
      - type: bind
        source: ./config
        target: /app/config
        read_only: true

这将创建一个ConfigMap并挂载到容器中。

5.4 滚动更新

Compose on Kubernetes默认使用滚动更新策略：

services:
  web:
    image: dockersamples/k8s-wordsmith-web:1.0
    deploy:
      update_config:
        parallelism: 2
        delay: 10s
      restart_policy:
        condition: on-failure

更新镜像版本后重新部署将触发滚动更新：

services:
  web:
    image: dockersamples/k8s-wordsmith-web:2.0  # 更新版本

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

六、常见问题与解决方案

6.1 安装问题

6.1.1 API服务器聚合未启用

症状：安装后kubectl api-versions | grep compose无输出

解决方案：确保Kubernetes集群启用了API聚合。对于自管理集群，检查API服务器启动参数：

--enable-aggregator-routing=true

6.1.2 etcd部署失败

症状：etcd pod一直处于Pending或Error状态

解决方案：检查资源是否充足，对于开发环境，可以减少etcd资源需求：

helm install compose-etcd stable/etcd --namespace compose \
  --set replicaCount=1 \
  --set resources.requests.cpu=100m \
  --set resources.requests.memory=128Mi \
  --set resources.limits.cpu=500m \
  --set resources.limits.memory=256Mi \
  --set persistentVolume.enabled=false

6.2 部署问题

6.2.1 服务无法访问

症状：应用已部署，但无法通过端口访问

排查步骤：

1. 检查服务是否创建：kubectl get svc -l com.docker.compose.stack=hellokube
2. 检查服务端点是否就绪：kubectl describe svc hellokube-web
3. 检查pod状态：kubectl get pods -l com.docker.compose.stack=hellokube
4. 检查pod日志：kubectl logs <pod-name>

6.2.2 依赖服务启动顺序问题

症状：应用启动时出现连接数据库失败

解决方案：使用健康检查和依赖等待：

services:
  words:
    image: dockersamples/k8s-wordsmith-api
    depends_on:
      - db
    deploy:
      restart_policy:
        condition: on-failure
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost/health"]
      interval: 5s
      timeout: 5s
      retries: 5

6.3 性能问题

6.3.1 资源限制导致服务不稳定

症状：pod频繁重启，日志中有OOM（内存溢出）错误

解决方案：调整资源限制：

services:
  web:
    deploy:
      resources:
        limits:
          memory: 1G  # 增加内存限制

七、开发与贡献

7.1 本地开发环境设置

如果你想为Compose on Kubernetes贡献代码或进行自定义开发，可以按照以下步骤设置开发环境：

7.1.1 前置要求

• Git
• Go 1.12+
• Docker Desktop（Mac或Windows），引擎版本18.09+
• 启用Buildkit：export DOCKER_BUILDKIT=1
• 启用Docker Desktop中的Kubernetes

7.1.2 获取代码

git clone https://gitcode.com/gh_mirrors/co/compose-on-kubernetes.git
cd compose-on-kubernetes

7.1.3 构建调试版本

make -f debug.Makefile install-debug-images

此命令将：

• 构建带有调试符号的镜像
• 在docker命名空间中安装API服务器和Compose控制器的调试版本
• 创建调试用的LoadBalancer服务

7.1.4 验证开发安装

kubectl get all -n docker

7.2 提交贡献

Compose on Kubernetes欢迎社区贡献。如果你有改进或修复，请遵循以下步骤：

1. Fork仓库
2. 创建特性分支：git checkout -b my-new-feature
3. 提交更改：git commit -am 'Add some feature'
4. 推送到分支：git push origin my-new-feature
5. 创建Pull Request

八、总结与展望

Compose on Kubernetes为熟悉Docker Compose的开发者提供了一条平滑过渡到Kubernetes的路径。它允许你继续使用简洁的Compose语法，同时利用Kubernetes强大的编排能力。

8.1 主要优势回顾

• 降低学习门槛：无需学习复杂的Kubernetes YAML配置
• 提高生产力：使用简洁的Compose语法快速定义和部署应用
• 保留熟悉工具链：继续使用Docker CLI进行应用管理
• 无缝迁移：现有Compose文件几乎无需修改即可部署到Kubernetes

8.2 注意事项

• 该项目目前已不再维护，对于生产环境，请考虑其他替代方案
• 对于复杂的Kubernetes原生功能，可能仍需要直接使用Kubernetes API或配置

8.3 替代方案

如果Compose on Kubernetes不再满足你的需求，可以考虑以下替代方案：

1. Kompose：将Compose文件转换为Kubernetes YAML文件
2. kustomize：Kubernetes原生的配置管理工具
3. Helm：Kubernetes包管理工具，适合复杂应用
4. Docker Compose v2+：支持docker compose up --compatibility模式生成Kubernetes资源

通过本文介绍的方法，你应该能够轻松地将Docker Compose应用部署到Kubernetes集群，并利用Kubernetes的强大功能进行扩展和管理。无论你是刚开始接触容器编排，还是从Docker Swarm迁移到Kubernetes，Compose on Kubernetes都提供了一个简单而强大的过渡方案。

希望本文对你有所帮助！如果你有任何问题或反馈，请在评论区留言。别忘了点赞、收藏并关注我们，获取更多容器和Kubernetes相关的教程和最佳实践。