From 71b39b6bf3a4ffc86466b26bd0f8dd7d4df226cb Mon Sep 17 00:00:00 2001 From: "xiaobing.wang" Date: Tue, 31 Mar 2026 20:34:07 +0800 Subject: [PATCH] docs: clarify release manifests and runtime wiring --- README.md | 3 +++ gitops-app-onboarding/SKILL.md | 16 +++++++++++++++- 2 files changed, 18 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index d49a638..620bcb0 100644 --- a/README.md +++ b/README.md @@ -26,6 +26,9 @@ - 平台 shared 之外的私有依赖必须明确来源，不能只写不存在的连接参数 - 应用自带私有依赖的内部口令优先自动生成；外部集成凭据再向用户逐项索取 - 只允许应用仓库 CI 向 GitOps 仓库同步当前应用自己的 release 结果与版本引用；如果当前应用的 chart 版本由 GitOps 仓库中的 `Application` 维护，则只同步更新 `apps//application.yaml` 里的 `targetRevision` +- 如果运行时资源通过 `releases//manifests/` 提供，就必须同步维护这个 path 与 `Application` 中对应的 source，不能只删目录不删引用 +- 第三方镜像保持真实来源；只有当前应用 CI 实际发布的镜像才写到 `registry.baizhi.cloud//...` +- 镜像内自带的 nginx / 反向代理 upstream 必须和 Chart 渲染出来的 Service 名一致，不能混用裸服务名和 fullname 前缀 不适合处理： diff --git a/gitops-app-onboarding/SKILL.md b/gitops-app-onboarding/SKILL.md index a26e5f8..36abf29 100644 --- a/gitops-app-onboarding/SKILL.md +++ b/gitops-app-onboarding/SKILL.md @@ -118,6 +118,9 @@ description: 面向当前 Baizhi GitOps 平台的项目接入工作流，只适 如果应用还有不适合放进 Chart 的静态清单，可以在后续发布结果中导出到当前 GitOps 仓库的 `releases//manifests/`。 +- 如果 Chart 运行时依赖的 `Secret`、`ConfigMap` 或 shared 资源并不是由 Chart 自己创建，而是通过 `deploy/release/secret.yaml` 或 GitOps 仓库中的 `shared/` 提供，就必须保留一个最小的 `releases//manifests/` 输出，并让当前应用的 `Application` 持续引用这个 path +- 如果某次发布不再导出 `releases//manifests/`，就必须同时移除当前应用 `Application` 中对应的 manifests source；不要留下一个指向不存在路径的 source + ## GitLab CI 规则 runner 约束： @@ -233,11 +236,15 @@ deploy/helm// - nginx 对外 Service 固定使用 `NodePort` - 后端 Service 默认使用集群内访问类型，不对外暴露 `NodePort` - 如果应用运行时依赖某个不属于平台 shared 的私有服务，Chart / release bundle 必须把该依赖的来源表达清楚：要么生成应用自带资源，要么明确引用用户已提供的外部地址；不要只留下一个指向不存在服务的 host +- 应用自带的私有依赖如果同时需要应用口令和依赖自身启动口令，Secret key 设计要把两种消费方式都表达清楚；例如既保留 `neo4j_password` 供业务容器连接使用，也额外提供 `neo4j_auth` 这类组合值供 Neo4j 自身启动使用 - `NodePort` 必须来自用户或平台已分配值，agent 不得自行猜测或默认分配端口 - 不要生成 Ingress 模板或 Ingress values - 设置 `enableServiceLinks: false` - 支持 `imagePullSecrets` - 环境变量注入保持可读 +- 如果镜像内自带 nginx / 反向代理配置，upstream service 名必须与 Chart 实际渲染出来的 Service 名一致；如果 Chart 使用 `fullname` 前缀，就不要在镜像配置里写裸服务名 `server`、`mcp`、`frontend` +- Kubernetes `env.value` 不会展开 `$(OTHER_ENV)` 这种 shell 变量引用；不要生成 `NEO4J_AUTH=neo4j/$(NEO4J_PASSWORD)` 这类写法并假设容器启动时会自动拼接 +- 对像 Neo4j 这类会把 `NEO4J_*` 解析为配置项的镜像，不要额外注入并不存在的配置名，例如 `NEO4J_PASSWORD` - 健康检查要符合真实应用行为 `_helpers.tpl` 一般至少提供： @@ -293,7 +300,8 @@ deploy/helm// 至少应满足： -- 镜像地址指向 `registry.baizhi.cloud//...` +- 应用自己构建并发布的运行时镜像使用 `registry.baizhi.cloud//...` +- 第三方基础镜像或官方镜像如果并未由当前应用 CI 同步到平台 registry，就保持其真实来源，不要擅自改写成 `registry.baizhi.cloud/library/...` - Secret 名符合平台约定 - 私有镜像拉取时包含 `imagePullSecrets` - 与 Chart schema 保持一致 @@ -311,6 +319,7 @@ deploy/helm// - 先区分“外部集成凭据”和“应用自带私有依赖的内部口令” - 如果是外部集成凭据，应在生成到对应配置时主动向用户索取 - 如果是应用自带私有依赖的内部口令，优先由生成流程一次性生成并写入 release secret，而不是要求用户手填 +- 如果某个工作负载需要组合型鉴权字段，例如 `username/password` 形式的单个环境变量，优先在 Secret 中直接写出完整值，再由 workload 直接读取该 key - 如果用户暂时没有提供，不要造占位内容冒充可部署配置 - 对部署阻塞项，按最小必要粒度逐项提问，优先直接问“这一项应填什么” - 在交互会话中，如果当前步骤需要某个必填项才能继续，就先向用户索取当前顺序中的下一项 @@ -354,6 +363,7 @@ shared 边界： - 只要应用运行时配置仍引用某个应用私有依赖，就应在应用 Chart / release bundle 中把它一并表达出来，而不是只在 values 里保留连接参数 - 不要把某个厂商的客户端证书、私钥、应用专属 `app_id`、tenant id、client id、namespace id、应用独有 webhook 签名密钥放进 `shared/` - 镜像拉取默认使用 `registry-pull-secret`，不要随便为每个应用再造一个 pull secret，除非平台模型发生变化 +- 如果 Chart 通过 `imagePullSecrets`、`platform-runtime-config`、`platform-shared-secrets` 或应用私有 release secret 引用运行时资源，而这些资源不是由 Chart 直接创建，就必须确保 `releases//manifests/` 仍然会把它们应用到目标 namespace ## 百智云用户鉴权接入 @@ -412,10 +422,14 @@ opensdk 读取与挂载规则： - 应用仓库接入文件齐全 - `.gitlab-ci.yml` 包含 test、镜像构建、chart 发布、release 结果同步逻辑 - release values 指向 `registry.baizhi.cloud` +- 非当前应用自行发布的第三方镜像仍保持真实来源，不会被错误改写到平台 registry - GitOps 仓库更新 job 指向 `https://deploy.baizhi.cloud/gitops-admin/argodeploy.git` - CI 中没有直接调用 Argo - 仅使用 `deploy.baizhi.cloud` 与 `registry.baizhi.cloud` - 没有使用不安全的 HTTP registry 访问方式 +- 如果 `Application` 仍引用 `releases//manifests/`，该 path 在发布结果中实际存在且能渲染；如果发布结果不再包含该 path，`Application` 中也不会残留这个 source +- 如果镜像内包含固定 upstream 配置，upstream service 名与当前 Chart 渲染的 Service 名保持一致，不会出现 `host not found in upstream` 这类启动错误 +- Neo4j 一类自带依赖的启动环境变量不会依赖 Kubernetes 不支持的 `$(OTHER_ENV)` 展开 - 如果存在用户未提供的必填私有配置，交互会话会继续停在当前必填项上索取补值 ## 最终输出要求