450 lines
15 KiB
Markdown
450 lines
15 KiB
Markdown
---
|
||
tags: [gitops, argocd, flux, kubernetes, deployment, cicd, app-of-apps]
|
||
create time: 2026-05-17 10:00
|
||
update time: 2026-05-17 10:30
|
||
---
|
||
|
||
# GitOps 与 ArgoCD
|
||
|
||
## 概述
|
||
|
||
本文档深入讲解 GitOps 工作流和 ArgoCD 的使用。内容覆盖：从"传统 CI/CD 的痛点"到 "Git 即真相源"，ArgoCD 架构解析、Application CRD 编写、App of Apps 模式、Helm/Kustomize 混合使用、同步钩子与安全实践。工具选型对比参见 [[../03-CICD与GitOps]]。
|
||
|
||
## 核心思想：让集群自己"拉取"状态
|
||
|
||
> [!question] 谁来"推动"变更到集群？
|
||
>
|
||
> 传统模式下，Jenkins 拿着 kubeconfig SSH 到 K8s 执行 `kubectl apply`。但问题来了：如果有人在集群里直接改了配置（比如手动 `kubectl edit deployment`），Jenkins 并不知道——这就是**配置漂移**。
|
||
>
|
||
> GitOps 的答案：**让 K8s 集群自己"拉取"自己的状态。** Git 仓库是唯一真相源，任何变更都通过 PR 进入 Git，工具自动同步到集群。
|
||
|
||
```mermaid
|
||
flowchart LR
|
||
Dev["开发者 PR"] -->|"修改 K8s manifest"| Git[(Git Repo)]
|
||
|
||
subgraph Cluster["K8s Cluster"]
|
||
Argo["ArgoCD / Flux"] -->|同步| K8sState["Pod/Service/ConfigMap"]
|
||
end
|
||
|
||
Git -.->|Webhook Polling| Argo
|
||
|
||
Argo -->|"检测到差异"| Diff{"状态一致?"}
|
||
Diff -- 否 --> Sync["自动同步到 K8s ✅"]
|
||
Diff -- 是 --> OK["已一致 ⏸️"]
|
||
|
||
style Git fill:#e3f2fd
|
||
style Argo fill:#fff3e0
|
||
style K8sState fill:#e8f5e9
|
||
```
|
||
|
||
## Push vs Pull：本质区别
|
||
|
||
| | 传统 CI/CD (Push) | GitOps (Pull) |
|
||
|---|---|---|
|
||
| **部署驱动** | CI 服务器主动推送 | Git 仓库变动触发拉取 |
|
||
| **安全边界** | CI 需要直连 K8s（暴露 kubeconfig） | ArgoCD 在集群内运行，无需外部访问 |
|
||
| **漂移检测** | 通常无 | 持续比对，自动修复 |
|
||
| **回滚方式** | 回到上一次 pipeline | `git revert` + 自动同步 |
|
||
|
||
> [!tip] Push vs Pull 的安全含义
|
||
>
|
||
> - **Push**：CI 服务器持有集群凭据，主动向 K8s 发请求。凭据泄露 = 集群沦陷。
|
||
> - **Pull**：ArgoCD 在集群内部以 Pod 运行，只需读取 Git 的只读权限。即使 Git 凭据泄露，攻击者也无法写入集群——他们无法改变 Git 中的 YAML。
|
||
|
||
## ArgoCD 架构深度解析
|
||
|
||
ArgoCD 是 CNCF 级别的 GitOps 持续交付工具。
|
||
|
||
```mermaid
|
||
flowchart TB
|
||
Git[(Git Repository)]
|
||
|
||
subgraph ArgoCDServer["ArgoCD Server (集群外)"]
|
||
UI["Web UI"]
|
||
API["API"]
|
||
end
|
||
|
||
subgraph ArgoCDController["ArgoCD Controller (集群内)"]
|
||
SyncLoop["同步循环\n(每 3 分钟)"]
|
||
Reconcile["Reconcile: Git Manifest vs K8s 实际状态"]
|
||
end
|
||
|
||
Git -->|只读 access_token| SyncLoop
|
||
SyncLoop --> Reconcile
|
||
Reconcile -->|"发现不一致"| Apply["kubectl apply"]
|
||
Apply --> K8s["K8s Cluster"]
|
||
K8s -->|"读取实际状态"| SyncLoop
|
||
|
||
style Git fill:#e3f2fd
|
||
style ArgoCDServer fill:#fff3e0
|
||
style ArgoCDController fill:#e8f5e9
|
||
```
|
||
|
||
### 关键概念
|
||
|
||
| 术语 | 说明 |
|
||
|------|------|
|
||
| **Application** | ArgoCD 管理的核心资源，定义"从哪个 Git 路径同步到哪个命名空间" |
|
||
| **Sync Policy** | 决定是自动同步还是手动触发；以及同步策略（Prune resources, Self-heal） |
|
||
| **Health Status** | ArgoCD 对资源的健康检查（Deployment 是否有可用副本、Pod 是否 Running 等） |
|
||
| **Drift Detection** | 对比 Git 中声明的配置与实际 K8s 状态的差异 |
|
||
| **App of Apps** | 用 Application 来管理 Application，实现分层编排 |
|
||
|
||
## Application 配置实战
|
||
|
||
### 典型 Application
|
||
|
||
```yaml
|
||
# apps/order-service.yaml
|
||
apiVersion: argoproj.io/v1alpha1
|
||
kind: Application
|
||
metadata:
|
||
name: order-service
|
||
namespace: argocd
|
||
spec:
|
||
project: default
|
||
source:
|
||
repoURL: https://github.com/team/k8s-manifests.git
|
||
targetRevision: main
|
||
path: overlays/production/order-service
|
||
destination:
|
||
server: https://kubernetes.default.svc
|
||
namespace: production
|
||
syncPolicy:
|
||
automated:
|
||
prune: true # 删除 Git 中不存在的资源
|
||
selfHeal: true # 自动修复被手动改动的资源
|
||
syncOptions:
|
||
- CreateNamespace=true # 目标命名空间不存在时自动创建
|
||
```
|
||
|
||
**字段速查**：
|
||
|
||
- `prune: true` — Git 里删了的东西，集群上也删掉
|
||
- `selfHeal: true` — 有人手动改了 Deployment？下次同步循环自动改回来
|
||
- `CreateNamespace=true` — 不需要提前手动创建命名空间
|
||
|
||
### App of Apps：多层级应用编排
|
||
|
||
当有几十上百个服务时，用一个 Application 管理一个服务太繁琐了。ArgoCD 支持 **"应用的 Application"** 模式：
|
||
|
||
```yaml
|
||
# root-application.yaml —— 根级别 Application
|
||
apiVersion: argoproj.io/v1alpha1
|
||
kind: Application
|
||
metadata:
|
||
name: cluster-services
|
||
spec:
|
||
sources:
|
||
- repoURL: https://github.com/team/k8s-manifests.git
|
||
targetRevision: main
|
||
path: apps/order-service
|
||
- repoURL: https://github.com/team/k8s-manifests.git
|
||
targetRevision: main
|
||
path: apps/payment-service
|
||
- repoURL: https://github.com/team/k8s-manifests.git
|
||
targetRevision: main
|
||
path: apps/user-service
|
||
```
|
||
|
||
这种模式下，开发者只需要往 `apps/` 目录下新增文件夹并提交 PR，根 Application 就会自动把新服务拉到集群。
|
||
|
||
> [!tip] App of Apps 的最佳实践
|
||
>
|
||
> - 按团队或环境划分层级：`root-app → team-a-services / team-b-services`
|
||
> - 每个子 Application 可以有自己的 `syncPolicy` 和 `namespace`
|
||
> - 不要超过 3 层嵌套，调试会变得困难
|
||
|
||
## 进阶：中间件集成
|
||
|
||
### Helm + Kustomize 混合使用
|
||
|
||
ArgoCD **同时支持** Helm 和 Kustomize 作为 source plugin。实际工程中，最常见的组合是：
|
||
|
||
> CI pipeline 用 Helm build chart → ArgoCD 通过 Helm source 读取并部署到集群。
|
||
|
||
```yaml
|
||
# apps/order-service.yaml —— 使用 Helm Source
|
||
apiVersion: argoproj.io/v1alpha1
|
||
kind: Application
|
||
metadata:
|
||
name: order-service
|
||
spec:
|
||
project: default
|
||
source:
|
||
repoURL: https://github.com/team/k8s-manifests.git
|
||
targetRevision: main
|
||
path: charts/order-service # Helm Chart 目录
|
||
helm:
|
||
valueFiles:
|
||
- values.yaml # 默认值文件
|
||
- values-production.yaml # 生产环境覆盖
|
||
parameters: # 命令行参数覆盖（优先级最高）
|
||
- name: replicas
|
||
value: "3"
|
||
- name: image.tag
|
||
value: "{{ .Values.image.sha }}" # 引用 CI 写入的 commit SHA
|
||
destination:
|
||
server: https://kubernetes.default.svc
|
||
namespace: production
|
||
```
|
||
|
||
> [!question] 为什么不只用纯 YAML？
|
||
>
|
||
> 想象一下：每个环境的 Deployment 只有 `replicas`、`resources`、`imageTag` 不同，其余完全一样。如果全部写为裸 YAML，维护 5 个环境 = 维护 5 份几乎相同的文件。Helm/Kustomize 让你用 **模板化 + 差异覆盖** 解决这个 DRY 问题。
|
||
|
||
### ArgoCD 原生 Kustomize 示例
|
||
|
||
```yaml
|
||
# 直接用 kustomize 作为 source
|
||
spec:
|
||
source:
|
||
repoURL: https://github.com/team/k8s-manifests.git
|
||
targetRevision: main
|
||
path: overlays/production/order-service # kustomize overlay 路径
|
||
kustomize:
|
||
images:
|
||
- name: myregistry/order-service
|
||
newTag: v1.2.3 # CI 注入的镜像版本
|
||
```
|
||
|
||
> [!note] 选择建议
|
||
>
|
||
> | 场景 | 推荐 |
|
||
> |------|------|
|
||
> | 需要复杂的条件渲染和复用 | Helm |
|
||
> | 简单的环境覆盖（改几个字段） | Kustomize |
|
||
> | ArgoCD 原生支持两者，可以混用（多源模式已在 App of Apps 中展示） | — |
|
||
|
||
## 同步工作流：Hook 与健康检查
|
||
|
||
### 同步生命周期
|
||
|
||
```mermaid
|
||
flowchart LR
|
||
A["Git 提交"] --> B{"ArgoCD\n检测到差异"}
|
||
B -->|"执行 PreSync Hook"| C["PreSync"]
|
||
C -->|"迁移 DB Schema"| D[健康检查]
|
||
D -->|"前向兼容? "| E["Sync"]
|
||
E -->|"部署新版本"| F["PostSync Hook"]
|
||
F -->|"灰度验证 / 通知"| G["Health Status"]
|
||
|
||
style C fill:#fff3e0
|
||
style E fill:#e3f2fd
|
||
style F fill:#e8f5e9
|
||
style G fill:#f3e5f5
|
||
```
|
||
|
||
### PreSync Hook：数据库迁移示例
|
||
|
||
```yaml
|
||
# hooks/db-migration.yaml
|
||
apiVersion: batch/v1
|
||
kind: Job
|
||
metadata:
|
||
name: db-migrate
|
||
annotations:
|
||
argocd.argoproj.io/hook: PreSync # Sync 之前执行
|
||
argocd.argoproj.io/hook-delete-policy: HookSucceeded # 成功后自动清理
|
||
spec:
|
||
template:
|
||
spec:
|
||
containers:
|
||
- name: migrate
|
||
image: myregistry/order-service:v1.2.3
|
||
command: ["./migrate", "--up"]
|
||
restartPolicy: Never
|
||
```
|
||
|
||
**常用 Hook 阶段**：
|
||
|
||
| 阶段 | 时机 | 典型用途 |
|
||
|------|------|---------|
|
||
| `PreSync` | Sync 之前 | DB 迁移、缓存预热 |
|
||
| `Sync` | 替代默认同步行为 | 复杂的多步骤部署 |
|
||
| `PostSync` | Sync 之后 | 灰度验证、发 Slack 通知 |
|
||
| `SyncFail` | Sync 失败时 | 回滚、告警 |
|
||
|
||
> [!important] Hook 注意事项
|
||
>
|
||
> - `hook-delete-policy: HookSucceeded` — 避免残留大量已完成的历史 Job
|
||
> - PreSync Hook 本身也有健康检查机制，Job 必须 Running → Succeeded 才算通过
|
||
> - Hook Job 和目标 Application 必须在同一个 Kubernetes 集群
|
||
|
||
### 自定义健康检查
|
||
|
||
ArgoCD 内置了对 Deployment、StatefulSet、Service 等资源的健康检查。对于自定义 CRD（比如 CassandraCluster），可以通过 Script Health Check 实现：
|
||
|
||
```yaml
|
||
# ConfigMap 挂载到 ArgoCD Server
|
||
apiVersion: v1
|
||
kind: ConfigMap
|
||
metadata:
|
||
name: resource-customizations
|
||
namespace: argocd
|
||
data:
|
||
myapp.example.com_CassandraCluster.health.lua: |
|
||
local status = {}
|
||
if obj.status ~= nil then
|
||
if obj.status.readyNodes ~= nil then
|
||
if obj.status.readyNodes >= 3 then
|
||
status.status = "Healthy"
|
||
else
|
||
status.status = "Progressing"
|
||
status.message = "Only " .. tostring(obj.status.readyNodes) .. " ready nodes"
|
||
end
|
||
end
|
||
end
|
||
return status
|
||
```
|
||
|
||
> [!tip] 常见内置资源健康状态速查
|
||
>
|
||
> | 资源类型 | Healthy 条件 | Progressing 条件 |
|
||
> |----------|-------------|-----------------|
|
||
> | Deployment | 所有 replicas Ready 且当前 | replicaReadyCount < desired |
|
||
> | StatefulSet | 所有 Pod Running | Pending 或 replica 不足 |
|
||
> | Service | 存在即 Healthy | —（通常不 Progressing） |
|
||
> | Ingress | 有 backend 即 Healthy | — |
|
||
> | ConfigMap/Secret | 存在即 Healthy | — |
|
||
|
||
## 日志调试与故障排查
|
||
|
||
### ArgoCD CLI 常用命令
|
||
|
||
```bash
|
||
# 实时日志
|
||
argocd app logs order-service --follow
|
||
|
||
# 指定Pod日志（查看特定容器）
|
||
argocd app logs order-service -p order-service-pod-abc123 -c sidecar
|
||
|
||
# 查看应用事件（谁触发的同步、为什么失败）
|
||
argocd app events order-service
|
||
|
||
# 强制刷新（跳过缓存）
|
||
argocd app get order-service --refresh
|
||
```
|
||
|
||
### 常见故障排查流程
|
||
|
||
```mermaid
|
||
flowchart TD
|
||
A["Application 显示 OutOfSync"] --> B{手动 sync 是否成功?}
|
||
B -- 是 --> C["✅ 可能是临时网络抖动, Watch 恢复即可"]
|
||
B -- 否 --> D["查看 Events\nargocd app events"]
|
||
|
||
D --> E{"错误原因?"}
|
||
E -- "ImagePullBackOff" --> F["镜像仓库不可达/凭据过期\n→ 检查 ImagePullSecrets"]
|
||
E -- "CrashLoopBackOff" --> G["应用启动失败\n→ 查看 Pod 日志\nargocd app logs"]
|
||
E -- "ResourceQuota exceeded" --> H["命名空间配额不足\n→ 调整 Quota 或精简资源"]
|
||
E -- "RBAC denied" --> I["ArgoCD SA 权限不足\n→ 检查 ClusterRole Binding"]
|
||
E -- "Custom health check failing" --> J["自定义健康脚本语法错误\n→ 检查 resource-customizations ConfigMap"]
|
||
|
||
style F fill:#ffebee
|
||
style G fill:#e3f2fd
|
||
style H fill:#fff3e0
|
||
style I fill:#f3e5f5
|
||
style J fill:#e8f5e9
|
||
```
|
||
|
||
### 调试 Checklist
|
||
|
||
- [ ] `kubectl get application -n argocd` — 确认 Application CR 状态
|
||
- [ ] `kubectl describe application xxx -n argocd` — 查看 Conditions 和最后同步信息
|
||
- [ ] `argocd app logs xxx --tail 100` — Controller 日志，搜索 Error 关键字
|
||
- [ ] 确认 Git Repo URL 和 token 可用：手动 curl 测试
|
||
- [ ] 如果是 self-heal 反复触发：检查是否有外部控制器在修改资源
|
||
|
||
## 安全要点
|
||
|
||
### RBAC 配置
|
||
|
||
```yaml
|
||
# argocd-rbac-cm.yaml
|
||
apiVersion: v1
|
||
kind: ConfigMap
|
||
metadata:
|
||
name: argocd-rbac-cm
|
||
namespace: argocd
|
||
data:
|
||
policy.default: role:readonly # 默认只读
|
||
policy.csv: |
|
||
# g, github-org:team-name, role:admin # 团队级管理
|
||
p, role:order-service-deployer, applications, sync, */order-service, allow
|
||
g, github:alice, role:order-service-deployer # alice 可同步 order-service
|
||
scopes: '[groups]' # 从 OIDC token 获取 groups
|
||
```
|
||
|
||
### Secrets 管理建议
|
||
|
||
| 方式 | 适用场景 | 备注 |
|
||
|------|---------|------|
|
||
| **ArgoCD Secret** | Git 仓库凭据、K8s cluster 注册 | 存储为 SealedSecret/ExternalSecret |
|
||
| **External Secrets Operator** | RDS 密码、API Key | 从 AWS Secrets Manager / Vault 拉取 |
|
||
| **SealedSecret** | 跨集群复用加密 secrets | 公钥加密，仅 controller 可解密 |
|
||
|
||
> [!warning] 常见误区
|
||
>
|
||
> - **不要把 Git SSH Private Key 存入集群的普通 Secret** — 应该用 `argocd reponame` 配置项统一管理
|
||
> - **Application 的 namespace 要单独隔离** — `argocd` 命名空间不应和生产共享
|
||
> - **启用 OIDC + RBAC scopes** — 让团队只能看到自己管理的 Application
|
||
|
||
---
|
||
|
||
现在回到日常操作：
|
||
|
||
## 常见运维场景
|
||
|
||
### 手动触发同步
|
||
|
||
当 Git 已更新但 ArgoCD 未自动同步时：
|
||
|
||
```bash
|
||
argocd app sync order-service --force
|
||
```
|
||
|
||
### 查看同步状态和历史
|
||
|
||
```bash
|
||
argocd app get order-service # 当前状态
|
||
argocd app history order-service # 同步历史
|
||
argocd app diff order-service # Git vs 实际的差异
|
||
```
|
||
|
||
### 回滚到上一个版本
|
||
|
||
```bash
|
||
argocd app rollback order-service
|
||
# 或直接 git revert 对应的 commit，ArgoCD 自动同步
|
||
```
|
||
|
||
### 解除锁定（Stuck App 恢复）
|
||
|
||
```bash
|
||
argocd app unlock order-service
|
||
```
|
||
|
||
## 工具选型：ArgoCD vs Flux
|
||
|
||
| 特性 | ArgoCD | Flux v2 |
|
||
|------|--------|---------|
|
||
| **UI** | 丰富的 Web UI，可视化对比 | CLI + Kubernetes-native，轻量 UI |
|
||
| **通知** | Slack/Discord/GitHub native | Event controller + Webhook |
|
||
| **Helm** | 内置 Helm Source 插件 | 一等公民（HelmRelease） |
|
||
| **多集群** | 多集群统一管理 | 需配合 Image Automation |
|
||
| **适合场景** | 可视化管理需求强的团队 | 纯 GitOps 极客团队 |
|
||
|
||
> [!note] 选型建议
|
||
>
|
||
> - 如果你已经重度使用 Helm：Flux 的 HelmRelease CRD 更自然
|
||
> - 如果你希望可视化查看每次部署的差异：ArgoCD 的 diff view 是杀手功能
|
||
> - 两者可以并存——比如 ArgoCD 管应用层，Flux 管基础设施层（CNI、CSI 等）
|
||
|
||
## 关联笔记
|
||
|
||
- [[01-CICD基础与实践]] — CI/CD Pipeline 的搭建与实践
|
||
- [[03-Helm模板管理]] — Helm Chart 编写与管理
|
||
- [[04-安全与发布策略]] — 安全管理与发布决策
|
||
- [[../03-CICD与GitOps]] — 参考手册与决策指南
|