京公网安备11010502063487号注解和标签到底差在哪?为什么注解能放很多内容却不能被选中?改注解会不会重启 Pod?为什么 kubectl apply 一个大 ConfigMap 会报 annotations Too long?这篇逐项量出来。
一个注解,键 1 字节 + 值 262143 字节(合计 262144):退出码 0;['configmap/ann-262143 created'] 一个注解,键 1 字节 + 值 262144 字节(合计 262145):退出码 1;['The ConfigMap "ann-262144" is invalid: metadata.annotations: Too long: may not be more than 262144 bytes'] 两个注解各 150000 字节(总计 300000,每个都没超):退出码 1;['The ConfigMap "ann-two" is invalid: metadata.annotations: Too long: may not be more than 262144 bytes'](上限是所有注解加起来) 对比标签:值 100 字节:退出码 1;['The ConfigMap "lab-big" is invalid: metadata.labels: Invalid value: "zzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzz": must be no more than 63 byte'](标签值上限 63)
注解总量上限是 262144 字节(256 KiB):一个键 1 字节、值 262143 字节(合计 262144)创建成功;值 262144 字节(合计 262145)被拒——metadata.annotations: Too long: may not be more than 262144 bytes;两个注解各 150000 字节(每个都没超)同样被拒,上限是所有注解加起来。对比标签:值 100 字节就被拒,标签值最多 63 字节。
-l owner=team-a(标签):['configmap/has-ann'] -l owner=team-b(only-ann 只有注解 owner=team-b):选不到 只能把全部对象读出来,在客户端按注解过滤:['only-ann'] --field-selector metadata.annotations.owner=team-b:退出码 1;['Error from server (BadRequest): Unable to find "/v1, Resource=configmaps" that match label selector "", field selector "metadata.annotations.owner=team-b": "metadata.annotations.owner" is not a known field selector: only "metadata.name", "metadata.na']
有标签 owner=team-a 的 has-ann 能被 -l owner=team-a 选到;只有注解 owner=team-b 的 only-ann 被 -l owner=team-b 选不到,只能读出全部对象在客户端按注解过滤;--field-selector metadata.annotations.owner=team-b 直接报错 is not a known field selector。注解不进索引,不能当筛选条件——想被选中就用标签,想带说明和配置就用注解。
给 Deployment 本身加注解 note=hello:ReplicaSet 数 1 → 1(没有新 ReplicaSet,不触发滚动)
改 spec.template.metadata.annotations(Pod 模板里的注解):ReplicaSet 数 1 → 2(模板变了,新建 ReplicaSet,触发滚动更新;kubectl rollout restart 就是这么做的)
rollout restart 写入的注解:{"kubectl.kubernetes.io/restartedAt":"2026-10-11T02:35:47+08:00","restarted-at":"v1"}
rollout history 的行数:3(每个 ReplicaSet 一个 revision)给 Deployment 本身加注解 note=hello:ReplicaSet 数 1 → 1,不触发滚动。改 spec.template.metadata.annotations(Pod 模板里的注解):ReplicaSet 数 1 → 2,模板变了,新建 ReplicaSet 触发滚动更新。kubectl rollout restart 正是往模板里写 kubectl.kubernetes.io/restartedAt 这个时间戳注解来触发滚动的。
ConfigMap data 约 100 KB:create → 退出码 0;client-side apply → 退出码 0;server-side apply → 退出码 0 ConfigMap data 约 300 KB:create → 退出码 0;client-side apply → 退出码 1(The ConfigMap "big-apply-300k" is invalid: metadata.annotations: Too long: may not be more than 262144 bytes);server-side apply → 退出码 0 apply 创建的 100 KB 的 ConfigMap 上,kubectl.kubernetes.io/last-applied-configuration 注解大小 100212 字节(≈ 整份对象)
kubectl apply 会把整份配置抄进 kubectl.kubernetes.io/last-applied-configuration 注解(100 KB 的 ConfigMap 上这个注解有 100212 字节)。ConfigMap data 约 100 KB:create、client-side apply、server-side apply 都成功;约 300 KB:create 成功(ConfigMap 上限是 1 MiB),client-side apply 失败——metadata.annotations: Too long: may not be more than 262144 bytes,server-side apply 成功(不写这个注解)。大对象要用 create / replace 或 server-side apply。