注解（Annotations）是附加到 Kubernetes 对象上的键值对。

与标签的区别：
- 标签：用于选择和过滤，有长度限制
- 注解：用于附加信息，无长度限制

用途：
- 存储非标识性信息
- 工具和库的配置
- 构建、发布、镜像信息
- 网络策略、监控配置

metadata:
  annotations:
    # 简单形式
    description: "My web application"

    # 带前缀
    example.com/owner: "team-a"
    example.com/contact: "[email protected]"

    # 多行值
    example.com/notes: |
      This is a multi-line
      annotation value

    # JSON 值
    example.com/config: '{"key": "value"}'

apiVersion: v1
kind: Pod
metadata:
  name: web
  annotations:
    description: "Web server for frontend"
    owner: "team-frontend"
    contact: "[email protected]"
    version: "1.0.0"
    changelog: "Initial deployment"
spec:
  containers:
  - name: nginx
    image: nginx

# 查看 Pod 注解
kubectl get pod web -o jsonpath='{.metadata.annotations}'

# 格式化输出
kubectl get pod web -o jsonpath='{.metadata.annotations}' | jq .

# 查看特定注解
kubectl get pod web -o jsonpath='{.metadata.annotations.description}'

# 添加注解
kubectl annotate pod web owner=team-a

# 修改注解（需要 --overwrite）
kubectl annotate pod web owner=team-b --overwrite

# 删除注解
kubectl annotate pod web owner-

annotations:
  build/version: "1.0.0"
  build/commit: "abc123"
  build/branch: "main"
  build/timestamp: "2026-07-01T10:00:00Z"
  build/builder: "ci-pipeline"

annotations:
  owner: "team-backend"
  contact: "[email protected]"
  oncall: "+1-555-0123"
  cost-center: "engineering"
  environment: "production"

annotations:
  # Ingress 配置
  nginx.ingress.kubernetes.io/rewrite-target: /
  nginx.ingress.kubernetes.io/ssl-redirect: "true"

  # Service 配置
  service.beta.kubernetes.io/aws-load-balancer-type: "nlb"

annotations:
  prometheus.io/scrape: "true"
  prometheus.io/port: "9090"
  prometheus.io/path: "/metrics"

# Kubernetes 官方
kubectl.kubernetes.io/
node.kubernetes.io/
apps.kubernetes.io/

# Ingress 控制器
nginx.ingress.kubernetes.io/
traefik.ingress.kubernetes.io/

# 云提供商
service.beta.kubernetes.io/
volume.beta.kubernetes.io/

# 工具
helm.sh/
argocd.argoproj.io/

1. 大小限制
   键值对总计不超过 256KB

2. 不可选择
   不能用标签选择器过滤注解

3. 不影响调度
   注解不影响 Pod 调度决策

4. 可选性
   注解是可选的，不影响核心功能

# CI/CD 工具使用注解存储信息
annotations:
  # Jenkins
  jenkins.io/build-url: "https://jenkins.example.com/job/123"

  # GitHub Actions
  github.com/workflow-run: "abc123"

  # ArgoCD
  argocd.argoproj.io/sync-status: "Synced"

1. 使用前缀
   避免键名冲突

2. 有意义的键名
   使用层次结构：category/subcategory

3. 适当的值
   短文本、JSON、URL 都可以

4. 文档化
   记录使用的注解及其含义

apiVersion: v1
kind: Pod
metadata:
  name: web
  annotations:
    description: "Web application"
    owner: "team-frontend"
    version: "1.0.0"
spec:
  containers:
  - name: nginx
    image: nginx

kubectl apply -f pod.yaml
kubectl get pod web -o jsonpath='{.metadata.annotations}' | jq .

# 添加注解
kubectl annotate pod web [email protected]
kubectl get pod web -o jsonpath='{.metadata.annotations.contact}'

# 修改注解
kubectl annotate pod web [email protected] --overwrite
kubectl get pod web -o jsonpath='{.metadata.annotations.contact}'

# 删除注解
kubectl annotate pod web contact-

apiVersion: v1
kind: Pod
metadata:
  name: demo
  labels:
    app: web
    env: production
  annotations:
    description: "Demo application"
    owner: "team-a"
spec:
  containers:
  - name: nginx
    image: nginx

# 标签可以用于选择
kubectl get pods -l app=web

# 注解不能用于选择
kubectl get pods -l description=web  # 不会工作

kubectl annotate pod web \
  build/commit=$(git rev-parse HEAD) \
  build/branch=$(git branch --show-current) \
  build/timestamp=$(date -u +"%Y-%m-%dT%H:%M:%SZ")

错误：注解和标签可以互换使用
正确：
- 标签：用于选择，有长度限制
- 注解：用于附加信息，几乎无长度限制

选择正确的工具完成正确的任务

错误：删除注解会影响 Pod 运行
正确：注解是可选的附加信息

除非工具明确依赖某个注解，否则删除不影响功能

错误：注解值必须是简单字符串
正确：注解值可以是：
- 短文本
- 多行文本
- JSON
- URL
- 任意字符串