From 15065b8fe301f3017b9f92f48febea1c4bd59744 Mon Sep 17 00:00:00 2001 From: "xiaobing.wang" Date: Sat, 9 May 2026 19:37:10 +0800 Subject: [PATCH] docs: clarify gitops sync waves --- gitops-app-onboarding/SKILL.md | 33 +++++++++++++++++++++++++-------- 1 file changed, 25 insertions(+), 8 deletions(-) diff --git a/gitops-app-onboarding/SKILL.md b/gitops-app-onboarding/SKILL.md index eda2f2e..41796b3 100644 --- a/gitops-app-onboarding/SKILL.md +++ b/gitops-app-onboarding/SKILL.md @@ -278,19 +278,31 @@ Chart 必须反映应用的真实运行架构。 - annotation 键必须写成 `argocd.argoproj.io/sync-wave`，不要写成 `rgocd.argoproj.io/sync-wave` 或其他拼写 - wave 值使用字符串，例如 `"-20"`、`"0"`、`"10"` - 低 wave 先同步，高 wave 后同步；不要把依赖方和被依赖方放在同一个 wave +- `releases//manifests/` 下的资源也必须参与 wave 设计；不要只给 Helm Chart 模板里的资源排序 +- 被 Job、Deployment、StatefulSet 或 Pod 通过 `envFrom`、`secretKeyRef`、`configMapKeyRef`、volume、`imagePullSecrets` 消费的 Secret / ConfigMap，wave 必须早于消费它们的 workload +- `registry-pull-secret`、`platform-shared-secrets` 等平台托管共享资源的 wave 已固定为 `"-1"`；不要修改它们，应用资源应围绕这个锚点排序 +- `manifests/db-secret.yaml` 如果存在，必须早于所有读取 `databaseSecret` / `-db` 的 migrate Job 和业务 workload；推荐使用 `"0"` +- 应用私有 Secret、应用私有 ConfigMap 必须早于所有会消费它们的 workload；推荐使用 `"0"` - 只有确实存在跨资源启动顺序要求时才加 sync-wave，不要给所有资源机械添加 annotation 推荐顺序： -- `-30`：ServiceAccount、RBAC、基础 Secret、基础 ConfigMap -- `-20`：PVC / `volumeClaimTemplates` 所依赖的存储前置资源、应用私有 Secret、应用私有 ConfigMap -- `-10`：应用自带的私有基础设施，例如 Neo4j、向量库、内部依赖服务的 StatefulSet / Deployment -- `-5`：内部依赖的 Service，尤其是会被后续 nginx upstream 或应用启动配置引用的服务名 -- `0`：后端、worker、API 等核心业务 Deployment / StatefulSet -- `5`：核心业务 Service -- `10`：nginx / frontend 入口 Deployment，以及对外 `NodePort` Service +- `-1`：平台托管共享资源，例如 `registry-pull-secret`、`platform-shared-secrets`、平台共享 ConfigMap +- `0`：应用自有前置资源，例如 ServiceAccount、RBAC、`manifests/db-secret.yaml`、应用私有 Secret、应用私有 ConfigMap、PVC / `volumeClaimTemplates` 所依赖的存储前置资源 +- `10`：migrate Job、应用自带的私有基础设施，例如 Neo4j、向量库、内部依赖服务的 StatefulSet / Deployment +- `15`：内部依赖的 Service，尤其是会被后续 nginx upstream 或应用启动配置引用的服务名 +- `20`：后端、worker、API 等核心业务 Deployment / StatefulSet +- `25`：核心业务 Service +- `30`：nginx / frontend 入口 Deployment，以及对外 `NodePort` Service -如果 nginx 配置在容器启动时解析 upstream，必须保证 upstream 对应 Service 的 wave 早于 nginx Deployment；如果应用启动依赖 Secret / ConfigMap / PVC，必须保证这些资源的 wave 早于消费它们的 workload。 +如果 nginx 配置在容器启动时解析 upstream，必须保证 upstream 对应 Service 的 wave 早于 nginx Deployment；如果应用启动依赖 Secret / ConfigMap / PVC / imagePullSecret，必须保证这些资源的 wave 早于消费它们的 workload。尤其注意平台共享资源已经在 `"-1"`，应用自有 secret/config 应从 `"0"` 开始，migrate Job 这类消费者必须排在它们之后，例如 `"10"`，不能把消费者放到 `"-10"` 或同一个 wave 里。 + +生成或修复 release manifests 时，逐项核对： + +- `releases//manifests/db-secret.yaml` 的 wave 早于 Chart 中所有引用该 secret 的 Job / Deployment / StatefulSet +- `releases//manifests/secret.yaml` 的 wave 早于 Chart 中所有引用该 secret 的 workload +- `registry-pull-secret` 在目标 namespace 存在，且 wave 早于所有使用私有镜像的 workload +- 共享 secret / config 如果由 release manifests 或 shared manifests 同步，也早于所有消费者 如果应用依赖平台 shared 之外的私有服务，必须明确表达依赖来源： @@ -500,6 +512,9 @@ Chart 必须反映应用的真实运行架构。 - Neo4j 一类自带依赖的启动环境变量不依赖 `$(OTHER_ENV)` 展开 - 如果应用包含需要持久化数据的服务，对应 PVC / `volumeClaimTemplates` 已显式设置 `storageClassName: longhorn` - 如果资源存在启动顺序依赖，`argocd.argoproj.io/sync-wave` 拼写正确，wave 顺序符合依赖方向 +- `releases//manifests/db-secret.yaml`、`secret.yaml`、pull secret、shared secret/config 的 wave 早于所有引用它们的 migrate Job 和业务 workload +- `registry-pull-secret`、`platform-shared-secrets` 等平台托管资源保持平台约定的 `"-1"`，应用自有前置资源围绕它排序，不要改平台资源 wave +- migrate Job 不要设置成负 wave；它依赖的应用自有 Secret / ConfigMap / DB secret 通常在 `"0"`，migrate Job 应排在更高 wave，例如 `"10"` - 如果检测到的私有 Git 依赖中包含 `git.in.chaitin.net/ai/baizhiyun/opensdk`，缺少必填百智云私有配置时交互停在当前项继续索取 ## 最终输出 @@ -527,3 +542,5 @@ Chart 必须反映应用的真实运行架构。 - `update-gitops-repo` 没有依赖 `package-chart`，GitOps 仓库先于 Chart 推送被更新 - 在 `.gitlab-ci.yml` 中用 Python heredoc 临时改 `Chart.yaml`、release values 或 `application.yaml` - `argocd.argoproj.io/sync-wave` 拼错为 `rgocd.argoproj.io/sync-wave`，或把依赖方放在被依赖资源之前 +- 只给 Chart 模板资源设计 wave，却遗漏 `releases//manifests/db-secret.yaml`、`secret.yaml`、pull secret 等 release manifests，导致 migrate Job 先于 Secret 执行 +- 不顾平台约定把 `registry-pull-secret`、`platform-shared-secrets` 等平台托管资源改成其他 wave；正确做法是保持它们在 `"-1"`，应用资源围绕 `"-1"` 排序