Kubernetes Ingress Annotations 是与特定 Ingress 控制器（如 Nginx、Traefik、HAProxy 等）配合使用，用于扩展和定制 Ingress 资源行为的关键配置项。它们通常以键值对的形式添加在 Ingress 资源的 metadata部分。
Ingress Annotations参数速查表
下面我用一个表格汇总常见的、主要用于 Nginx Ingress 控制器 的 Annotations，并按其功能分类，方便你快速查阅：
|-----------|------------------------------------------------------|--------|--------------------------------------------------|
| 功能分类 | 注解名称 (Annotation) | 类型 | 说明与示例值 |
| 路由与路径 | nginx.ingress.kubernetes.io/rewrite-target | URI | 重写请求路径。例: /old重写为 /new |
| | nginx.ingress.kubernetes.io/app-root | string | 将根路径重定向。例: 访问 /重定向到 /home |
| | nginx.ingress.kubernetes.io/use-regex | bool | 启用正则表达式匹配路径。例: "true" |
| SSL/TLS | nginx.ingress.kubernetes.io/ssl-redirect | bool | 将HTTP请求重定向到HTTPS (需配置TLS)。例: "true" |
| | nginx.ingress.kubernetes.io/force-ssl-redirect | bool | 强制所有HTTP重定向到HTTPS (即使未配置TLS)。例: "true" |
| | nginx.ingress.kubernetes.io/ssl-passthrough | bool | SSL流量直接透传到后端。例: "true" |
| 认证与安全 | nginx.ingress.kubernetes.io/auth-type | string | 认证类型。例: "basic"(基本认证) 或 "digest"(摘要认证) |
| | nginx.ingress.kubernetes.io/auth-secret | string | 包含认证凭据的Secret。例: "namespace/secret-name" |
| | nginx.ingress.kubernetes.io/auth-realm | string | 认证域提示信息。例: "Authentication Required" |
| | nginx.ingress.kubernetes.io/auth-url | string | 外部认证服务URL。例: "http://auth-service/auth" |
| | nginx.ingress.kubernetes.io/whitelist-source-range | string | IP白名单。例: "192.168.0.0/24" |
| 流量控制 | nginx.ingress.kubernetes.io/limit-rps | number | 限制每秒请求数。例: "50" |
| | nginx.ingress.kubernetes.io/limit-connections | number | 限制单个IP的并发连接数。例: "100" |
| | nginx.ingress.kubernetes.io/proxy-body-size | string | 请求体最大大小。例: "20m" |
| | nginx.ingress.kubernetes.io/proxy-connect-timeout | number | 与上游服务器连接超时时间(秒)。例: "30" |
| | nginx.ingress.kubernetes.io/proxy-read-timeout | number | 读取上游响应的超时时间(秒)。例: "60" |
| 会话保持 | nginx.ingress.kubernetes.io/affinity | string | 启用会话保持。例: "cookie"(目前仅支持cookie方式) |
| | nginx.ingress.kubernetes.io/session-cookie-name | string | 自定义会话Cookie名称。例: "MYCOOKIE" |
| | nginx.ingress.kubernetes.io/affinity-mode | string | 会话保持模式。例: "balanced"(均衡) 或 "persistent"(持久) |
| Canary发布 | nginx.ingress.kubernetes.io/canary | bool | 启用金丝雀发布。例: "true" |
| | nginx.ingress.kubernetes.io/canary-weight | number | 流量权重 (0-100)。例: "30"(30%流量到Canary) |
| | nginx.ingress.kubernetes.io/canary-by-header | string | 基于请求头路由。例: "X-Canary" |
| | nginx.ingress.kubernetes.io/canary-by-header-value | string | 指定请求头的值。例: "enable" |
| | nginx.ingress.kubernetes.io/canary-by-cookie | string | 基于Cookie路由。例: "canary"(Cookie存在即路由到Canary) |
| CORS | nginx.ingress.kubernetes.io/enable-cors | bool | 启用跨域资源共享(CORS)。例: "true" |
| | nginx.ingress.kubernetes.io/cors-allow-origin | string | 允许的跨域来源。例: "*"或 "https://example.com" |
| | nginx.ingress.kubernetes.io/cors-allow-methods | string | 允许的HTTP方法。例: "GET, PUT, POST" |
| | nginx.ingress.kubernetes.io/cors-allow-headers | string | 允许的请求头。例: "DNT,User-Agent,X-Requested-With" |
| 后端协议 | nginx.ingress.kubernetes.io/backend-protocol | string | 指定与后端服务通信的协议。例: "HTTPS"、"GRPC"、"GRPCS" |
| 自定义配置 | nginx.ingress.kubernetes.io/server-snippet | string | 在Nginx的server块中插入自定义配置 |
| | nginx.ingress.kubernetes.io/configuration-snippet | string | 在Nginx的location块中插入自定义配置 |
使用注意事项
-
注解值格式 ：所有注解的键和值都必须是字符串。布尔值（如 true/false）或数字（如权重、超时时间）必须用引号包裹（例如
"true"、"100"）。 -
控制器特异性 ：绝大多数注解都依赖于特定的 Ingress 控制器（如 Nginx、Traefik、HAProxy），不同控制器的注解前缀和名称可能不同（例如 Nginx 使用
nginx.ingress.kubernetes.io/，Traefik 使用traefik.ingress.kubernetes.io/，AWS ALB 使用alb.ingress.kubernetes.io/）。使用时请确认你的集群使用的控制器类型，并查阅其官方文档 。 -
金丝雀发布优先级：当同时配置多种金丝雀规则（如按头、按Cookie、按权重）时，优先级通常为：请求头 > Cookie > 权重。
-
会话保持 ：基于 Cookie 的会话保持是目前常见的方式，可通过
affinity-mode选择balanced（均衡）或persistent（持久）模式 。