GitOps实践指南：基于ArgoCD的声明式持续部署

概述

GitOps 是一种以 Git 为唯一信源的运维理念，通过声明式配置实现基础设施和应用的自动化部署。其核心思想是：将所有配置写入 Git 仓库，每次提交自动同步到集群，确保环境一致性。

ArgoCD 是目前最流行的 GitOps 工具之一，专注于 Kubernetes 环境的持续交付。本文介绍 ArgoCD 的部署、配置及最佳实践。

环境准备

前置条件

  • Kubernetes 1.19+
  • kubectl 已配置集群访问
  • Git 仓库（GitHub/GitLab/私有均可）

安装 ArgoCD

1
2
3
4
5
6
7
8
# 创建命名空间
kubectl create namespace argocd

# 部署 ArgoCD
kubectl apply -n argocd -f https://raw.githubusercontent.com/argoproj/argo-cd/stable/manifests/install.yaml

# 查看服务（等待 pod 就绪）
kubectl get pods -n argocd

生产环境建议使用高可用版本：

1
kubectl apply -n argocd -f https://raw.githubusercontent.com/argoproj/argo-cd/stable/manifests/ha/install.yaml

访问 ArgoCD UI

方法一：NodePort（快速验证）

1
2
kubectl patch svc argocd-server -n argocd -p '{"spec":{"type":"NodePort"}}'
kubectl get svc argocd-server -n argocd

方法二：Ingress（生产推荐）

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: argocd-ingress
  namespace: argocd
  annotations:
    nginx.ingress.kubernetes.io/ssl-redirect: "true"
spec:
  rules:
  - host: argocd.example.com
    http:
      paths:
      - path: /
        pathType: Prefix
        backend:
          service:
            name: argocd-server
            port:
              number: 443

获取初始密码

1
2
# 用户名：admin
kubectl get secret argocd-initial-admin-secret -n argocd -o jsonpath="{.data.password}" | base64 -d

应用创建与管理

方式一：Web UI 创建

  1. 登录 ArgoCD Web UI
  2. 点击 New Application
  3. 填写应用信息：
    • Project：default
    • Sync Policy：Automatic（自动同步）
    • Repository URL：Git 仓库地址
    • Revision：HEAD 或具体分支/标签
    • Path：应用在仓库中的路径
    • Cluster：目标集群（https://kubernetes.default.svc 表示本地集群）
    • Namespace：部署目标命名空间

方式二：声明式 YAML

创建 Application 资源：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: demo-app
  namespace: argocd
spec:
  project: default
  source:
    repoURL: https://github.com/yourorg/demo.git
    targetRevision: main
    path: ./k8s/prod
  destination:
    server: https://kubernetes.default.svc
    namespace: production
  syncPolicy:
    automated:
      prune: true        # 自动删除不在 Git 中的资源
      selfHeal: true     # 自动修复集群与 Git 的差异

应用同步：

1
kubectl apply -f demo-app.yaml

GitHub Actions 集成示例

在仓库中创建 .github/workflows/sync.yml：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
name: Sync to Cluster
on:
  push:
    branches: [main]
jobs:
  sync:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v3
    - name: Login to ArgoCD
      env:
        ARGOCD_AUTH_TOKEN: ${{ secrets.ARGOCD_TOKEN }}
      run: |
        argocd login argocd.example.com --username admin --password ${{ secrets.ARGOCD_PASSWORD }}
    - name: Sync Application
      run: |
        argocd app sync demo-app --force

在 ArgoCD 中生成访问令牌：Settings → User Info → Tokens → Create New Token。

最佳实践

1. 分环境管理

建议使用独立仓库或路径区分环境：

1
2
3
4
5
6
7
8
9
10
your-repo/
├── base/              # 共享配置（命名空间、RBAC）
│   ├── namespace.yaml
│   └── rbac.yaml
├── prod/              # 生产环境覆盖
│   ├── kustomization.yaml
│   └── deployment.yaml
└── dev/               # 开发环境覆盖
    ├── kustomization.yaml
    └── deployment.yaml

推荐配合 Kustomize 使用，实现环境差异化配置。

2. 安全建议

  • 使用 ReadOnly 模式部署公共镜像，避免使用 latest 标签
  • 配置 Application 的 spec.ignoreDifferences 忽略特定字段（如 operator 自动管理的字段）
  • 启用 ArgoCD 的 RBAC，限制不同团队的操作权限
  • 定期轮换 ArgoCD 服务账户的 Token

3. 同步策略选择

策略 适用场景
Automated + Prune + SelfHeal 开发环境，快速迭代
Automated（仅自动应用） 预发布环境，需要人工确认变更
Manual 生产环境，强制人工审批

生产环境建议关闭 selfHeal，避免意外覆盖手动修改。

常见问题处理

应用处于 OutOfSync 状态

1
2
3
4
5
6
7
8
# 查看详细差异
argocd app diff demo-app

# 手动同步
argocd app sync demo-app

# 强制同步（覆盖集群状态）
argocd app sync demo-app --force

同步失败排查

1
2
3
4
5
# 查看 ArgoCD Pod 日志
kubectl logs -n argocd -l app.kubernetes.io/name=argocd-application-controller

# 查看具体资源状态
kubectl describe app demo-app -n argocd

资源卡在 Terminating

通常是 finalizer 未清理导致：

1
2
3
4
5
# 查看资源 finalizers
kubectl get deployment your-app -n production -o jsonpath='{.spec.finalizers}'

# 手动移除 finalizer
kubectl patch deployment your-app -n production -p '{"metadata":{"finalizers":null}}'

总结

GitOps 通过「Git 即真相」的理念，大幅简化了部署流程，降低了人为错误风险。ArgoCD 作为 CNCF 毕业项目，生态成熟，社区活跃，推荐在生产环境中优先考虑。

关键要点：

  1. 声明式配置优于命令式操作
  2. 自动同步适合开发环境，生产环境建议人工审批
  3. 配合 Kustomize 实现多环境管理
  4. 安全第一，合理使用 RBAC 和 Token 管理