K8s Ingress Annotations参数使用指南
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（持久）模式 。