【Kubernetes】Labels vs. Annotations: 给你的资源打对“标签”，别再傻傻分不清了-CSDN博客

本文链接：https://blog.csdn.net/showyoui/article/details/149102587

文章目录

楔子：整理房间的艺术

刚开始接触 Kubernetes 时，我看着 metadata 下的 labels 和 annotations，感觉它们就像一对双胞胎：都是键值对，都能给资源加点额外信息。我心想：“这有啥区别？随便用一个不就行了？”

结果，随着管理的资源越来越多，我才发现自己当初的想法有多天真。用错“标签”的后果，就像你把所有书都贴上“好看”的贴纸，却忘了按“科幻”、“历史”、“悬疑”来分类。找起书来，那叫一个灾难。

今天，我们就来彻底弄明白这对“双胞胎”到底谁是谁，让你在管理 K8s 资源时，能像一个收纳大师一样，把所有东西都安排得明明白白。

`Labels`：K8s 的“检索目录”，为筛选而生

想象一下，Labels 就是你给 K8s 资源贴上的可供筛选的、标准化的分类贴纸。

它的唯一核心目的，就是识别和选择对象集合。K8s 内部的各种组件，比如 Service、ReplicaSet、Deployment，就是靠 Labels 来找到它们需要管理的那些 Pod 的。没有 Labels，Service 就像一个失去了地址的快递员，完全不知道该把流量送到哪个 Pod 手里。

Talk is cheap, show me the code!

一个最经典的场景：Service 如何找到它的后端 Pod？

# --- 这是你的 Service ---
apiVersion: v1
kind: Service
metadata:
  name: my-app-service
spec:
  selector:
    # 看这里！这就是“订单”，它要找所有贴着 app: my-app 贴纸的 Pod
    app: my-app
    tier: frontend
  ports:
  - protocol: TCP
    port: 80
    targetPort: 9376

# --- 这是你的 Pod ---
apiVersion: v1
kind: Pod
metadata:
  name: my-app-pod-1
  labels:
    # 看这里！我贴上了这两张贴纸
    app: my-app
    tier: frontend
spec:
  containers:
  - name: my-app-container
    image: my-app:1.0

Service 通过 spec.selector 定义了一个“订单”，而 Pod 通过 metadata.labels 给自己贴上了“名牌”。当 selector 和 labels 完全匹配时，K8s 的 EndpointSlice 控制器就会自动将这个 Pod 的 IP 地址和端口加入到 Service 的后端端点列表中。

Labels 的“规矩”：

K8s 对 Labels 的要求很严格，因为它要被频繁地查询和匹配。

键和值都不能超过 63 个字符。
必须以字母或数字开头和结尾，中间只能包含字母、数字、‘-’、‘_’、‘.’。
这种严格的规范，本质上是为了优化查询性能。在 K8s 的源码实现中，对 LabelSelector 的处理是性能攸关的核心路径。

什么时候用 Labels？

就问自己一个问题：“我将来需要通过程序（比如 Selector）批量查找和管理符合这个特征的资源吗？”

如果答案是“是”，那么就用 Label。例如：

environment: production
app.kubernetes.io/name: mysql
project: a-cool-project

`Annotations`：给机器和未来自己看的“备注”

如果说 Labels 是给 K8s 核心组件看的“分类目录”，那么 Annotations 就是写给其他工具或者人类看的“详细备注”。

Annotations 的数据是非识别性的，K8s 的核心组件会完全忽略它们。它的主要作用是让各种外部工具、控制器或者运维人员能够在资源上附加一些额外的信息。

Annotations 的应用场景五花八门：

工具的配置指令：最常见的 Ingress 控制器，就是通过 Annotations 来获取详细配置的。

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: my-ingress
  annotations:
    # 这就是告诉 Nginx Ingress Controller：我要开启重写功能
    nginx.ingress.kubernetes.io/rewrite-target: /
    # 告诉 cert-manager：请为我自动申请这个域名的证书
    cert-manager.io/cluster-issuer: "letsencrypt-prod"

记录构建信息：你可以把构建时间、Git 提交哈希、镜像地址等信息放在这里，方便追踪和调试。
```
annotations:
  build-timestamp: "2025-07-02T10:00:00Z"
  git-commit-hash: "a1b2c3d4e5f6"
```
操作指令：比如 Prometheus 通过 prometheus.io/scrape: 'true' 来决定是否要采集这个 Pod 的监控指标。kubectl 自身也会用 kubectl.kubernetes.io/restartedAt 来触发 Deployment 的滚动更新。

Annotations 的“规矩”与“自由”：

这里要特别注意，Annotation 的“自由”主要体现在它的值 (Value) 上，而它的键 (Key) 同样需要遵守严格的命名规则，这一点和 Label 完全一样。

键 (Key) 的规矩（严格）:
- Annotation 的键必须遵循与 Label 键相同的格式：[前缀/]/名称。
- 名称部分：最多 63 个字符，以字母或数字开头和结尾，中间可包含 -、_、.。
- 前缀部分 (可选)：必须是 DNS 子域名格式（如 nginx.ingress.kubernetes.io），用于避免命名冲突。kubernetes.io/ 和 k8s.io/ 前缀为官方保留。
值 (Value) 的自由（宽松）:
- Annotation 的值没有任何格式限制，你可以放 JSON、URL 或者任何你想要的描述信息。
- 一个对象上所有 Annotation 的总大小不能超过 256KB。

一图胜千言：Labels vs. Annotations

特性	Labels (分类贴纸)	Annotations (备注便签)
核心用途	对象识别与筛选	记录“非识别性”的元数据
能否被选择器查询	能 (核心功能)	不能
主要消费者	K8s 核心组件 (Service, ReplicaSet)	各种工具、控制器 (Ingress, Prometheus), 人类
语法限制	键和值都严格 (为查询优化)	键严格，值宽松 (为信息承载)
灵魂拷问	我需要用程序找到它吗？	我需要给它添加描述吗？