Kubernetes 资源定义重度依赖 YAML 文件，本文会讲解一些 YAML 编写的技巧和坑！
- 原文地址：https://itnext.io/kubernetes-yaml-tips-and-tricks-904a2c0b2b81
核心要点摘要
- Kubernetes YAML 最基础的要求是缩进稳定，不要使用 Tab。
- YAML 会自动推断类型，
yes、no、on、off、数字、日期等值如果没有引号，可能被解析成和预期不同的类型。 - Map 和 List 是 YAML 的核心结构，嵌套层级一旦错位，Kubernetes 资源含义就会变化。
- 锚点和引用可以减少重复配置，但要控制使用范围，避免让配置变得难读。
- 提交前建议使用 yamllint、VS Code YAML 扩展、
yq等工具做格式和解析验证。
为什么 Kubernetes YAML 容易出错
YAML 的优点是可读性强，适合描述 Kubernetes 这类层级化资源。它的问题也很明显：很多语义依赖缩进和类型推断。
同一段文本，在人眼里看起来可能差不多，但解析器会根据缩进、冒号、短横线、引号和关键字做严格解释。配置一旦解析错，轻则部署失败，重则资源字段和你以为的不一样。
可引用地说：写 Kubernetes YAML，不只是把字段写出来，更重要的是确认解析器看到的结构和你脑子里的结构一致。
不要用 Tab
缩进，对 YAML 很重要，不要用 Tab 来缩进，用两个空格、四个空格都是 OK 的。
YAML 官方在 FAQ 中说明过为什么不要用 Tab：
由于不同的编辑器和工具对制表符（Tabs）的处理方式不同，制表符已被禁用。而且由于缩进对于正确解读YAML至关重要，这个问题极其棘手，甚至都不值得尝试。实际上，Python的吉多·范罗苏姆（Guido van Rossum）已经承认，在Python源代码中允许使用制表符给许多人带来了麻烦，如果他重新设计Python，他会禁止使用制表符。
在 Kubernetes YAML 里，建议团队统一缩进风格。两个空格、四个空格都可以，但不要混用。编辑器里最好开启显示空白字符，并配置保存时不要把空格转成 Tab。
Map 和 List 是最核心的结构
YAML 中最重要的结构是 Map 和 List，Map 是一堆键值对，而且可以嵌套，对应 JSON 的话示例如下：
另一个重要结构是列表，列表的每一项前面有个短横线：
任何列表或映射的值都可以是字符串、数字、布尔值、null 或其他 Map 或 List。
在大多数情况下，字符串不需要引号。但有时，如果你漏掉了引号，解析结果就可能和预期不一样。
常见坑一：布尔值自动转换
挪威问题
默认情况下，单词 “yes” 和 “no” 可能被转换为布尔值。
注意，不止 false 会被当做 bool 值，no、off 也可能被转换为 bool 值。这可能跟你的原始期望不符。
解决方式很简单：如果你希望它就是字符串，就加上双引号，比如 "no"、"off"。
这在 Kubernetes 里尤其要注意。标签、注解、环境变量、ConfigMap 内容里经常会出现看似普通的字符串，如果被自动转换成布尔值，就可能导致配置含义变化。
常见坑二：数字和日期自动转换
数字转换
有些版本号，你原本是当做字符串的，如果没有加双引号，也可能会有问题，比如：
还有日期，可能会被自动转换为时间戳，比如：
版本号、镜像 tag、账号、编号、日期、开关类字符串，如果业务上就是字符串，建议直接加引号。不要把“看起来像数字”交给解析器猜。
常见坑三：键名也可能有类型歧义
键关键字
虽然 JSON 中的键始终是字符串，但在 YAML 中，它们可以是任何值，包括布尔值。
将 on 作为键是一个糟糕的主意。
如果确实需要使用容易被解析器误判的键名，建议加引号。更好的做法是避免把 on、off、yes、no 这类词作为关键键名。
其他有用的功能
1、您可以使用 --- 分隔文档
在 Kubernetes 场景中，一个文件里放多个资源很常见，比如 Deployment、Service、ConfigMap 放在同一个 YAML 文件里。--- 可以把它们分隔成多个文档。
2、引用机制，避免重复编写内容
上例中，matchLabels 是一个 Map，里边有一个 run 的字段，matchLabels 右侧加了一个 &pod-label，之后就可以在其他地方使用 *pod-label 引用。
当然，也可以引用一大段，比如：
user: &user
name: John
address:
street: 123 Main St
city: Anytown
admin:
<<: *user
role: admin
锚点和引用适合减少重复配置，但也不要滥用。配置文件的第一目标是让团队看得懂。对于多人维护的 Kubernetes YAML，如果锚点层层嵌套，反而会增加 review 和排障成本。
调试工具
- 像 http://www.yamllint.com/ 这样的在线 YAML linter
- 像 https://yamllint.readthedocs.io/en/stable/ 这样的 CLI
- 如果您使用 Visual Studio Code，请从 Red Hat 安装 YAML 扩展以实现自动完成 https://marketplace.visualstudio.com/items?itemName=redhat.vscode-yaml
另外，在用 JSON 时经常会用到一个工具叫 jq，在 YAML 中也可以使用 yq 工具，比如上面的 YAML 文件可以使用 yq 转换为 JSON 做测试：
ulric@192 trash % cat a.yaml
user: &user
name: John
address:
street: 123 Main St
city: Anytown
admin:
<<: *user
role: admin%
ulric@192 trash % yq --tojson a.yaml
Flag --tojson has been deprecated, please use -o=json instead
{
"user": {
"name": "John",
"address": {
"street": "123 Main St",
"city": "Anytown"
}
},
"admin": {
"name": "John",
"address": {
"street": "123 Main St",
"city": "Anytown"
},
"role": "admin"
}
}
其他 yq 的用法这里就不赘述了。下次见！
提交 Kubernetes YAML 前的检查清单
建议提交前至少检查下面几件事：
- 文件里没有 Tab，缩进风格统一。
- Map 和 List 的层级符合预期，尤其是
spec、template、containers、env、volumeMounts这类嵌套字段。 - 字符串值中容易被推断为布尔值、数字或日期的内容都加了引号。
- 标签、注解、环境变量、ConfigMap 中的值和 Kubernetes 期望的类型一致。
- 用 yamllint、VS Code YAML 扩展或
yq做过解析验证。 - 如果是 Kubernetes 资源，再配合
kubectl的 dry-run 或类似机制确认资源能被 API 正确识别。
FAQ
Q1：YAML 缩进用两个空格还是四个空格？
两个空格和四个空格都可以，关键是团队内部统一。不要使用 Tab，也不要在同一个文件里混用不同风格。
Q2：什么时候必须给字符串加引号？
当字符串看起来像布尔值、数字、日期、版本号或特殊关键字时，建议加引号。比如 "no"、"off"、"1.20"、"2025-07-08"。
Q3：锚点和引用适合在 Kubernetes YAML 里大量使用吗？
不建议大量使用。它们可以减少重复，但也会让配置的实际展开结果不够直观。多人协作时，要优先保证可读性和可审查性。
结论
YAML 本身不复杂，但 Kubernetes YAML 很容易因为缩进、类型推断和嵌套结构出问题。
最稳妥的习惯是：不用 Tab，关键字符串加引号，复杂结构用工具解析验证，提交前确认 Kubernetes 看到的资源结构和你预期一致。这样能避免很多“看起来没问题、实际解析错了”的配置坑。
在监控领域创业四年了，如果您想索要监控/可观测性白皮书资料或申请产品演示，都可联系我们（免费哒）👇
