注解

你可以为特定的 Ingress 对象添加这些 Kubernetes 注解来自定义其行为。

提示
注解的键和值只能是字符串类型。其他类型（如布尔值或数值）必须加上引号，例如 "true"、"false"、"100"。

注解前缀可以通过 --annotations-prefix 命令行参数 修改，但默认值为 nginx.ingress.kubernetes.io，如下表所示。

Canary

在某些情况下，你可能希望通过将少量请求发送到与生产服务不同的服务来“金丝雀”测试一组新变更。金丝雀注解使 Ingress 规范能够根据应用的规则作为替代服务路由请求。在设置 nginx.ingress.kubernetes.io/canary: "true" 后，可以启用以下配置金丝雀的注解：

• nginx.ingress.kubernetes.io/canary-by-header：用于通知 Ingress 将请求路由到金丝雀 Ingress 中指定的服务的请求头。当请求头设置为 always 时，请求将被路由到金丝雀服务。当请求头设置为 never 时，请求永远不会被路由到金丝雀服务。对于任何其他值，请求头将被忽略，并根据优先级与其他金丝雀规则进行比较。

• nginx.ingress.kubernetes.io/canary-by-header-value：用于匹配通知 Ingress 将请求路由到金丝雀 Ingress 中指定的服务的请求头值。当请求头设置为该值时，请求将被路由到金丝雀服务。对于任何其他请求头值，请求头将被忽略，并根据优先级与其他金丝雀规则进行比较。此注解必须与 nginx.ingress.kubernetes.io/canary-by-header 一起使用。该注解是 nginx.ingress.kubernetes.io/canary-by-header 的扩展，允许自定义请求头值而不是使用硬编码值。如果未定义 nginx.ingress.kubernetes.io/canary-by-header 注解，则此注解无效。

• nginx.ingress.kubernetes.io/canary-by-header-pattern：其工作方式与 canary-by-header-value 相同，只是它使用 PCRE 正则表达式匹配。注意，当设置了 canary-by-header-value 时，此注解将被忽略。当给定的正则表达式在请求处理期间导致错误时，请求将被视为不匹配。

• nginx.ingress.kubernetes.io/canary-by-cookie：用于通知 Ingress 将请求路由到金丝雀 Ingress 中指定的服务的 Cookie。当 Cookie 值设置为 always 时，请求将被路由到金丝雀服务。当 Cookie 值设置为 never 时，请求永远不会被路由到金丝雀服务。对于任何其他值，Cookie 将被忽略，并根据优先级与其他金丝雀规则进行比较。

• nginx.ingress.kubernetes.io/canary-weight：基于整数（0 - ）的随机请求百分比，应路由到金丝雀 Ingress 中指定的服务。权重为 0 表示不会通过此金丝雀规则将任何请求发送到金丝雀 Ingress 中的服务。权重为 <weight-total> 表示所有请求都将发送到 Ingress 中指定的替代服务。<weight-total> 默认为 100，可以通过 nginx.ingress.kubernetes.io/canary-weight-total 增加。

• nginx.ingress.kubernetes.io/canary-weight-total：流量的总权重。如果未指定，则默认为 100。

金丝雀规则按优先级顺序评估。优先级如下：canary-by-header -> canary-by-cookie -> canary-weight

注意，当你将一个 Ingress 标记为金丝雀时，所有其他非金丝雀注解将被忽略（从相应的主 Ingress 继承），除了 nginx.ingress.kubernetes.io/load-balance、nginx.ingress.kubernetes.io/upstream-hash-by 和 与会话亲和性相关的注解。如果你想恢复金丝雀的原始行为（当会话亲和性被忽略时），可以在金丝雀 Ingress 定义上设置值为 legacy 的 nginx.ingress.kubernetes.io/affinity-canary-behavior 注解。

已知限制

目前每个 Ingress 规则最多只能应用一个金丝雀 Ingress。

Rewrite

在某些场景中，后端服务暴露的 URL 与 Ingress 规则中指定的路径不同。如果没有重写，任何请求都将返回 404。将注解 nginx.ingress.kubernetes.io/rewrite-target 设置为服务期望的路径。

如果应用根目录暴露在不同的路径中并需要重定向，设置注解 nginx.ingress.kubernetes.io/app-root 以重定向 / 的请求。

示例
请查看 rewrite 示例。

Session

会话亲和性 (Session Affinity)

