1. 发布前那几分钟，YAML 到底在怕什么
Kubernetes 配置检查与发布安全，说白了就是回答一个问题：这份 YAML 推上去，会不会把线上搞挂。Kubernetes 的难点从来不在敲命令，而在配置文件本身——字段太多、API 版本变化快、缩进错一格就整段失效，更怕的是kubectl apply一把梭，把正在跑的 Deployment 直接替换成半成品。适合谁看？正在用 kubectl 管集群、准备把发布流程塞进 CI、又不想每次上线都靠运气的后端和运维同学。
我平时做发布前检查，会把它拆成三层：第一层是 YAML 静态校验，确认语法和 schema 没问题；第二层是kubectl dry-run和kubectl diff，让 API Server 帮你判断这份配置在集群里合不合法、和现状差在哪；第三层是 CI 里的统一鉴权通道，保证每个校验工具用的是同一套 Key、同一套 API 入口，不会出现「本地能跑、流水线报 401」的割裂感。前两层靠 kubectl 自带能力就能覆盖大半，第三层才是真正容易被忽略的地方——校验工具一多，Key 就散落在各个脚本、各个环境变量里，改一次要翻五个仓库。
这篇就按这个顺序走：先给一份可复制的config.toml和settings.json骨架，把校验工具的配置统一起来；再演示怎么用 TaoToken 的统一 Key 和 API 通道，把 kubectl 校验、YAML linter、CI 鉴权串成一条线；最后附上逐步验证动作和预期输出，以及我踩过的几个典型报错。全程命令可直接复制，配置改完就能跑。
2. 前置准备：TaoToken 统一 Key 与 API 通道
在动手配校验工具之前，先把鉴权通道理清楚。Kubernetes 发布检查里会用到好几类工具：kubectl 本身、kubeval/kube-score 这类 linter、以及 CI 里调用模型做配置审查的脚本。如果每个工具各自配一套 Key，维护成本会很高。TaoToken 的思路是提供一个统一的 API 入口，让这些工具共用同一套 Key 和同一个 base URL。
你需要先拿到一个可用的 Key。登录 TaoToken 控制台，在 API Keys 页面创建一个新 Key，复制出来备用。这个 Key 后面会同时出现在config.toml、settings.json和 CI 的环境变量里，所以建议按环境命名，比如k8s-check-dev、k8s-check-ci，方便后续轮换。
TaoToken 的 API 入口是https://taotoken.net/api，注意这个地址不带任何查询参数，直接作为 base URL 使用。控制台地址是https://taotoken.net/console，API Keys 管理页在https://taotoken.net/api-keys。如果你后面要接 Claude Code 这类编码工具做配置审查，对应的接入文档在https://taotoken.net/doc，Claude Code 的专用入口是https://taotoken.net/ClaudeCodeAnthropic。
注意：Key 只创建一次、只复制一次，页面刷新后就看不到完整值了。建议直接存进 CI 的 Secret 管理里，不要写进任何会提交到 Git 的文件。
这里有个容易混淆的点：TaoToken 提供的是统一的 API 通道和 Key 管理，它不替代 kubectl，也不替代你的编辑器。kubectl 该连哪个集群还是连哪个集群，TaoToken 负责的是「校验工具调用外部能力时的鉴权统一」。把这两件事分清楚，后面的配置就不会拧巴。
3. 可复制配置：config.toml 与 settings.json 骨架
先给config.toml。这个文件我用来放校验工具的通用参数，包括 API base URL、超时、以及要检查的 YAML 目录。放在项目根目录，CI 和本地共用同一份。
# config.toml - K8s 配置检查通用参数 [api] base_url = "https://taotoken.net/api" api_key_env = "TAOTOKEN_API_KEY" # 从环境变量读取，不硬编码 timeout_seconds = 30 max_retries = 2 [check] yaml_dirs = ["./manifests", "./k8s/overlays"] exclude_patterns = ["**/testdata/**", "**/*.tmpl"] fail_on_warning = false [kubectl] dry_run_mode = "server" # client | server diff_enabled = true context = "staging" # 默认校验上下文 [linters] kubeval_enabled = true kube_score_enabled = true kube_score_threshold = 7 # 低于该分数视为不通过再给settings.json。这个文件主要给编辑器插件和 CI 里的 Node 脚本用，结构和config.toml对齐，避免两套配置各说各话。
{ "taotoken": { "baseUrl": "https://taotoken.net/api", "apiKeyEnv": "TAOTOKEN_API_KEY", "timeoutMs": 30000 }, "kubernetes": { "yamlDirs": ["./manifests", "./k8s/overlays"], "dryRun": "server", "diff": true, "context": "staging" }, "linters": { "kubeval": { "enabled": true }, "kubeScore": { "enabled": true, "threshold": 7 } }, "yaml.schemas": { "kubernetes": "/*.yaml" } }两个文件里的apiKeyEnv都指向同一个环境变量TAOTOKEN_API_KEY，这就是「统一 Key」的落点。本地开发时在 shell 里 export，CI 里从 Secret 注入，工具侧只认这个变量名，不关心值从哪来。
export TAOTOKEN_API_KEY="你的Key"提示：
config.toml里的context建议默认指向 staging，不要默认 prod。发布检查的第一原则是「先在非生产环境验证」，默认值选错一次，后面所有 dry-run 都白做。
4. 逐步验证：从 YAML 静态校验到 kubectl dry-run
配置就位后，按顺序跑一遍。每一步都有明确的预期输出，跑不通就停在那一步排查，不要跳步。
4.1 YAML 语法与 schema 校验
先确认文件本身没写错。用 kubectl 自带的 client 端 dry-run 做第一道过滤：
kubectl apply -f ./manifests/deploy.yaml --dry-run=client预期输出是deployment.apps/my-app created (dry-run)这类提示。如果报error: error parsing ./manifests/deploy.yaml: error converting YAML to JSON，说明缩进或冒号有问题，先修语法再往下走。
接着用 kubeval 做 schema 级校验，确认字段名和 API 版本对得上：
kubeval --strict ./manifests/deploy.yaml预期输出类似PASS - ./manifests/deploy.yaml contains a valid Deployment。如果报Failed initializing schema或字段不识别，多半是 API 版本写旧了，比如把apps/v1写成了extensions/v1beta1。
4.2 kubectl explain 查字段
遇到不确定的字段，别猜，直接问集群：
kubectl explain deployment.spec.template.spec.containers.resources预期输出会列出limits、requests的类型和含义。这一步在写resources和探针配置时特别有用，比翻文档快。
4.3 server 端 dry-run 与 diff
client 端只校验语法，server 端才会真正让 API Server 判断这份配置在集群里合不合法：
kubectl apply -f ./manifests/deploy.yaml --dry-run=server预期输出和 client 类似，但会额外暴露 RBAC、准入控制器、资源配额这类只有服务端才知道的问题。比如报admission webhook "validate.example.com" denied the request，就是被准入策略拦了。
再看和现状的差异：
kubectl diff -f ./manifests/deploy.yaml预期输出是标准的 diff 格式，+是新增、-是删除。如果输出为空，说明集群里已经是这个状态，apply 不会产生变更。这一步在 CI 里特别适合做「变更预览」，把 diff 贴到 PR 评论里，review 的人一眼就能看出这次发布动了什么。
4.4 kube-score 做健康度评分
kubeval 管「合不合法」，kube-score 管「合不合理」：
kube-score score ./manifests/deploy.yaml预期输出是一份带分数的检查报告，会指出Container has no resource limits、Pod is not set to run as non-root这类问题。config.toml里设的kube_score_threshold = 7就是用来卡这条线的，低于 7 分 CI 直接失败。
4.5 在 CI 里串起来
把上面几步写进流水线，鉴权统一走TAOTOKEN_API_KEY：
#!/usr/bin/env bash set -euo pipefail export TAOTOKEN_API_KEY="${TAOTOKEN_API_KEY:?missing key}" kubectl apply -f ./manifests/ --dry-run=client kubeval --strict ./manifests/*.yaml kubectl apply -f ./manifests/ --dry-run=server kubectl diff -f ./manifests/ || true # diff 有差异时返回非零，这里不阻断 kube-score score ./manifests/*.yaml预期结果是：前四步全部通过，kube-score 输出评分且不低于阈值。任何一步失败，流水线在对应步骤停下，日志里能直接看到是语法问题、schema 问题还是健康度问题。
5. 本篇常见错排查
报错一：error: the path "./manifests" does not exist路径写错或 CI 工作目录不对。先pwd和ls ./manifests确认，再检查config.toml里的yaml_dirs是不是相对路径。CI 里建议用绝对路径或先cd到仓库根目录。
报错二：error: You must be logged in to the server (Unauthorized)kubectl 的 kubeconfig 没配好，和 TaoToken 的 Key 是两回事。检查kubectl config current-context和kubectl config view，确认 context 指向的集群和凭证正确。config.toml里的context只是给脚本用的默认值，不会自动切换 kubeconfig。
报错三：Failed initializing schema https://kubernetesjsonschema.dev/...kubeval 拉 schema 超时或版本不匹配。加--kubernetes-version指定集群版本，比如kubeval --kubernetes-version 1.28.0。如果网络受限，提前把 schema 缓存到本地。
报错四：admission webhook denied the requestserver 端 dry-run 被准入控制器拦了。看 webhook 返回的具体 message，通常是缺 label、缺 annotation 或镜像仓库不在白名单。这类问题 client 端 dry-run 发现不了，必须走 server 端。
报错五：CI 里TAOTOKEN_API_KEY: unbound variableSecret 没注入或变量名拼错。检查 CI 的 Secret 配置，确认变量名和config.toml、settings.json里的apiKeyEnv完全一致。大小写敏感，TAOTOKEN_API_KEY和taotoken_api_key是两个变量。
报错六：kubectl diff在 CI 里导致流水线失败diff 有差异时返回码非零，这是预期行为。用|| true兜住，或者单独判断返回码：返回 1 表示有差异（正常），返回 2 表示出错（需要排查）。
6. 把校验通道固定下来，发布才不靠运气
整套流程跑通后，你会发现真正省心的不是某一条命令，而是「统一 Key + 统一配置」带来的确定性。config.toml和settings.json两份骨架对齐了本地和 CI 的行为，TAOTOKEN_API_KEY一个变量管住了所有工具的鉴权，kubectl dry-run、kubeval、kube-score 各司其职，谁出问题一眼能定位。
如果你后面要把这套检查接进编码工具或 Agent 流程，让模型帮你审 YAML，可以走 TaoToken 的 Coding Plan，入口在https://taotoken.net/coding-plan。需要直接调模型做配置对话验证的，用模型对话入口https://taotoken.net。接入文档和 Claude Code 专用通道分别在https://taotoken.net/doc和https://taotoken.net/ClaudeCodeAnthropic。Key 管理和 API 入口保持不变：控制台https://taotoken.net/console，API Keyshttps://taotoken.net/api-keys，API base URLhttps://taotoken.net/api。
最后留一个我自己的习惯：每次改完config.toml，先本地跑一遍kubectl diff，把输出贴到 PR 描述里再提 review。这样 reviewer 不用 checkout 分支就能看到这次发布到底动了哪些字段，比口头描述「改了个探针」靠谱得多。
