基础设施即代码 / 知识点
YAML 语法速查手册
YAML 1.1 / 1.2 与解析器差异
YAML 1.2.2当前稳定规范修订版 1.2.2 对 YAML 1.2 做澄清和勘误。
YAML 1.2.2 基准
当前稳定规范修订版 1.2.2 对 YAML 1.2 做澄清和勘误。
所属主题
YAML 1.1 / 1.2 与解析器差异
语法 / 形式
YAML 1.2.2推荐示例
%YAML 1.2关键边界
1.2.2 没有对 1.2 引入新的规范语义变化。
yes/no/on/off/y/nYAML 1.1 生态常把更多词解析为布尔值。
YAML 1.1 Boolean 陷阱
YAML 1.1 生态常把更多词解析为布尔值。
所属主题
YAML 1.1 / 1.2 与解析器差异
语法 / 形式
yes/no/on/off/y/n推荐示例
countryCode: 'NO'关键边界
如果配置要跨老解析器,类似 NO、ON、yes、off 的业务字符串应加引号。
0777 vs 0o777YAML 1.2 core 使用 0o 前缀;老 1.1 语义常见前导 0 八进制。
YAML 1.1 八进制差异
YAML 1.2 core 使用 0o 前缀;老 1.1 语义常见前导 0 八进制。
所属主题
YAML 1.1 / 1.2 与解析器差异
语法 / 形式
0777 vs 0o777推荐示例
mode: '0755'关键边界
Linux 文件 mode 在很多应用 schema 中其实要求字符串;按上层 schema 写。
2026-08-27不同 schema/库可能把日期样式 plain scalar 解析成字符串或日期对象。
Timestamp 解析差异
不同 schema/库可能把日期样式 plain scalar 解析成字符串或日期对象。
所属主题
YAML 1.1 / 1.2 与解析器差异
语法 / 形式
2026-08-27推荐示例
releaseDate: '2026-08-27'关键边界
跨语言配置需要稳定字符串时统一加引号。
<<: *baseMerge key 被大量 YAML 工具支持,但并非所有 YAML 1.2 解析器都一致支持。
Merge Key 支持差异
Merge key 被大量 YAML 工具支持,但并非所有 YAML 1.2 解析器都一致支持。
所属主题
YAML 1.1 / 1.2 与解析器差异
语法 / 形式
<<: *base推荐示例
config:
<<: *base关键边界
部署到新工具链前必须实际验证。
key: a
key: b重复 mapping key 在解析器中的报错/覆盖策略并不值得依赖。
Duplicate Key 行为差异
重复 mapping key 在解析器中的报错/覆盖策略并不值得依赖。
所属主题
YAML 1.1 / 1.2 与解析器差异
语法 / 形式
key: a
key: b推荐示例
name: one关键边界
lint 阶段直接禁止重复 key。
!Custom value自定义 tag 是否允许、如何构造对象完全由解析框架决定。
未知 Tag 行为差异
自定义 tag 是否允许、如何构造对象完全由解析框架决定。
所属主题
YAML 1.1 / 1.2 与解析器差异
语法 / 形式
!Custom value推荐示例
value: !Custom data关键边界
反序列化不可信 YAML 时尤其要禁用危险对象构造。
JSON-style collectionsYAML 1.2 设计上与 JSON 数据模型更兼容。
JSON 是 YAML 1.2 子集方向
YAML 1.2 设计上与 JSON 数据模型更兼容。
所属主题
YAML 1.1 / 1.2 与解析器差异
语法 / 形式
JSON-style collections推荐示例
{"name": "demo", "ports": [80, 443]}关键边界
合法 JSON 文本可用于许多 YAML 1.2 场景,但应用的 schema/loader 行为仍需确认。
{{ ... }}Go template 由 Helm 在 YAML 解析/提交前后相关阶段处理。
Helm 模板不是 YAML
Go template 由 Helm 在 YAML 解析/提交前后相关阶段处理。
所属主题
YAML 1.1 / 1.2 与解析器差异
语法 / 形式
{{ ... }}推荐示例
image: "{{ .Values.image }}"关键边界
模板文件可能不是独立合法 YAML,不能把 {{ }} 当 YAML 语法。
${VAR}Compose 的变量插值是 Docker Compose 规范能力。
Docker Compose 插值不是 YAML
Compose 的变量插值是 Docker Compose 规范能力。
所属主题
YAML 1.1 / 1.2 与解析器差异
语法 / 形式
${VAR}推荐示例
image: "app:${TAG}"关键边界
纯 YAML parser 不会自动展开 ${TAG}。
---Kubernetes 清单常使用 --- 在一个文件放多个对象。
Kubernetes 多文档是上层用法
Kubernetes 清单常使用 --- 在一个文件放多个对象。
所属主题
YAML 1.1 / 1.2 与解析器差异
语法 / 形式
---推荐示例
---
apiVersion: v1
kind: ConfigMap关键边界
多 document 是 YAML 能力;每个文档如何解释是 Kubernetes schema 的事情。
校验、安全与工程实践
parser/linter先确认 YAML 语法能被目标解析器读取。
先做 YAML Parse 校验
先确认 YAML 语法能被目标解析器读取。
所属主题
校验、安全与工程实践
语法 / 形式
parser/linter推荐示例
yamllint config.yaml关键边界
语法合法只是第一层,还需要上层 schema 校验。
application schema使用 Kubernetes/OpenAPI/JSON Schema/应用自身 schema 校验字段。
再做业务 Schema 校验
使用 Kubernetes/OpenAPI/JSON Schema/应用自身 schema 校验字段。
所属主题
校验、安全与工程实践
语法 / 形式
application schema推荐示例
kubectl apply --dry-run=server -f <FILE>关键边界
YAML parser 不知道 replicas 是否允许字符串等业务约束。
yamllint <FILE>检查缩进、重复 key、行长、truthy 风格等常见问题。
使用 yamllint
检查缩进、重复 key、行长、truthy 风格等常见问题。
所属主题
校验、安全与工程实践
语法 / 形式
yamllint <FILE>推荐示例
yamllint config.yaml关键边界
lint 规则是工程规范,不等于全部 YAML 语法规范。
validate → diff → apply修改 YAML 后先比较变更。
生产修改先 Diff
修改 YAML 后先比较变更。
所属主题
校验、安全与工程实践
语法 / 形式
validate → diff → apply推荐示例
git diff -- config.yaml关键边界
尤其注意缩进变化可能导致结构级变化。
mapping order消费端逻辑不要把 mapping key 顺序当业务协议。
不要依赖键顺序
消费端逻辑不要把 mapping key 顺序当业务协议。
所属主题
校验、安全与工程实践
语法 / 形式
mapping order推荐示例
steps:
- validate
- deploy关键边界
需要顺序时用 Sequence。
anchors/aliasesAnchor 适合少量重复数据,不适合构造复杂继承系统。
避免过深 Anchor 继承
Anchor 适合少量重复数据,不适合构造复杂继承系统。
所属主题
校验、安全与工程实践
语法 / 形式
anchors/aliases推荐示例
defaults: &defaults
timeout: 30关键边界
多层 alias/merge 会降低可读性和工具兼容性。
parser limits解析不可信 YAML 时设置 alias/node/depth 等资源限制。
限制不可信 Alias Expansion
解析不可信 YAML 时设置 alias/node/depth 等资源限制。
所属主题
校验、安全与工程实践
语法 / 形式
parser limits推荐示例
maxAliasesForCollections: <LIMIT>关键边界
防止 alias expansion 导致 CPU/内存拒绝服务;具体参数取决于解析库。
safe loader处理用户 YAML 时使用安全加载模式。
禁用不可信对象构造
处理用户 YAML 时使用安全加载模式。
所属主题
校验、安全与工程实践
语法 / 形式
safe loader推荐示例
safeLoad(<YAML>)关键边界
某些历史 YAML 库允许 tag 实例化语言对象,可能导致严重安全问题。
version + library团队文档记录实际 loader 与 YAML schema。
明确目标 YAML 版本与解析库
团队文档记录实际 loader 与 YAML schema。
所属主题
校验、安全与工程实践
语法 / 形式
version + library推荐示例
YAML: 1.2
Parser: <LIBRARY>/<VERSION>关键边界
比笼统说“这是 YAML”更能避免跨语言解析差异。