在 Kubernetes 的 YAML 配置文件中，metadata（元数据）是用来标识和组织资源对象的。如果把一个 K8s 资源比作一份档案，那么 spec 是档案的内容，而 metadata 就是档案封面上贴的标签、编号和分类信息。
metadata 主要由三个核心部分组成：Name（名字）、Namespace（命名空间） 和 Labels/Annotations（标签与注解）。
1. 唯一标识：Name & Namespace
这是资源在集群中的“身份证号”。
- name: 资源的名称。在同一个命名空间内，同类型的资源名字必须唯一。
- namespace: 资源所属的逻辑隔离区。如果不写，默认是
default。
示例：
metadata:
name: ai-fe-deployment # 它的名字
namespace: ai-dev # 它住在 ai-dev 房间里
2. 核心纽带：Labels（标签）
这是 metadata 中最重要的功能。标签是键值对（Key-Value），用于对资源进行分组和关联。
为什么需要 Labels？
K8s 的组件之间不是通过“名字”硬编码连接的，而是通过 “标签选择器 (Selector)” 动态寻找的。
看你之前的 ai-fe 配置中的链路：
-
Pod 上贴标签：
# Deployment 的模板部分 template: metadata: labels: app: ai-fe # 给生成的 Pod 贴上“我是 ai-fe”的标签 -
Service 找标签：
# Service 部分 spec: selector: app: ai-fe # Service 说：凡是带“app: ai-fe”标签的 Pod，流量都归我管 -
Deployment 管理标签：
# Deployment 自己的选择器 spec: selector: matchLabels: app: ai-fe # Deployment 说：我要监控所有带这个标签的 Pod，少了就补，多了就删
比喻：这就好比在一群人中，Service 喊一句：“穿红色衣服的（Label）站出来受命”，它不需要知道每个人的具体名字。
3. 辅助信息：Annotations（注解）
注解也是键值对，但它与 Labels 有本质区别：
- Labels 是给 K8s 筛选用的（具有搜索功能）。
- Annotations 是给人或第三方工具看的（不具备搜索功能）。
常见用途：
- 记录版本发布信息：
build_ver: "1.0.5"。 - 记录负责人：
owner: "sunwenquan@tengits.com"。 - 给 Ingress 控制器传参数：例如
kubernetes.io/ingress.class: "nginx"。
4. 系统生成的 Metadata（你通常不需要写）
当你执行 kubectl get pod <name> -o yaml 查看一个已经在运行的 Pod 时，你会发现 metadata 里多了很多东西：
- uid: K8s 自动生成的唯一 ID（防止删了重名后的混淆）。
- resourceVersion: 资源版本号，用于并发控制。
- creationTimestamp: 创建时间。
- selfLink: 资源在 API 中的路径。
总结：如何正确使用 Metadata？
| 字段 | 是否必填 | 作用 | 提示 |
|---|---|---|---|
| name | 是 | 唯一名称 | 只能包含小写字母、数字和中划线 - |
| namespace | 否 | 环境隔离 | 建议明确指定，避免全堆在 default |
| labels | 强烈建议 | 关联与分组 | 必须与 Service 的 selector 对应上 |
| annotations | 否 | 存储辅助信息 | 适合放日志记录、描述、联系人信息 |
避坑指南：
如果你修改了 Deployment 的 metadata.labels 却忘了改 spec.selector.matchLabels，K8s 会报错，因为它无法匹配到自己管理的“下属”。这两处的标签必须严丝合缝地对上。