Skip to content

docs: add runner OpenAPI schema fetch brittleness + --validate=false guide#125

Closed
weicao wants to merge 1 commit into
mainfrom
feature/addon-runner-openapi-schema-fetch-brittleness
Closed

docs: add runner OpenAPI schema fetch brittleness + --validate=false guide#125
weicao wants to merge 1 commit into
mainfrom
feature/addon-runner-openapi-schema-fetch-brittleness

Conversation

@weicao
Copy link
Copy Markdown
Contributor

@weicao weicao commented May 13, 2026

Summary

New methodology doc addon-runner-openapi-schema-fetch-brittleness-guide.md covering when test harness kubectl apply calls hit transient failed to download openapi: ... Client.Timeout / context cancellation errors against unstable remote API entry, and how to scope --validate=false defensively.

Body (generic methodology, version-agnostic, no engine binding):

  • §1: Why kubectl apply default client-side OpenAPI schema fetch is a brittle path; 3 distinguishable failure signatures
  • §2: 5 hard rules — server-side admission must NOT be relaxed; --validate=false only on identified brittle apply points (never global alias); change is runner-harness hardening (NOT product / addon / KB fix evidence); 3-class apply failure classification (server admission / RBAC / network transient); consolidate brittle apply points into helper for single grep coverage
  • §3: patch-gate 3 indicators
  • §4: 5-point PR review checklist
  • §5: 2 anti-pattern vs correct-pattern pairs
  • §6: relation to addon-runner-incluster-vcluster-access-pattern-guide.md, addon-test-acceptance-and-first-blocker-guide.md, addon-evidence-discipline-guide.md, addon-postready-bounded-timeout-failure-classification-guide.md

Appendix A is OceanBase enterprise addon T-PITR.4 OpenAPI body read cancellation case (RUN_ID pitr-runtime-postreadyfix-N2-...) + runner-side helper landing on tests/pitr.sh sha 6edf74fc...f4b3375e... + structural follow-up via addon-runner-incluster-vcluster-access-pattern-guide.md (in-cluster DNS removes the workstation hop). Explicit boundary: helper landing only proves apply succeeded in 1 subsequent sample; NOT release-ready / NOT permanent immunity.

SKILL-INDEX.md updated: added entry under ### 5. 改造 runner / 工具链.

Test plan

  • Manual: methodology body has zero OB-specific commands
  • Manual: appendix is the only OB-specific section and has explicit boundary
  • Manual: cross-doc references resolve

🤖 Generated with Claude Code

…guide

Methodology body covers:
- Why kubectl apply default client-side OpenAPI schema fetch is a brittle
  path that hangs / cancels on unstable remote API entry
- 5 hard rules: server-side admission must NOT be relaxed; --validate=false
  only on identified brittle apply points (never global alias); change is
  runner-harness hardening only (NOT product / addon / KB fix evidence);
  3-class apply failure classification (server admission / RBAC / network);
  consolidate brittle apply points into helper for single grep coverage
- patch-gate 3 indicators
- 5-point PR review checklist
- 2 anti-pattern vs correct-pattern pairs

Appendix A is OceanBase enterprise addon T-PITR.4 apply hit Client.Timeout
on OpenAPI body read case (RUN_ID pitr-runtime-postreadyfix-N2-...) +
runner-side helper landing on tests/pitr.sh sha 6edf74fc -> f4b3375e +
later structural fix via addon-runner-incluster-vcluster-access-pattern.
Explicit boundary: helper landing only proves apply succeeded in 1 sample;
NOT release-ready evidence.
@weicao
Copy link
Copy Markdown
Contributor Author

weicao commented May 13, 2026

Blocking for merge:

  1. PR body still contains 🤖 Generated with [Claude Code].... Public PR body must not include AI/tool attribution.
  2. The new guide intro has only 4 standard fields. Please add > **Affected by version skew**: ... after Applies to KB version.
  3. This PR links to docs that are not on main yet: addon-runner-incluster-vcluster-access-pattern-guide.md (docs: add runner in-cluster vcluster access pattern guide #124) and addon-postready-bounded-timeout-failure-classification-guide.md (docs: add postReady bounded timeout + failure classification guide #122). Please merge/rebase in dependency order, or remove/defer those links until targets exist.

One content note for the recheck: keep --validate=false framed as runner-harness hardening only; it must not be described as product/addon/KB stability evidence.

@weicao
Copy link
Copy Markdown
Contributor Author

weicao commented May 18, 2026

Closing per Allen's docs PR queue triage (DM 2026-05-18). Superseded by main-branch standard guide(s).

@weicao weicao closed this May 18, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant