Kubernetes Ingress Annotations 是与特定 Ingress 控制器（如 Nginx、Traefik、HAProxy 等）配合使用，用于扩展和定制 Ingress 资源行为的关键配置项。它们通常以键值对的形式添加在 Ingress 资源的 metadata部分。
Ingress Annotations参数速查表
下面我用一个表格汇总常见的、主要用于 Nginx Ingress 控制器 的 Annotations，并按其功能分类，方便你快速查阅：
功能分类 |
注解名称 (Annotation) |
类型 |
说明与示例值 |
路由与路径 |
|
URI |
重写请求路径。例: |
|
string |
将根路径重定向。例: 访问 |
|
|
bool |
启用正则表达式匹配路径。例: |
|
SSL/TLS |
|
bool |
将HTTP请求重定向到HTTPS (需配置TLS)。例: |
|
bool |
强制所有HTTP重定向到HTTPS (即使未配置TLS)。例: |
|
|
bool |
SSL流量直接透传到后端。例: |
|
认证与安全 |
|
string |
认证类型。例: |
|
string |
包含认证凭据的Secret。例: |
|
|
string |
认证域提示信息。例: |
|
|
string |
外部认证服务URL。例: |
|
|
string |
IP白名单。例: |
|
流量控制 |
|
number |
限制每秒请求数。例: |
|
number |
限制单个IP的并发连接数。例: |
|
|
string |
请求体最大大小。例: |
|
|
number |
与上游服务器连接超时时间(秒)。例: |
|
|
number |
读取上游响应的超时时间(秒)。例: |
|
会话保持 |
|
string |
启用会话保持。例: |
|
string |
自定义会话Cookie名称。例: |
|
|
string |
会话保持模式。例: |
|
Canary发布 |
|
bool |
启用金丝雀发布。例: |
|
number |
流量权重 (0-100)。例: |
|
|
string |
基于请求头路由。例: |
|
|
string |
指定请求头的值。例: |
|
|
string |
基于Cookie路由。例: |
|
CORS |
|
bool |
启用跨域资源共享(CORS)。例: |
|
string |
允许的跨域来源。例: |
|
|
string |
允许的HTTP方法。例: |
|
|
string |
允许的请求头。例: |
|
后端协议 |
|
string |
指定与后端服务通信的协议。例: |
自定义配置 |
|
string |
在Nginx的server块中插入自定义配置 |
|
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（持久）模式 。