3. 单集群GitOps流水线实战：从Git仓库到Kubernetes集群的完整部署流程

本章将带领你从零搭建一条完整的单集群GitOps流水线，实现第一个“Hello World”应用的自动同步。通过实战，你将深入理解GitOps的核心工作流：Git仓库作为唯一事实来源、Argo CD自动检测差异并同步、集群状态与声明状态保持一致。

3.1 流水线架构概览

下图展示了单集群GitOps流水线的核心组件与数据流向。开发者仅需向Git仓库推送YAML清单，Argo CD自动完成后续所有同步操作。

3.2 准备Git仓库与应用清单

首先，创建一个专用Git仓库，用于存放应用的Kubernetes声明式清单。本实战使用一个简单的Nginx“Hello World”应用。

3.2.1 创建仓库结构

# 在GitHub/GitLab/Gitee上创建仓库，例如：hello-world-gitops
# 克隆到本地
git clone https://github.com/your-org/hello-world-gitops.git
cd hello-world-gitops

# 创建目录结构
mkdir -p apps/hello-world/overlays/production
mkdir -p apps/hello-world/base

3.2.2 编写基础K8s清单

在 apps/hello-world/base 目录下创建以下文件：

文件名	资源类型	说明
deployment.yaml	Deployment	定义Nginx容器副本数、镜像版本、端口
service.yaml	Service	暴露Nginx服务，类型为ClusterIP
kustomization.yaml	Kustomize	声明base资源列表

# apps/hello-world/base/deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: hello-world
  labels:
    app: hello-world
spec:
  replicas: 2
  selector:
    matchLabels:
      app: hello-world
  template:
    metadata:
      labels:
        app: hello-world
    spec:
      containers:
      - name: nginx
        image: nginx:1.25-alpine
        ports:
        - containerPort: 80
        resources:
          requests:
            memory: "64Mi"
            cpu: "100m"
          limits:
            memory: "128Mi"
            cpu: "200m"

# apps/hello-world/base/service.yaml
apiVersion: v1
kind: Service
metadata:
  name: hello-world-svc
  labels:
    app: hello-world
spec:
  selector:
    app: hello-world
  ports:
  - port: 80
    targetPort: 80
    protocol: TCP
  type: ClusterIP

# apps/hello-world/base/kustomization.yaml
apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
resources:
  - deployment.yaml
  - service.yaml
commonLabels:
  app.kubernetes.io/managed-by: argocd

3.2.3 编写Production Overlay

在 apps/hello-world/overlays/production 目录下创建覆盖配置：

# apps/hello-world/overlays/production/kustomization.yaml
apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
namespace: production
bases:
  - ../../base
patches:
  - target:
      kind: Deployment
      name: hello-world
    patch: |-
      - op: replace
        path: /spec/replicas
        value: 3
      - op: replace
        path: /spec/template/spec/containers/0/image
        value: nginx:1.25-alpine

3.3 推送代码并创建Argo CD Application

将代码推送到Git仓库后，通过Argo CD CLI或UI创建Application资源，建立Git仓库与Kubernetes集群的关联。

3.3.1 推送代码

git add .
git commit -m "feat: init hello-world gitops manifests"
git push origin main

3.3.2 通过CLI创建Application

argocd app create hello-world \
  --repo https://github.com/your-org/hello-world-gitops.git \
  --path apps/hello-world/overlays/production \
  --dest-server https://kubernetes.default.svc \
  --dest-namespace production \
  --sync-policy automated \
  --auto-prune \
  --self-heal

参数	值	说明
--repo	Git仓库URL	Argo CD拉取清单的来源
--path	overlays/production	指定Kustomize overlay目录
--dest-server	集群API Server地址	单集群场景使用内置地址
--sync-policy automated	自动同步	Git仓库变化时自动触发同步
--auto-prune	自动清理	删除Git中已移除的资源
--self-heal	自愈	集群手动修改后自动恢复

3.4 验证自动同步与自愈能力

Application创建成功后，Argo CD会自动执行首次同步。以下步骤验证流水线的核心能力。

3.4.1 查看同步状态

# 查看Application状态
argocd app get hello-world

# 输出示例（关键字段）
# Health Status:  Healthy
# Sync Status:    Synced
# Revision:       abc1234
# Sync Policy:    Automated

3.4.2 验证集群资源

# 确认命名空间和Pod已创建
kubectl get ns production
kubectl -n production get pods,svc

# 预期输出
# NAME                              READY   STATUS    RESTARTS   AGE
# pod/hello-world-7d8f9c6b8-2xq3k   1/1     Running   0          2m
# pod/hello-world-7d8f9c6b8-9m4n7   1/1     Running   0          2m
# pod/hello-world-7d8f9c6b8-k6r2p   1/1     Running   0          2m
# 
# NAME                      TYPE        CLUSTER-IP      EXTERNAL-IP   PORT(S)   AGE
# service/hello-world-svc   ClusterIP   10.96.123.45    <none>        80/TCP    2m

3.4.3 测试自愈能力

手动删除一个Pod，观察Argo CD自动恢复：

# 删除一个Pod
kubectl -n production delete pod hello-world-7d8f9c6b8-2xq3k

# 等待几秒后查看Pod数量
kubectl -n production get pods | grep hello-world | wc -l
# 输出: 3  （自动恢复为3个副本）

3.5 通过Git触发更新

GitOps的核心优势在于：所有变更通过Git提交驱动。下面演示修改Nginx镜像版本，触发自动同步。

3.5.1 修改镜像版本

# 编辑overlay中的patch文件
# 将 nginx:1.25-alpine 改为 nginx:1.26-alpine
vim apps/hello-world/overlays/production/kustomization.yaml

# 提交并推送
git add .
git commit -m "chore: bump nginx to 1.26-alpine"
git push origin main

3.5.2 观察自动同步

# 实时查看同步日志
argocd app logs hello-world --follow

# 查看滚动更新过程
kubectl -n production get pods -w

Argo CD会在检测到Git仓库新提交后（默认轮询间隔3分钟），自动执行同步操作，触发Kubernetes滚动更新。

3.6 流水线关键指标与排障

下表总结了单集群GitOps流水线的关键监控指标和常见问题处理方式：

指标/问题	正常值/表现	异常处理
Sync Status	Synced	OutOfSync → 检查Git仓库与集群差异
Health Status	Healthy	Degraded → 查看Pod日志/事件
同步延迟	< 5分钟	配置Webhook减少轮询间隔
Prune冲突	无	检查 --auto-prune 是否启用
镜像拉取失败	无	检查镜像仓库认证/镜像标签

3.7 本章小结

通过本实战，你已完成以下关键里程碑：

• 搭建Git仓库：使用Kustomize组织多环境清单
• 创建Argo CD Application：配置自动同步、自愈、自动清理
• 验证自动部署：首次同步即完成应用部署
• 测试自愈能力：手动破坏后自动恢复
• 触发Git驱动更新：修改镜像版本自动触发滚动更新