Kubernetes 里的 YAML：12 个让部署在凌晨 2 点炸掉的配置错误
作者：Safe Local Tools 编辑组
YAML 很亲切，直到两个空格的缩进误差把生产搞挂。 Kubernetes 把 YAML 变成基础设施的默认面孔，工程师常在压力下编辑一种 对空白敏感 的格式——内容来自 Stack Overflow、ChatGPT 或带不可见字符的 Helm 模板。
本文列举十二个常混过 Code Review 的坑，说明 API Server 如何把 YAML 转成 JSON，以及如何用 Safe Local Tools 在浏览器本地互转 YAML 与 JSON，再执行 kubectl apply。
YAML 是给人看的接口，不是宽容的语言
YAML 1.2 的标量形式比 JSON 丰富，也更容易坑机器：
yes/no可能被解析成布尔值。0123在部分引擎里按八进制处理。- 多行字符串里混入 Tab 会破坏缩进。
Kubernetes 在服务端做 YAML→JSON。文件「语法合法」但 JSON 类型意外时，会出现 运行时行为诡异 而非立即报错。
错误 1 — 用 Tab 缩进
YAML 结构层禁止 Tab 缩进，许多编辑器仍默认插入 Tab。
现象： found character that cannot start any token 或报错行号飘忽。
修复： 仅用空格、仓库加 .editorconfig、pre-commit 拒绝 *.yaml 中的 \t。
错误 2 — 缩进层级不一致
containers: 下多一个空格，环境变量可能挂到错误对象。
现象： 探针或 env「消失」。
修复： 折叠无关分支；启用 Kubernetes YAML schema（若 IDE 支持）。
错误 3 — 未加引号的歧义字符串
env:
- name: DEBUG
value: off # 部分解析器会变成 false修复： 对歧义值加引号：value: "off"。
错误 4 — 多行脚本未用块标量
args: 里含 : 的 shell 容易解析失败。
修复： 使用 | 或 > 块标量，必要时加引号。
错误 5 — 重复键（静默覆盖）
部分加载器允许重复键，后者覆盖前者且无警告。
修复： 严格 lint；临时转 JSON 查重复键。
错误 6 — 未渲染的 Helm 模板
文件里残留 {{ .Values.foo }} 不是合法资源。
修复： CI 中 helm template 或 kubectl apply --dry-run=server。
错误 7 — apiVersion / kind 不匹配
YAML 合法但集群不认识该版本。
修复： 维护各集群版本矩阵；kubectl api-resources 核对。
错误 8 — 单文件数千行
大文件极易在合并时弄乱缩进。
修复： Kustomize 拆分 Deployment / Service / Ingress。
错误 9 — 在 Git 里提交明文 Secret
data: 里的 base64 仍属敏感信息。
修复： Sealed Secrets、SOPS 或外部 Secret 方案。
错误 10 — 误解 --- 文档分隔符
少写分隔符会把多份资源粘成一份。
修复： 资源之间显式 ---；控制单文件职责。
错误 11 — 资源数量类型错误
CPU 500m、内存 512Mi 应为 字符串，不是浮点。
现象： 调度忽略 limits 或用默认值。
错误 12 — 锚点与别名
&id / *id 在纯 JSON 中不存在；转换器可能展开或报错。
修复： 提交到仓库的清单尽量显式重复；锚点仅用于本地模板阶段。
为何先转 JSON 能帮忙排错
JSON 更严：无注释（纯 JSON）、少歧义标量、重复键更易暴露。YAML → JSON → YAML 能发现：
- 隐式类型转换
null与空字符串差异- 本应是数组却被解析成对象
Safe Local Tools 在本地互转，不必把内部清单贴到云端格式化网站。
上线前工作流
- CI 格式化 + lint YAML。
- 本地转 JSON 核对结构。
kubectl apply --dry-run=server。- 金丝雀发布；关注 field 拒绝类事件。
Helm、Kustomize 与 CRD
自定义资源还有 OpenAPI 约束——Deployment 里合法的字段在 CRD 上可能非法。能生成客户端校验就生成；否则 dry-run 仍是底线。
安全习惯
- 清单当代码：签名提交、强制 Review。
- 扫描
hostPath、privileged: true、过大 RBAC。 - 生产镜像尽量 digest 固定，不只 tag。
ChatGPT 写的 YAML
大模型缩进不稳定、apiVersion 会 hallucinate。务必走同一套机械检查，聊天框里高亮「看起来对」≠ 可部署。
CI 与 schema 校验
PR 中可组合 yamllint、kubeconform 与 kubectl apply --dry-run=server。Helm 项目应把 helm template 渲染结果当作评审产物，而不是只 diff 模板逻辑。
NetworkPolicy / Ingress 易错点
网络策略的 spec 缩进错误会导致规则未生效；Ingress TLS 引用的 Secret 名称拼错时，控制器可能静默回退默认证书。转 JSON 核对嵌套结构再 apply。
收尾
YAML 出错多半是空白与类型，被 Kubernetes 严格的 JSON 模型放大。合并前在本地转换检查——试用 YAML ↔ JSON 转换 →