注解 nginx.ingress.kubernetes.io/affinity 会在 Ingress 的所有上游中启用并设置亲和性类型。这样，请求将始终被定向到同一个上游服务器。NGINX 唯一可用的亲和性类型是 cookie。

注解 nginx.ingress.kubernetes.io/affinity-mode 定义会话的粘性。设置为 balanced（默认值）会在部署扩展时重新分配部分会话，从而重新平衡服务器上的负载。设置为 persistent 则不会将会话重新平衡到新服务器，从而提供最大的粘性。

注解 nginx.ingress.kubernetes.io/affinity-canary-behavior 定义了启用会话亲和性时金丝雀的行为。设置为 sticky（默认值）会确保由金丝雀服务的用户继续由金丝雀服务。设置为 legacy 会恢复原始的金丝雀行为，即忽略会话亲和性。

注意
如果为一个主机定义了多个 Ingress，并且至少有一个 Ingress 使用了 nginx.ingress.kubernetes.io/affinity: cookie，那么只有使用 nginx.ingress.kubernetes.io/affinity 的 Ingress 上的路径会使用会话 Cookie 亲和性。为该主机定义的其他 Ingress 上的所有路径将通过随机选择后端服务器进行负载均衡。

示例
请查看 affinity 示例。

Cookie 亲和性

如果使用 cookie 亲和性类型，还可以通过注解 nginx.ingress.kubernetes.io/session-cookie-name 指定用于路由请求的 Cookie 名称。默认会创建一个名为 INGRESSCOOKIE 的 Cookie。

NGINX 注解 nginx.ingress.kubernetes.io/session-cookie-path 定义了将在 Cookie 上设置的路径。除非注解 nginx.ingress.kubernetes.io/use-regex 设置为 true，否则此字段是可选的；会话 Cookie 路径不支持正则表达式。

使用 nginx.ingress.kubernetes.io/session-cookie-domain 设置粘性 Cookie 的 Domain 属性。

使用 nginx.ingress.kubernetes.io/session-cookie-samesite 为粘性 Cookie 应用 SameSite 属性。浏览器接受的值为 None、Lax 和 Strict。某些浏览器会拒绝带有 SameSite=None 的 Cookie，包括在 SameSite=None 规范之前创建的 Cookie（例如 Chrome 5X）。其他浏览器错误地将 SameSite=None Cookie 视为 SameSite=Strict（例如运行在 OSX 14 上的 Safari）。为了在这些不兼容的浏览器中省略 SameSite=None，可以添加注解 nginx.ingress.kubernetes.io/session-cookie-conditional-samesite-none: "true"。

使用 nginx.ingress.kubernetes.io/session-cookie-expires 控制 Cookie 的过期时间，其值为 Cookie 过期的秒数。

当 use-regex 设置为 true 时，使用 nginx.ingress.kubernetes.io/session-cookie-path 控制 Cookie 路径。

使用 nginx.ingress.kubernetes.io/session-cookie-change-on-failure 控制请求失败后的 Cookie 变更。

认证 (Authentication)

可以通过在 Ingress 规则中添加额外的注解来添加认证。认证的来源是一个包含用户名和密码的 Secret。

相关注解包括：

nginx.ingress.kubernetes.io/auth-type: [basic|digest]
指示 HTTP 认证类型：Basic 或 Digest 访问认证。

nginx.ingress.kubernetes.io/auth-secret: secretName
包含被授予访问 Ingress 规则中定义的 path 的用户名和密码的 Secret 名称。此注解也接受替代形式 “namespace/secretName”，此时 Secret 查找将在引用的命名空间而不是 Ingress 命名空间中进行。

nginx.ingress.kubernetes.io/auth-secret-type: [auth-file|auth-map]
auth-secret 可以有两种形式： • auth-file - 默认值，Secret 中 auth 键下的 htpasswd 文件 • auth-map - Secret 的键是用户名，值是哈希后的密码

nginx.ingress.kubernetes.io/auth-realm: "realm string"

示例
请查看 auth 示例。

自定义 NGINX 上游哈希 (Custom NGINX Upstream Hashing)

NGINX 支持基于 一致性哈希 的客户端-服务器映射负载均衡。键可以包含文本、变量或其组合。此功能允许除客户端 IP 或 Cookie 之外的请求粘性。将使用 ketama 一致性哈希方法，确保在上游组变更时只有少量键会被重新映射到不同的服务器。

