注解

你可以使用 Kubernetes 注解（Annotations） 为对象附加任意的非标识的元数据，客户端程序（例如工具和库）能够获取这些元数据信息。

官方文档参考

文档	链接
注解（中文）	https://kubernetes.io/zh-cn/docs/concepts/overview/working-with-objects/annotations/
Annotations（英文，内容补充参考）	https://kubernetes.io/docs/concepts/overview/working-with-objects/annotations/

为对象附加元数据

你可以使用标签或注解将元数据附加到 Kubernetes 对象，但两者的定位不同：

对比项	标签（Labels）	注解（Annotations）
用途	选择对象、查找满足条件的对象集合	附加非标识元数据，不用于标识和选择对象
值的大小	最长 63 字符	可以很小也可以很大（单对象全部注解合计上限 256 KiB）
值的内容	受字符集限制	结构化或非结构化均可，可包含标签不允许的字符
能否共存	可以在同一对象的 metadata 中同时使用标签和注解	同左

注解和标签一样，是键/值对：

"metadata": {
  "annotations": {
    "key1" : "value1",
    "key2" : "value2"
  }
}

键和值都必须是字符串

映射中的键和值必须是字符串——不能使用数字、布尔值、列表或其他类型。

以下是一些适合记录在注解中的信息：

类别	示例
声明式配置层管理的字段	与客户端/服务端默认值、自动生成字段、自动扩缩容系统设置的字段区分开
构建/发布/镜像信息	时间戳、发布 ID、git 分支、PR 编号、镜像哈希、镜像仓库地址
指针类信息	指向日志、监控、分析或审计仓库的地址
客户端库/工具信息	用于调试的名称、版本、构建信息
来源信息	用户或工具/系统的来源，例如来自其他生态组件的相关对象的 URL
灰度发布工具元数据	例如配置或检查点（checkpoints）
责任人信息	负责人的电话或寻呼机号码，或指明信息位置的目录条目（如团队网站）
行为指令	最终用户向实现层发出的、用于修改行为或启用非标准特性的指令

这些信息也可以存到外部数据库或目录中，但那样做会使得为部署、管理、内省等场景构建共享的客户端库和工具变得困难得多。

语法和字符集

注解是键/值对。有效的注解键有两个段：可选的前缀和名称，用斜杠（/）分隔。

组成部分	规则
名称段（必需）	63 字符或更少，以字母数字（[a-z0-9A-Z]）开头和结尾，中间可包含破折号（-）、下划线（_）、点（.）和字母数字
前缀（可选）	必须是 DNS 子域：由点（.）分隔的一系列 DNS 标签，总长不超过 253 个字符，后跟斜杠（/）
有效注解值	没有字符集限制——可包含任意字符串，包括特殊字符、空白字符以及 JSON、YAML 等结构化数据

如果省略前缀，则注解键被假定对该用户是私有的。向最终用户对象添加注解的自动系统组件（例如 kube-scheduler、kube-controller-manager、kube-apiserver、kubectl 或其他第三方自动化）必须指定前缀。

kubernetes.io/ 和 k8s.io/ 前缀是为 Kubernetes 核心组件保留的。

存二进制数据要先 Base64

如果计划存储二进制数据（如 CBOR），Kubernetes 项目建议先做 base64 编码。另外，单个对象上所有注解（键和值合计）总大小不得超过 256 KiB。

例如，下面是一个带有注解 imageregistry: https://hub.docker.com/ 的 Pod 的清单：

apiVersion: v1
kind: Pod
metadata:
  name: annotations-demo
  annotations:
    imageregistry: "https://hub.docker.com/"   # 注解值可以是任意字符串
spec:
  containers:
  - name: nginx
    image: nginx:1.14.2
    ports:
    - containerPort: 80

注解是工具生态的"扩展点"

很多组件的行为都通过注解配置，例如 Ingress Controller 的规则参数、kubectl 的 kubernetes.io/last-applied-configuration（kubectl apply 保存的上一份配置）等。为自定义注解指定自己的前缀（如 example.com/xxx），避免和系统或其他工具冲突。

我的总结与避坑清单

1. 先问"这份数据要不要用来筛选对象"：要筛选就放标签，不筛选就放注解；两者可以在同一个对象上共存。
2. 注解值虽无字符集限制，但整组注解合计上限是 256 KiB，不要把大段配置、日志或整个镜像清单塞进去。
3. 注解的键和值都必须是字符串，数字、布尔、列表都要先序列化成字符串。
4. 自定义注解务必带自有域名前缀（如 mycompany.com/owner）；不带前缀的键视为用户私有，kubernetes.io/、k8s.io/ 是系统保留前缀。
5. kubernetes.io/last-applied-configuration 由 kubectl 自动维护，不要手工修改它，否则可能影响 kubectl apply 的合并行为。
6. 二进制数据先 base64 编码再放注解，并且优先考虑用 ConfigMap/Secret 而不是注解来承载。
7. 用 kubectl annotate 更新注解时，键已存在且未加 --overwrite 会失败；删除注解用 key- 语法（如 kubectl annotate pod demo imageregistry-）。
8. 一些控制器会通过注解下发行为指令（如 Ingress 的 rewrite/ssl-redirect 参数），写错注解键名不会报错、只会"静默不生效"，排障时要先核对键名拼写和前缀。
9. 注解不参与任何选择逻辑，试图用 -l（标签选择）去过滤注解是行不通的；需要按注解过滤只能借助 kubectl get -o json | jq 之类的外部处理。