示例场景

假设你有一个 Nginx Deployment，需要：

1. 通过 annotations 传递自定义参数（比如日志级别、备份策略、告警阈值）；
2. 用一个简单的脚本读取这些参数，执行对应的运维操作（比如根据日志级别调整配置）。

第一步：在 Deployment.yaml 中定义注解（传递参数）

这里的 annotations 就是用来传递自定义参数的载体，键名可以自定义（建议加前缀避免冲突），值可以是字符串、简单 JSON 等：

yaml

apiVersion: apps/v1
kind: Deployment
metadata:
  name: nginx-deploy
  # 核心：通过 annotations 传递自定义参数
  annotations:
    # 自定义参数1：日志级别（字符串类型）
    ops/config/log-level: "info"
    # 自定义参数2：是否开启自动备份（布尔型，字符串形式）
    ops/backup/enable: "true"
    # 自定义参数3：备份保留天数（数值型，字符串形式）
    ops/backup/retention-days: "7"
    # 自定义参数4：告警CPU阈值（JSON格式，存复杂参数）
    ops/alert/cpu-threshold: '{"warning": 80, "critical": 95}'
spec:
  replicas: 2
  selector:
    matchLabels:
      app: nginx
  template:
    metadata:
      labels:
        app: nginx
    spec:
      containers:
      - name: nginx
        image: nginx:1.25
        ports:
        - containerPort: 80

第二步：读取注解中的参数（脚本实现）

写一个简单的 Shell 脚本（也可以用 Python/Go），通过 kubectl 读取 Deployment 的 annotations，解析并使用这些参数：

bash

运行

#!/bin/bash
# 脚本名：read-annotations-params.sh
# 功能：读取 Deployment 的 annotations 参数并执行对应逻辑

# 定义要读取的 Deployment 名称
DEPLOYMENT_NAME="nginx-deploy"
NAMESPACE="default"

# 1. 读取单个简单参数（日志级别）
LOG_LEVEL=$(kubectl get deploy $DEPLOYMENT_NAME -n $NAMESPACE -o jsonpath='{.metadata.annotations.ops/config/log-level}')
# 2. 读取备份开关参数
BACKUP_ENABLE=$(kubectl get deploy $DEPLOYMENT_NAME -n $NAMESPACE -o jsonpath='{.metadata.annotations.ops/backup/enable}')
# 3. 读取备份保留天数
RETENTION_DAYS=$(kubectl get deploy $DEPLOYMENT_NAME -n $NAMESPACE -o jsonpath='{.metadata.annotations.ops/backup/retention-days}')
# 4. 读取复杂JSON参数（需要 jq 解析）
CPU_THRESHOLD_JSON=$(kubectl get deploy $DEPLOYMENT_NAME -n $NAMESPACE -o jsonpath='{.metadata.annotations.ops/alert/cpu-threshold}')
# 解析JSON中的 warning 阈值
CPU_WARNING=$(echo $CPU_THRESHOLD_JSON | jq -r '.warning')

# 打印读取到的参数（模拟使用参数）
echo "===== 从 annotations 读取的参数 ====="
echo "日志级别：$LOG_LEVEL"
echo "是否开启备份：$BACKUP_ENABLE"
echo "备份保留天数：$RETENTION_DAYS"
echo "CPU告警警告阈值：$CPU_WARNING%"

# 根据参数执行逻辑（示例）
if [ "$BACKUP_ENABLE" = "true" ]; then
  echo "✅ 执行备份操作，保留 $RETENTION_DAYS 天备份..."
  # 这里可以写实际的备份命令，比如备份Nginx配置
  # cp /etc/nginx/nginx.conf /backup/nginx-$(date +%Y%m%d).conf
fi

if [ "$LOG_LEVEL" = "debug" ]; then
  echo "🔍 调整Nginx日志级别为debug..."
  # 实际场景中可以修改Nginx配置并重启
fi

第三步：运行脚本验证效果

1. 先部署上面的 Deployment：

   bash

   运行

   kubectl apply -f deployment.yaml
   

2. 给脚本加执行权限并运行：

   bash

   运行

   chmod +x read-annotations-params.sh
   ./read-annotations-params.sh
   

3. 输出结果（参数成功读取并使用）：

   plaintext

   ===== 从 annotations 读取的参数 =====
   日志级别：info
   是否开启备份：true
   备份保留天数：7
   CPU告警警告阈值：80%
   ✅ 执行备份操作，保留 7 天备份...
   

进阶场景：控制器读取注解参数

除了脚本，K8s 自定义控制器（比如 Operator）也会通过注解读取参数，比如：

yaml

# 示例：给 Deployment 加注解，让自定义Ingress控制器读取转发规则
annotations:
  # 自定义参数：Ingress域名
  custom-ingress/domain: "nginx.example.com"
  # 自定义参数：是否开启HTTPS
  custom-ingress/https-enable: "true"
  # 自定义参数：证书名称
  custom-ingress/tls-secret: "nginx-tls-secret"

控制器会监听 Deployment 的注解变化，自动创建对应的 Ingress 资源，无需手动配置 —— 这就是注解传递参数的典型生产场景。

一、Ingress 相关插件（最常用）

Ingress 插件是读取注解做动态配置的典型代表，几乎所有 Ingress 控制器都依赖注解实现自定义规则。

1. Ingress-NGINX（官方主流 Ingress 控制器）

通过注解可以动态配置路由规则、超时时间、SSL、限流等，无需修改 Ingress 核心配置：

