docs: add runtime contract preflight guide (3-layer chart-vs-runtime drift)#72
docs: add runtime contract preflight guide (3-layer chart-vs-runtime drift)#72
Conversation
…ion tree Add addon-runtime-contract-preflight-guide.md (652 lines) covering chart spec vs runtime contract drift across 3 layers: - Layer 1: chart spec field rejected by KB CRD schema (install-time fail) - Layer 2: vcluster substrate bootstrap precondition (CoreDNS image) - Layer 5: runtime env contract drift (ActionSet spec.env declare gap) Layer 0 / 3 / 4 reserved for future sediment. Non-contiguous numbering explained at section 3 opening. Layer 5 main 6-section authored by Oracle line addon owner (W7 ActionSet env audit, ORA-12154 grounded, idc4 19c standalone evidence with double verification). Polished and folded by SQL Server line. Layer 2 main 6-section authored by Oracle line addon owner (CoreDNS ImagePullBackOff grounded, registry.aliyuncs.com fix verified). idc bastion view inline placeholder for MariaDB line co-author (mirror family classification, sideload vs image swap tradeoff, blacklist wisdom, vcluster substrate bootstrap timing pitfalls). Layer 1 main 6-section drafted with placeholder for SQL Server line PoC evidence (KB 1.0.2 isExclusive field-not-declared-in-schema), to be filled after T08 reproduction completes. Decision tree (mermaid) at section 8 separates Layer 1 / 2 / 5 by 3 evidence questions: install-time fail / smoke-PASS-but-cross-pod-fail / ActionSet env declare diff. Same-surface-error different-root-cause covered as twin-fault scenario in Layer 2 + Layer 5 stack. Cross-doc family map at section 9 places this doc as the runtime contract dimension within the preflight family (5 docs, scope strictly non-overlapping). Cross-refs to chart-vs-kb-schema-skew-diagnosis, soak-test-result-classification, test-acceptance-and-first-blocker, probe-classification, and bounded-eventual-convergence guides. Case appendix A-D covers Oracle W7 grounded, idc4 CoreDNS fix grounded, SQL Server isExclusive (pending PoC fold-in), MariaDB line mirror family cross-line evidence (PR #54 reference).
Add SKILL-INDEX.md entry for addon-runtime-contract-preflight-guide.md in section 3 "环境 ready 前 / 环境层撞坑", documenting the 3-layer chart-vs-runtime contract drift methodology and its position within the preflight family (5 docs, scope strictly non-overlapping). Entry references the Oracle line W7 grounded evidence (idc4 19c + 12c double minor-version confirm) and MariaDB line idc bastion view co-authored content (PR #54 mirror family + 11:16-12:55 syncer deployment experience).
…onfirm + Step 3.5 audit Apply 4 fold-ins from Oracle line W8 deliverable + 12c second-engine confirm into runtime-contract-preflight-guide v1: 1. Section 4 Step 3.5 — ActionSet env reference systemAccount CMPD declare audit, with cross-variant `cmpd*.yaml` diff audit script covering systemAccounts names + vars credentialVarRef.name set + lifecycleActions keys (closes the silent W8-style runtime gap) 2. Section 6.2 Source datapoint — N=2 minor-version reproducibility confirm: 12c standalone (cluster o12-t8-21609) RMAN 628MB 1m58s + expdp 220KB 2m56s + 19c standalone (cluster o19-i4-8854) RMAN 553MB 2m32s, identical kubectl patch actionset spec.env recipe 3. Section 6.2 Inter-minor-version chart drift sub-bullet (Layer 5 grounded form orthogonal to KB cross-version drift): symptom + audit signal + fix shape, anchored on Oracle line W8 commit 1cb93055 cmpd-19c misalignment evidence 4. Section 6.3 MongoDB wording footnote — no current MongoDB line owner, K8s evidence pack inferred wording, pending future line owner grounded confirm
Curator structural pass v1 —
|
…load trap + mirror blacklist + bootstrap timing
Refine the four idc-bastion-view sub-blocks Tom drafted as starter content in §6.3 with grounded detail from the 2026-05-05 patched syncer cross-compile + sideload cycle:
- Sideload 现场踩坑: clarify that imagePullPolicy 'Never' is fresh-deploy invariant only; existing CmpD upgrade must keep 'IfNotPresent' (which honors local cache identically). Add per-node 'ctr images ls' as the evidence gate for declaring sideload complete (sideload to N-1 of N nodes is a silent partial-success). Add cross-compile workaround pattern: when host docker buildx cannot pull a base image, GOOS=linux GOARCH=amd64 go build + minimal Dockerfile graft binary onto a substrate-pullable base image. Add the 'verify before propagate' trap: cross-host / cross-stash builds may miss module registration code that lives in collaborator's local stash; handoff 'image ready' must include a verify gate.
- Mirror 黑名单 wisdom: correct three entries to match real failure modes —
- alpine/distroless toolchain image (e.g. kubeblocks-tools:1.0.2) lacks /bin/bash, bash-dependent runner scripts cannot start (not 'exec format error'). Pin to debian-flavored tag or split into init+main containers.
- Third-party Aliyun-hosted Go base image (xuriwuyun/golang) reliably times out from offshore Mac docker buildx. Workaround is to bypass buildx entirely via cross-compile, not to fix the mirror.
- ghcr.io references in chart main body are a hard blocker, not a fallback. Sideload救场 is short-term; the long-term fix is upstream chart replaces ghcr.io with mirror-friendly registry.
- Vcluster substrate bootstrap 时序常见踩点: split the Secret kubeconfig timing pitfall into two distinct cases (vcluster-syncer's own Secret vs test-runner Job's Secret) since they fail at different layers and have different mitigations. Add the probe Job pattern as substrate-readiness gate, with cross-link to addon-host-runner-job-pattern-guide.md §基础资源. Add the rule that DNS readiness must be probed from inside the workload's namespace, not from the bastion host.
- Cross-engine impact MariaDB row: replace the cross-line guess wording with substrate-based wording (Could not resolve host name / getaddrinfo / Galera gcomm channel open). Mark wording status as ⚠ pending grounded sample, not ✅, since the MariaDB cycle 2026-05-05 ran with vcluster API via NodePort and idc-k8s CoreDNS healthy — Layer 2 DNS failure path was not triggered, no real error trace captured.
- Source datapoint MariaDB cross-line evidence: add concrete anchors from the 2026-05-05 11:16-12:55 patched syncer deploy (idc-k8s 3-node mariadb-runner namespace, kubectl cp tar + ctr import to all 3 nodes, CmpD imagePullPolicy: IfNotPresent honored cache, alpha.16 fresh-matrix 8/8 PASS validating the patch).
Evidence anchors:
- addons/mariadb/templates/cmpd-{replication,semisync,galera}.yaml — chart main-body image route via DockerHub family
- addon-idc-image-registry-mirror-guide.md PR #54 §1 mirror family + §5 MariaDB row — chart audit + ACR-direct runner toolchain pair
- addon-host-runner-job-pattern-guide.md §基础资源 + §常见坑表 — initContainer toolchain split + alpine vs glibc + image cache warm-up
- addon-evidence-discipline-guide.md anti-pattern library — the 'verify before propagate' trap is a documented anti-pattern instance
|
Cross-line grounded confirm for the Redis/Valkey row in §6.2 / §6.3: The current wording 1. The "Redis" prefix is preserved in 2. The error is a family with 4 suffixes, each indicating a different failure layer. The single-suffix listing in §6.2 / §6.3 makes anti-pattern matchability narrower than necessary:
A reader-side anti-pattern check should match the prefix ( Grounded source: chaos-test artifact from the Valkey IDC full-cycle 2026-05-05, archive SHA-256 |
…ection Allen curator pass 4 mandatory fixes (PR #72 c472d1e2): - Status: stable -> draft (v1) (5-field intro) - SKILL-INDEX 文档全列表 entry added (paste-ready wording) - Line 552/577 addon-smoke-test-pre-flight-checklist-guide.md marked (planned, PR #71) for forward-decl - Lines 574/576/702 addon-idc-image-registry-mirror-guide.md backtick -> clickable markdown (landed doc on main) - Line 576 addon-host-runner-job-pattern-guide.md also linkified (landed doc on main) James jsonpath correction (PR #72 1c15cbb5): Step 3.5 audit shape was wrong. DP_DB_USER / DP_DB_PASSWORD are NOT declared in ActionSet spec.env at all -- KB dataprotection Job runner auto-injects them based on BackupPolicy.spec.backupMethods[] .target.account (which references systemAccount name). The W8 contract boundary lives at BackupPolicy layer, not ActionSet layer. Corrected audit: 1. cluster-side: kubectl get backuppolicy ... .spec.backupMethods[]. target.account vs kubectl get cmpd ... .spec.systemAccounts[].name diff 2. chart-side: yq diff cmpd-19c.yaml systemAccounts vs backuppolicytemplate.yaml backupMethods[].target.account 3. Added "Audit shape 关键澄清" paragraph documenting that systemAccount -> DP_DB_* contract is at BackupPolicy layer W8 grounded form documented: addons/oracle/templates/ backuppolicytemplate.yaml line 33 references account: kbdataprotection but cmpd-19c.yaml does not declare it -> KB never generates secret -> CreateContainerConfigError on 19c. Doctrine B 5-pattern grep on this commit: clean.
1 participant
Summary
Add
addon-runtime-contract-preflight-guide.md(652 lines) — a methodology doc covering the 3 alignment surfaces between chart spec and actual runtime contract that, when drifted, produce smoke-passing-but-runtime-cryptic failures.Why
addon-kb-schema-version-preflight-guide.mdcovers the schema dimension (image / chart / CRD three-layer artifact version alignment). But schema validation alone doesn't catch a class of failures that pass install + smoke but fail at dataprotection / cross-pod runtime: chart spec doesn't declare a runtime requirement (env, substrate bootstrap, etc.), and runtime hits silent-empty + cryptic surface error likeORA-12154 TNS:could not resolve(which is misleadingly DNS-shaped but actually rooted in chart-vs-runtime contract drift).This guide formalizes the runtime contract preflight as a sibling doc within the preflight family (5 docs, scope strictly non-overlapping):
addon-test-script-preflight-guide.md— shared client state dimensionaddon-kb-schema-version-preflight-guide.md— schema dimensionaddon-vcluster-kb-install-preflight-guide.md— bootstrap harness dimensionaddon-multi-ns-registry-scan-preflight-guide.md— test scope dimensionWhat's added
registry.aliyuncs.com/google_containers/coredns:1.10.1mirror swap fix; MariaDB line idc bastion view inline placeholder for 4 fold-in topics — mirror family classification, sideload vs deployment image swap tradeoff, mirror blacklist wisdom, vcluster substrate bootstrap timing pitfalls)Co-author plan
3-line co-author work split (per Allen msg=4284b1d7 placement decision: split from extension to standalone doc):
345bfef9onoracle/release-1.0-merge-auditfor Half A+B fix; commit1cb93055for W8 cmpd-19c misalignment evidence (will land via W-chain consolidation PR)Cross-engine validation
o19-i4-8854) — W7 fix verified, Backupo19-i4-8854-rman19c-w7verify2Completed 553MB 2m32so12-t8-21609) — second-engine confirm:o12-rman-w7verifyCompleted 628MB 1m58s +o12-expdp-w7verifyCompleted 220KB 2m56skubectl patch actionset --type=json -p='/spec/env'recipe lands on both 12c and 19c after addon Helm upgradeTest plan
git fetch origin tom/runtime-contract-preflight-v1 && git checkout -b ... && commit && push)addon-kb-schema-version-preflight-guide.md(PR docs(kb-schema-preflight): three-layer KB version preflight guide v1 #70) — bidirectional after both PR landaddon-smoke-test-pre-flight-checklist-guide.md(PR docs(smoke-test-preflight): smoke test pre-flight checklist guide v1 (with §7 CoreDNS) #71) §7 CoreDNS doctrineSubmission hygiene
Commit body and PR text were scrubbed for generated-content attribution markers before curator review.