K8s 清单结构是什么
Kubernetes 的所有资源清单都是同一套骨架：apiVersion 加 kind 定位资源类型，metadata 描述对象身份，spec 描述期望状态，status 由控制器回填实际状态。写清单时只需要关心前三段，status 永远是只读的。理解这套骨架之后，Deployment、Service、ConfigMap 的差异就只是字段内容不同，学习成本大幅下降。
基本信息
| apiVersion | API 组与版本，如 apps/v1、networking.k8s.io/v1、v1 |
|---|---|
| kind | 资源类型，如 Deployment、Service、ConfigMap |
| metadata | name、namespace、labels、annotations，名称在命名空间内唯一 |
| spec | 期望状态：副本数、Pod 模板、端口、路由规则等 |
| status | 实际状态，由控制器维护，只读，不应写进清单 |
典型使用场景
- 写新清单：照着骨架填参数，不必记住每个资源的完整字段表
- 排查差异：对比 spec 与实际状态，快速看出被谁改动过
- 字段查证：用 kubectl explain 查询当前集群的真实字段定义
- 多资源文件：用分隔符把多个资源写在一个文件里统一提交
- 理解报错：字段被拒绝时先判断是否属于正确的 API 版本
最小清单骨架
最小清单骨架
apiVersion: apps/v1 # 定位 API 组与版本，写错会被拒绝
kind: Deployment # 资源类型
metadata:
name: web # 名称，命名空间内唯一
namespace: dev # 不写则落在 default
labels:
app: web
spec: # 以下是期望状态，由使用者定义
replicas: 2
selector:
matchLabels:
app: web # 必须与模板标签一致，否则报错
template:
metadata:
labels:
app: web
spec:
containers:
- name: web
image: nginx:1.27-alpine四段结构对照
| 段落 | 谁定义 | 作用 |
|---|---|---|
| apiVersion 与 kind | 使用者 | 声明资源类型与 API 版本 |
| metadata | 使用者 | 对象身份、归属命名空间与标签 |
| spec | 使用者 | 期望状态，控制器向它对齐 |
| status | 控制器 | 实际状态，只读，写进清单会被忽略 |
字段写法不确定时用 kubectl explain 加资源类型与字段路径查询，读的是当前集群的真实定义，比搜索过时文章可靠得多。
在 Deployment 之类的资源里，spec.selector 与 Pod 模板的标签必须一致，且 selector 创建后不可修改：不一致会直接报错，改标签策略往往需要重建资源。
一份文件里写多个资源时用三短横线分隔，顺序会按文件从上到下依次创建：把命名空间、配置对象放在工作负载之前，能避免工作负载因依赖尚不存在而报错。