diff --git a/docs/addon-reconfigure-version-skew-guide.md b/docs/addon-reconfigure-version-skew-guide.md index 7736cbb..4883e8d 100644 --- a/docs/addon-reconfigure-version-skew-guide.md +++ b/docs/addon-reconfigure-version-skew-guide.md @@ -37,7 +37,7 @@ addon 同一份 chart 部署在不同 KB 版本上,行为分歧需要 addon - **legacy reload 路径**:`paramsdef.yaml` / `ParametersDefinition` 里的 `reloadAction.shellTrigger`;KB 1.0.x / 1.1.x 的主推路径,1.2 main 进入 deprecated / 移除窗口 - **CMPD reconfigure 路径**:`ComponentDefinition.spec.configs[].reconfigure.exec`;KB 1.2 main 的主推路径,对 1.0.x / 1.1.x 控制器在多数情况下被忽略 -- **silent regression**:reconfigure OpsRequest 报 `Succeed`、controller hash 收口、但 valkey/redis runtime 的 `CONFIG GET` 仍返回旧值;跨版本演化里最常见的 trap 形态 +- **silent regression**:reconfigure OpsRequest 报 `Succeed`、controller hash 收口、但**引擎 runtime 实际值仍是旧值**(valkey/redis 用 `CONFIG GET` 读,Oracle 用 `v$parameter`,MariaDB 用 `SHOW VARIABLES`,等等 — 见 chapter 5 cross-engine readback 表);跨版本演化里最常见的 trap 形态 - **fan-out 语义**:reconfigure 是只在 primary 上执行(KB 默认)还是分发到所有 pod(addon 显式 `targetPodSelector: All`) - **version band**:指 KB 的 release tag 区间,例如 1.0.x / 1.1.x / 1.2.x(含 main);不同 version band 的接口契约可能不一致 @@ -82,7 +82,7 @@ addon 同一份 chart 部署在不同 KB 版本上,行为分歧需要 addon **最强的 ground truth**:**直接 deploy 到目标 KB 版本上发起一次 minimum reconfigure OpsRequest**,观察: - controller phase(Succeed / Failed) - live `ParametersDefinition` / `ComponentParameter` / `OpsRequest` 状态 -- runtime `CONFIG GET` 实际值(**这条最关键**,下面 chapter 5 详述) +- runtime engine readback 实际值(**这条最关键**,下面 chapter 5 详述;具体命令按引擎选 — Redis/Valkey `CONFIG GET` / Oracle `v$parameter` / MariaDB `SHOW VARIABLES` / SQL Server `sys.configurations` / OceanBase `__all_sys_parameter`) ## chapter 3:目标 KB 版本会走哪条路径 — controller 角度的判定 @@ -139,7 +139,22 @@ target KB version? |---|---|---| | controller | `OpsRequest=Succeed`、`ComponentParameter=Succeed`、live config-hash 收口 | — | | addon action | `reload-parameter.sh` exit 0、reload action log 无 error | — | -| runtime(**唯一可信**) | — | 在每个数据 pod 上 `redis-cli CONFIG GET ` 直接读 runtime 值,对照 desired | +| runtime(**唯一可信**) | — | 在每个数据 pod 上做 **engine-specific runtime readback** 直接读 runtime 值,对照 desired | + +### Engine-specific runtime readback 命令对照(cross-engine reference) + +verification 应用层必须用每个引擎自己的 runtime 读取通道;以下是常用引擎的 readback 入口(Per James msg=54af835d cross-engine generalization input): + +| Engine | Runtime readback command / source | Notes | +|---|---|---| +| Valkey / Redis | `valkey-cli CONFIG GET ` / `redis-cli CONFIG GET ` | 注意 `CONFIG SET` 静默 +OK 失败语义(见 trap T4) | +| MariaDB / MySQL | `SHOW VARIABLES LIKE ''` 或 `SELECT @@` | 区分 GLOBAL vs SESSION scope | +| PostgreSQL | `SHOW ` 或 `SELECT current_setting('')` | 部分参数 reload 后 `pg_reload_conf()` 才生效 | +| Oracle | `SHOW PARAMETER ` (sqlplus) 或 `SELECT value FROM v$parameter WHERE name=''` | 区分 spfile vs runtime;部分参数 require restart(不属于 dynamic 参数) | +| SQL Server | `SELECT * FROM sys.configurations WHERE name=''` 或 `EXEC sp_configure ''` | `RECONFIGURE` 后 `value_in_use` 才反映 runtime | +| OceanBase | `SELECT * FROM oceanbase.__all_sys_parameter WHERE name=''` 或 `SHOW PARAMETERS LIKE ''` | 区分 cluster-level / tenant-level scope | + +**通用原则**:runtime ground truth 必须从 engine **本身**读,不能只看 controller phase / addon action exit code / config-hash 收口。本 guide 后续 chapter 用 `CONFIG GET` 当 example, 实际跑 verify 时按上表换成对应引擎的 readback。 **typical silent regression 现场**: - chart 是 1.0/1.1 风格(仅 paramsdef.reloadAction),部署到 1.2 main controller @@ -153,7 +168,7 @@ target KB version? - cmpd reconfigure 被忽略 ok - 但如果 reload-parameter.sh 在两条路径下行为不一致(参数名转换、authentication、retry 逻辑),会有微妙 drift -**actionable**:跨版本部署时 reconfigure 验证至少要 **bring-down 到 runtime CONFIG GET 一次**,不能只看 controller phase。 +**actionable**:跨版本部署时 reconfigure 验证至少要 **bring-down 到 runtime engine readback 一次**(per chapter 5 上方表格选对应引擎命令;Redis/Valkey 用 `CONFIG GET`,Oracle 用 `SHOW PARAMETER` / `v$parameter`,等等),不能只看 controller phase。 ## chapter 6:portability 套路 — 双写 / 单写 / template variant