430 lines
13 KiB
Markdown
430 lines
13 KiB
Markdown
---
|
||
name: gitops-app-onboarding
|
||
description: 面向当前 Baizhi GitOps 平台的项目接入工作流，只适用于 `deploy.baizhi.cloud`、`registry.baizhi.cloud`、GitLab + Argo CD 这套固定交付模型。只要用户提到“给当前平台接入新项目”“恢复 .gitlab-ci.yml / deploy 目录”“补齐当前平台的 Helm chart / release bundle”“修当前平台的发版链路”“让应用仓库在发版时推送自己的 release 结果”，就应优先使用这个 skill；如果只是通用 CI、通用 Helm 或通用 GitOps 任务而未指向当前平台，不应触发。
|
||
---
|
||
|
||
# GitOps 项目接入 Skill
|
||
|
||
## 目标
|
||
|
||
让 agent 能独立完成下面四件事：
|
||
|
||
- 生成或修复 `.gitlab-ci.yml`
|
||
- 生成或修复 `deploy/helm/<app>/`
|
||
- 生成或修复 `deploy/release/`
|
||
- 让发版链路把当前应用的发布结果同步到固定 GitOps 仓库
|
||
|
||
## 平台固定常量
|
||
|
||
除非用户明确要求修改，否则固定使用：
|
||
|
||
- GitOps 主机：`deploy.baizhi.cloud`
|
||
- Registry 主机：`registry.baizhi.cloud`
|
||
- Helm OCI 仓库：`oci://registry.baizhi.cloud/helm`
|
||
- GitOps 仓库地址：`https://deploy.baizhi.cloud/gitops-admin/argodeploy.git`
|
||
- Registry 用户名：`registry-ci`
|
||
- 共享 pull secret：`registry-pull-secret`
|
||
- GitOps 控制器：Argo CD
|
||
- 代码托管：GitLab
|
||
|
||
GitLab CI 默认依赖这些变量：
|
||
|
||
- `GITEA_USER`
|
||
- `GITEA_TOKEN`
|
||
- `REGISTRY_PASSWORD`
|
||
|
||
## 开始前先做什么
|
||
|
||
先按这个顺序读仓库：
|
||
|
||
1. `README.md`
|
||
2. Dockerfile、包管理文件、构建脚本、已有 deploy 文件
|
||
3. 用户提供的额外设计文档
|
||
|
||
在动手前先确定：
|
||
|
||
- 组件列表
|
||
- 每个组件的构建上下文与入口
|
||
- 对外暴露方式
|
||
- 运行时配置结构
|
||
- 平台共享依赖与应用私有依赖
|
||
|
||
应用仓库自己的 `README.md` 是应用运行架构的真相来源；本 skill 只定义平台接入规则。
|
||
|
||
## 边界
|
||
|
||
- 只处理应用仓库侧接入
|
||
- 不修改与当前应用无关的 GitOps 清单
|
||
- 对 GitOps 的唯一动作，是在应用仓库 CI 中同步当前应用自己的 release 结果与版本引用
|
||
- 如果当前应用的 `Application` 已存在，只允许更新 `apps/<app>/application.yaml` 中当前应用 chart source 的 `targetRevision`
|
||
- 不修改 `AppProject`、bootstrap、其他应用的 `Application`
|
||
|
||
## 应用仓库必须产出哪些文件
|
||
|
||
### CI
|
||
|
||
- `.gitlab-ci.yml`
|
||
|
||
### Chart
|
||
|
||
- `deploy/helm/<app>/Chart.yaml`
|
||
- `deploy/helm/<app>/values.yaml`
|
||
- `deploy/helm/<app>/templates/*`
|
||
|
||
### release 作者源
|
||
|
||
- `deploy/release/metadata.yaml`
|
||
- `deploy/release/values.yaml`
|
||
- `deploy/release/secret.yaml`
|
||
|
||
## GitOps 仓库里最终应该有哪些文件
|
||
|
||
CI 导出结果固定为：
|
||
|
||
- `deploy/release/metadata.yaml` -> `releases/<app>/metadata.yaml`
|
||
- `deploy/release/values.yaml` -> `releases/<app>/values.yaml`
|
||
- `deploy/release/secret.yaml` -> `releases/<app>/manifests/secret.yaml`
|
||
- `apps/<app>/application.yaml` -> 只更新 chart source 的 `targetRevision`
|
||
|
||
固定规则：
|
||
|
||
- 不导出 `releases/<app>/secret.yaml`
|
||
- 不生成或覆盖 `db-secret.yaml`、 `kustomization.yaml` 这类 GitOps 仓库里已有的文件
|
||
|
||
## GitLab CI 规则
|
||
|
||
### stages
|
||
|
||
固定使用：
|
||
|
||
- `test`
|
||
- `build`
|
||
- `release`
|
||
|
||
### runner tags
|
||
|
||
只要 job 使用 Docker、DinD 或 `docker buildx`，就必须带：
|
||
|
||
- `docker`
|
||
- `network`
|
||
|
||
### test job
|
||
|
||
用途：只做测试，不改 GitOps，不推镜像。
|
||
|
||
要求：
|
||
|
||
- 运行在分支和 MR 上
|
||
- 安装当前语言栈的最小依赖
|
||
- 如依赖私有仓库，补齐认证
|
||
- 使用项目原生测试入口
|
||
|
||
Go 项目默认变量写在 `.gitlab-ci.yml` 的 `variables:`：
|
||
|
||
- `GOPROXY=https://goproxy.cn,direct`
|
||
- `GOSUMDB=sum.golang.google.cn`
|
||
- `GOPRIVATE=git.in.chaitin.net`
|
||
- `GONOSUMDB=git.in.chaitin.net`
|
||
- `GONOPROXY=git.in.chaitin.net`
|
||
- `GOINSECURE=git.in.chaitin.net`
|
||
- `GIT_SSL_NO_VERIFY="true"`
|
||
|
||
### release 触发条件
|
||
|
||
只在 `vX.Y.Z` tag 上触发发布链路。
|
||
|
||
### build-images job
|
||
|
||
输入：源码、Dockerfile、多组件构建上下文。
|
||
|
||
输出：推送到 `registry.baizhi.cloud/<app>/<component>:<version>` 的运行时镜像。
|
||
|
||
要求：
|
||
|
||
- 登录 `registry.baizhi.cloud`
|
||
- 优先使用 `docker buildx`
|
||
- 私有 Git 依赖通过 `.netrc` 和 build secret 传入
|
||
- 如需额外 CA，也通过 build secret 传入
|
||
- 如果 Dockerfile 内会执行 `go mod download`、`go build` 等 Go 构建命令，必须通过 `--build-arg` 透传 Go 构建变量，不要只写在 `.gitlab-ci.yml` 的 `variables:` 里
|
||
- 至少透传：`GOPROXY`、`GOSUMDB`、`GOINSECURE`
|
||
- 如果 Dockerfile 用到了 `GOPRIVATE`、`GONOSUMDB`、`GONOPROXY`，也一并透传
|
||
- Dockerfile 中对应变量必须有 `ARG`，并让构建命令实际使用传入值，而不是退回默认值
|
||
|
||
禁止：
|
||
|
||
- `http://registry...`
|
||
- `--plain-http`
|
||
- `--insecure-skip-tls-verify`
|
||
- 不要假设 `.gitlab-ci.yml` 中的环境变量会自动进入 `docker build` / `docker buildx build`
|
||
|
||
### package-chart job
|
||
|
||
输入：`deploy/helm/<app>/Chart.yaml`、`deploy/helm/<app>/values.yaml`、`deploy/helm/<app>/templates/*`
|
||
|
||
输出：推送到 `oci://registry.baizhi.cloud/helm` 的 Chart 包。
|
||
|
||
要求：
|
||
|
||
- `helm registry login registry.baizhi.cloud`
|
||
- 在临时目录复制 `deploy/helm/<app>/`
|
||
- 把复制品中的 `version` 和 `appVersion` 改成 tag 版本
|
||
- `helm package`
|
||
- `helm push`
|
||
|
||
### update-gitops-repo job
|
||
|
||
输入：`deploy/release/*`、当前 tag 版本、GitOps 仓库中的 `apps/<app>/application.yaml`
|
||
|
||
输出：
|
||
|
||
- `releases/<app>/metadata.yaml`
|
||
- `releases/<app>/values.yaml`
|
||
- `releases/<app>/manifests/` 下的发布结果
|
||
- `apps/<app>/application.yaml` 中当前应用 chart source 的 `targetRevision`
|
||
|
||
处理顺序固定为：
|
||
|
||
1. 克隆 `https://${GITEA_USER}:${GITEA_TOKEN}@deploy.baizhi.cloud/gitops-admin/argodeploy.git`
|
||
2. 确保 `releases/<app>/` 与 `releases/<app>/manifests/` 存在，不要整体清空目录
|
||
3. 将应用仓库中的 `deploy/release/metadata.yaml` 和 `deploy/release/values.yaml` 复制到 GitOps 仓库的 `releases/<app>/metadata.yaml` 与 `releases/<app>/values.yaml`，覆盖已有内容
|
||
4. 保留已有的 `releases/<app>/manifests/kustomization.yaml` 与 `releases/<app>/manifests/db-secret.yaml`
|
||
5. 将 `deploy/release/secret.yaml` 物化为 `releases/<app>/manifests/secret.yaml`
|
||
6. 替换 `releases/<app>/metadata.yaml` 和 `releases/<app>/values.yaml` 中的 `__VERSION__`
|
||
7. 更新 `apps/<app>/application.yaml` 中当前应用 chart source 的 `targetRevision`
|
||
8. 只有存在 diff 时才提交并推送 `main`
|
||
|
||
禁止：
|
||
|
||
- 在 CI 中调用 `kubectl`
|
||
- 在 CI 中调用 `argocd app sync`
|
||
- 把 hard refresh 当常规发布步骤
|
||
|
||
## Helm Chart 规则
|
||
|
||
Chart 必须反映应用的真实运行架构。
|
||
|
||
固定要求：
|
||
|
||
- 按职责拆文件，不堆一个大模板
|
||
- 模板中不硬编码生产 tag
|
||
- 所有镜像名从 values 读取
|
||
- 所有 Service 暴露方式从 values 读取
|
||
- nginx 对外 Service 固定使用 `NodePort`
|
||
- 后端 Service 只做集群内访问
|
||
- 不生成 Ingress 模板，也不保留 Ingress values
|
||
- `NodePort` 必须来自用户或平台已分配值，不能猜
|
||
- 设置 `enableServiceLinks: false`
|
||
- 支持 `imagePullSecrets`
|
||
- 环境变量注入保持可读
|
||
- 如果镜像内带 nginx / 反向代理配置，upstream service 名必须与 Chart 渲染出的 Service 名一致
|
||
- 生成 chart 时要确认应用是否包含需要经 nginx 转发的静态文件；如果有，必须明确静态资源目录、挂载方式和 nginx 路由，不要只配后端 upstream
|
||
- 不要依赖 Kubernetes 不支持的 `$(OTHER_ENV)` 展开
|
||
- 对 Neo4j 这类镜像，不要注入不存在的 `NEO4J_*` 配置名，例如 `NEO4J_PASSWORD`
|
||
|
||
如果应用依赖平台 shared 之外的私有服务，必须明确表达依赖来源：
|
||
|
||
- 要么由 Chart 生成应用自带资源
|
||
- 要么明确引用用户提供的外部地址
|
||
|
||
不能只留一个指向不存在服务的 host。
|
||
|
||
如果应用自带依赖同时需要业务连接口令和依赖自身启动口令，Secret key 要同时表达两种消费方式，例如：
|
||
|
||
- `neo4j_password`
|
||
- `neo4j_auth`
|
||
|
||
## 对外暴露模型
|
||
|
||
固定使用：
|
||
|
||
- nginx 作为统一入口
|
||
- 对外只暴露一个 nginx `NodePort`
|
||
- 后端服务只在集群内通信
|
||
- 不生成 Ingress
|
||
|
||
`NodePort` 处理规则：
|
||
|
||
- 用户或文档已提供时直接使用
|
||
- 没提供时，在生成到这一项时立即索取
|
||
- 不要写示例端口或默认端口
|
||
|
||
## Release Bundle 规则
|
||
|
||
### `metadata.yaml`
|
||
|
||
至少包含：
|
||
|
||
- 应用名
|
||
- release 名
|
||
- namespace
|
||
- chart 名
|
||
- chart 版本
|
||
- chart 仓库
|
||
- 镜像 tag
|
||
- 源码仓库地址
|
||
|
||
### `values.yaml`
|
||
|
||
必须是可部署默认值，不是示例值。
|
||
|
||
至少满足：
|
||
|
||
- 应用自建镜像使用 `registry.baizhi.cloud/<app>/...`
|
||
- 第三方镜像保持真实来源
|
||
- Secret 名与 Chart 约定一致
|
||
- PostgreSQL 连接读取应用自己的 `databaseSecret`
|
||
- 私有镜像包含 `imagePullSecrets`
|
||
- 与 Chart schema 一致
|
||
- nginx 对外入口使用 `NodePort`
|
||
- `NodePort` 值来自用户或平台分配结果
|
||
- 不包含 Ingress 配置项
|
||
|
||
### `manifests/db-secret.yaml`
|
||
|
||
这是 deploy 仓库注册应用阶段生成的数据库源，不是应用仓库侧要生成的文件。至少包含：
|
||
|
||
- `host`
|
||
- `port`
|
||
- `database`
|
||
- `username`
|
||
- `password`
|
||
|
||
固定规则：
|
||
|
||
- chart 如果依赖 Postgres 则必须消费这个 secret
|
||
|
||
### `secret.yaml`
|
||
|
||
只放应用私有 Secret，key 名必须与 Chart 读取的 key 对齐。
|
||
|
||
规则：
|
||
|
||
- 不伪造生产值
|
||
- 外部集成凭据在生成到对应配置时逐项索取
|
||
- 应用自带私有依赖的内部口令优先自动生成
|
||
- 组合型鉴权字段优先直接写成完整 key 值
|
||
- 缺值时停在当前项继续问，不要留看似可部署的假配置
|
||
|
||
## 平台共享配置契约
|
||
|
||
`shared/` 只放平台级共享配置。
|
||
|
||
共享资源：
|
||
|
||
- `platform-runtime-config`
|
||
- `platform-shared-secrets`
|
||
- `registry-pull-secret`
|
||
|
||
`platform-runtime-config` 提供：
|
||
|
||
- `LLM_BASE_URL`
|
||
- `EMBEDDER_BASE_URL`
|
||
|
||
`platform-shared-secrets` 提供：
|
||
|
||
- `REDIS_PASSWORD`
|
||
- `QDRANT_API_KEY`
|
||
- `MINIO_ACCESS_KEY`
|
||
- `MINIO_SECRET_KEY`
|
||
|
||
平台共享基础设施固定为：
|
||
|
||
- `PostgreSQL`
|
||
- `Redis`
|
||
- `Qdrant`
|
||
- `MinIO`
|
||
|
||
固定 FQDN：
|
||
|
||
- `redis.infra.svc.cluster.local`
|
||
- `qdrant.infra.svc.cluster.local`
|
||
- `minio.infra.svc.cluster.local`
|
||
|
||
固定规则：
|
||
|
||
- 不要写成当前应用 namespace 下的裸服务名
|
||
- 不默认为 `Redis`、`Qdrant`、`MinIO` 生成应用私有实例
|
||
- `Neo4j` 不属于 shared；如应用需要，由应用自己部署
|
||
- 不要把应用私有鉴权材料放进 `shared/`
|
||
- 如果 Chart 依赖的运行时资源不是由 Chart 直接创建，就必须确保 `releases/<app>/manifests/` 仍会把这些资源 apply 到目标 namespace
|
||
|
||
## 百智云用户鉴权接入
|
||
|
||
这是平台必填接入项。
|
||
|
||
固定规则：
|
||
|
||
- 不要把鉴权材料放进 `shared/`
|
||
- 不要伪造生产值
|
||
- 按固定顺序逐项索取：`app_id` -> `app.crt` -> `app.key` -> `ca.crt` -> `public.key`
|
||
- 缺少哪一项，就停在那一项继续问
|
||
|
||
挂载规则：
|
||
|
||
- 固定挂载目录：`/app/ssl`
|
||
- 固定文件路径：`/app/ssl/app.crt`、`/app/ssl/app.key`、`/app/ssl/ca.crt`
|
||
- 不要改成其他自定义目录
|
||
- `public.key` 如果保留，应明确其用途，不要混同为 mTLS 必需文件
|
||
|
||
## 提问方式
|
||
|
||
- 只问当前步骤真正阻塞的值
|
||
- 逐项问，不要一次性要一大串
|
||
- 对外部集成字段，在写到对应配置时就问
|
||
- 对应用自带私有依赖内部口令，优先自动生成
|
||
- 如果当前正在等补值，回复重点只放当前这一项
|
||
|
||
## 执行顺序
|
||
|
||
按下面顺序推进：
|
||
|
||
1. 读 README 与构建文件
|
||
2. 梳理组件、依赖、暴露模型
|
||
3. 生成或修复 `.gitlab-ci.yml`
|
||
4. 生成或修复 Chart
|
||
5. 缺少必填值时停在当前项索取
|
||
6. 生成或修复 `deploy/release/`
|
||
7. 自检并汇报风险点
|
||
|
||
## 自检
|
||
|
||
完成后尽量执行：
|
||
|
||
- `git status --short`
|
||
- `git diff --check`
|
||
- `helm template`（前提是 Chart 与 values 已能渲染）
|
||
|
||
至少确认：
|
||
|
||
- 接入文件齐全
|
||
- `.gitlab-ci.yml` 包含 test、镜像构建、Chart 发布、GitOps 同步
|
||
- release values 指向 `registry.baizhi.cloud`
|
||
- 第三方镜像没有被错误改写到平台 registry
|
||
- GitOps update job 指向 `https://deploy.baizhi.cloud/gitops-admin/argodeploy.git`
|
||
- CI 中没有直接调用 Argo
|
||
- 只使用 `deploy.baizhi.cloud` 与 `registry.baizhi.cloud`
|
||
- 没有使用不安全的 registry 访问方式
|
||
- 如果 `Application` 仍引用 `releases/<app>/manifests/`，该 path 在发布结果中实际存在
|
||
- 如果镜像内包含固定 upstream 配置，upstream service 名与 Chart 渲染结果一致
|
||
- Neo4j 一类自带依赖的启动环境变量不依赖 `$(OTHER_ENV)` 展开
|
||
- 缺少必填私有配置时，交互停在当前项继续索取
|
||
|
||
## 最终输出
|
||
|
||
默认按这个顺序汇报：
|
||
|
||
1. 修改了哪些文件
|
||
2. 关键决定
|
||
3. 最值得人工复核的点
|
||
|
||
## 常见错误
|
||
|
||
- 把应用私有鉴权材料放进 `shared/`
|
||
- 在 CI 里直接刷新 Argo
|
||
- 重新引入旧域名
|
||
- 使用 insecure registry 参数
|
||
- Chart 与应用真实组件不匹配
|
||
- 在生产 release values 中写示例地址
|
||
- 擅自发明新的公网 host
|
||
- 用户未提供必填值时伪造占位内容
|