annotate 是干什么的
kubectl annotate 管理资源的注解（annotation）：注解是键值对形式的任意非标识性元数据，值只能是字符串，不适合被选择器匹配。很多控制器与入口实现的行为靠注解驱动，例如 Ingress 的重写与超时规则、证书自动签发、Prometheus 抓取开关、发布工具记录的变更原因，因此注解虽小，却常常是「改一个字符串就改变线上行为」的地方。
基本信息
| 语法 | kubectl annotate <资源类型> <名称> <key>=<value> |
|---|---|
| 覆盖已有键 | 加 --overwrite |
| 删除注解 | 键名后加连字符，如 owner- |
| 值类型 | 只能是字符串，数字与布尔写成字符串 |
| 生效时机 | 多数控制器实时监听，个别需重启组件 |
典型使用场景
- 记录变更原因：用 kubernetes.io/change-cause 标注本次发布做了什么，回滚时可读
- 配置入口行为：Ingress 上写重写、超时、上传大小限制等控制器注解
- 标注归属关系：写入负责人、工单号、外部系统 ID，便于追责与清理
- 驱动控制器：证书签发、服务网格注入、日志采集开关都可通过注解开启
- 临时排除资源：部分工具靠注解把对象从同步或抓取范围内排除
常用命令
常用命令
kubectl annotate deploy web owner='team-a' # 新增注解
kubectl annotate deploy web kubernetes.io/change-cause='upgrade to 1.26.0' --overwrite
kubectl annotate ingress web nginx.ingress.kubernetes.io/rewrite-target=/ # 改入口行为
kubectl annotate deploy web owner- # 删除该键（末尾连字符）
kubectl get deploy web -o jsonpath='{.metadata.annotations}' # 查看全部注解注解与标签的分工
| 维度 | 标签 labels | 注解 annotations |
|---|---|---|
| 是否被选择器匹配 | 是，Service 与 Deployment 都靠它选 Pod | 否，选择器不支持注解 |
| 值限制 | 有长度与字符集限制 | 字符串，可较长 |
| 典型用途 | 分组与选择、金丝雀标记 | 控制器参数、变更记录、外部系统引用 |
| 改动风险 | 可能瞬间改变流量走向 | 可能改变控制器行为，但影响不透明 |
删除注解与新增注解长得只差一个连字符，误删旧注解可能让控制器行为突变，例如 Ingress 重写规则失效、证书不再自动续签。对生产对象的注解改动，建议先在灰度对象上验证或保留原值记录。
部分注解属于保留域（kubernetes.io/、k8s.io/ 等前缀），由系统或控制器使用，写入错误值会让控制器拒绝处理该对象；自定义信息请使用团队自己的域名前缀，避免与保留域冲突。