Star9
73
代码
代码
Issues3
Pull Requests45
项目讨论
Wiki
分析
Star9
73
已关闭
新增提案：0035-安装部署支持多仓库镜像以及兼容k8s的1.28.8版本 #62
xuyouh创建于 1月29日关闭于 22 天前
新增提案：0035-安装部署支持多仓库镜像以及兼容k8s的1.28.8版本 #62
已关闭
xuyouh创建于 1月29日关闭于 22 天前
从xuyouhong/ofepofep/sig_installation_deploy_opt合入到openFuyao/ofepmain
共 1 个文件变更+713-0
Aofeps/sig-Installation/ofep-0035-支持多仓库镜像部署以及兼容k8s的1.28.8版本.md+713-0
@@ -0,0 +1,713 @@
1+<!-- 格式合规检查：已通过 -->
2+---
3+# 提案标题
4+title: 支持多仓库镜像部署以及兼容 k8s 的 1.28.8 版本安装
5+# 提案编号
6+ofep-number: 0035
7+# 提案作者
8+authors:
9+ - "@xuyouhong"
10+# 提案主导SIG
11+owning-sig: sig-Installation
12+# 提案协作SIG
13+participating-sigs: []
14+# 提案状态(初步草案|准备开始实现|已在SIG中实现并合并|提案被暂缓|提案被否决|作者主动撤回提案|被另一个oFEP取代)
15+status: provisional
16+# 创建日期
17+creation-date: 2025-01-29
18+# 评审人
19+reviewers:
20+ - TBD
21+# 批准人
22+approvers:
23+ - TBD
24+# 相关联的其他oFEP
25+see-also:
26+ - "/ofeps/sig-Installation/ofep-0013-安装部署完全支持离线环境.md"
27+ - "/ofeps/sig-Installation/ofep-0040-引导节点安仓库自依赖安装和提供bkeagent健康端口.md"
28+# 当前oFEP替代了哪些已有提案
29+replaces: []
30+# 当前oFEP被哪些提案替代，当status为replaced时需要填写此字段
31+replaced-by: []
32+# 此oFEP当前开发阶段
33+stage: alpha
34+# 最近一次推进的版本
35+latest-milestone: "v26.03"
36+# 各阶段目标版本
37+milestone:
38+ alpha: ""
39+ beta: ""
40+ stable: ""
41+# 功能开关及影响组件
42+feature-gates:
43+ - name: MultiRegistryImageDeploy
44+ components:
45+ - bkeadm
46+ - cluster-api-provider-bke
47+ - bke-manifests
48+ - name: K8s1288OfflineInstall
49+ components:
50+ - bkeadm
51+ - bke-manifests
52+# 是否支持关闭该功能
53+disable-supported: true
54+# 该功能引入的监控指标
55+metrics: []
56+---
57+ 
58+# oFEP-0035：支持多仓库镜像部署以及兼容 k8s 的 1.28.8 版本安装
59+ 
60+<!-- toc -->
61+- [发布签核清单](#release-signoff-checklist)
62+- [摘要](#summary)
63+- [动机](#motivation)
64+ - [目标](#goals)
65+ - [非目标](#non-goals)
66+- [提案](#proposal)
67+ - [用户故事与用例视图](#user-stories)
68+ - [注释/约束/警告](#notesconstraintscaveats)
69+ - [风险与缓解措施](#risks-and-mitigations)
70+- [设计细节](#design-details)
71+ - [架构与设计前提](#architecture-and-design-premises)
72+ - [特性描述](#feature-description)
73+ - [4+1 架构视图](#41-architecture-views)
74+ - [模块接口与配置约定](#module-interfaces-and-configuration)
75+ - [关键设计决策表](#关键设计决策表)
76+ - [DFX 质量属性设计](#dfx-quality-attributes)
77+ - [测试计划](#test-plan)
78+ - [毕业标准](#graduation-criteria)
79+ - [升级/降级策略](#upgrade--downgrade-strategy)
80+ - [版本倾斜策略](#version-skew-strategy)
81+- [生产可用性审查](#production-readiness-review)
82+- [实施历史](#implementation-history)
83+- [缺点](#drawbacks)
84+- [替代方案](#alternatives)
85+- [所需基础设施](#infrastructure-needed)
86+<!-- /toc -->
87+ 
88+## 发布签核清单
89+ 
90+标记有（R）的项目*在达到里程碑/发布*之前是必需的。
91+ 
92+- [ ]（R）发布里程碑中的增强问题，链接到 [openfuyao/ofep](https://gitcode.com/openfuyao/ofep) 中的 oFEP 目录
93+- [ ] (R) oFEP 审批者已批准 oFEP 状态为“可实施”
94+- [ ] (R) 设计细节已适当记录
95+- [ ]（R）测试计划已到位，并考虑了 SIG 架构和 SIG 测试的输入（包括测试重构）
96+ - [ ] 针对所有 Beta API 操作（端点）进行 e2e 测试
97+ - [ ] (R) 确保 GA e2e 测试满足一致性测试的要求
98+ - [ ] (R) GA e2e 测试至少需要两周时间才能证明测试结果无 flake（不稳定或偶发失败）
99+- [ ] (R) 毕业标准已设定
100+- [ ] (R) 生产准备情况审查完成
101+- [ ] (R) 生产准备情况审查已获批准
102+- [ ] “实施历史”部分已更新里程碑
103+- [ ] 面向用户的文档已在 [openfuyao/docs](https://gitcode.com/openfuyao/docs) 创建，以便发布到 [openfuyao.com](https://openfuyao.com/)
104+- [ ] 支持文档 - 例如，额外的设计文档、邮件列表讨论/SIG 会议链接、相关 PR/问题、发行说明
105+ 
106+- [openfuyao.com](https://openfuyao.com/)
107+- [openfuyao/ofep](https://gitcode.com/openfuyao/ofep)
108+- [openfuyao/docs](https://gitcode.com/openfuyao/docs)
109+ 
110+## 摘要
111+ 
112+本提案涵盖 openFuyao 安装部署链路上的两项增强能力：
113+ 
114+1. **多仓库镜像部署**：集群安装过程中，镜像不再强制来自单一 `cr.openfuyao.cn` 仓库，而是按社区制品规范分别从自编译镜像仓、可再分发三方仓（`hub.oepkgs.net`）及各自上游仓（如 `registry.k8s.io`、`docker.io`）拉取；同时支持用户将镜像导入**同一自定义内部仓库**（仓库名+项目名相同场景）后，通过模板渲染统一 `repo` 参数或 registry 重定向完成安装。
115+2. **兼容 Kubernetes v1.28.8 离线安装**：社区制备 v1.28.8 版本镜像与二进制，支持用户在离线制品包中指定 K8s 版本后完成 **≥ v1.28.8** 的低版本集群离线部署（containerd v2.1.1 已初步验证可拉起 Pod）；在线安装暂不支持指定该低版本。
116+ 
117+与 [oFEP-0013](/ofeps/sig-Installation/ofep-0013-安装部署完全支持离线环境.md) 的关系：oFEP-0013 聚焦全离线制品包与 containerd 单点 mirror；本 oFEP 扩展为**多来源镜像**在线/自定义仓场景，并增加 K8s 1.28.8 离线版本支持。
118+ 
119+## 动机
120+ 
121+openFuyao 社区与政企伙伴在安装部署中存在以下痛点：
122+ 
123+| 痛点 | 现状 | 影响 |
124+|------|------|------|
125+| 镜像来源单一 | 官方安装路径默认所有镜像来自 `cr.openfuyao.cn` | 与社区制品分仓规范（cr / oepkg / 上游）不一致；流水线无法按来源归类 |
126+| 自定义仓能力受限 | 模板渲染仅支持单一 `repo` 参数替换 | 伙伴将镜像导入同一内部 Harbor 后，无法灵活覆盖多来源 YAML |
127+| K8s 版本固定 | 仅支持社区当前主推 K8s 版本 | 部分客户需 v1.28.8 等较低版本离线部署，无法满足合规或存量环境 |
128+ 
129+部分发行版伙伴会将安装所需镜像统一导入内部**同一 URL、同一 repo/项目**下，需要 openFuyao 安装工具链支持该交付形态。
130+ 
131+### 目标
132+ 
133+1. **流水线场景（多来源）**：在线/离线安装时，Pod 可按镜像来源分别从 `cr.openfuyao.cn`、`hub.oepkgs.net`、`registry.k8s.io`、`docker.io` 等拉取，满足社区制品分仓要求。
134+2. **自定义仓场景（单 repo）**：支持用户将镜像导入同一内部仓库（仓库名+项目名相同），通过 **统一 `repo` 模板渲染** 或 **registry 重定向** 完成引导集群与管理/业务集群安装。
135+3. **引导集群离线小包 2**：支持不含 openFuyao 前端/console 的最小引导集安装（与 oFEP-0040 自依赖方向对齐）。
136+4. **K8s v1.28.8 离线安装**：社区提供 v1.28.8 对应 kube-*、etcd 等镜像与二进制；用户修改版本配置 YAML 后可离线部署；组件安装支持按 K8s 版本进行模板渲染。
137+5. openFuyao 核心组件 YAML/chart 整改，暴露 `repo` 或可 `--set` 的 values 参数。
138+ 
139+### 非目标
140+ 
141+1. 不改造第三方上游 chart 内写死的镜像地址（保持原状，文档说明限制）。
142+2. K8s v1.28.8 **在线**安装自动同步 OBS 低版本文件（当前不支持，仅离线）。
143+3. 不在本 oFEP 解决扩展组件应用市场多 repo 强制统一（扩展组件仅梳理镜像来源，不要求同一 repo）。
144+4. 不覆盖 oFEP-0013 已定义的增量 patch 制品包全流程（可复用 containerd mirror 能力）。
145+5. 不支持低于 v1.28.8 的 K8s 版本。
146+ 
147+## 提案
148+ 
149+本提案通过 registry 重定向（k3s/containerd）、manifest 模板渲染、离线制品版本配置及 bke-manifests 整改，使安装部署同时满足社区多仓流水线与伙伴单仓导入两种交付诉求。
150+ 
151+**成功衡量标准：**
152+ 
153+**多仓库镜像部署：**
154+ 
155+- 在线安装场景下，CAPI 等组件镜像可从 `registry.k8s.io` 拉取，openFuyao 组件从 `cr.openfuyao.cn` 拉取，三方镜像从各自上游或 `hub.oepkgs.net` 拉取（P0）。
156+- 自定义单 repo 场景：传入统一 `repo` 参数后，核心组件 Pod 镜像前缀正确渲染（P0）。
157+- 离线安装场景：引导集群 k3s mirror、业务集群 containerd `certs.d` 重定向生效（P0）。
158+ 
159+**K8s v1.28.8 离线安装：**
160+ 
161+- 离线包指定 `v1.28.8` 后，kube-apiserver/controller-manager/scheduler、etcd、kube-proxy 等以 1.28.8 版本镜像拉起且 Pod Running（P0）。
162+- containerd v2.1.1 + 1.28.8 控制面组合通过 SIG 回归（P0）。
163+ 
164+### 用户故事与用例视图
165+ 
166+#### 故事 1：社区多来源镜像在线安装
167+ 
168+作为社区流水线维护者，我希望集群安装时自编译镜像、oepkg 三方镜像及不可再分发镜像各从其规范仓库拉取，而非全部指向 `cr.openfuyao.cn`。
169+ 
170+#### 故事 2：伙伴单仓自定义镜像安装
171+ 
172+作为政企运维人员，我将所有安装镜像导入内部 Harbor 同一项目下，希望通过配置 `imageRepo` 或统一 `repo` 参数完成集群安装，无需逐个改 YAML。
173+ 
174+#### 故事 3：K8s 1.28.8 离线部署
175+ 
176+作为离线环境客户，我希望在制备离线包时指定 Kubernetes v1.28.8，引导节点与业务集群均使用该版本控制面组件完成离线安装。
177+ 
178+**用例图：**
179+ 
180+```mermaid
181+flowchart LR
182+ Ops((运维/流水线))
183+ 
184+ subgraph multi["多仓库镜像部署"]
185+ UC1["配置 imageRepo / repo"]
186+ UC2["registry 重定向或模板渲染"]
187+ UC3["集群 Pod 多源拉镜像"]
188+ end
189+ 
190+ subgraph k128["K8s 1.28.8"]
191+ UC4["离线包指定版本"]
192+ UC5["版本化模板渲染"]
193+ end
194+ 
195+ Ops --> UC1
196+ UC1 --> UC2
197+ UC2 --> UC3
198+ Ops --> UC4
199+ UC4 --> UC5
200+```
201+ 
202+**设计意图**：多仓与低版本 K8s 两条能力正交——前者解决镜像来源规范与自定义仓，后者解决控制面版本选型；均通过安装时配置与模板/重定向实现，不改动运行时业务逻辑。
203+ 
204+### 注释/约束/警告
205+ 
206+1. **镜像分仓规范**：自编译 → `cr.openfuyao.cn`；可再分发三方 → `hub.oepkgs.net`；不可再分发 → 各自上游。
207+2. **模板渲染限制**：统一 `repo` 参数仅支持**一个**仓库前缀，适用于「同仓同项目」自定义场景。
208+3. **k3s 重定向**：引导集群新增 mirror 项需**重启 k3s 容器**；containerd `certs.d` 新增 hosts 一般**无需重启** containerd。
209+4. **K8s 1.28.8**：仅验证离线路径；在线 OBS 版本同步暂不支持指定 1.28.8。
210+5. 扩展组件 chart 中写死的三方镜像不做统一 repo 改造。
211+ 
212+### 风险与缓解措施
213+ 
214+| 风险 | 影响 | 缓解措施 |
215+|------|------|----------|
216+| 多 mirror 配置错误 | ImagePullBackOff | 文档提供 k3s/containerd 配置样例；安装前校验脚本 |
217+| 模板 `repo` 与镜像路径不匹配 | 渲染后镜像不存在 | 默认值回退社区官方路径；安装日志打印最终 image |
218+| 1.28.8 与最新 addon 不兼容 | 扩展组件安装失败 | 明确兼容矩阵；离线包绑定 VersionConfig |
219+| 重定向 TLS 跳过验证 | 中间人风险 | 内网场景文档警示；生产建议配置 CA |
220+| chart 内镜像无法 `--set` | 部分扩展组件仍走上游 | 非目标明确；用户手册说明手动/import 策略 |
221+ 
222+## 设计细节
223+ 
224+### 架构与设计前提
225+ 
226+**多仓库拉取目标态：**
227+ 
228+```mermaid
229+sequenceDiagram
230+ participant Bootstrap as 引导节点
231+ participant Cluster as 业务/管理集群
232+ participant CR as cr.openfuyao.cn
233+ participant OEPKG as hub.oepkgs.net
234+ participant Upstream as registry.k8s.io / docker.io
235+ 
236+ Bootstrap->>Bootstrap: 编辑 BC，设置 imageRepo
237+ Bootstrap->>Cluster: 创建集群
238+ Cluster->>CR: 拉取自编译镜像
239+ Cluster->>OEPKG: 拉取可再分发三方镜像
240+ Cluster->>Upstream: 拉取不可再分发三方镜像
241+```
242+ 
243+**K8s 1.28.8 离线安装流程：**
244+ 
245+```mermaid
246+flowchart TD
247+ A[开始] --> B[安装 containerd v2.1.1]
248+ B --> C[从 cr.openfuyao.cn 安装 k8s 1.28.8 与 etcd]
249+ C --> D[安装 kube-proxy]
250+ D --> E[安装 coredns、calico]
251+ E --> F[安装 openFuyao 核心组件]
252+ F --> G[结束]
253+```
254+ 
255+**实现前提：**
256+ 
257+- 引导集群使用 k3s，mirror 配置位于 `/etc/rancher/k3s/registry.yaml`。
258+- 管理/业务集群使用 containerd，多仓库重定向位于 `/etc/containerd/certs.d/<registry>/hosts.yaml`。
259+- 核心组件 manifest/chart 支持 `repo` 占位符或 `--set`；扩展组件按应用市场独立安装。
260+- K8s 低版本通过离线制品 VersionConfig 与版本化模板选择对应 tag。
261+ 
262+### 特性描述
263+ 
264+#### 背景与目标
265+ 
266+见「动机」与「提案」。涉及仓库：`bkeadm`、`cluster-api-provider-bke`、`bke-manifests`、`openfuyao-system-controller`（核心组件安装）。
267+ 
268+#### 依赖组件
269+ 
270+| 组件 | 描述 | 可获得性 |
271+|------|------|----------|
272+| bkeadm | 引导 init、离线包构建、registry 配置 | 必选 |
273+| cluster-api-provider-bke | BKECluster 调谐、containerd 配置下发 | 必选 |
274+| bke-manifests | 安装 YAML/chart 模板与 `repo` 占位符 | 必选 |
275+| k3s | 引导集群 CRI，registry.yaml mirror | 引导集群必选 |
276+| containerd v2.1.1 | 节点 CRI，certs.d 多仓 pull | 集群节点必选 |
277+| hub.oepkgs.net / 上游 registry | 三方镜像来源 | 在线必选 |
278+ 
279+#### License
280+ 
281+Mulan PSL v2 License。
282+ 
283+### 4+1 架构视图
284+ 
285+#### 上下文与用例视图 (Context and Use Case View)
286+ 
287+```mermaid
288+flowchart TB
289+ User((运维人员))
290+ CR[cr.openfuyao.cn]
291+ OEPKG[hub.oepkgs.net]
292+ Upstream[上游 registry]
293+ Custom[自定义 Harbor]
294+ 
295+ subgraph Bootstrap[引导集群]
296+ K3s[k3s mirror]
297+ end
298+ 
299+ subgraph Cluster[管理业务集群]
300+ CD[containerd certs.d]
301+ Pods[工作负载 Pod]
302+ end
303+ 
304+ User -->|imageRepo repo| K3s
305+ User -->|离线版本 YAML| CD
306+ Pods --> CD
307+ K3s --> CR
308+ K3s --> OEPKG
309+ K3s --> Upstream
310+ K3s --> Custom
311+ CD --> CR
312+ CD --> OEPKG
313+ CD --> Upstream
314+ CD --> Custom
315+```
316+ 
317+**设计意图**：安装配置在引导节点录入，运行时由 k3s/containerd 按 mirror 或渲染后 image 从多 registry 拉取。
318+ 
319+#### 逻辑视图 (Logical View)
320+ 
321+```mermaid
322+flowchart TB
323+ subgraph install["安装控制面"]
324+ BC[BKECluster spec]
325+ Template[模板渲染 engine]
326+ MirrorK3s[k3s registry mirror]
327+ MirrorCD[containerd certs.d]
328+ end
329+ 
330+ subgraph artifacts["制品"]
331+ Manifests[bke-manifests YAML/chart]
332+ VersionCfg[VersionConfig / K8s 版本]
333+ end
334+ 
335+ BC --> Template
336+ BC --> MirrorK3s
337+ BC --> MirrorCD
338+ Manifests --> Template
339+ VersionCfg --> Template
340+ Template --> Pods[Pod spec image]
341+ MirrorK3s --> Pull[镜像拉取]
342+ MirrorCD --> Pull
343+```
344+ 
345+**设计意图**：`imageRepo`/`repo` 与版本配置驱动模板；mirror 与渲染两条路径互补，覆盖在线多仓与单仓自定义场景。
346+ 
347+#### 开发视图 (Development View)
348+ 
349+```mermaid
350+flowchart TB
351+ subgraph bkeadm_repo["bkeadm"]
352+ init_pkg["pkg/initialize · repository"]
353+ build_pkg["pkg/build · 离线包/版本配置"]
354+ end
355+ 
356+ subgraph cap_repo["cluster-api-provider-bke"]
357+ containerd_cfg["ContainerdConfig · certs.d 生成"]
358+ phase["phase 渲染 · repo 参数"]
359+ end
360+ 
361+ subgraph manifests["bke-manifests"]
362+ core_yaml["核心组件 YAML 模板"]
363+ charts["chart values.repo"]
364+ k128_tpl["K8s 1.28.8 版本模板"]
365+ end
366+```
367+ 
368+**设计意图**：模板与 mirror 配置分属 manifests 与 CAP-BKE/bkeadm；K8s 低版本模板与 VersionConfig 同仓维护。
369+ 
370+#### 运行视图 (Runtime View)
371+ 
372+```mermaid
373+sequenceDiagram
374+ actor User
375+ participant BKE as bkeadm CAP
376+ participant K3s as k3s containerd
377+ participant Reg as 多 registry
378+ 
379+ User->>BKE: 创建集群（imageRepo / repo / 版本）
380+ BKE->>BKE: 渲染 manifest / 写入 mirror 配置
381+ BKE->>K3s: 应用 Pod / 更新 registry 配置
382+ K3s->>Reg: pull 自编译镜像
383+ K3s->>Reg: pull oepkg / 上游镜像
384+ Note over K3s: 1.28.8 离线：pull v1.28.8 tag
385+```
386+ 
387+**设计意图**：安装阶段一次性写入配置与渲染结果；运行期由 CRI 按配置拉取，无额外控制面轮询。
388+ 
389+#### 部署视图 (Deployment View)
390+ 
391+```mermaid
392+flowchart TB
393+ CR[cr.openfuyao.cn]
394+ OEPKG[hub.oepkgs.net]
395+ UP[上游 registry]
396+ HARBOR[自定义 Harbor]
397+ 
398+ subgraph bootstrap[引导节点]
399+ k3s_reg[k3s registry.yaml]
400+ k3s[k3s]
401+ end
402+ 
403+ subgraph nodes[集群节点]
404+ certs[containerd certs.d]
405+ ctr[containerd]
406+ end
407+ 
408+ CR --> k3s_reg
409+ OEPKG --> k3s_reg
410+ UP --> k3s_reg
411+ HARBOR --> k3s_reg
412+ k3s_reg --> k3s
413+ CR --> certs
414+ OEPKG --> certs
415+ UP --> certs
416+ HARBOR --> certs
417+ certs --> ctr
418+```
419+ 
420+**设计意图**：引导节点与集群节点分别通过 k3s registry.yaml 与 containerd certs.d 对接多 registry。
421+ 
422+### 模块接口与配置约定
423+ 
424+#### 1. 多仓库镜像部署
425+ 
426+##### 1.1 镜像来源规划
427+ 
428+| 镜像来源 | 存储位置 |
429+|----------|----------|
430+| 自编译镜像 | `cr.openfuyao.cn` |
431+| license 允许分发的三方镜像 | `hub.oepkgs.net` |
432+| 不允许分发的三方镜像 | 各自上游仓库 |
433+ 
434+**示例 Pod 镜像分布：**
435+ 
436+```yaml
437+# CAPI
438+image: registry.k8s.io/cluster-api/cluster-api-controller:v1.4.3
439+# openFuyao
440+image: cr.openfuyao.cn/openfuyao/cluster-api-provider-bke:latest
441+# 三方
442+image: docker.io/library/openssl:latest
443+```
444+ 
445+##### 1.2 安装场景与处理方式
446+ 
447+**引导集群：**
448+ 
449+| 场景 | 处理方式 |
450+|------|----------|
451+| 在线安装 | 无须额外处理 |
452+| 离线安装 | k3s registry 重定向 |
453+| 自定义仓：同仓同项目 | 模板渲染 或 离线小包 |
454+| 自定义仓：同仓不同项目 | 手动改 YAML 或 离线小包 |
455+| 自定义仓：多仓同映射 | k3s 重定向 或 离线小包 |
456+ 
457+**管理/业务集群：**
458+ 
459+| 场景 | 处理方式 |
460+|------|----------|
461+| 在线安装 | 无须额外处理 |
462+| 离线安装 | containerd 重定向（certs.d） |
463+| 自定义仓：同仓同项目 | 模板渲染 |
464+| 自定义仓：同仓不同项目 | 手动改 K8s YAML |
465+| 自定义仓：多仓同映射 | containerd 重定向 |
466+ 
467+##### 1.3 Registry 重定向配置
468+ 
469+**引导集群 k3s**（`/etc/rancher/k3s/registry.yaml`，变更需重启 k3s）：
470+ 
471+```yaml
472+mirrors:
473+ cr.openfuyao.cn:
474+ endpoint:
475+ - "https://deploy.bocloud.k8s:443"
476+ registry.k8s.io:
477+ endpoint:
478+ - "https://deploy.bocloud.k8s:443"
479+ docker.io:
480+ endpoint:
481+ - "https://deploy.bocloud.k8s:443"
482+configs:
483+ "cr.openfuyao.cn":
484+ tls:
485+ insecure_skip_verify: true
486+```
487+ 
488+**管理/业务集群 containerd**（`/etc/containerd/certs.d/docker.io/hosts.yaml`，新增文件无需重启）：
489+ 
490+```yaml
491+server = "https://docker.io"
492+[host."https://deploy.bocloud.k8s:40443"]
493+ capabilities = ["pull", "resolve", "push"]
494+ skip_verify = true
495+```
496+ 
497+##### 1.4 模板渲染（统一 repo）
498+ 
499+BKECluster 字段：`spec.clusterConfig.cluster.imageRepo`；渲染参数：`repo`（单前缀，适用于同仓同项目）。
500+ 
501+```yaml
502+image: {{ if .repo }}{{ .repo }}{{ else }}registry.k8s.io/cluster-api/{{ end }}cluster-api-controller:v1.4.3
503+image: {{ if .repo }}{{ .repo }}{{ else }}cr.openfuyao.cn/openfuyao/{{ end }}cluster-api-provider-bke:latest
504+image: {{ if .repo }}{{ .repo }}{{ else }}docker.io/{{ end }}openssl:latest
505+```
506+ 
507+**核心组件**：openfuyao-system-controller 安装；yaml 用 `sed -i` 或 chart `--set repo=...`（prometheus、ingress、metrics-server 等）。
508+ 
509+**扩展组件**：应用市场安装；梳理 cr/oepkg/三方来源，**不要求**统一 repo；chart values 暴露的可 `--set`，写死在 yaml 的暂不处理。
510+ 
511+##### 1.5 终态交付诉求
512+ 
513+- 流水线：满足场景 1（多来源在线）与场景 2（离线 redirect）。
514+- 伙伴客户：满足场景 3.1（同仓同项目自定义在线仓）。
515+- 支持引导集群**离线小包 2**（openFuyao 前端/console 相关镜像与 chart）。
516+- openFuyao 核心组件 YAML 整改 + 统一 `repo` 模板渲染。
517+ 
518+#### 2. 兼容 Kubernetes v1.28.8 离线安装
519+ 
520+##### 2.1 验证组件矩阵（初步）
521+ 
522+| 组件 | 版本 |
523+|------|------|
524+| kube-apiserver / controller-manager / scheduler / kubectl / kubelet | v1.28.8 |
525+| kube-proxy | v1.28.8 |
526+| etcd | 3.5.12-0 |
527+| calico | 3.31.3 |
528+| coredns | 1.12.2-of.1 |
529+| containerd | v2.1.1 |
530+ 
531+##### 2.2 使用方式
532+ 
533+- **离线**：用户修改离线制品版本 YAML（K8s 版本为 v1.28.8）后上传/制备；社区提供 1.28.8 镜像与二进制。
534+- **在线**：OBS 版本文件自动同步，**暂不支持**指定 1.28.8。
535+ 
536+##### 2.3 版本化模板
537+ 
538+安装 K8s 组件时根据 VersionConfig 选择对应版本模板，拉起 v1.28.8 控制面及 etcd 镜像（非当前默认 latest/of-v1.33 线路）。
539+ 
540+### 关键设计决策表
541+ 
542+| 决策点 | 选项 | 选定方案 | 理由 |
543+|--------|------|----------|------|
544+| 多来源在线拉取 | 单仓聚合 / 分仓拉取 | **分仓按社区规范** | 符合流水线制品治理 |
545+| 自定义单仓 | 仅重定向 / 仅模板 / 两者 | **重定向 + 模板渲染** | 覆盖引导/集群不同 CRI 与伙伴导入习惯 |
546+| 统一 repo 粒度 | 多 repo 参数 / 单 repo | **单 `repo` 前缀** | 匹配「同 URL 同项目」伙伴诉求，实现简单 |
547+| 扩展组件 chart | 强制改 repo / 保持原状 | **保持三方 chart 原状** | 降低维护成本，文档说明 |
548+| K8s 1.28.8 范围 | 在线+离线 / 仅离线 | **仅离线** | 在线 OBS 同步链路未扩展低版本 |
549+| 引导集群小包 | 仅全量离线包 / 分包 | **支持离线小包 2** | 与最小引导集、oFEP-0040 方向一致 |
550+| containerd 重定向 | 主配置 mirror / certs.d | **certs.d hosts.yaml（v2）** | 增删 mirror 无需重启 containerd |
551+ 
552+### DFX 质量属性设计
553+ 
554+#### 性能
555+ 
556+- 多 registry 并行 pull 不增加控制面 API 负载；节点首次 pull 延迟取决于各 registry RTT。
557+- 模板渲染为安装时一次性操作，不引入运行时开销。
558+ 
559+#### 可靠性
560+ 
561+- mirror 配置错误时 CRI 拉取失败应 fail-fast，Pod 处于 ImagePullBackOff，安装流程可重试。
562+- K8s 1.28.8 离线包与 VersionConfig 绑定，避免 tag 漂移。
563+ 
564+#### 安全
565+ 
566+- 生产环境 mirror 应配置 CA，避免长期使用 `insecure_skip_verify`。
567+ 
568+#### 兼容性
569+ 
570+- 未配置多仓/ repo 时保持现有单 `cr.openfuyao.cn` 行为（`disable-supported: true`）。
571+- K8s 1.28.8 与默认高版本安装路径并存，由离线包版本字段选择。
572+- 与 oFEP-0013 containerd 全局 mirror 配置可共存，文档说明优先级。
573+ 
574+#### 可服务性
575+ 
576+- 提供 k3s `registry.yaml` 与 containerd `certs.d` 样例及排障：`crictl pull` 验证。
577+- 明确 1.28.8 兼容矩阵与不支持在线低版本的说明。
578+ 
579+#### 可测试性
580+ 
581+- 单元测试：模板 `repo` 渲染默认值与自定义值。
582+- 集成测试：多 mirror 配置后 `crictl images` 来源正确。
583+- e2e：在线多源 pull；单 repo 渲染；1.28.8 离线全链路。
584+ 
585+#### 易用性
586+ 
587+- 伙伴场景优先文档化「同仓同项目 + 单一 repo 参数」最短路径。
588+- 扩展组件三方 chart 限制在 FAQ 中说明。
589+ 
590+### 测试计划
591+ 
592+[ ] 我/我们理解，相关组件的所有者可能会要求更新已有的测试，以便在提交实现该增强功能所需的更改之前，使代码达到足够稳固的质量标准。
593+ 
594+#### 先决条件测试更新
595+ 
596+- 补充 bke-manifests 模板渲染单测（`repo` 占位符）。
597+- 补充 containerd certs.d 生成逻辑单测。
598+ 
599+#### 单元测试
600+ 
601+| 包 | 覆盖重点 |
602+|----|----------|
603+| bke-manifests | `repo` 模板渲染、默认 registry 回退 |
604+| cluster-api-provider-bke | ContainerdConfig / certs.d 生成 |
605+| bkeadm/pkg/build | VersionConfig 1.28.8 制品解析 |
606+ 
607+#### 集成测试
608+ 
609+| 编号 | 场景 | 预期 |
610+|------|------|------|
611+| INT-MR-001 | 在线安装，多来源 YAML | Pod 分别从 cr/oepkg/上游 pull 成功 |
612+| INT-MR-002 | 单 repo 模板渲染 | 所有核心 Pod image 前缀一致 |
613+| INT-MR-003 | k3s registry.yaml 重定向 | 引导 Pod 从内部 Harbor pull |
614+| INT-MR-004 | containerd certs.d 重定向 | 节点 Pod 从内部 Harbor pull |
615+| INT-K128-001 | 离线包 v1.28.8 | 控制面 Pod 版本为 1.28.8 且 Running |
616+ 
617+#### e2e 测试
618+ 
619+| 编号 | 优先级 | 步骤 | 预期 |
620+|------|--------|------|------|
621+| MR-001-在线多仓 | P0 | 官方在线安装多组件集群 | 镜像来源符合分仓表 |
622+| MR-002-单repo自定义 | P0 | 导入 Harbor + repo 参数 | 集群安装成功 |
623+| MR-003-离线redirect | P0 | 离线包 + containerd mirror | 无公网 pull |
624+| K128-001-离线1.28.8 | P0 | 修改版本 YAML → 离线安装 | 控制面 1.28.8 Ready |
625+| K128-002-在线默认 | P1 | 在线安装不传低版本 | 仍为社区默认 K8s 版本 |
626+ 
627+### 毕业标准
628+ 
629+#### Alpha 阶段
630+ 
631+- 多仓在线 pull 与单 repo 模板渲染代码合入。
632+- K8s 1.28.8 离线制品与模板合入。
633+- P0 集成/e2e 用例通过。
634+ 
635+#### Beta 阶段
636+ 
637+- P0 + P1 用例稳定 ≥ 2 周。
638+- 至少 1 个伙伴环境完成单 repo 自定义安装验证。
639+- 1.28.8 离线安装文档与 VersionConfig 发布。
640+ 
641+#### GA 阶段
642+ 
643+- ≥ 3 次生产/准生产多仓或 1.28.8 离线部署记录。
644+- Beta 反馈问题关闭。
645+ 
646+### 升级/降级策略
647+ 
648+- **升级**：新增 mirror/模板不影响已有集群；新集群安装默认启用多仓规范。K8s 版本仅在**新装**离线包时选择，已装集群不自动降级控制面。
649+- **降级**：关闭多仓行为可回退为单 `cr.openfuyao.cn`（不传 repo、不配置额外 mirror）。
650+- 1.28.8 集群升级到高版本 K8s 不在本 oFEP 范围，遵循社区升级文档。
651+ 
652+### 版本倾斜策略
653+ 
654+- bkeadm、bke-manifests、CAP-BKE 版本需对齐，否则模板 tag 与 VersionConfig 可能不一致。
655+- K8s 1.28.8 节点与 1.33.x 引导节点可共存于不同集群，同一集群内控制面组件版本须一致。
656+- containerd v2.1.1 为 1.28.8 路径验证版本，与其他 K8s 版本组合需在矩阵中声明。
657+ 
658+## 生产可用性审查
659+ 
660+### 功能启用和回滚
661+ 
662+- **启用**：安装时配置 `imageRepo`/`repo`、mirror 文件或离线包 K8s 版本即可；无全局 Feature Gate 强制开启。
663+- **回滚**：移除额外 mirror 配置并重启 k3s/containerd（如适用）；或使用默认在线/离线包不带低版本字段。
664+- **disable-supported**：true。
665+ 
666+### 监控要求
667+ 
668+- 安装失败可通过 Pod ImagePullBackOff 事件与 `crictl pull` 诊断。
669+- 暂无新增 Prometheus 指标；后续可考虑记录 pull 失败 registry 维度。
670+ 
671+### 依赖项
672+ 
673+- 各镜像 registry 可用性直接影响安装；hub.oepkgs.net 与上游 registry 网络策略需提前放通。
674+- K8s 1.28.8 依赖社区制品库发布对应 tag 镜像。
675+ 
676+### 故障排除
677+ 
678+| 故障模式 | 检测 | 缓解 |
679+|----------|------|------|
680+| mirror 配置错误 | ImagePullBackOff | 核对 registry.yaml / hosts.yaml |
681+| repo 渲染错误 | Pod image 路径异常 | 检查 BC 与模板默认值 |
682+| 1.28.8 镜像缺失 | pull 404 | 确认离线包 VersionConfig 与制品同步 |
683+ 
684+## 实施历史
685+ 
686+| 日期 | 里程碑 |
687+|------------|--------|
688+| 2026-01-29 | oFEP-0035 草案创建 |
689+| 2026-02-01 | 按 oFEP-0040 格式优化：补全摘要/目标/4+1 视图/Mermaid/DFX/测试计划 |
690+ 
691+## 缺点
692+ 
693+1. 单 `repo` 参数无法覆盖「同仓不同项目」场景，仍需手动改 YAML。
694+2. 三方 chart 镜像无法统一改造，扩展组件体验不一致。
695+3. k3s mirror 变更需重启，引导集群有短暂影响。
696+4. K8s 1.28.8 仅离线支持，在线客户无法选用该版本。
697+5. 多 mirror + TLS skip 配置增加安全审计成本。
698+ 
699+## 替代方案
700+ 
701+| 方案 | 描述 | 未采纳原因 |
702+|------|------|------------|
703+| 全部镜像预聚合到单仓 | 安装前脚本 sync 所有镜像到 Harbor | 违背社区分仓规范；包体与同步成本高 |
704+| 仅手动改 YAML | 不提供模板与 mirror | 维护成本极高，易漏改 |
705+| 仅重定向不模板 | 所有场景用 mirror | 同仓同项目伙伴场景配置复杂 |
706+| 在线支持 1.28.8 | OBS 同步多版本 | 实现与测试范围大，首期仅离线 |
707+ 
708+## 所需基础设施
709+ 
710+- 社区制品流水线按 cr / oepkg / 上游分仓构建与校验。
711+- 发布 K8s v1.28.8 离线镜像与二进制制品及 VersionConfig。
712+- bke-manifests 仓库核心 YAML/chart 整改 PR 与评审流程。
713+- CI：多仓 pull 与 1.28.8 离线安装冒烟用例。