docs(troubleshoot): cmpd/cmpv version compat declaration mismatch#239
Draft
weicao wants to merge 2 commits into
Draft
docs(troubleshoot): cmpd/cmpv version compat declaration mismatch#239weicao wants to merge 2 commits into
weicao wants to merge 2 commits into
Conversation
added 2 commits
May 19, 2026 15:08
… guide Engine-neutral troubleshooting guide for the failure mode where a chart upgrade replaces the singleton cmpv with compatibilityRules that no longer list older cmpd names retained by KubeBlocks for live clusters. Documents the symptom (Cluster stuck Creating, ITS containers with empty image:, Pod rejected by kube-apiserver), 30-second diagnosis, wrong first-reactions, runtime patch (N=1) including the Component-generation poke needed for already-rendered ITS, and the chart-side permanent fix via a previousCompDefNameSuffixes list with full name-tail semantics. Sediment from Skyworth Oracle 19c PoC incident 2026-05-19; engine-specific case appendix lives under docs/cases/oracle/.
Per Emma review on PR #239 — the engine-neutral guide body must not be bound to one specific incident. Replace the case-appendix link line's mention of Skyworth PoC, the date, and cluster ID ora19-7d549fc5bc with a generic pointer to docs/cases/<engine>/. Oracle 19c-specific case content (ITS literal, cmpv before/after, runtime patch sequence) moves entirely under the case appendix file. Engine name-shape examples like oracle-19c-1.0.7 are retained as illustrative naming examples (marked example:) because they document the chart convention, not a specific incident.
3 tasks
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
docs/troubleshoot/cmpd-cmpv-version-compat-declaration-mismatch.md, an engine-neutral troubleshooting guide for the failure mode where a charthelm upgradereplaces the singleton ComponentVersion (cmpv) but the newcompatibilityRulesblock stops listing older ComponentDefinition (cmpd) names that KubeBlocks retains for live clusters.phase=Creating, ITS containers rendered with emptyimage:strings, kube-apiserver rejects the Pod template, no Pod is ever created, Console "view logs" spins to timeout. Easy to misclassify as a Console / API server / PVC scheduling problem.previousCompDefNameSuffixeslist with full name-tail semantics (so non-emptycompDefinitionVersionSuffixand suffix-discontinuity transitions stay correct).ora19-7d549fc5bc); engine-specific case appendix planned underdocs/cases/oracle/cmpd-cmpv-19c-1.0.7-compat-gap.md.Why this matters for other addon teams
The mechanism is engine-neutral — any KubeBlocks addon chart that bumps Chart.Version while leaving live clusters at older cmpds and renders cmpv with only the current chart-version compDef will hit the same symptom. Documenting it once in
kubeblocks-addon-docssaves the next addon team a debug round.Test plan
addon-chart-vs-kb-schema-skew-diagnosis-guide.md,addon-helm-reinstall-ssa-field-manager-conflict-guide.md)previousCompDefNameSuffixes(full name tail, not bare Chart.Version) to match apecloud-addons PR #1331This PR is draft pending Emma's W1-close batch review.
🤖 Generated with Claude Code