有一种特殊的上游哈希模式称为子集（subset）。在此模式下，上游服务器被分组为子集，粘性通过将键映射到子集而不是单个上游服务器来实现。从选定的粘性子集中均匀随机选择特定服务器。它在粘性和负载分配之间提供了平衡。

要为后端启用一致性哈希：

nginx.ingress.kubernetes.io/upstream-hash-by：用于一致性哈希的 NGINX 变量、文本值或其组合。例如：nginx.ingress.kubernetes.io/upstream-hash-by: "$request_uri" 或 nginx.ingress.kubernetes.io/upstream-hash-by: "$request_uri$host" 或 nginx.ingress.kubernetes.io/upstream-hash-by: "${request_uri}-text-value" 以当前请求 URI 一致哈希上游请求。

可以通过设置 nginx.ingress.kubernetes.io/upstream-hash-by-subset: "true" 启用 “子集” 哈希。这将请求映射到节点子集而不是单个节点。nginx.ingress.kubernetes.io/upstream-hash-by-subset-size 确定每个子集的大小（默认为 3）。

请查看 chashsubset 示例。

自定义 NGINX 负载均衡 (Custom NGINX Load Balancing)

这与 ConfigMap 中的 load-balance 类似，但按 Ingress 配置负载均衡算法。

注意，nginx.ingress.kubernetes.io/upstream-hash-by 优先于此设置。如果未设置此注解和 nginx.ingress.kubernetes.io/upstream-hash-by，则回退到全局配置的负载均衡算法。

自定义 NGINX 上游虚拟主机 (Custom NGINX Upstream Vhost)

此配置设置允许你控制以下语句中的主机值：proxy_set_header Host $host，这是 location 块的一部分。如果你需要通过不同于 $host 的方式调用上游服务器，这将非常有用。

客户端证书认证 (Client Certificate Authentication)

可以通过在 Ingress 规则中添加额外的注解来启用客户端证书认证。

客户端证书认证按主机应用，无法为单个路径指定不同的规则。

要启用，添加注解 nginx.ingress.kubernetes.io/auth-tls-secret: namespace/secretName。此 Secret 必须包含名为 ca.crt 的文件，其中包含用于对此 Ingress 进行认证的完整证书颁发机构链 ca.crt。

你可以通过以下注解进一步自定义客户端证书认证和行为：

• nginx.ingress.kubernetes.io/auth-tls-verify-depth：提供的客户端证书与证书颁发机构链之间的验证深度。（默认：1） • nginx.ingress.kubernetes.io/auth-tls-verify-client：启用客户端证书验证。可能的值包括： • on：请求一个客户端证书，该证书必须由包含在 nginx.ingress.kubernetes.io/auth-tls-secret: namespace/secretName 指定的 Secret 的 ca.crt 键中的证书签名。证书验证失败将导致状态码 400（Bad Request）（默认值）。 • off：不请求客户端证书，也不进行客户端证书验证。 • optional：对来自 auth-tls-secret 的 CA 进行可选的客户端证书验证。当提供的证书未被 CA 签名时，请求将失败并返回状态码 400（Bad Request）。当未提供证书或提供其他无效证书时，请求不会失败，但验证结果会发送到上游服务。 • optional_no_ca：进行可选的客户端证书验证，但当客户端证书未被 auth-tls-secret 中的 CA 签名时不使请求失败。证书验证结果会发送到上游服务。 • nginx.ingress.kubernetes.io/auth-tls-error-page：在证书认证错误时应将用户重定向到的 URL/页面。 • nginx.ingress.kubernetes.io/auth-tls-pass-certificate-to-upstream：指示是否应将接收到的证书传递到上游服务器的 ssl-client-cert 头中。可能的值是 “true” 或 “false”（默认值）。 • nginx.ingress.kubernetes.io/auth-tls-match-cn：添加对客户端证书 CN 的检查，使用以 “CN=” 开头的字符串/正则表达式，例如 "CN=myvalidclient"。如果在 mTLS 期间发送的证书 CN 与你的字符串/正则表达式不匹配，将返回状态码 403。另一种使用方式是在正则表达式中添加多个选项，例如 "CN=(option1|option2|myvalidclient)"。在这种情况下，只要括号中的选项之一与证书 CN 匹配，你将收到 200 状态码。

根据 auth-tls-* 注解，以下头信息会被发送到上游服务：

