From f557f1cd206af925afd8ad8ebcf73b20ad04e12e Mon Sep 17 00:00:00 2001 From: Codex Date: Tue, 26 May 2026 03:40:05 +0800 Subject: [PATCH] docs: record G14 GitOps Argo sync guard --- AGENTS.md | 1 + docs/reference/g14-gitops-cicd.md | 9 +++++++-- 2 files changed, 8 insertions(+), 2 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 7a359bc1..a89f9c2b 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -5,6 +5,7 @@ HWLAB 是硬件实验室运行面和控制面项目。本文是 agent、指挥 ## P0 G14 原生 k8s/GitOps 运行面归一 - G14 是当前 HWLAB DEV/PROD 原生 k8s 与 GitOps 运行面真相；`hwlab-dev` 与 `hwlab-prod` 均由 G14 k3s、Tekton、`G14-gitops` 和 Argo CD 管理，详见 [docs/reference/g14-gitops-cicd.md](docs/reference/g14-gitops-cicd.md)。 +- G14 GitOps render 若改变 Argo Application、AppProject、runtime path 或 DEV/PROD 拆分目录，必须同步应用 `deploy/gitops/g14/argocd/project.yaml`、`application-dev.yaml` 和 `application-prod.yaml`；只推 `G14-gitops` 分支不等于 Argo 已切到新 path。 - D601 HWLAB DEV、D601 `dev-cd-apply`、`ci-publish` 和旧 `main` JS 脚本式 CI/CD 只作为 legacy 迁移来源和事故参考；新开发、发布、验收、文档和运行面实验不得把 D601 当作当前 HWLAB runtime source-of-truth。 - G14 k3s 操作必须通过 UniDesk route `G14:k3s` 执行；不得用 D601 kubeconfig、Docker Desktop Kubernetes、master server 本地 check/build 或旧 JS CD 结果作为 G14 DEV/PROD 通过证据。 diff --git a/docs/reference/g14-gitops-cicd.md b/docs/reference/g14-gitops-cicd.md index f0b97867..606afa9c 100644 --- a/docs/reference/g14-gitops-cicd.md +++ b/docs/reference/g14-gitops-cicd.md @@ -58,6 +58,10 @@ G14 不要求 GitHub webhook 或 GitHub Actions 配置。`hwlab-ci/hwlab-g14-bra Pipeline 的标准路径是：`G14` source commit -> `CI.json` Tekton 测试 -> commit-tagged image push 到 G14 registry -> render `deploy/gitops/g14/**` -> push `G14-gitops` -> Argo CD 同步 runtime。CD 只消费已经构建好的镜像和 Git desired state，不在 Argo CD 内构建镜像。 +GitOps promotion 成功只证明 `G14-gitops` 分支已经写入新 desired state；如果 render 改变了 Argo Application、AppProject、runtime path 或 DEV/PROD 拆分目录，必须同步检查并应用 `deploy/gitops/g14/argocd/project.yaml`、`application-dev.yaml` 和 `application-prod.yaml`。`hwlab-g14-dev` 必须指向 `deploy/gitops/g14/runtime-dev`，`hwlab-g14-prod` 必须指向 `deploy/gitops/g14/runtime-prod`；如果集群里 Application 仍指向旧 `deploy/gitops/g14/runtime`，Argo 会停在旧 revision，即使 CI/publish/promote 全部成功也不会滚动新镜像。 + +观察 PipelineRun、Argo 和 rollout 时使用短连接轮询：一次 `kubectl get` 或有限 `logs --tail` 后返回，由指挥侧间隔重试。不要用长时间 `kubectl wait --timeout=900s` 占住 `tran G14:k3s` 透传锁；如果误用长 wait，只能杀掉本地等待客户端并清理 stale tran lock，不能把这个等待过程当成 CD 失败。 + 下载阶段排障命令： ```sh @@ -73,8 +77,9 @@ KUBECONFIG=/etc/rancher/k3s/k3s.yaml kubectl -n hwlab-ci logs pod/