From 3781da0a98f1e11c4d93437b9d0dcd281f76ad11 Mon Sep 17 00:00:00 2001 From: Wei Cao Date: Mon, 4 May 2026 04:08:14 +0800 Subject: [PATCH] [style-harmonize] retrofit 5-field intro block on 10 legacy guides Closes the format conformance gap on the last 10 guides without standardized intro block. Brings total coverage from 21/31 to 31/31 (100% format conformance for methodology guides). Files (10): - addon-bootstrap-role-publish-guide.md - addon-componentdefinition-upgrade-guide.md - addon-control-plane-election-guide.md - addon-ops-restart-troubleshooting-guide.md - addon-probe-script-fork-and-zombie-guide.md - addon-reconfigure-guide.md - addon-switchover-guide.md - addon-test-environment-gate-hygiene-guide.md - addon-test-host-stress-and-pollution-accumulation-guide.md (added missing KB version + Affected-by-skew, kept original 3 fields) - addon-tls-guide.md Pure structural addition: 5 lines per file (4 new fields + blank separator); host-stress added 2 fields. Methodology body unchanged. KB version field per file content: - Methodology / design-principle docs (control-plane-election, switchover, bootstrap-role-publish): KB version = any - Test methodology (env-gate-hygiene, host-stress-pollution): any - KB API surface docs (componentdefinition-upgrade, ops-restart-troubleshooting): 1.0.x / 1.1.x / main - Reconfigure: 1.0.x / 1.1.x with cross-ref to version-skew (PR #13) - Probe-fork-zombie: any (PID 1 reap is K8s contract) - TLS: any (cert-manager / Secret are K8s contracts) Same retrofit pattern as PR #29 (case files batch) and PR #35 (4 guides batch 2). --- docs/addon-bootstrap-role-publish-guide.md | 6 ++++++ docs/addon-componentdefinition-upgrade-guide.md | 6 ++++++ docs/addon-control-plane-election-guide.md | 6 ++++++ docs/addon-ops-restart-troubleshooting-guide.md | 8 +++++++- docs/addon-probe-script-fork-and-zombie-guide.md | 6 ++++++ docs/addon-reconfigure-guide.md | 6 ++++++ docs/addon-switchover-guide.md | 6 ++++++ docs/addon-test-environment-gate-hygiene-guide.md | 6 ++++++ ...n-test-host-stress-and-pollution-accumulation-guide.md | 2 ++ docs/addon-tls-guide.md | 6 ++++++ 10 files changed, 57 insertions(+), 1 deletion(-) diff --git a/docs/addon-bootstrap-role-publish-guide.md b/docs/addon-bootstrap-role-publish-guide.md index 38f9701..892249b 100644 --- a/docs/addon-bootstrap-role-publish-guide.md +++ b/docs/addon-bootstrap-role-publish-guide.md @@ -1,5 +1,11 @@ # Addon Bootstrap Role Publish 指南 +> **Audience**: addon dev / test 工程师，需要排查 primary 角色 / endpoint / VIP 误判时 +> **Status**: stable +> **Applies to**: 任何 KB addon（HA topology 含 primary/secondary 角色概念的引擎） +> **Applies to KB version**: any（role truth vs publish chain 是 K8s addon 通用问题，跨 KB 版本一致） +> **Affected by version skew**: 不受 KB 版本影响 — bootstrap 初期 role truth 发布与 KB controller / endpoint controller 的相对 ordering 是 K8s 通用契约 + 本文面向 Addon 开发与测试工程师，聚焦一个经常被混读的问题：当 primary service、pod role label、EndpointSlice 或 VIP reachability 表现异常时，问题不一定先出在 service 或 controller publish 链路，也可能更早出在 bootstrap 初期的 role truth 发布。 正文只写通用方法论，不绑定某一个引擎。 diff --git a/docs/addon-componentdefinition-upgrade-guide.md b/docs/addon-componentdefinition-upgrade-guide.md index 7407dcb..36d8a13 100644 --- a/docs/addon-componentdefinition-upgrade-guide.md +++ b/docs/addon-componentdefinition-upgrade-guide.md @@ -1,5 +1,11 @@ # Addon ComponentDefinition 升级与 Immutable Spec 指南 +> **Audience**: addon dev / test 工程师，遇到 cluster 卡 Creating / component Unavailable / 升级 OpsRequest 卡住时 +> **Status**: stable +> **Applies to**: 任何 KB addon（ComponentDefinition immutable spec 是 KB API 通用契约） +> **Applies to KB version**: KB 1.0.x / 1.1.x / main（CmpD 不可变字段在 1.x 演进中保持，跨版本契约稳定） +> **Affected by version skew**: KB 升级时 CmpD spec 字段集会随版本扩展（见 [`addon-chart-vs-kb-schema-skew-diagnosis-guide.md`](addon-chart-vs-kb-schema-skew-diagnosis-guide.md)），但"已 immutable 的字段不能改"这条原则跨版本不变 + 本文面向 Addon 开发与测试工程师，聚焦一个很容易被误判的问题：Addon 升级失败时，表面看起来像 cluster 卡在 `Creating`、component 不可用，甚至像 runtime 没起来，但 first blocker 其实可能更早地卡在 live `ComponentDefinition` 自身。 正文只写通用方法论，不绑定某一个引擎。 diff --git a/docs/addon-control-plane-election-guide.md b/docs/addon-control-plane-election-guide.md index 8bbab4d..47eea8e 100644 --- a/docs/addon-control-plane-election-guide.md +++ b/docs/addon-control-plane-election-guide.md @@ -1,5 +1,11 @@ # Addon 控制面选主收口指南 +> **Audience**: addon dev / test / TL，特别是设计或重构 HA 选主路径的工程师 +> **Status**: stable +> **Applies to**: 任何 KB addon（HA topology 含 primary/secondary 选主语义的引擎） +> **Applies to KB version**: any（control-plane 收口是设计原则，与 KB 版本解耦） +> **Affected by version skew**: 不受 KB 版本影响 — role truth / publication truth / fencing truth 三类 truth 的单点收口是设计原则，跨 KB 版本一致 + 本文面向 Addon 开发与测试工程师，聚焦一个通用主题：当实例角色判断、对外发布、fencing、failover / switchover 分散在多个脚本或组件里时，如何把选主职责收口到单一 control-plane。 正文只写通用方法论，不绑定某一个引擎。具体引擎实现、命令、案例结论应放在独立案例材料中。 diff --git a/docs/addon-ops-restart-troubleshooting-guide.md b/docs/addon-ops-restart-troubleshooting-guide.md index 68db9d4..f2bdcc2 100644 --- a/docs/addon-ops-restart-troubleshooting-guide.md +++ b/docs/addon-ops-restart-troubleshooting-guide.md @@ -1,6 +1,12 @@ # Addon Ops Restart 排障分流指南 -本文面向 Addon 开发与测试工程师，聚焦一个常见但容易被混读的问题：当 restart / rolling restart / pod rolling update 看起来“卡住”时，先不要立刻进入 Pod 级进度分析，而要先判断这条 `OpsRequest` 是否已经真正进入执行体。 +> **Audience**: addon dev / test / 排障工程师，遇到 OpsRequest restart 看起来卡住时 +> **Status**: stable +> **Applies to**: 任何 KB addon（OpsRequest queue/execute 分层是 KB 通用控制流） +> **Applies to KB version**: KB 1.0.x / 1.1.x / main（OpsRequest queue 入口与执行体内部状态机契约跨 1.x 稳定） +> **Affected by version skew**: 不受 KB 版本影响 — 'queue 入口未放行' vs '执行体内部' 的两段式排障逻辑跨版本一致 + +本文面向 Addon 开发与测试工程师，聚焦一个常见但容易被混读的问题：当 restart / rolling restart / pod rolling update 看起来"卡住"时，先不要立刻进入 Pod 级进度分析，而要先判断这条 `OpsRequest` 是否已经真正进入执行体。 正文只写通用方法论，不绑定某一个引擎。引擎相关实现、现场、样本结论放在独立案例材料中。 diff --git a/docs/addon-probe-script-fork-and-zombie-guide.md b/docs/addon-probe-script-fork-and-zombie-guide.md index 821a9f4..d1ca7a2 100644 --- a/docs/addon-probe-script-fork-and-zombie-guide.md +++ b/docs/addon-probe-script-fork-and-zombie-guide.md @@ -1,5 +1,11 @@ # Addon Probe 脚本 fork 与 zombie 进程指南 +> **Audience**: addon dev 写 probe / lifecycle 脚本时；addon test 在 idle / soak 阶段做 zombie 验证时；reviewer 检查 fork pattern 时 +> **Status**: stable +> **Applies to**: 任何 KB addon（fork-from-probe / pipeline-with-timeout 模式跨引擎适用） +> **Applies to KB version**: any（PID 1 reap 行为是 K8s 容器模型 / 内核契约，与 KB 版本解耦） +> **Affected by version skew**: 不受 KB 版本影响 — kbagent SIGKILL probe 行为 + Go binary PID 1 不 reap 跨 KB 版本一致 + 本文面向 Addon 开发与测试工程师，聚焦一类会被 5290 case 测试 0 product fail 都掩盖、但放到生产长寿 pod 上几小时就把集群打挂的问题：**addon probe / lifecycle 脚本里在 kbagent 容器内产生的 orphan 子进程，会以 zombie 形式累积，最终撞 pod PID 上限**。 orphan 来源有两类： diff --git a/docs/addon-reconfigure-guide.md b/docs/addon-reconfigure-guide.md index 886502f..1d60781 100644 --- a/docs/addon-reconfigure-guide.md +++ b/docs/addon-reconfigure-guide.md @@ -1,5 +1,11 @@ # Addon Reconfigure 开发与排障指南 +> **Audience**: addon dev / TL，需要实现或排查参数 reconfigure 路径 +> **Status**: stable +> **Applies to**: 任何 KB addon 的参数变更能力（含 dynamic 与 static 参数路径） +> **Applies to KB version**: KB 1.0.x / 1.1.x（reload Action / dynamicParameters 契约稳定）；KB main / 1.2 reconfigure interface 重构跨版本演化与排障详见 `addon-reconfigure-version-skew-guide.md`（PR #13 待 land） +> **Affected by version skew**: 是 — reconfigure interface 在 KB 1.0/1.1 vs KB main/1.2 不同（PR #10100 / #10109）；本 guide 主体写 1.0/1.1 路径，跨版本演化见 reconfigure-version-skew + 本文面向 KubeBlocks Addon 开发者，例如 MariaDB、PostgreSQL、Redis、Valkey 等 Addon 的维护者。 目标是说明 Addon 在实现参数变更能力时，如何区分动态参数和静态参数，如何声明 `dynamicParameters` 与对应的 live-apply 执行路径，以及当 reconfigure 行为不符合预期时如何排查。 diff --git a/docs/addon-switchover-guide.md b/docs/addon-switchover-guide.md index deb5c4e..a1c478b 100644 --- a/docs/addon-switchover-guide.md +++ b/docs/addon-switchover-guide.md @@ -1,5 +1,11 @@ # Addon Switchover 开发与幂等性指南 +> **Audience**: addon dev / TL，需要实现 switchover / failover lifecycle action +> **Status**: stable +> **Applies to**: 任何 KB addon（HA topology 含 primary 切换语义的引擎） +> **Applies to KB version**: any（lifecycle action 幂等性契约跨 KB 版本一致） +> **Affected by version skew**: 不受 KB 版本影响 — switchover 幂等性原则、命名约定、错误处理跨 KB 版本稳定 + 本文面向 KubeBlocks Addon 开发者，重点总结 switchover / failover 生命周期动作中的设计原则、幂等性语义、常见坑。引擎相关内容只放在案例附录中。 ## 先用白话理解这篇文档 diff --git a/docs/addon-test-environment-gate-hygiene-guide.md b/docs/addon-test-environment-gate-hygiene-guide.md index e4e4224..0e2ab12 100644 --- a/docs/addon-test-environment-gate-hygiene-guide.md +++ b/docs/addon-test-environment-gate-hygiene-guide.md @@ -1,5 +1,11 @@ # Addon 测试环境 Gate 卫生指南 +> **Audience**: addon test 工程师 / TL，配置 runner / cleanup gate / pre-restart 验证流程时 +> **Status**: stable +> **Applies to**: 任何 KB addon 测试工作流（cluster-level gate 是测试 hygiene 通用要求） +> **Applies to KB version**: any（环境就绪契约与 KB 版本解耦） +> **Affected by version skew**: 不受 KB 版本影响 — environment gate hygiene 跨 KB 版本一致 + 本文面向 Addon 测试工程师与技术负责人，重点解决"机器/容器重启之后、跑测试之前，测试环境本身能不能用"的问题。它不是关于产品 / addon 的成功语义，而是关于**让 first blocker 不要落在测试环境本身**。 ## 适用场景 diff --git a/docs/addon-test-host-stress-and-pollution-accumulation-guide.md b/docs/addon-test-host-stress-and-pollution-accumulation-guide.md index 300f1f2..c27502a 100644 --- a/docs/addon-test-host-stress-and-pollution-accumulation-guide.md +++ b/docs/addon-test-host-stress-and-pollution-accumulation-guide.md @@ -3,6 +3,8 @@ > **Audience**: addon test engineer / TL、host 运维、值班工程师 > **Status**: draft（cell-4 evidence pending；chapter 7 N=2 对账 pending） > **Applies to**: 任何在共享单 host k3d 环境跑 addon 全量回归的场景；具体引擎实现细节放案例附录 +> **Applies to KB version**: any（host stress / cascade reactive overload 是 K8s 平面通用现象） +> **Affected by version skew**: 不受 KB 版本影响 — cleanup gate / cell-2 cascade / pollution accumulation 跨 KB 版本一致 ## 先用白话理解这篇文档 diff --git a/docs/addon-tls-guide.md b/docs/addon-tls-guide.md index 7a41f16..d1e4a06 100644 --- a/docs/addon-tls-guide.md +++ b/docs/addon-tls-guide.md @@ -1,5 +1,11 @@ # Addon TLS 开发与验证指南 +> **Audience**: addon dev / TL，需要实现或排查 TLS 能力（cert rotation / mTLS / cert-manager 集成） +> **Status**: stable +> **Applies to**: 任何 KB addon 的 TLS 实现（含 cert-manager 集成 / 双层 Secret 模型 / cert rotation 路径） +> **Applies to KB version**: any（TLS 设计原则与 KB 版本解耦；cert-manager / Secret API 是 K8s 通用契约） +> **Affected by version skew**: 不受 KB 版本影响 — TLS 共性问题（私钥 vs 证书 vs CA / NotAfter 验证 / inter-pod 复制流证书 cache）跨 KB 版本一致 + 本文面向 KubeBlocks Addon 开发者，聚焦 TLS 能力的设计、验证与排障。通用正文只描述 Addon TLS 的共性问题；引擎、协议、命令行工具和拓扑细节只放在案例附录中。 ## 先用白话理解这篇文档