Argo CD是落地GitOps的核心工具，但需前提：Git仓库含正确声明式配置、集群权限完备、接受git push为唯一可信变更入口。
GitOps 流水线不是“装个工具就自动跑起来”的东西，它本质是一套工作流约定 + 工具链协同。Argo CD 是当前最直接落地 GitOps 的工具，但它的运行前提是：Git 仓库里有正确的声明式配置、集群权限已配好、你已接受「git push 是唯一可信变更入口」这个前提。
Argo CD 安装前必须确认的三件事
别急着 helm install 或 flux bootstrap，先检查：
- 集群是否启用了
admissionregistration.k8s.io/v1（Kubernetes 1.16+ 默认开启；低于该版本需手动启用 MutatingWebhookConfiguration） - 你是否有权限创建
CustomResourceDefinition、ClusterRoleBinding和ServiceAccount—— 大多数私有集群默认禁止普通用户创建 CRD - Git 仓库是否已初始化，且至少含一个能被
kustomize build或helm template正确解析的目录（比如./clusters/prod下有kustomization.yaml）
用 Argo CD CLI 安装时 path 配置错一个字符就 OutOfSync
Argo CD 应用定义里的 spec.source.path 必须精确指向含 kustomization.yaml 或 Chart.yaml 的目录，不是 Git 仓库根，也不是上层父目录。
Pilot Digital Twin Setup
下载
部署一个包含 4 个智能体（agent）的数字孪生平台。在以下情况下使用该技能： 1. 用户希望为物理资产监控与预测性维护等场景搭建数字孪生系统……
- 错误示例：
path: manifests，而实际文件在manifests/overlays/staging/kustomization.yaml→ Argo CD 构建结果为空，状态永远是Missing - 正确写法：
path: manifests/overlays/staging，且确保该路径下kustomization.yaml中所有resources:引用的相对路径（如../bases/deployment）在仓库内真实存在 - 验证方法：本地执行
kustomize build manifests/overlays/staging，输出应为完整 YAML 清单；若报错，Argo CD 一定失败
Sync 卡在 Progressing 不是网络问题，而是 Pod 没 Ready
Argo CD 的 Progressing 状态不表示“正在同步”，而是“已提交资源，正在等待其就绪”。常见卡点与排查方式：
-
Deployment的replicas: 3全部 Pending → 检查kubectl describe nodes是否资源不足，或kubectl get events -A是否有ImagePullBackOff -
StatefulSet第二个 Pod 一直 Waiting → 查看podManagementPolicy是否为OrderedReady，再检查第一个 Pod 的InitContainer日志（kubectl logs <pod> -c <init-container-name>） -
Job或CronJob未完成 → Argo CD 默认不等待 Job 完成，需显式配置syncPolicy.automated.prune: true并加注解argocd.argoproj.io/hook: PostSync
Git 仓库权限和 SSH 密钥最容易被忽略的细节
Argo CD 用 SSH 克隆仓库时，不是用你的个人密钥，而是用它自己生成的密钥对 —— 这个密钥必须被 Git 服务端明确授权，且不能依赖 ~/.ssh/config。
- 如果用 GitHub/GitLab，必须把 Argo CD 生成的公钥（通常在
argocd-secret的sshKnownHosts字段或通过argocd cluster add输出）添加到对应账户的 Deploy Keys（而非 User Settings → SSH Keys），否则克隆失败 - 私有 Git 服务器（如 Gitea）若启用了
StrictHostKeyChecking，需提前将 Git 服务器的 host key 写入 Argo CD 的sshKnownHosts，否则首次连接阻塞 - HTTP(S) 方式更简单，但需确保仓库 URL 带 token（如
https://token:x-oauth-basic@github.com/user/repo.git），且该 token 有repo权限
GitOps 的复杂度不在工具安装，而在「谁改了什么、为什么改、改完怎么验证」这三件事能否全部沉淀进 Git 提交记录里。绕过 Git 直接 kubectl apply，哪怕只执行一次，就会让 Argo CD 的 OutOfSync 成为常态，而不是起点。