yaml

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: nginx-ingress
  annotations:
    # 动态设置连接超时时间（核心参数）
    nginx.ingress.kubernetes.io/proxy-connect-timeout: "30s"
    # 动态设置响应超时时间
    nginx.ingress.kubernetes.io/proxy-read-timeout: "60s"
    # 动态开启HTTPS重定向
    nginx.ingress.kubernetes.io/ssl-redirect: "true"
    # 动态配置限流（每秒10个请求）
    nginx.ingress.kubernetes.io/limit-rps: "10"
    # 动态设置跨域（CORS）
    nginx.ingress.kubernetes.io/enable-cors: "true"
    nginx.ingress.kubernetes.io/cors-allow-origin: "*"
spec:
  rules:
  - host: example.com
    http:
      paths:
      - path: /
        pathType: Prefix
        backend:
          service:
            name: nginx-service
            port:
              number: 80

2. Traefik（轻量级 Ingress 控制器）

同样通过注解动态配置路由、负载均衡、健康检查等：

yaml

metadata:
  annotations:
    # 动态设置路由优先级
    traefik.ingress.kubernetes.io/priority: "10"
    # 动态开启健康检查
    traefik.ingress.kubernetes.io/service.healthcheck.path: "/health"
    traefik.ingress.kubernetes.io/service.healthcheck.interval: "10s"
    # 动态配置负载均衡策略（轮询/IP哈希）
    traefik.ingress.kubernetes.io/service.sticky.cookie: "true"

二、监控 / 可观测性插件

这类插件通过注解动态控制监控采集规则，无需修改监控服务器配置。

1. Prometheus（监控采集）

通过注解动态决定是否采集 Pod/Deployment 的指标、采集端口 / 路径等：

yaml

apiVersion: apps/v1
kind: Deployment
metadata:
  name: app-deploy
  annotations:
    # 动态开启指标采集（核心开关）
    prometheus.io/scrape: "true"
    # 动态指定采集端口
    prometheus.io/port: "8080"
    # 动态指定采集路径
    prometheus.io/path: "/metrics"
    # 动态添加采集标签（用于分类）
    prometheus.io/label: "app=myapp"

2. Grafana Agent（轻量级监控采集）

类似 Prometheus，通过注解动态配置采集规则：

yaml

annotations:
  # 动态开启采集
  grafana.com/scrape: "true"
  # 动态指定采集间隔
  grafana.com/scrape-interval: "15s"

三、服务网格插件

以 Istio 为代表，通过注解动态配置流量治理规则。

Istio（服务网格）

通过注解动态控制流量路由、熔断、重试、镜像等：

yaml

apiVersion: v1
kind: Service
metadata:
  name: app-service
  annotations:
    # 动态开启流量镜像（把10%流量镜像到测试服务）
    traffic.sidecar.istio.io/mirror: "app-service-test"
    traffic.sidecar.istio.io/mirror-percent: "10"
    # 动态配置重试策略（最多重试3次，间隔2秒）
    retries.istio.io/attempts: "3"
    retries.istio.io/perTryTimeout: "2s"
    # 动态关闭Sidecar注入（针对特定服务）
    sidecar.istio.io/inject: "false"

四、调度 / 资源管理插件

这类插件通过注解动态调整 Pod 调度、资源限制等规则。

1. Kubernetes Descheduler（重新调度插件）

通过注解动态标记 Pod 是否允许被重新调度：

yaml

apiVersion: v1
kind: Pod
metadata:
  annotations:
    # 动态禁止Descheduler删除该Pod
    descheduler.alpha.kubernetes.io/evict: "false"

2. Vertical Pod Autoscaler (VPA)（垂直扩缩容）

通过注解动态调整 VPA 策略：

yaml

annotations:
  # 动态设置VPA更新策略（立即更新/重启时更新）
  vpa-update-policy: "immediate"
  # 动态忽略某些容器的资源调整
  vpa.exclude-containers: "sidecar"

五、备份 / 存储插件

Velero（K8s 备份工具）

通过注解动态控制备份策略：

yaml

apiVersion: apps/v1
kind: Deployment
metadata:
  name: app-deploy
  annotations:
    # 动态排除该资源不参与备份
    velero.io/exclude-from-backup: "true"
    # 动态指定备份时的标签
    velero.io/backup-label: "env=prod"

六、安全 / 权限插件

PodSecurityPolicy（PSP，已被 PodSecurityContext 替代）

旧版本中通过注解动态控制 Pod 安全策略：

yaml

annotations:
  # 动态指定Pod使用的安全策略
  podsecuritypolicy.kubernetes.io/enforce: "restricted"

核心使用原则

1. 注解前缀：每个插件的注解都有固定前缀（如 nginx.ingress.kubernetes.io/、prometheus.io/），避免冲突；
2. 动态生效：多数插件会监听注解变化，修改注解后无需重启插件，配置即可动态生效；
3. 优先级：注解配置 > 插件全局配置，可实现 “全局默认 + 资源自定义” 的灵活策略。

总结

1. annotations 传递参数的核心是：把参数以键值对形式写在 metadata.annotations 中，键名建议加自定义前缀（如 ops/）避免冲突；
2. 读取参数的方式：通过 kubectl jsonpath 或 K8s API 获取注解值，脚本 / 控制器解析后使用；
3. 适用场景：传递运维配置、自定义规则、第三方工具参数等，无需修改资源核心配置即可扩展逻辑。