• ssl-client-issuer-dn：客户端证书的颁发者信息。例如：”CN=My CA” • ssl-client-subject-dn：客户端证书的主题信息。例如：”CN=My Client” • ssl-client-verify：客户端验证的结果。可能的值：”SUCCESS”, “FAILED: “ • ssl-client-cert：PEM 格式的完整客户端证书。仅当 nginx.ingress.kubernetes.io/auth-tls-pass-certificate-to-upstream 设置为 “true” 时发送。例如：-----BEGIN%20CERTIFICATE-----%0A...---END%20CERTIFICATE-----%0A

示例
请查看 client-certs 示例。

注意
在 Cloudflare 中无法使用带有客户端认证的 TLS，并可能导致意外行为。

Cloudflare 仅允许认证的源拉取（Authenticated Origin Pulls），并且需要使用他们自己的证书：https://blog.cloudflare.com/protecting-the-origin-with-tls-authenticated-origin-pulls/

仅允许认证的源拉取，可以通过以下教程配置：https://support.cloudflare.com/hc/en-us/articles/204494148-Setting-up-NGINX-to-use-TLS-Authenticated-Origin-Pulls

后端证书认证 (Backend Certificate Authentication)

可以通过在 Ingress 规则中添加额外的注解，使用证书对代理的 HTTPS 后端进行认证。

• nginx.ingress.kubernetes.io/proxy-ssl-secret: secretName：指定一个 Secret，其中包含用于对代理的 HTTPS 服务器进行认证的证书 tls.crt、密钥 tls.key（PEM 格式）。它还应该包含受信任的 CA 证书 ca.crt（PEM 格式），用于验证代理的 HTTPS 服务器的证书。此注解期望 Secret 名称的形式为 “namespace/secretName”。 • nginx.ingress.kubernetes.io/proxy-ssl-verify：启用或禁用对代理的 HTTPS 服务器证书的验证。（默认：off） • nginx.ingress.kubernetes.io/proxy-ssl-verify-depth：设置代理的 HTTPS 服务器证书链中的验证深度。（默认：1） • nginx.ingress.kubernetes.io/proxy-ssl-ciphers：指定对代理的 HTTPS 服务器请求启用的 密码。密码以 OpenSSL 库理解的格式指定。 • nginx.ingress.kubernetes.io/proxy-ssl-name：允许设置 proxy_ssl_name。这允许覆盖用于验证代理的 HTTPS 服务器证书的服务器名称。此值还会在建立与代理的 HTTPS 服务器的连接时通过 SNI 传递。 • nginx.ingress.kubernetes.io/proxy-ssl-protocols：启用对代理的 HTTPS 服务器请求的指定 协议。 • nginx.ingress.kubernetes.io/proxy-ssl-server-name：启用通过 TLS 服务器名称指示扩展（SNI，RFC 6066）传递服务器名称，以建立与代理的 HTTPS 服务器的连接。

配置片段 (Configuration Snippet)

使用此注解，你可以向 NGINX location 添加额外的配置。例如：

nginx.ingress.kubernetes.io/configuration-snippet: |
  more_set_headers "Request-Id: $req_id";

请注意，这在多租户集群中可能是危险的，因为它可能导致权限受限的人能够检索集群上的所有 Secret。建议的缓解措施是禁用此功能，因此它可能对你无效。有关更多信息，请参阅 CVE-2021-25742 和 GitHub 上的相关问题。

自定义 HTTP 错误 (Custom HTTP Errors)

与 ConfigMap 中的 custom-http-errors 值类似，此注解将为与此 Ingress 关联的 NGINX location 设置 NGINX proxy-intercept-errors。如果在 Ingress 上指定了 default backend 注解，错误将被路由到该注解的默认后端服务（而不是全局默认后端）。不同的 Ingress 可以指定不同的错误代码集。即使多个 Ingress 对象共享相同的主机名，此注解也可以用于为每个 Ingress 拦截不同的错误代码（例如，如果同一主机名上的不同路径位于不同的 Ingress 上，则可以拦截不同的错误代码）。如果还全局指定了 custom-http-errors，则此注解中指定的错误值将覆盖给定 Ingress 主机名和路径的全局值。

示例用法：

nginx.ingress.kubernetes.io/custom-http-errors: "404,415"

自定义头信息 (Custom Headers)

