Skip to content

docs(addon): k3d host precheck guide#31

Merged
weicao merged 1 commit intomainfrom
feat/k3d-host-precheck-guide
May 2, 2026
Merged

docs(addon): k3d host precheck guide#31
weicao merged 1 commit intomainfrom
feat/k3d-host-precheck-guide

Conversation

@weicao
Copy link
Copy Markdown
Contributor

@weicao weicao commented May 2, 2026

Summary

新增 docs/addon-k3d-host-precheck-guide.md,配合已在 kubeblocks-tests 仓落地的 scripts/k3d-precheck.sh(commit ca0d17a),把"跑 smoke / chaos 之前先做 host-level k3d snapshot"沉淀为通用方法论:

  • 何时跑 / 适用场景 —— smoke / chaos / regression 之前;主机或 Docker Desktop 重启后;多 k3d 集群同主机共存;runner 在 T1 / 创建集群 / kubectl get ns 阶段就 timeout / EOF。
  • 工具三档输出 —— 表格 / --json / --quiet;退出码 0 / 1 / 2 语义化。
  • 3 个 tooling 通用坑(cross-ref 已有 guide) ——
    1. k3d kubeconfig get 输出 https://0.0.0.0:<port> → TLS EOF(macOS 修法:sed 替换 127.0.0.1
    2. k3d v5 label key 由 k3d-clusterk3d.cluster(不带点 → docker stats filter 全归零)
    3. macOS bash 3.2 缺 mapfile / declare -A → 用 zsh + 临时文件
  • Runner 集成 pattern —— pre-hook 直接挡 + JSON snapshot 落 evidence/ 便于事后归因。
  • 跨主机 ops profile —— 三台测试机 baseline(MacBook-Pro-7 / caoweis-MacBook-Air / weideMacBook-Air),各自 Docker socket、内存约束、典型水位、precheck 输出示例;含 Symlink trap 和"独立 Docker daemon"提醒。
  • 7 条硬规则 + 反模式表 —— precheck 必须前置不能后置、失败必须先停 runner、只读不准 destructive、JSON 字段必须 stable,等等。
  • 同步在 docs/SKILL-INDEX.md 添加索引项(紧接 addon-probe-script-fork-and-zombie-guide 之后)。

Test plan

  • 工具脚本 kubeblocks-tests/scripts/k3d-precheck.sh 已在三台测试机分别跑通三档输出(表格 / --json / --quiet
  • guide 内的 cross-ref 链接(addon-k3d-kubeconfig-loopback-fix-guide / addon-test-runner-portability-guide / addon-test-environment-gate-hygiene-guide)均存在
  • docs/SKILL-INDEX.md 索引项位置正确,描述与 guide 内容一致
  • 其他 addon 团队按 guide 在自己机器上加 runner pre-hook 后再 review baseline

addon-k3d-host-precheck-guide.md — 三档输出 host precheck 工具配套方法论:
何时跑、退出码语义、3 个 tooling 通用坑(k3d kubeconfig 0.0.0.0 → 127.0.0.1
sed 修法 / k3d v5 label key 由 k3d-cluster 变 k3d.cluster / macOS bash 3.2
缺 mapfile 与 declare -A 的应对)、runner pre-hook 集成、三台测试机
(MacBook-Pro-7 / caoweis-MacBook-Air / weideMacBook-Air)跨主机 ops
profile baseline、7 条硬规则与反模式表。

工具脚本 kubeblocks-tests/scripts/k3d-precheck.sh 已先在 kubeblocks-tests
仓 commit ca0d17a 落地(zsh + 临时文件方案,三档输出:表格 / JSON /
quiet exit code)。本 guide 与该脚本配套使用。

SKILL-INDEX.md — 在 addon-probe-script-fork-and-zombie-guide 之后追加索引项。
@weicao weicao merged commit 57f4b21 into main May 2, 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