清单结构是什么
一份 Kubernetes 清单的骨架由四段组成：接口版本与资源类型说明「这是什么」，元数据段给出名称、命名空间与标签，定义段描述期望状态的细节。集群读到清单后做的事就是让现网向这份期望状态靠拢，而不是执行一串命令——这是声明式与命令式最根本的差别。
缩进与类型为什么关键
缩进层级决定字段挂在哪个对象下，同一层级必须一致，且只能用空格。更隐蔽的是类型推断：不加引号时某些词会被解析成布尔值，版本号、端口与开关类的值一旦被误判，对象可能创建成功但行为完全不对。
基本信息
| 适用格式 | YAML 与 JSON 均可，日常以 YAML 为主 |
|---|---|
| 必填段落 | 接口版本、资源类型、元数据、定义 |
| 缩进规则 | 使用空格，禁止制表符，同层缩进必须一致 |
| 命名空间 | 多数资源可写，不写则落在当前上下文默认命名空间 |
| 标签 | 元数据与模板中的标签需与选择器保持一致 |
| 状态段 | 只读的运行时字段，写清单时不要出现 |
典型使用场景
- 新建资源：按骨架写好清单后提交给集群
- 改造模板：从现网对象导出后清理运行态字段作为模板
- 排查创建失败：从缩进与字段层级入手，定位被拒或解析异常的原因
- 多环境复用：同一份模板加差异化覆盖，避免手工改动生产清单
- 代码评审：清单进版本库后可逐行评审字段变化
- 学习字段位置：用解释命令确认某个参数应该写在哪一层
最小工作负载骨架
最小工作负载骨架
apiVersion: apps/v1 # 接口版本，非核心资源要带组名
kind: Deployment # 资源类型
metadata:
name: web
namespace: prod
labels:
app: web
spec:
replicas: 3
selector: # 必须匹配下面模板的标签
matchLabels:
app: web
template:
metadata:
labels:
app: web
spec:
containers:
- name: web
image: registry.example.com/web:1.26.0
ports:
- containerPort: 8080易错点速记
易错点速记
缩进用空格不用制表符，同层级必须对齐
版本号、端口、开关键必要时加引号，避免被当成布尔值
选择器与模板标签不一致时创建会被拒
不可变字段（如选择器）改动后只能删除重建
状态段是只读运行时数据，永远不要写进清单四段含义
| 段落 | 作用 | 常见错误 |
|---|---|---|
| 接口版本与类型 | 告诉集群这是哪一类对象的哪个版本 | 核心资源误写组名，或版本号已废弃 |
| 元数据 | 名称、命名空间、标签与注解 | 标签与选择器不一致 |
| 定义 | 期望状态的具体描述 | 字段挂错层级或缩进错位 |
| 状态 | 集群写入的运行时信息 | 误把状态段写进提交的清单 |
接口版本写法随资源而异：核心资源通常是单纯的版本号，工作负载等属于某个接口组的资源要写成组名加版本号。
不确定字段位置时先查解释文档而不是猜：字段挂错层级往往不会报错，而是被当作未知字段忽略。