此注解的形式为 nginx.ingress.kubernetes.io/custom-headers: <namespace>/<custom headers configmap>，用于指定包含自定义头信息的命名空间和 ConfigMap 名称。此注解使用 more_set_headers NGINX 指令。

以下示例注解对应的 ConfigMap 示例：

nginx.ingress.kubernetes.io/custom-headers: default/custom-headers-configmap

示例 ConfigMap：

apiVersion: v1
data:
  Content-Type: application/json
kind: ConfigMap
metadata:
  name: custom-headers-configmap
  namespace: default

注意
首先在 global-allowed-response-headers 中定义允许的响应头。

默认后端 (Default Backend)

此注解的形式为 nginx.ingress.kubernetes.io/default-backend: <svc name>，用于指定自定义的默认后端。<svc name> 是对你应用此注解的同一命名空间中的服务的引用。此注解会覆盖全局默认后端。如果服务有 多个端口，第一个端口将接收后端流量。

当 Ingress 规则中配置的服务没有任何活动端点时，将使用此服务处理响应。如果同时设置了此注解和 custom-http-errors 注解，它还将用于处理错误响应。

启用 CORS (Enable CORS)

要在 Ingress 规则中启用跨源资源共享（CORS），添加注解 nginx.ingress.kubernetes.io/enable-cors: "true"。这将在服务器 location 中添加一个启用此功能的配置部分。

可以通过以下注解控制 CORS：

• nginx.ingress.kubernetes.io/cors-allow-methods：控制接受哪些方法。

这是一个多值字段，用 ‘,’ 分隔，仅接受字母（大小写）。

• 默认值：GET, PUT, POST, DELETE, PATCH, OPTIONS • 示例：nginx.ingress.kubernetes.io/cors-allow-methods: "PUT, GET, POST, OPTIONS"

• nginx.ingress.kubernetes.io/cors-allow-headers：控制接受哪些头信息。

这是一个多值字段，用 ‘,’ 分隔，接受字母、数字、_ 和 -。

• 默认值：DNT,Keep-Alive,User-Agent,X-Requested-With,If-Modified-Since,Cache-Control,Content-Type,Range,Authorization • 示例：nginx.ingress.kubernetes.io/cors-allow-headers: "X-Forwarded-For, X-app123-XPTO"

• nginx.ingress.kubernetes.io/cors-expose-headers：控制哪些头信息暴露给响应。

这是一个多值字段，用 ‘,’ 分隔，接受字母、数字、_、- 和 *。

• 默认值：空 • 示例：nginx.ingress.kubernetes.io/cors-expose-headers: "*, X-CustomResponseHeader"

• nginx.ingress.kubernetes.io/cors-allow-origin：控制 CORS 接受的 Origin。

这是一个多值字段，用 ‘,’ 分隔。必须遵循以下格式：protocol://origin-site.com 或 protocol://origin-site.com:port

• 默认值：*
• 示例：nginx.ingress.kubernetes.io/cors-allow-origin: "https://origin-site.com:4443, http://origin-site.com, myprotocol://example.org:1199"

它还支持单级通配符子域名，格式为：protocol://*.foo.bar、protocol://*.bar.foo:8080 或 protocol://*.abc.bar.foo:9000
示例：nginx.ingress.kubernetes.io/cors-allow-origin: "https://*.origin-site.com:4443, http://*.origin-site.com, myprotocol://example.org:1199"

• nginx.ingress.kubernetes.io/cors-allow-credentials：控制在 CORS 操作期间是否可以传递凭据。
• 默认值：true
• 示例：nginx.ingress.kubernetes.io/cors-allow-credentials: "false"

• nginx.ingress.kubernetes.io/cors-max-age：控制预检请求可以缓存的时间。
• 默认值：1728000
• 示例：nginx.ingress.kubernetes.io/cors-max-age: 600

注意
更多信息请参阅 https://enable-cors.org

HTTP2 推送预加载 (HTTP2 Push Preload)

启用自动将 “Link” 响应头字段中指定的预加载链接转换为推送请求。

示例
• nginx.ingress.kubernetes.io/http2-push-preload: "true"

服务器别名 (Server Alias)

通过注解 nginx.ingress.kubernetes.io/server-alias: "<alias 1>,<alias 2>" 可以在 NGINX 配置的服务器定义中添加一个或多个别名。这将创建一个具有相同配置的服务器，但会向 server_name 指令添加新值。

