拼装 Application 清单

目标

逐字段构建完整的 Argo CD Application manifest，再把该应用将要部署的 namespace 与 Deployment 实际提交到 cluster，并亲手确认 Argo CD 如何识别自己管理的资源。

为什么重要

Application 是一份声明，规定“以什么内容（source）、部署到哪里（destination）、遵循什么规则（syncPolicy）进行同步”。与其死记字段名，更重要的是理解每个字段用于防止什么事故。不启用 prune，从 Git 删除的资源会永久留在 cluster；启用 selfHeal，手工修改会被还原；使用 HPA 却没有 ignoreDifferences，Argo CD 与 HPA 会围绕 replicas 不断争夺。这个实验会按顺序构建文件，逐一预防这些问题。

步骤

创建 /root/capa-app/ 目录，并在其中创建 application.yaml。apiVersion 为 argoproj.io/v1alpha1，kind 为 Application，metadata.name 为 guestbook，metadata.namespace 为 argocd。
在同一文件中，把 spec.project 设为 capa-demo，spec.source.repoURL 设为 https://gitea.homelab.internal/platform/guestbook.git，spec.source.targetRevision 设为 main，spec.source.path 设为 overlays/prod。
把 spec.destination.server 设为 https://kubernetes.default.svc，spec.destination.namespace 设为 capa-guestbook。不要写 destination.name。
把 spec.syncPolicy.automated.prune 与 spec.syncPolicy.automated.selfHeal 都设为 true，并在 spec.syncPolicy.syncOptions 中加入 CreateNamespace=true、PruneLast=true 两项。
把 spec.syncPolicy.retry.limit 设为 5，spec.syncPolicy.retry.backoff.duration 设为 5s，factor 设为 2，maxDuration 设为 3m。
在 spec.ignoreDifferences 的第一项中加入 group: apps、kind: Deployment，并在 jsonPointers 中加入 /spec/replicas，将 HPA 管理的字段排除在比较之外。
在 cluster 中实际创建 namespace capa-guestbook，并添加 label app.kubernetes.io/part-of=capa。
在 namespace capa-guestbook 中实际创建 Deployment guestbook-ui。replicas 为 2，container image 为 nginx:1.27，并在 Deployment 自身的 annotation 中按 Argo CD 格式设置 argocd.argoproj.io/tracking-id。应用名称为 guestbook。

参考

验证文件时，可以像 yq '.spec.syncPolicy' /root/capa-app/application.yaml 一样只提取一部分，速度更快。
实际资源可以先通过 kubectl create ... --dry-run=client -o yaml 生成骨架，再进行编辑，以减少拼写错误。
常见错误 1：把 syncOptions 写成 map。它是 string array。
常见错误 2：tracking ID 中 core group 的写法。apps group 资源与 core group 资源的格式不同。

创建工作目录与 Application 骨架

创建 /root/capa-app/ 目录，并在其中创建 application.yaml。apiVersion 为 argoproj.io/v1alpha1，kind 为 Application，metadata.name 为 guestbook，metadata.namespace 为 argocd。

Application 是 argoproj.io group 的 custom resource。metadata.namespace 不是部署目标，而是 Application object 自身所在的位置，通常是安装 Argo CD 的 namespace。

配置 source——获取什么内容

在同一文件中，把 spec.project 设为 capa-demo，spec.source.repoURL 设为 https://gitea.homelab.internal/platform/guestbook.git，spec.source.targetRevision 设为 main，spec.source.path 设为 overlays/prod。

spec.source 下包含 repository 地址、revision、path 三项。targetRevision 可接受 branch、tag、commit SHA；生产环境使用固定名称通常比 HEAD 更安全。

配置 destination——部署到哪里

把 spec.destination.server 设为 https://kubernetes.default.svc，spec.destination.namespace 设为 capa-guestbook。不要写 destination.name。

部署到同一 cluster 时使用的地址是固定的。server 与 name 是指向同一对象的两种方式，不能同时使用。

配置自动同步与 syncOptions

把 spec.syncPolicy.automated.prune 与 spec.syncPolicy.automated.selfHeal 都设为 true，并在 spec.syncPolicy.syncOptions 中加入 CreateNamespace=true、PruneLast=true 两项。

automated 下的两个 boolean 分别决定“Git 中删除的资源是否也从 cluster 删除”和“是否还原手工修改”。syncOptions 是 string array，格式为 key=value。

设计 retry backoff

把 spec.syncPolicy.retry.limit 设为 5，spec.syncPolicy.retry.backoff.duration 设为 5s，factor 设为 2，maxDuration 设为 3m。

backoff 从 duration 开始，每次乘以 factor，并在 maxDuration 停止增长。按要求计算，确认结果是否为 5 秒、10 秒、20 秒、40 秒、80 秒。

从 diff 中排除 HPA 管理字段

在 spec.ignoreDifferences 的第一项中加入 group: apps、kind: Deployment，并在 jsonPointers 中加入 /spec/replicas，将 HPA 管理的字段排除在比较之外。

ignoreDifferences 是 array；每项先通过 group/kind 缩小对象范围，再通过 jsonPointers 指定字段。JSON Pointer 使用斜线而不是点号表示路径。

实际创建目标 namespace

在 cluster 中实际创建 namespace capa-guestbook，并添加 label app.kubernetes.io/part-of=capa。

从这里开始不是编辑文件，而是操作真实 cluster。可先用 kubectl create namespace 创建，再添加 label；也可编写 manifest 后 apply。

创建带 tracking annotation 的 Deployment

在 namespace capa-guestbook 中实际创建 Deployment guestbook-ui。replicas 为 2，container image 为 nginx:1.27，并在 Deployment 自身的 annotation 中按 Argo CD 格式设置 argocd.argoproj.io/tracking-id。应用名称为 guestbook。

tracking ID 格式为 APP_NAME:GROUP/KIND:NAMESPACE/NAME。Deployment 属于 apps group，因此 GROUP 位置不能为空。