Skip to content

docs: add runner in-cluster vcluster access pattern guide#124

Closed
weicao wants to merge 1 commit into
mainfrom
feature/addon-runner-incluster-vcluster-access
Closed

docs: add runner in-cluster vcluster access pattern guide#124
weicao wants to merge 1 commit into
mainfrom
feature/addon-runner-incluster-vcluster-access

Conversation

@weicao
Copy link
Copy Markdown
Contributor

@weicao weicao commented May 13, 2026

Summary

New methodology doc addon-runner-incluster-vcluster-access-pattern-guide.md covering when addon tests on a remote IDC vcluster, the runner pod should sit inside the host k8s cluster and reach the vcluster API via in-cluster service DNS, taking the workstation network out of the test critical path.

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

  • §1: 3 vcluster API access topologies — workstation+port-forward / workstation+NodePort / runner-pod+in-cluster-DNS — with their respective failure classes
  • §2: 5 hard rules — kubeconfig server field = in-cluster service DNS; long-running pod (sleep infinity); nohup ... & so kubectl exec returns immediately; evidence retrieval via kubectl exec -- tar c piped to tar x (avoids kubectl cp etcd timeout); closeout treats host-API impact as independent from runner result
  • §3: 5-point PR / design review checklist
  • §4: 2 anti-pattern vs correct-pattern pairs
  • §5: relation to addon-host-runner-job-pattern-guide.md, addon-test-runner-cadence-discipline-guide.md, addon-test-acceptance-and-first-blocker-guide.md, addon-evidence-discipline-guide.md

Appendix A is OceanBase enterprise addon migration from workstation + kubectl port-forward to idc4 host-runner + in-cluster service DNS, plus reverse example showing the prior path's pf-staleness T1_vcluster_api_unreachable_via_macD_portforward_mid_run blocker. Explicit boundary: 3-sample observation supports only "no workstation-network impact on in-pod test execution in those samples"; NOT extrapolated to 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

Methodology body covers:
- 3 vcluster API access topologies: (1) workstation + port-forward, (2)
  workstation + NodePort, (3) runner pod in host k8s + in-cluster service DNS
- Why (3) eliminates workstation-network-as-critical-path failure class
- 5 hard rules: kubeconfig server = in-cluster DNS; long-running pod with
  sleep infinity; nohup ... & on launch so kubectl exec returns immediately;
  evidence via kubectl exec -- tar c piped to tar x instead of kubectl cp;
  closeout treats host-API impact as independent from runner result
- 5-point PR / design review checklist
- 2 anti-pattern vs correct-pattern pairs

Appendix A is OceanBase enterprise addon migration from
workstation+port-forward to idc4 host-runner+in-cluster DNS case, explicitly
bounded as 3-sample observation, not extrapolated to permanent immunity.
@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. The appendix references addon-runner-portforward-staleness-keepalive-guide.md as a sibling that is only in PR docs: add runner port-forward staleness keepalive (stop-gap) guide #126, not on main. Either remove/defer that reference, or merge/rebase in dependency order after the target exists.

The structural recommendation itself looks good: host-runner + in-cluster DNS removes workstation network from the test critical path.

@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