注意
服务器别名不能与现有服务器的主机名冲突。如果发生冲突，服务器别名注解将被忽略。如果创建了一个服务器别名，之后又创建了一个具有相同主机名的新服务器，新服务器的配置将覆盖别名配置。

更多信息请参阅 server_name 文档。

服务器片段 (Server Snippet)

使用注解 nginx.ingress.kubernetes.io/server-snippet 可以在服务器配置块中添加自定义配置。

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  annotations:
    nginx.ingress.kubernetes.io/server-snippet: |
      set $agentflag 0;
      if ($http_user_agent ~* "(Mobile)" ){
        set $agentflag 1;
      }
      if ( $agentflag = 1 ) {
        return 301 https://m.example.com;
      }

注意
此注解每个主机只能使用一次。

客户端请求体缓冲区大小 (Client Body Buffer Size)

设置用于读取客户端请求体的缓冲区大小（按 location）。如果请求体大于缓冲区，整个请求体或其部分将被写入临时文件。默认情况下，缓冲区大小等于两个内存页。在 x86、其他 32 位平台和 x86-64 上为 8K。在其他 64 位平台上通常为 16K。此注解应用于 Ingress 规则中提供的每个 location。

注意
注解值必须采用 NGINX 理解的格式。

示例
• nginx.ingress.kubernetes.io/client-body-buffer-size: "1000" # 1000 字节
• nginx.ingress.kubernetes.io/client-body-buffer-size: 1k # 1 千字节
• nginx.ingress.kubernetes.io/client-body-buffer-size: 1K # 1 千字节
• nginx.ingress.kubernetes.io/client-body-buffer-size: 1m # 1 兆字节
• nginx.ingress.kubernetes.io/client-body-buffer-size: 1M # 1 兆字节

更多信息请参阅 https://nginx.org

外部认证 (External Authentication)

要使用提供认证的现有服务，可以在 Ingress 规则中添加注解 nginx.ingress.kubernetes.io/auth-url，指示应将 HTTP 请求发送到的 URL。

nginx.ingress.kubernetes.io/auth-url: "URL to the authentication service"

此外，还可以设置：

• nginx.ingress.kubernetes.io/auth-keepalive: <Connections> 指定与 auth-url 的最大保持活动连接数。仅当 URL 的主机部分不使用变量时生效。默认为 0（禁用保持活动）。

注意：由于 Lua 子请求 的限制，不适用于 HTTP/2 监听器。UseHTTP2 配置应禁用！

• nginx.ingress.kubernetes.io/auth-keepalive-share-vars: 是否在当前请求和认证请求之间共享 NGINX 变量。示例用例是跟踪请求：当设置为 “true” 时，后端和认证请求的 X-Request-ID HTTP 头将相同。默认为 “false”。
• nginx.ingress.kubernetes.io/auth-keepalive-requests: <Requests> 指定通过一个保持活动连接可以服务的最大请求数。默认为 1000，仅在 auth-keepalive 设置为大于 0 时应用。
• nginx.ingress.kubernetes.io/auth-keepalive-timeout: <Timeout> 指定空闲保持活动连接保持打开的持续时间（秒）。默认为 60，仅在 auth-keepalive 设置为大于 0 时应用。
• nginx.ingress.kubernetes.io/auth-method: <Method> 指定使用的 HTTP 方法。
• nginx.ingress.kubernetes.io/auth-signin: <SignIn_URL> 指定错误页面的位置。
• nginx.ingress.kubernetes.io/auth-signin-redirect-param: <SignIn_URL> 指定错误页面中应包含失败登录请求原始 URL 的 URL 参数。
• nginx.ingress.kubernetes.io/auth-response-headers: <Response_Header_1, ..., Response_Header_n> 指定认证请求完成后传递给后端的头信息。
• nginx.ingress.kubernetes.io/auth-proxy-set-headers: <ConfigMap> 指定传递给认证服务的头信息的 ConfigMap 名称。
• nginx.ingress.kubernetes.io/auth-request-redirect: <Request_Redirect_URL> 指定 X-Auth-Request-Redirect 头的值。
• nginx.ingress.kubernetes.io/auth-cache-key: <Cache_Key> 启用认证请求的缓存。指定认证响应的查找键。例如 $remote_user$http_authorization。每个服务器和 location 都有自己的键空间。因此，缓存的响应仅在每个服务器和 location 的基础上有效。
• nginx.ingress.kubernetes.io/auth-cache-duration: <Cache_duration> 根据响应代码指定认证响应的缓存时间。例如 200 202 30m。详情请参阅 proxy_cache_valid。可以指定多个逗号分隔的值：200 202 10m, 401 5m。默认为 200 202 401 5m。
• nginx.ingress.kubernetes.io/auth-always-set-cookie: <Boolean_Flag> 设置认证请求返回的 Cookie。默认情况下，仅当上游报告代码为 200、201、204、206、301、302、303、304、307 或 308 时才会设置 Cookie。
• nginx.ingress.kubernetes.io/auth-snippet: <Auth_Snippet> 指定用于外部认证的自定义片段。例如：

