From 013e7bf47c219f65131493d9d469baad90cc46c7 Mon Sep 17 00:00:00 2001 From: "xiaobing.wang" Date: Sat, 9 May 2026 11:48:19 +0800 Subject: [PATCH] docs: tighten gitops ci release rules --- gitops-app-onboarding/SKILL.md | 77 +++++++++++++++++++++++++++++++--- 1 file changed, 71 insertions(+), 6 deletions(-) diff --git a/gitops-app-onboarding/SKILL.md b/gitops-app-onboarding/SKILL.md index a059998..eda2f2e 100644 --- a/gitops-app-onboarding/SKILL.md +++ b/gitops-app-onboarding/SKILL.md @@ -143,14 +143,20 @@ Go 项目默认变量写在 `.gitlab-ci.yml` 的 `variables:`： 只在 `vX.Y.Z` tag 上触发发布链路。 -### build-images job +### image build jobs -输入：源码、Dockerfile、多组件构建上下文。 +输入：源码、Dockerfile、单组件构建上下文。 -输出：推送到 `registry.baizhi.cloud//:` 的运行时镜像。 +输出：分别推送到 `registry.baizhi.cloud//:` 的运行时镜像。 + +设计原则：不同服务的镜像必须独立构建，避免一个组件改动或失败拖慢所有组件发布。 要求： +- 不要生成一个串行构建所有镜像的单体 `build-images` job；每个需要构建镜像的服务使用独立 job，例如 `build-backend-image`、`build-frontend-image`、`build-nginx-image` +- 如果多个组件构建脚本完全一致，可以使用 `parallel:matrix`，但矩阵中的每个组件仍必须是 GitLab 可独立调度、独立失败、独立重试的构建单元 +- 每个镜像构建 job 只负责一个组件的 Dockerfile、构建上下文、tag 与 push +- release 链路必须等待所有应用自建镜像构建成功；优先用 `needs:` 精确声明，而不是只依赖 stage 顺序 - 登录 `registry.baizhi.cloud` - 优先使用 `docker buildx` - 只有检测到私有 Git 依赖时，才通过 `.netrc` 和 build secret 传入；否则不要生成 `.netrc` 相关步骤 @@ -169,6 +175,23 @@ Go 项目默认变量写在 `.gitlab-ci.yml` 的 `variables:`： - `--insecure-skip-tls-verify` - 不要假设 `.gitlab-ci.yml` 中的环境变量会自动进入 `docker build` / `docker buildx build` +### GitLab CI YAML 与脚本合法性 + +生成或修复 `.gitlab-ci.yml` 时要优先保证 GitLab CI 配置本身可解析、可执行、可维护。 + +要求： + +- 不要在 CI 脚本里用 Python 临时解析或改写 YAML；优先使用 `yq`、`helm`、`git`、`install`、`mkdir`、`cp`、`rsync` 这类明确的 CLI +- 修改 `Chart.yaml` 的 `version` / `appVersion` 使用 `yq -i`，不要用 Python heredoc 或内联脚本 +- 修改 Argo CD `Application` 的 `targetRevision` 使用 `yq -i` 定位字段，避免用脆弱的 `sed` 跨行替换 +- 对 CI 文件做合法性自检时，至少能用 `yq e '.' .gitlab-ci.yml` 验证 YAML 语法；如果环境有 GitLab CI lint 工具或 API，再补充 GitLab 语义校验 +- `.gitlab-ci.yml` 中的多行 shell 逻辑保持最小化；复杂到需要编程语言脚本时，优先把脚本提交到仓库中的可审查文件，而不是在 CI YAML 里塞内联程序 + +禁止： + +- 在 `.gitlab-ci.yml` 中嵌入 `python - <<'PY'`、`python -c` 或临时 Python 脚本来改 YAML +- 用字符串替换方式盲改 `application.yaml` 中所有 `targetRevision` + ### package-chart job 输入：`deploy/helm//Chart.yaml`、`deploy/helm//values.yaml`、`deploy/helm//templates/*` @@ -179,10 +202,11 @@ Go 项目默认变量写在 `.gitlab-ci.yml` 的 `variables:`： - `helm registry login registry.baizhi.cloud` - 在临时目录复制 `deploy/helm//` -- 把复制品中的 `version` 和 `appVersion` 改成 tag 版本 +- 用 `yq -i` 把复制品中的 `version` 和 `appVersion` 改成 tag 版本 - 业务镜像的默认 tag 必须跟随 `appVersion`，不要依赖 release values 覆盖业务镜像 tag - `helm package` - `helm push` +- 如果应用包含自建镜像，`package-chart` 必须通过 `needs:` 等待所有镜像构建 job 成功 ### update-gitops-repo job @@ -195,6 +219,12 @@ Go 项目默认变量写在 `.gitlab-ci.yml` 的 `variables:`： - `releases//manifests/` 下的发布结果 - `apps//application.yaml` 中当前应用 chart source 的 `targetRevision` +依赖关系： + +- `update-gitops-repo` 必须显式依赖 `package-chart` 成功，优先写 `needs: ["package-chart"]` +- 不要让 `update-gitops-repo` 和 `package-chart` 仅靠同 stage 顺序或隐式执行顺序关联 +- 如果 release stage 中还有其他准备 job，也必须保证 GitOps 仓库更新发生在 Chart 包成功推送之后 + 处理顺序固定为： 1. 克隆 `https://${GITEA_USER}:${GITEA_TOKEN}@deploy.baizhi.cloud/gitops-admin/argodeploy.git` @@ -203,7 +233,7 @@ Go 项目默认变量写在 `.gitlab-ci.yml` 的 `variables:`： 4. 保留已有的 `releases//manifests/kustomization.yaml` 与 `releases//manifests/db-secret.yaml` 5. 将 `deploy/release/secret.yaml` 物化为 `releases//manifests/secret.yaml` 6. 替换 `releases//metadata.yaml` 中的 `__VERSION__`；只有第三方镜像、非业务版本字段或明确需要的环境配置才允许替换 `releases//values.yaml` 中的 `__VERSION__` -7. 更新 `apps//application.yaml` 中当前应用 chart source 的 `targetRevision` +7. 用 `yq -i` 更新 `apps//application.yaml` 中当前应用 chart source 的 `targetRevision`，只改当前应用的 chart source 8. 只有存在 diff 时才提交并推送 `main` 禁止： @@ -211,6 +241,7 @@ Go 项目默认变量写在 `.gitlab-ci.yml` 的 `variables:`： - 在 CI 中调用 `kubectl` - 在 CI 中调用 `argocd app sync` - 把 hard refresh 当常规发布步骤 +- 在 Chart 包推送成功前更新 GitOps 仓库 ## Helm Chart 规则 @@ -238,6 +269,29 @@ Chart 必须反映应用的真实运行架构。 - 不要依赖 Kubernetes 不支持的 `$(OTHER_ENV)` 展开 - 对 Neo4j 这类镜像，不要注入不存在的 `NEO4J_*` 配置名，例如 `NEO4J_PASSWORD` +### Argo CD sync-wave + +当 Chart 或 release manifests 中存在资源依赖顺序时，使用 Argo CD sync wave 明确表达顺序，避免依赖文件名、模板渲染顺序或 Kubernetes 最终一致性碰运气。 + +固定规则： + +- annotation 键必须写成 `argocd.argoproj.io/sync-wave`，不要写成 `rgocd.argoproj.io/sync-wave` 或其他拼写 +- wave 值使用字符串，例如 `"-20"`、`"0"`、`"10"` +- 低 wave 先同步，高 wave 后同步；不要把依赖方和被依赖方放在同一个 wave +- 只有确实存在跨资源启动顺序要求时才加 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 + +如果 nginx 配置在容器启动时解析 upstream，必须保证 upstream 对应 Service 的 wave 早于 nginx Deployment；如果应用启动依赖 Secret / ConfigMap / PVC，必须保证这些资源的 wave 早于消费它们的 workload。 + 如果应用依赖平台 shared 之外的私有服务，必须明确表达依赖来源： - 要么由 Chart 生成应用自带资源 @@ -419,12 +473,17 @@ Chart 必须反映应用的真实运行架构。 - `git status --short` - `git diff --check` +- `yq e '.' .gitlab-ci.yml` - `helm template`（前提是 Chart 与 values 已能渲染） 至少确认： - 接入文件齐全 -- `.gitlab-ci.yml` 包含 test、镜像构建、Chart 发布、GitOps 同步 +- `.gitlab-ci.yml` YAML 语法合法，不包含用于改 YAML 的内联 Python +- `.gitlab-ci.yml` 包含 test、组件级独立镜像构建、Chart 发布、GitOps 同步 +- 多服务应用的业务镜像不是由一个串行 `build-images` job 统一构建；每个自建镜像可被 GitLab 独立调度和重试 +- `package-chart` 通过 `needs:` 等待所有必要镜像构建成功 +- `update-gitops-repo` 通过 `needs:` 依赖 `package-chart` 成功 - release values 指向 `registry.baizhi.cloud` - release values 不覆盖应用自建业务镜像 tag；业务镜像 tag 由 Chart `appVersion` 默认决定 - 第三方镜像没有被错误改写到平台 registry @@ -432,6 +491,7 @@ Chart 必须反映应用的真实运行架构。 - 如果 Dockerfile 原本使用 Docker Hub 源，已切换到 `registry-mirrors.dev.in.chaitin.net`，且未误改其他非 Docker Hub 镜像源 - 如果 Dockerfile 中使用 `apk`，已切换到中科大源 - GitOps update job 指向 `https://deploy.baizhi.cloud/gitops-admin/argodeploy.git` +- GitOps update job 用 `yq` 精确更新当前应用 chart source 的 `targetRevision` - CI 中没有直接调用 Argo - 只使用 `deploy.baizhi.cloud` 与 `registry.baizhi.cloud` - 没有使用不安全的 registry 访问方式 @@ -439,6 +499,7 @@ Chart 必须反映应用的真实运行架构。 - 如果镜像内包含固定 upstream 配置，upstream service 名与 Chart 渲染结果一致 - Neo4j 一类自带依赖的启动环境变量不依赖 `$(OTHER_ENV)` 展开 - 如果应用包含需要持久化数据的服务，对应 PVC / `volumeClaimTemplates` 已显式设置 `storageClassName: longhorn` +- 如果资源存在启动顺序依赖，`argocd.argoproj.io/sync-wave` 拼写正确，wave 顺序符合依赖方向 - 如果检测到的私有 Git 依赖中包含 `git.in.chaitin.net/ai/baizhiyun/opensdk`，缺少必填百智云私有配置时交互停在当前项继续索取 ## 最终输出 @@ -462,3 +523,7 @@ Chart 必须反映应用的真实运行架构。 - 在未检测到私有 Git 依赖中的 `git.in.chaitin.net/ai/baizhiyun/opensdk` 时仍强行接入百智云 - Dockerfile 明明使用了 Docker Hub / `apk` 默认源，却没有切到 `registry-mirrors.dev.in.chaitin.net` / 中科大源，或误改了原本不在 Docker Hub 的镜像源 - 用户未提供必填值时伪造占位内容 +- 多个服务镜像塞进一个串行 build job，导致无法并行构建、无法单独重试、失败定位困难 +- `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`，或把依赖方放在被依赖资源之前