容器服务 Nginx ingress 提供了与社区完全兼容的注解（Annotation），能够实现更丰富的七层负载均衡能力和更多样的服务路由规则。本文介绍容器服务 Nginx ingress 中常用注解的含义和使用方法。
注意
| 注解 | 说明 |
|---|---|
| nginx.ingress.kubernetes.io/canary | 启用灰度发布功能。配置为true时，表示启用该功能。 |
| nginx.ingress.kubernetes.io/canary-by-header | 基于 Header 实现灰度发布，将请求流量分配到灰度服务入口。 |
| nginx.ingress.kubernetes.io/canary-by-header-value | 当请求中的 Header 值与该配置匹配时，请求流量会被分配到灰度服务入口。 |
| nginx.ingress.kubernetes.io/canary-by-header-pattern | 基于请求中的 Header 值进行流量切分，支持正则匹配。 |
| nginx.ingress.kubernetes.io/canary-by-cookie | 基于 Cookie 实现灰度发布，将请求流量分配到灰度服务入口。 |
| nginx.ingress.kubernetes.io/canary-weight | 基于权重实现灰度发布，流量会根据权重占比随机路由到灰度服务入口。 |
| nginx.ingress.kubernetes.io/canary-weight-total | 配置基于权重切分流量时的权重总和。 |
说明
灰度发布相关注解的详细使用方式，请参见 使用 Nginx Ingress 实现灰度发布和蓝绿发布。
| 注解 | 说明 |
|---|---|
当客户端的 HTTPS 被外部集群进行 SSL 卸载（SSL offloading）时，是否仍将 HTTP 的请求强制跳转到 HTTPS 端口。取值：
| |
是否将 www.domain.com 重定向到 domain.com，取值：
| |
| nginx.ingress.kubernetes.io/permanent-redirect | 配置永久重定向的目标地址。 |
| nginx.ingress.kubernetes.io/permanent-redirect-code | 配置永久重定向的响应码。 |
| nginx.ingress.kubernetes.io/temporal-redirect | 配置临时重定向的目标地址。 |
使用 ssl-redirect 时，是否保留 URI 的尾斜杠。取值：
| |
| nginx.ingress.kubernetes.io/proxy-redirect-from | 配置要替换的源文本，同 Nginx proxy_redirect命令 的第一个参数。 |
| nginx.ingress.kubernetes.io/proxy-redirect-to | 配置要替换的目标文本，同 Nginx proxy_redirect 命令的第二个参数。 |
配置是否开启 HTTP 重定向，即当收到 HTTP 的请求时，强制重定向到 HTTPS 端口。
说明 当 Ingress 上有证书时，默认为 true。即开启 HTTP 重定向。 |
说明
重定向相关注解的详细使用方式，请参见 Nginx Ingress 配置重定向规则。
| 注解 | 说明 |
|---|---|
| nginx.ingress.kubernetes.io/mirror-target | 配置镜像后端的地址。 |
| nginx.ingress.kubernetes.io/mirror-host | 默认情况下，流量复制请求的 Host 头会被设置成和mirror-target配置保持一致。可以通过该字段覆写 Host 头的内容。 |
| nginx.ingress.kubernetes.io/mirror-request-body | 请求体默认会发送给镜像后端，配置该字段为off时，禁止将请求体发送给镜像后端。 |
说明
流量复制相关注解的详细使用方式，请参见 Nginx Ingress 配置流量复制。
| 注解 | 说明 |
|---|---|
| nginx.ingress.kubernetes.io/backend-protocol | 指定后端服务使用的协议，支持 HTTP（默认值）、HTTP2、HTTPS、GRPC 和 GRPCS。 |
| nginx.ingress.kubernetes.io/default-backend | 配置默认后端资源对象的 Service 名称。 |
说明
后端服务相关注解的详细使用方式，请参见 Nginx Ingress 使用 HTTPS 对接后端服务。
在某些场景中，后端服务中公开的 URL 与 Ingress 规则中指定的路径不同。如果没有重写，任何请求都将返回 404。
| 注解 | 说明 |
|---|---|
| nginx.ingress.kubernetes.io/rewrite-target | 配置 URL 重写规则。 |
| nginx.ingress.kubernetes.io/app-root | 配置应用重定向的根目录。 |
说明
URL 重写相关注解的详细使用方式，请参见 Nginx Ingress 配置 URL 重写规则。
支持通过在 Ingress 规则中添加附加注释来添加身份验证。
| 注解 | 说明 |
|---|---|
| nginx.ingress.kubernetes.io/auth-type | 配置身份认证类型，支持basic和digest。 |
| nginx.ingress.kubernetes.io/auth-secret | 配置身份认证使用的 Secret 名称。 |
配置身份认证的 Secret 内容格式，支持如下 2 种格式：
| |
| nginx.ingress.kubernetes.io/auth-realm | 配置身份认证的提示信息。 |
| 注解 | 说明 |
|---|---|
| nginx.ingress.kubernetes.io/auth-url | 配置外部认证服务的 URL。 |
| nginx.ingress.kubernetes.io/auth-keepalive | 配置外部认证 URL 链接的最大保持时间。 |
是否在当前请求和外部认证请求之间共享 Nginx 变量。
| |
| nginx.ingress.kubernetes.io/auth-keepalive-requests | 配置外部认证的一次连接中，允许处理的请求数。 |
| nginx.ingress.kubernetes.io/auth-keepalive-timeout | 配置外部认证 URL 链接的超时时间。 |
| nginx.ingress.kubernetes.io/auth-proxy-set-headers | 配置要传递给认证服务请求头的 Configmap 名称。 |
| nginx.ingress.kubernetes.io/auth-cache-key | 开启认证缓存，并设置认证缓存的关键字。 |
| nginx.ingress.kubernetes.io/auth-cache-duration | 根据响应码设置认证缓存的有效时间。 |
| nginx.ingress.kubernetes.io/auth-snippet | 配置用于外部认证的自定义代码段。 |
配置是否开启 GlobalExternalAuth，取值：
|
| 注解 | 说明 |
|---|---|
| nginx.ingress.kubernetes.io/affinity | 配置会话亲和性类型，仅支持设置为cookie。 |
配置会话亲和性模式，取值：
| |
配置蓝绿发布的会话亲和策略，取值：
|
| 注解 | 说明 |
|---|---|
| nginx.ingress.kubernetes.io/auth-tls-secret | 配置客户端认证的 Secret 名称。该 Secret 中必须包含一个名为 ca.crt 的文件，可对此 Ingress 进行身份验证。 |
| nginx.ingress.kubernetes.io/auth-tls-verify-depth | 配置客户端证书链的验证深度，默认为 1。 |
| nginx.ingress.kubernetes.io/auth-tls-verify-client | 启用客户端证书校验。 |
| nginx.ingress.kubernetes.io/auth-tls-error-page | 配置客户端证书验证错误时的跳转页面。 |
nginx.ingress.kubernetes.io/auth-tls-pass-certificate-to-upstream | 配置是否将证书传递到上游服务器。取值：
|
| nginx.ingress.kubernetes.io/auth-tls-match-cn | 为使用CN=前缀的请求的客户端证书的 CN 添加健全性检查。 |
| 注解 | 说明 |
|---|---|
| nginx.ingress.kubernetes.io/proxy-ssl-secret | 配置后端认证的 Secret 名称。该 Secret 中必须包含一个名为 ca.crt 的文件，用于验证代理服务器的证书。 |
启用或禁用验证代理服务器证书，取值：
| |
| nginx.ingress.kubernetes.io/proxy-ssl-verify-depth | 配置代理服务器证书链的验证深度，默认为 1。 |
| nginx.ingress.kubernetes.io/proxy-ssl-ciphers | 配置发送到代理服务器的请求使用的加密算法。该加密算法需要能被 OpenSSL 识别。 |
| nginx.ingress.kubernetes.io/proxy-ssl-name | 覆盖用于验证代理服务器证书的服务器名称。当与代理服务器建立连接时，该值会通过 SNI 传递。 |
| nginx.ingress.kubernetes.io/proxy-ssl-protocols | 配置发给代理服务器的请求使用指定协议。 |
| nginx.ingress.kubernetes.io/proxy-ssl-server-name | 与代理的 HTTPS 服务器建立连接时，允许通过 TLS 服务器的 SNI（名称指示扩展）传递服务器名称。 |
| 注解 | 说明 |
|---|---|
是否启用跨域访问，取值：
| |
| nginx.ingress.kubernetes.io/cors-allow-origin | 配置允许跨域访问的域名。 |
| nginx.ingress.kubernetes.io/cors-allow-methods | 配置允许跨域访问的方法。 |
| nginx.ingress.kubernetes.io/cors-allow-headers | 配置允许跨域访问的请求头。 |
| nginx.ingress.kubernetes.io/cors-expose-headers | 配置允许暴露给浏览器响应的 Header。 |
是否允许客户端携带验证信息，取值：
| |
| nginx.ingress.kubernetes.io/cors-max-age | 配置返回结果缓存的最长时间。 |
| 注解 | 说明 |
|---|---|
| nginx.ingress.kubernetes.io/proxy-connect-timeout | 配置将请求发送至 Upstream server 的超时时间。 |
| nginx.ingress.kubernetes.io/proxy-send-timeout | 配置两次写操作的最大间隔时长。 |
| nginx.ingress.kubernetes.io/proxy-read-timeout | 配置在连接断开之前，两次从 Upstream server 接收读操作的超时时间。 |
| nginx.ingress.kubernetes.io/proxy-next-upstream | 配置重试策略或者重试条件。 |
| nginx.ingress.kubernetes.io/proxy-next-upstream-timeout | 配置允许将连接传递到下一个服务器的超时时间。 |
| nginx.ingress.kubernetes.io/proxy-next-upstream-tries | 请求的最大重试次数。 |
配置是否启用请求缓冲功能，取值：
|
| 注解 | 说明 |
|---|---|
| nginx.ingress.kubernetes.io/global-rate-limit | 配置一个窗口允许的最大请求数。 |
| nginx.ingress.kubernetes.io/global-rate-limit-window | 配置窗口的持续时间。 |
| nginx.ingress.kubernetes.io/global-rate-limit-key | 配置用于计数的键。 |
| nginx.ingress.kubernetes.io/global-rate-limit-ignored-cidrs | 配置不限速的 IP 列表和 CIDR 列表，不同的 IP 和 CIDR 用逗号分隔。 |
| 注解 | 说明 |
|---|---|
| nginx.ingress.kubernetes.io/client-body-buffer-size | 每个 location 读取客户端请求体的缓存大小。 |
| nginx.ingress.kubernetes.io/configuration-snippet | 在 location 指令域添加 Nginx 配置指令。 |
| nginx.ingress.kubernetes.io/custom-http-errors | 根据响应码设置为错误状态，只针对当前 Ingress 关联的 location。 |
| nginx.ingress.kubernetes.io/disable-proxy-intercept-errors | 当配置了custom-http-errors时，可以使用该注解禁用 Nginx 的 proxy-intercept-errors，但仅适用于与此 Ingress 关联的 Nginx 的 location。 |
配置是否 Nginx 可以自动把 Link 头中指定的预加载链接推送给客户端。取值：
| |
| nginx.ingress.kubernetes.io/limit-connections | 配置单个 IP 地址的并发连接数限制。 |
| nginx.ingress.kubernetes.io/limit-rps | 配置单个 IP 地址每秒请求频率限制。 |
| nginx.ingress.kubernetes.io/proxy-body-size | 配置 Nginx 中的请求体最大限制。如果客户端请求体的大小超过了最大限制，Nginx 会返回413错误码。 |
| nginx.ingress.kubernetes.io/proxy-cookie-domain | 将 Upstream server 通过 Set-Cookie 字段设定的 Domain 属性修改为指定的值。 |
| nginx.ingress.kubernetes.io/proxy-cookie-path | 配置在代理服务器响应的 Set-Cookie 字段。 |
| nginx.ingress.kubernetes.io/proxy-http-version | 配置 Nginx 反向代理与后端通信的 HTTP 协议版本，取值为1.0或1.1。 |
是否启用重写日志，取值：
| |
| nginx.ingress.kubernetes.io/satisfy | 默认情况下，请求需要满足所有身份验证要求才能被允许。使用该注解允许满足任何或所有身份验证要求的请求。 |
| nginx.ingress.kubernetes.io/server-alias | 在 Nginx 配置的服务器定义中设置一个或多个别名。 |
| nginx.ingress.kubernetes.io/server-snippet | 扩展配置到 Server 模块。 |
配置 Upstream 成员列表。取值：
| |
| nginx.ingress.kubernetes.io/session-cookie-name | 配置 Cookie 名称。 |
| nginx.ingress.kubernetes.io/session-cookie-path | 配置 Cookie 字段 Path 的值。 |
| nginx.ingress.kubernetes.io/session-cookie-domain | 配置 Cookie 的 Domain 属性。 |
nginx.ingress.kubernetes.io/session-cookie-change-on-failure | 当会话保持的被代理服务器请求失败时，下次请求是否更改为向另一台被代理服务器转发。
|
| nginx.ingress.kubernetes.io/session-cookie-samesite | 配置 Samesite 属性到 Cookie 上。 |
| nginx.ingress.kubernetes.io/session-cookie-conditional-samesite-none | 配置在不兼容SameSite=None的浏览器中忽略SameSite=None属性。 |
配置 Controller 是否将 TLS 链接直接发发送到后端，取值：
| |
| nginx.ingress.kubernetes.io/stream-snippet | 添加自定义的流配置到 Server 块。 |
| nginx.ingress.kubernetes.io/upstream-hash-by | 用于一致散列的 Nginx 变量、文本值或其任何组合。 |
| nginx.ingress.kubernetes.io/x-forwarded-prefix | 用字符串值将非标准的 X-Forwarded-Prefix 标头添加到上游请求中。 |
| nginx.ingress.kubernetes.io/load-balance | 配置后端服务的负载均衡算法。取值为：（默认值）round_robin 和 ewma。 |
| nginx.ingress.kubernetes.io/upstream-vhost | 允许修改语句proxy_set_header Host $host中的 host 值。 |
| nginx.ingress.kubernetes.io/denylist-source-range | 配置路由 IP 黑名单，支持 IP 地址或 CIDR 地址块，以逗号分隔。 |
| nginx.ingress.kubernetes.io/whitelist-source-range | 配置路由 IP 白名单，支持 IP 地址或 CIDR 地址块，以逗号分隔。 |
配置是否开启代理缓冲，取值：
| |
| nginx.ingress.kubernetes.io/proxy-buffers-number | 配置从代理服务器中读取响应的缓冲区的数量。默认为 4。 |
| nginx.ingress.kubernetes.io/proxy-buffer-size | 配置从代理服务器中读取响应的缓冲的大小。默认为4k。 |
| nginx.ingress.kubernetes.io/proxy-max-temp-file-size | 配置临时缓冲区大小。当从代理服务器读取响应的缓冲区时，如果完整的响应数据量大于缓冲区大小，一部分响应数据可以保存在临时缓冲区里。 |
| nginx.ingress.kubernetes.io/ssl-ciphers | 配置 TLS 用于协商使用的加密算法组合。 |
配置使用 SSLv3 和 TLS 协议时，服务器加密算法是否优先于客户端加密算法。取值：
| |
| nginx.ingress.kubernetes.io/connection-proxy-header | 配置覆盖 Nginx 的默认链接头。 |
配置是否开启访问日志，取值：
| |
配置是否开启 opentracing，取值：
| |
配置是否信任 trace spans，取值：
| |
配置是否开启 Opentelemetry，取值：
| |
nginx.ingress.kubernetes.io/opentelemetry-trust-incoming-span | 配置是否信任 Opentelemetry 的 trace spans，取值：
|
配置是否使用正则表达式形式的路径，取值：
| |
是否开启 ModSecurity，取值：
| |
配置是否开启 OWASP Core Rule Set，取值：
| |
| nginx.ingress.kubernetes.io/modsecurity-transaction-id | 配置从 Nginx 传递事务 ID，而不是在库中自动生成。 |
| nginx.ingress.kubernetes.io/modsecurity-snippet | 配置自定义 ModSecurity 规则。 |