nginx.ingress.kubernetes.io/auth-url: http://foo.com/external-auth
nginx.ingress.kubernetes.io/auth-snippet: |
  proxy_set_header Foo-Header 42;

注意：nginx.ingress.kubernetes.io/auth-snippet 是一个可选注解。但是，它只能与 nginx.ingress.kubernetes.io/auth-url 一起使用，如果未设置 nginx.ingress.kubernetes.io/auth-url，它将被忽略。

示例
请查看 external-auth 示例。

全局外部认证 (Global External Authentication)

默认情况下，如果在 Ingress NGINX ConfigMap 中设置了 global-auth-url，控制器会将所有请求重定向到提供认证的现有服务。如果你想禁用该 Ingress 的此行为，可以使用 nginx.ingress.kubernetes.io/enable-global-auth: "false" 注解。

• nginx.ingress.kubernetes.io/enable-global-auth: 指示是否应将 GlobalExternalAuth 配置应用于此 Ingress 规则。默认值为 "true"。

注意
更多信息请参阅 global-auth-url。

速率限制 (Rate Limiting)

这些注解定义了连接和传输速率的限制。可用于缓解 DDoS 攻击。

注意
速率限制按 Ingress NGINX 控制器副本应用。如果你运行多个副本或使用水平 Pod 自动扩缩器（HPA），有效速率限制将乘以副本数。使用 HPA 时，随着副本数基于负载变化，确切的速率限制会变得动态。

• nginx.ingress.kubernetes.io/limit-connections: 每个控制器副本允许来自单个 IP 地址的并发连接数。超过此限制将返回 503 错误。
• nginx.ingress.kubernetes.io/limit-rps: 每个控制器副本每秒接受的来自给定 IP 的请求数。突发限制设置为此限制乘以突发乘数，默认乘数为 5。当客户端超过此限制时，返回 limit-req-status-code 默认值： 503。
• nginx.ingress.kubernetes.io/limit-rpm: 每个控制器副本每分钟接受的来自给定 IP 的请求数。突发限制设置为此限制乘以突发乘数，默认乘数为 5。当客户端超过此限制时，返回 limit-req-status-code 默认值： 503。
• nginx.ingress.kubernetes.io/limit-burst-multiplier: 限制速率的突发大小乘数。默认突发乘数为 5，此注解覆盖默认乘数。当客户端超过此限制时，返回 limit-req-status-code 默认值： 503。
• nginx.ingress.kubernetes.io/limit-rate-after: 初始千字节数，之后对给定连接的响应传输将受到速率限制。此功能必须与 proxy-buffering 一起启用。
• nginx.ingress.kubernetes.io/limit-rate: 允许发送到给定连接的每秒千字节数。零值禁用速率限制。此功能必须与 proxy-buffering 一起启用。
• nginx.ingress.kubernetes.io/limit-whitelist: 排除在速率限制之外的客户端 IP 源范围。值为 CIDR 的逗号分隔列表。

如果在单个 Ingress 规则中指定多个注解，限制将按 limit-connections、limit-rpm、limit-rps 的顺序应用。

要为所有 Ingress 规则全局配置设置，可以在 NGINX ConfigMap 中设置 limit-rate-after 和 limit-rate 值。Ingress 注解中设置的值将覆盖全局设置。

客户端 IP 地址将基于 PROXY 协议 的使用或启用 use-forwarded-headers 时的 X-Forwarded-For 头值设置。

永久重定向 (Permanent Redirect)

此注解允许返回永久重定向（返回码 301）而不是将数据发送到上游。例如 nginx.ingress.kubernetes.io/permanent-redirect: https://www.google.com 会将所有内容重定向到 Google。

永久重定向码 (Permanent Redirect Code)

