Argo CD 入门 — CodeRoadMapArgo CD 入门
这一课你将能做到
- 在学习集群（minikube/kind）安装 Argo CD，用 port-forward 打开 UI，取出初始 admin 密码并登录
- 编写 Application CR 指向仓库中的 backend Chart 与环境 values，读懂 Synced/OutOfSync 与 Healthy/Degraded 两组状态的区别
- 演示「改 values 中 image.tag → 自动同步」闭环，并（可选）用
selfHeal 纠正一次手改漂移
为什么要学
Argo CD 是使用最广的 GitOps 控制器之一：用 Application（批量场景用 ApplicationSet）声明「从哪个仓库、哪条分支、哪个路径、用什么 Helm 参数、同步到哪个集群哪个命名空间」。它把 gitops-intro 的抽象原则变成具体产品：持续对比 desired（Git 渲染结果）与 live（集群实况），UI 可视化 diff，同步动作等价于受控的 helm upgrade。本课在学习集群走通最小闭环——安装、声明、同步、纠漂移；生产的 SSO、多集群、RBAC 项目化放到真正落地时再加深。面试高频词「Argo CD 同步机制」在本课给出可背版本。
先建立图像
Git repo
deploy/charts/backend ← Chart
deploy/env/dev/backend-values.yaml ← 环境差异
│
▼ Application.spec.source（repoURL/path/targetRevision/valueFiles）
Argo CD（argocd 命名空间）
① refresh：拉 Git → helm 渲染出 desired
② compare：desired vs live，产出 diff → Synced / OutOfSync
③ sync：把 desired 落到集群（等价 kubectl apply / helm 升级）
│
▼
destination：coderoadmap-dev 命名空间里的 Deployment/Service
| 状态词 | 人话 | 常见原因 |
|---|
| Synced | live 与 desired 一致 | 正常 |
| OutOfSync | 有差异 | 待同步 / 有人手改集群 / Git 变了未刷新 |
| Healthy | 资源就绪（探针通过等） | 正常 |
| Degraded/Progressing | 健康有问题 | 探针失败、镜像拉不下来 |
两组状态独立：Synced + Degraded 完全可能同时出现
→ 同步层面没问题，运行层面挂了：去看 Pod/事件，别盯着 UI 干瞪眼
跟着做
步骤 1：安装到学习集群
kubectl create namespace argocd
kubectl apply -n argocd -f https://raw.githubusercontent.com/argoproj/argo-cd/stable/manifests/install.yaml
# 等待全部 Running
kubectl get pods -n argocd -w
应看到 argocd-server、argocd-application-controller、argocd-repo-server 等组件。这是学习清单；生产请用官方 HA 清单与安全加固指南。
步骤 2：取密码并打开 UI
# 初始 admin 密码（就是 argocd-server Pod 名，首次登录后建议改掉）
kubectl -n argocd get secret argocd-initial-admin-secret \
-o jsonpath="{.data.password}" | base64 -d; echo
# 端口转发
kubectl -n argocd port-forward svc/argocd-server 8080:443
浏览器打开 https://localhost:8080（学习环境接受自签证书警告），用户 admin + 上一步密码。也可安装 argocd CLI 后 argocd login localhost:8080 走命令行。
步骤 3：确保 Argo 能读到你的 Git
- 公开 HTTPS 仓库：Application 里直接填
repoURL 即可
- 私有仓库：UI Settings → Repositories 添加凭据（PAT/SSH），或建 Secret 声明
- 先在本机
git clone 通了再填，能排除一半路径类故障
步骤 4：编写 Application（核心产物）
记住：valueFiles 相对于 spec.source.path（Chart 目录），不是仓库根：
# deploy/argocd/applications/backend-dev.yaml
apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
name: backend-dev
namespace: argocd # Application 本身放在 argocd ns
spec:
project: default
source:
repoURL: https://github.com/your-org/java-nav.git # 换成你的仓库
targetRevision: main
path: deploy/charts/backend # Chart 目录
helm:
valueFiles:
- ../../env/dev/backend-values.yaml # 相对 path 上溯
destination:
server: https://kubernetes.default.svc # 同集群
namespace: coderoadmap-dev
syncPolicy:
automated:
prune: true # Git 里删了资源，集群里也删（谨慎）
selfHeal: true # 有人手改集群，自动拉回 Git 期望
syncOptions:
- CreateNamespace=true
kubectl apply -f deploy/argocd/applications/backend-dev.yaml
UI 应出现 backend-dev 应用卡片；automated 策略下会自动完成首次同步，否则手动点 Sync。
步骤 5：改 tag 触发同步闭环
# 编辑 deploy/env/dev/backend-values.yaml 的 image.tag，提交推送
git add deploy/env/dev/backend-values.yaml
git commit -m "dev: bump backend image to 1.0.1"
git push
回到 UI 刷新（或等 3 分钟默认轮询/webhook 秒触发）：应看到短暂 OutOfSync → Syncing → Synced；同时：
kubectl get pods -n coderoadmap-dev -w # 观察滚动更新
这就是「部署 = 合并一个 PR」的完整体验，全程没有任何人在终端敲过 upgrade。
步骤 6：手改漂移，理解 selfHeal（可选）
kubectl -n coderoadmap-dev scale deploy/backend --replicas=5
几十秒内副本应被拉回 values 里的 replicaCount，UI 里那次 OutOfSync 也自动消失。笔记写死：「救火手改会被拉回——正确做法永远是改 Git。」
讲清楚要点
- 因为 Application 声明了 source 与 destination，所以每个环境的同步目标清晰可审——多环境 = 多 Application（backend-dev/backend-prod），批量同构用 ApplicationSet。
- 因为 desired 来自 Git 渲染，所以「改集群不改 Git」只会制造 OutOfSync 或 selfHeal 对抗——习惯必须迁移到改 values 走 PR。
- 因为 refresh 与 sync 是两个阶段，所以看到 OutOfSync 先分辨「Git 变了没同步」还是「集群被人动了」——前者点 Sync，后者查漂移来源。
- 因为 automated + prune 会删除 Git 中已移除的资源，所以删模板前要确认影响面——误删清单等于误删集群对象；风险高的环境可先关 prune。
- 因为 admin 初始密码就是 Secret 里的 Pod 名，所以装完立即改密并不要把 UI 暴露公网——port-forward 仅限本机调试。
- 因为同步状态 ≠ 健康状态，所以 Synced 仍可能 Degraded——健康度来自内置探针检查（如 Deployment available），排障仍要
kubectl describe/logs。
你可能会懵的地方
-
Application 为什么装在 argocd 命名空间？
Argo 默认监听 argocd ns 里的 Application CR（可配置多命名空间）；Application 描述「同步什么到哪」，它本身不是业务资源。业务资源落在 destination.namespace。
-
Argo CD 和 helm CLI 的 Release 是什么关系？
用 Helm 渲染时，Argo 会在集群内以类 helm 方式安装升级，但它的管理单元是 Application 而非 helm Release；helm list 能否看到取决于版本与配置。日常以 Argo 的应用历史为准，不要两套并管。
-
必须开 automated 吗？
不必须。常见分级：dev 全自动（automated+selfHeal），prod 手动 Sync（PR 合并后由人点或由流水线触发 Sync）。学习阶段先手动理解每一步，再开自动化。
-
多集群怎么接？
destination.server 换成已注册的外部集群 API 地址（UI/CLI 注册集群）；本课只做同集群 kubernetes.default.svc。
-
三个核心组件各干什么？
argocd-server 提供 API/UI；argocd-repo-server 拉仓库并渲染（helm/kustomize 在这跑）；argocd-application-controller 执行对比与同步。排障时日志要找对组件。
错法对照
| 错法 | 问题 | 正解 |
|---|
| valueFiles 写成相对仓库根 | 按相对 Chart path 解析时找不到文件 | ../../env/... 或调整目录布局 |
| 生产 UI 直接暴露公网 + 默认密码 | 控制面被接管 | 改密、SSO/OIDC、入口鉴权 |
| 只看 Synced 不看 Healthy | 同步成功但服务挂着 | 两个状态都看，再下钻 Pod/事件 |
| 关掉分支保护直接推 prod values | 绕过评审改生产 | CODEOWNERS + 保护分支 |
| Argo 与 CI helm upgrade 同管一个应用 | 两套真相打架 | 单一真相源，二选一 |
| 开 prune 却随意删模板 | Git 删 = 集群删 | 删除走评审，确认影响面 |
卡点急救
- 现象：Application 一直 OutOfSync 且报 values file not found——valueFiles 相对路径错；检查它相对
spec.source.path 的层级（../../env/dev/backend-values.yaml），或把 env values 挪进 Chart 同级可解析位置；看 UI 的 sync 错误详情定位真实路径。
- 现象：Pods 一直 Progressing、Healthy 显示 Degraded——应用层问题不是同步问题：
kubectl -n coderoadmap-dev describe pod、logs 看探针路径（actuator）与镜像 tag；修的是 values 或镜像本身，然后 Git 提交。
- 现象：改了 Git 但 UI 不刷新——默认轮询有间隔（3 分钟）；等、点 Refresh、或给仓库配 webhook 立即触发；确认 targetRevision 分支与你 push 的分支一致。
面试常问
-
Argo CD 的同步机制是怎样的？
三个阶段：refresh（定时/webhook 触发，拉取 Git 并用 helm/kustomize 渲染出 desired manifest）→ compare（desired 与集群 live 状态对比，给出 Synced/OutOfSync 与 diff 详情）→ sync（按需手动或自动执行，把 desired 应用到集群，可带 prune/selfHeal/同步选项）。同步状态与健康状态分离，健康度由探针类检查决定。
-
Synced 和 Healthy 有什么区别？
Synced 描述「配置一致性」：集群资源与 Git 期望是否一致；Healthy 描述「运行状态」：资源本身是否就绪（Deployment 的 available、Pod Ready 等）。Synced+Degraded 表示配置已到位但运行异常，OutOfSync+Healthy 表示运行正常但配置有差异（典型：有人手改了集群）。二者组合定位问题维度不同。
-
automated sync 里的 prune 和 selfHeal 分别解决什么？
prune 让「Git 中删除的资源」在集群中同步删除，防止僵尸资源；selfHeal 让「集群侧手改」被自动拉回 Git 期望，保证 Git 是唯一事实源。前者管「Git 少了」，后者管「集群多了/变了」——两者合起来才是完整的持续调和。
自测三问
- Application 的
source.path、source.helm.valueFiles、destination.namespace 各指什么？valueFiles 相对谁解析？
- OutOfSync 与 Degraded 可能同时出现吗？各说明什么问题、分别怎么查？
- selfHeal 开启后，「临时 kubectl scale 救火」为什么不可持续？正确流程是什么？
小结一句话
Argo CD 用 Application 把 Git 中的 Helm Chart/values 持续同步到集群：refresh→compare→sync 三步是可背的同步机制，Synced/Healthy 两组状态、selfHeal/prune 两个开关撑起「部署 = 合并 PR」的体验。
延伸