此注解允许你修改用于永久重定向的状态码。例如 nginx.ingress.kubernetes.io/permanent-redirect-code: '308' 会返回 308 的永久重定向。

临时重定向 (Temporal Redirect)

此注解允许返回临时重定向（返回码 302）而不是将数据发送到上游。例如 nginx.ingress.kubernetes.io/temporal-redirect: https://www.google.com 会将所有内容重定向到 Google，返回码为 302（临时移动）。

临时重定向码 (Temporal Redirect Code)

此注解允许你修改用于临时重定向的状态码。例如 nginx.ingress.kubernetes.io/temporal-redirect-code: '307' 会返回 307 的临时重定向。

SSL 透传 (SSL Passthrough)

注解 nginx.ingress.kubernetes.io/ssl-passthrough 指示控制器将 TLS 连接直接发送到后端，而不是让 NGINX 解密通信。另请参阅用户指南中的 TLS/HTTPS。

注意
默认情况下禁用 SSL 透传，需要启动控制器时使用 --enable-ssl-passthrough 标志。

注意
由于 SSL 透传工作在 OSI 模型的第 4 层（TCP）而不是第 7 层（HTTP），使用 SSL 透传会使 Ingress 对象上设置的所有其他注解无效。

服务上游 (Service Upstream)

默认情况下，Ingress-Nginx 控制器在 NGINX 上游配置中使用所有端点（Pod IP/端口）的列表。

nginx.ingress.kubernetes.io/service-upstream 注解禁用该行为，改为在 NGINX 中使用单个上游，即服务的 Cluster IP 和端口。

这对于零停机部署等场景非常有用。参见问题 #257。

已知问题

如果指定了 service-upstream 注解，应考虑以下事项：

• 粘性会话将不起作用，因为仅支持轮询负载均衡。
• proxy_next_upstream 指令将不起作用，意味着在错误时请求不会分派到另一个上游。

服务器端 HTTPS 强制重定向 (Server-side HTTPS Enforcement Through Redirect)

默认情况下，如果为该 Ingress 启用了 TLS，控制器会重定向（308）到 HTTPS。如果你想全局禁用此行为，可以在 NGINX ConfigMap 中使用 ssl-redirect: "false"。

要为特定的 Ingress 资源配置此功能，可以在特定资源中使用 nginx.ingress.kubernetes.io/ssl-redirect: "false" 注解。

在集群外使用 SSL 卸载（例如 AWS ELB）时，即使没有可用的 TLS 证书，也可能需要强制重定向到 HTTPS。可以通过在特定资源中使用 nginx.ingress.kubernetes.io/force-ssl-redirect: "true" 注解实现。

要在 ssl-redirect 中保留 URI 的尾部斜杠，可以为该特定资源设置 nginx.ingress.kubernetes.io/preserve-trailing-slash: "true" 注解。

从/到 www 重定向 (Redirect From/To www)

在某些场景中，需要从 www.domain.com 重定向到 domain.com 或反之亦然，重定向的方式取决于 Ingress 对象中配置的 host 值。

例如，如果 .spec.rules.host 配置为类似 www.example.com 的值，则此注解将从 example.com 重定向到 www.example.com。如果 .spec.rules.host 配置为类似 example.com 的值（即不带 www），则此注解将从 www.example.com 重定向到 example.com。

要启用此功能，使用注解 nginx.ingress.kubernetes.io/from-to-www-redirect: "true"

注意
如果某个时候创建了一个主机等于其中一个选项（如 domain.com）的新 Ingress，该注解将被忽略。

注意
对于 HTTPS 到 HTTPS 的重定向，TLS 部分中位于 Ingress 的 Secret 中定义的 SSL 证书必须在证书的通用名中包含两个 FQDN。

拒绝列表源范围 (Denylist Source Range)

你可以通过 nginx.ingress.kubernetes.io/denylist-source-range 注解指定被阻止的客户端 IP 源范围。值为 CIDR 的逗号分隔列表，例如 10.0.0.0/24,172.10.0.1。

要为所有 Ingress 规则全局配置此设置，可以在 NGINX ConfigMap 中设置 denylist-source-range 值。

注意
向 Ingress 规则添加注解会覆盖任何全局限制。

允许列表源范围 (Whitelist Source Range)

你可以通过 nginx.ingress.kubernetes.io/whitelist-source-range 注解指定允许的客户端 IP 源范围。值为 CIDR 的逗号分隔列表，例如 `10.0.0.0/