ingress-nginx配置(注解)

编辑这个页面

注解

您可以将这些 Kubernetes 注解（Annotations）添加到特定的 Ingress 对象，以自定义其行为。

提示
注解键和值只能是字符串。其他类型，如布尔值或数值必须被引用，即 "true"、"false"、"100"。

注意
可以使用 --annotations-prefix 命令行参数 更改注解前缀，但默认值为 nginx.ingress.kubernetes.io，如下表所述。

金丝雀发布 (Canary)

在某些情况下，您可能希望通过向少量与生产服务不同的服务发送少量请求来“灰度”一组新的更改。Canary 注解使 Ingress 规范可以充当路由请求的替代服务，具体取决于所应用的规则。设置 nginx.ingress.kubernetes.io/canary: "true" 后，可以启用以下用于配置金丝雀发布的注解：

• nginx.ingress.kubernetes.io/canary-by-header：用于通知 Ingress 将请求路由到 Canary Ingress 中指定的服务的 Header。当请求 Header 设置为 always 时，它将被路由到 Canary。当 Header 设置为 never 时，它将永远不会路由到金丝雀。对于任何其他值，Header 将被忽略，并且按优先级将请求与其他金丝雀规则进行比较。
• nginx.ingress.kubernetes.io/canary-by-header-value：匹配的 Header 值，用于通知 Ingress 将请求路由到 Canary Ingress 中指定的服务。当请求 Header 设置为此值时，它将被路由到 Canary。对于任何其他 Header 值，Header 将被忽略，并按优先级将请求与其他金丝雀规则进行比较。此注解必须与 nginx.ingress.kubernetes.io/canary-by-header 一起使用。该注解是 canary-by-header 的扩展，允许自定义 Header 值，而不使用硬编码值。如果 nginx.ingress.kubernetes.io/canary-by-header 未定义，则此注解没有任何作用。
• nginx.ingress.kubernetes.io/canary-by-header-pattern：这与 canary-by-header-value 相同，但使用 PCRE Regex 匹配。请注意，当 canary-by-header-value 设置时，此注解将被忽略。当给定的正则表达式在请求处理期间导致错误时，该请求将被视为不匹配。
• nginx.ingress.kubernetes.io/canary-by-cookie：用于通知 Ingress 将请求路由到 Canary Ingress 中指定的服务的 Cookie。当 Cookie 值设置为 always 时，它将被路由到 Canary。当 Cookie 设置为 never 时，它将永远不会路由到 Canary。对于任何其他值，将忽略 Cookie，并按优先级将请求与其他 Canary 规则进行比较。
• nginx.ingress.kubernetes.io/canary-weight：随机请求的整数百分比（0-100），应将其路由到 Canary Ingress 中指定的服务。权重 0 表示此 Canary 规则不会在 Canary 入口中将任何请求发送到服务。权重为 100 表示所有请求都将发送到 Ingress 中指定的替代服务。

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

注意
当您将某个入口标记为 Canary 时，除 nginx.ingress.kubernetes.io/load-balance 和 nginx.ingress.kubernetes.io/upstream-hash-by 之外，所有其他非 Canary 注解将被忽略（从相应的主要入口继承）。

已知局限性

目前，每个 Ingress 规则最多可以应用一个 Canary Ingress。

重写 (Rewrite)

在某些情况下，后端服务中公开的 URL 与 Ingress 规则中指定的路径不同。如果没有重写，则任何请求都将返回 404。将注解 nginx.ingress.kubernetes.io/rewrite-target 设置为服务所需的路径。

如果应用程序根目录暴露在其他路径中，并且需要重定向，请设置注解 nginx.ingress.kubernetes.io/app-root 以将请求重定向到 /。

示例

请检查 重写示例。

会话亲和性 (Session Affinity)

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

注解 nginx.ingress.kubernetes.io/affinity-mode 定义了会话的粘性。如果将部署规模扩大，将此选项设置为 balanced（默认）将重新分配一些会话，从而重新平衡服务器上的负载。将此设置为 persistent 不会重新平衡与新服务器的会话，因此提供了最大的粘性。

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

示例

请检查 亲和性示例。

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-samesite 应用 SameSite 属性到粘性 Cookie。浏览器接受的值是 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"。

认证 (Authentication)

可以添加身份验证，并在 Ingress 规则中添加其他注解。身份验证的来源是包含用户名和密码的 Secret。

注解如下：

• nginx.ingress.kubernetes.io/auth-type: [basic|digest]
  指示 HTTP 身份验证类型：基本或摘要访问身份验证。
• nginx.ingress.kubernetes.io/auth-secret: secretName
  Secret 的名称，其中包含用户名和密码，这些用户名和密码被授予 path 对 Ingress 规则中定义的访问权限。此注解还接受替代形式“命名空间/secretName"，在这种情况下，Secret 查找在引用的命名空间而不是 Ingress 命名空间中执行。

• nginx.ingress.kubernetes.io/auth-secret-type: [auth-file|auth-map]
  本 auth-secret 可以有两种形式：

  • auth-file：默认情况下，密钥 auth 内的 htpasswd 文件为 Secret。
  • auth-map：Secret 密钥是用户名，值是哈希密码。
• nginx.ingress.kubernetes.io/auth-realm: "realm string"

示例

请检查 身份验证示例。

自定义 NGINX 上游哈希

NGINX 支持客户端 - 服务器映射的负载平衡，该映射基于给定密钥的 一致哈希 值。键可以包含文本、变量或其任何组合。此功能允许请求粘性而不是客户端 IP 或 Cookie。将使用 ketama 一致的哈希方法，该方法确保在上游组更改时仅将少数密钥重新映射到不同的服务器。

上游哈希的一种特殊模式称为子集。在这种模式下，上游服务器被分组为子集，粘性通过将密钥映射到子集而不是单个上游服务器来工作。从选定的粘性子集中随机选择特定的服务器。它提供了粘性和负载分配之间的平衡。

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

• nginx.ingress.kubernetes.io/upstream-hash-by：NGINX 变量、文本值或它们的任意组合，以用于一致的哈希。例如 nginx.ingress.kubernetes.io/upstream-hash-by: "$request_uri"，通过当前请求 URI 一致地哈希上游请求。

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

请检查 chashsubset 示例。

自定义 NGINX 负载平衡

这与 load-balance ConfigMap 中的配置 类似，但是每个入口配置负载平衡算法。

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

自定义 NGINX 上游虚拟主机

通过此配置设置，您可以在以下语句中控制 Host 的值：proxy_set_header Host $host，它是 Location 块的一部分。如果您需要通过 $host 以外的方式调用上游服务器，这将非常有用。

客户端证书认证

可以使用"Ingress 规则”中的附加注解来启用“客户端证书认证”。

注解如下：

• nginx.ingress.kubernetes.io/auth-tls-secret: secretName：包含完整的证书颁发机构链的 Secret 的名称，该链 ca.crt 可以针对此 Ingress 进行身份验证。此注解还接受替代形式“命名空间/secretName"，在这种情况下，Secret 查找在引用的命名空间而不是 Ingress 命名空间中执行。
• nginx.ingress.kubernetes.io/auth-tls-verify-depth：提供的客户证书和证书颁发机构链之间的验证深度。
• nginx.ingress.kubernetes.io/auth-tls-verify-client：启用客户端证书的验证。
• nginx.ingress.kubernetes.io/auth-tls-error-page：如果发生证书身份验证错误，应重定向用户的 URL / 页面。
• nginx.ingress.kubernetes.io/auth-tls-pass-certificate-to-upstream：指示是否应将收到的证书传递给上游服务器。默认情况下是禁用的。

示例

请检查 客户端证书示例。

注意
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

后端证书认证

使用入口规则中的附加注解，可以使用证书对代理的 HTTPS 后端进行身份验证。

• nginx.ingress.kubernetes.io/proxy-ssl-secret: secretName：使用证书 tls.crt（tls.key PEM 格式的密钥）指定用于对代理 HTTPS 服务器进行身份验证的 Secret。它还应包含 ca.crt PEM 格式的受信任 CA 证书，该证书用于验证代理 HTTPS 服务器的证书。此注解还接受替代形式“命名空间/secretName"，在这种情况下，Secret 查找在引用的命名空间而不是 Ingress 命名空间中执行。
• nginx.ingress.kubernetes.io/proxy-ssl-verify：启用或禁用对代理 HTTPS 服务器证书的验证。（默认值：关闭）
• 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 服务器的请求的指定 协议。

配置片段 (Configuration Snippet)

使用此注解，您可以将其他配置添加到 NGINX Location。例如：

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

自定义 HTTP 错误

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

用法示例：

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

默认后端 (Default Backend)

此注解具有 nginx.ingress.kubernetes.io/default-backend: <svc name> 指定自定义默认后端的形式。这 <svc name> 是对您在其中应用此注解的相同命名空间中的服务的引用。此注解将覆盖全局默认后端。

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

启用 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 控制接受哪些 Header。这是一个多值字段，以“，”分隔，并接受字母、数字、_ 和 -。

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

• nginx.ingress.kubernetes.io/cors-allow-origin 控制 CORS 接受的源。这是一个单字段值，格式如下：http(s)://origin-site.com 或 http(s)://origin-site.com:port

  • 默认：*
  • 例：nginx.ingress.kubernetes.io/cors-allow-origin: "https://origin-site.com:4443"

• 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 推送预加载

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

示例

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

服务器别名 (Server Alias)

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

注意
服务器别名不能与现有服务器的主机名冲突。如果是这样，服务器别名注解将被忽略。如果创建了服务器别名，然后又创建了具有相同主机名的新服务器，则新服务器配置将取代别名配置。

欲了解更多信息，请参阅 该 server_name 文档。

Server Snippet 段

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

apiVersion: networking.k8s.io/v1beta1
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;
        }

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

客户端主体缓冲区大小

设置缓冲区大小，以读取每个 Location 的客户端请求正文。如果请求主体大于缓冲区，则将整个主体或仅将其一部分写入临时文件。默认情况下，缓冲区大小等于两个内存页。在 x86、其他 32 位平台和 x86-64 上为 8K。在其他 64 位平台上，通常为 16K。此注解将应用于入口规则中提供的每个 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 兆字节

有关更多信息，请参见 http://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-method：<Method> 指定要使用的 HTTP 方法。
• nginx.ingress.kubernetes.io/auth-signin：<SignIn_URL> 指定错误页面的位置。
• nginx.ingress.kubernetes.io/auth-response-headers：<Response_Header_1, ..., Response_Header_n> 指定在身份验证请求完成后传递给后端的 Header。
• nginx.ingress.kubernetes.io/auth-proxy-set-headers：<ConfigMap> ConfigMap 的名称，该名称指定要传递给身份验证服务的 Header。
• nginx.ingress.kubernetes.io/auth-request-redirect：<Request_Redirect_URL> 指定 X-Auth-Request-Redirect Header 值。
• 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-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-auth-url 在 NGINX ConfigMap 中设置，则控制器会将所有请求重定向到提供身份验证的现有服务。如果您想为该入口禁用此行为，则可以在 NGINX ConfigMap 中使用 enable-global-auth: "false"。nginx.ingress.kubernetes.io/enable-global-auth：指示是否应将 GlobalExternalAuth 配置应用于此 Ingress 规则。默认值设置为 "true"。

注意
有关更多信息，请参见 global-auth-url。

限速 (Rate Limiting)

这些注解定义了对连接和传输速率的限制。这些可以用来减轻 DDoS 攻击。

• 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-rate-after：初始千字节数，之后将进一步限制对给定连接的响应的进一步传输。必须在启用 代理缓冲 的情况下使用此功能。
• nginx.ingress.kubernetes.io/limit-rate：每秒允许发送到给定连接的千字节数。零值禁用速率限制。必须在启用 代理缓冲 的情况下使用此功能。
• nginx.ingress.kubernetes.io/limit-whitelist：客户端 IP 源范围要从速率限制中排除。该值是逗号分隔的 CIDR 列表。

如果你在一个单一的入口规则指定多个注解，限制在顺序应用 limit-connections，limit-rpm，limit-rps。

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

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

永久重定向

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

永久重定向码

此注解使您可以修改用于永久重定向的状态代码。例如，nginx.ingress.kubernetes.io/permanent-redirect-code: '308' 将以 308 返回您的永久重定向。

临时重定向 (Temporal Redirect)

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

SSL 直通 (SSL Passthrough)

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

注意
SSL 直通默认情况下处于禁用状态，并且需要使用该 --enable-ssl-passthrough 标志启动控制器。

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

Service Upstream

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

该 nginx.ingress.kubernetes.io/service-upstream 注解禁用该行为，而是使用在 NGINX，该服务的集群 IP 和端口的单一上游。

这对于零停机时间部署之类的事情可能是理想的，因为它减少了 Pod 上下时重新加载 NGINX 配置的需求。参见问题 ＃257。

已知的问题

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

• 粘性会话将不起作用，因为仅支持循环负载平衡。
• 该 proxy_next_upstream 指令不会有任何影响，因为如果出错，该请求将不会分派到另一个上游。

通过重定向执行服务器端 HTTPS

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

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

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

从/重定向到 WWW

在某些情况下，需要从重定向 www.domain.com 到 domain.com，反之亦然。要启用此功能，请使用注解 nginx.ingress.kubernetes.io/from-to-www-redirect: "true"。

注意
如果在某个时候创建了一个新的 Ingress，且其宿主等于选项之一（如 domain.com），则注解将被省略。

注意
对于从 HTTPS 到 HTTPS 的重定向是强制性的，位于 Ingress TLS 部分中的 Secret 中定义的 SSL 证书包含两个通用名称的 FQDN。

白名单来源范围

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

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

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

自定义超时

使用配置 ConfigMap 可以为与上游服务器的连接设置默认的全局超时。在某些情况下，要求具有不同的值。为此，我们提供了允许进行此自定义的注解：

• nginx.ingress.kubernetes.io/proxy-connect-timeout
• nginx.ingress.kubernetes.io/proxy-send-timeout
• nginx.ingress.kubernetes.io/proxy-read-timeout
• 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/proxy-request-buffering

代理重定向

使用注解 nginx.ingress.kubernetes.io/proxy-redirect-from，nginx.ingress.kubernetes.io/proxy-redirect-to 可以在 代理服务器响应 的 Location 和 Refresh Header 字段中设置应更改的文本。

在注解中设置为"off"或"default" nginx.ingress.kubernetes.io/proxy-redirect-from 会禁用 nginx.ingress.kubernetes.io/proxy-redirect-to，否则，必须同时使用两个注解。请注意，每个注解必须是不带空格的字符串。

默认情况下，每个注解的值为"off"。

自定义最大 Body 大小 (Custom max body size)

对于 NGINX，当请求中的大小超过客户端请求正文的最大允许大小时，将向客户端返回 413 错误。该大小可以通过参数来配置 client_max_body_size。

要为所有 Ingress 规则全局配置此设置，proxy-body-size 可以在 NGINX ConfigMap 中 设置该值。要在 Ingress 规则中使用自定义值，请定义以下注解：

nginx.ingress.kubernetes.io/proxy-body-size: 8m

代理 Cookie 域

设置 应在 代理服务器响应的"Set-Cookie"Header 字段的 domain 属性 中 更改 的文本。

要为所有 Ingress 规则全局配置此设置，proxy-cookie-domain 可以在 NGINX ConfigMap 中 设置该值。

代理 Cookie 路径

设置 应在 代理服务器响应的"Set-Cookie"Header 字段的 path 属性 中 更改 的文本。

要为所有 Ingress 规则全局配置此设置，proxy-cookie-path 可以在 NGINX ConfigMap 中 设置该值。

代理缓冲 (Proxy Buffering)

启用或禁用代理缓冲 proxy_buffering。默认情况下，NGINX 配置中禁用代理缓冲。

要为所有 Ingress 规则全局配置此设置，proxy-buffering 可以在 NGINX ConfigMap 中 设置该值。要在 Ingress 规则中使用自定义值，请定义以下注解：

nginx.ingress.kubernetes.io/proxy-buffering: "on"

代理缓冲区数

设置 proxy_buffers 用于读取从代理服务器接收到的响应的第一部分的缓冲区数。默认情况下，代理缓冲区数设置为 4。

要全局配置此设置，请 proxy-buffers-number 在 NGINX ConfigMap 中进行 设置。要在 Ingress 规则中使用自定义值，请定义以下注解：

nginx.ingress.kubernetes.io/proxy-buffers-number: "4"

代理缓冲区大小

设置 proxy_buffer_size 用于读取从代理服务器接收到的响应的第一部分的缓冲区的大小。默认情况下，代理缓冲区大小设置为"4k"。

要全局配置此设置，请 proxy-buffer-size 在 NGINX ConfigMap 中进行 设置。要在 Ingress 规则中使用自定义值，请定义以下注解：

nginx.ingress.kubernetes.io/proxy-buffer-size: "8k"

代理最大临时文件大小

如果 buffering 启用了来自代理服务器的响应，并且整个响应不适合通过 proxy_buffer_size 和 proxy_buffers 指令设置的缓冲区，则可以将响应的一部分保存到临时文件中。此伪指令设置 size 临时文件的最大值，设置为 proxy_max_temp_file_size。一次写入临时文件的数据大小由 proxy_temp_file_write_size 指令设置。

零值禁用对临时文件的响应的缓冲。

要在 Ingress 规则中使用自定义值，请定义以下注解：

nginx.ingress.kubernetes.io/proxy-max-temp-file-size: "1024m"

代理 HTTP 版本

使用此注解设置 proxy_http_version Nginx 反向代理将用于与后端通信的。默认情况下，它设置为"1.1"。

nginx.ingress.kubernetes.io/proxy-http-version: "1.0"

SSL 密码

指定 启用的密码。

使用此注解将 ssl_ciphers 在服务器级别设置指令。该配置对主机中的所有路径均有效。

nginx.ingress.kubernetes.io/ssl-ciphers: "ALL:!aNULL:!EXPORT56:RC4+RSA:+HIGH:+MEDIUM:+LOW:+SSLv2:+EXP"

连接代理头

使用此注解将覆盖 NGINX 设置的默认连接头。要在 Ingress 规则中使用自定义值，请定义注解：

nginx.ingress.kubernetes.io/connection-proxy-header: "keep-alive"

启用访问日志

默认情况下，访问日志处于启用状态，但在某些情况下，可能需要针对给定的入口禁用访问日志。为此，请使用注解：

nginx.ingress.kubernetes.io/enable-access-log: "false"

启用重写日志

默认情况下，未启用重写日志。在某些情况下，可能需要启用 NGINX 重写日志。请注意，重写日志将在通知级别发送到 error_log 文件。要启用此功能，请使用注解：

nginx.ingress.kubernetes.io/enable-rewrite-log: "true"

启用开放追踪 (Opentracing)

可以通过 ConfigMap 在全局范围内启用或禁用 Opentracing，但是有时需要重写它才能启用它或针对特定入口禁用它（例如，关闭对外部运行状况检查端点的跟踪）。

nginx.ingress.kubernetes.io/enable-opentracing: "true"

X 转发前缀 Header

要 X-Forwarded-Prefix 使用字符串值将非标准 Header 添加到上游请求中，可以使用以下注解：

nginx.ingress.kubernetes.io/x-forwarded-prefix: "/path"

ModSecurity

ModSecurity 是一个开源 Web 应用程序防火墙。可以为一组特定的入口 Location 启用它。首先必须通过在 ConfigMap 中 启用 ModSecurity 来启用 ModSecurity 模块。请注意，这将为所有路径启用 ModSecurity，并且必须手动禁用每个路径。

可以使用以下注解启用它：

nginx.ingress.kubernetes.io/enable-modsecurity: "true"

ModSecurity 将使用 推荐的配置 以“仅检测”模式运行。

您可以通过设置以下注解来启用 OWASP 核心规则集：

nginx.ingress.kubernetes.io/enable-owasp-core-rules: "true"

您可以通过设置以下内容从 Nginx 传递 transactionID：

nginx.ingress.kubernetes.io/modsecurity-transaction-id: "$request_id"

您还可以通过代码段添加自己的 ModSecurity 规则集：

nginx.ingress.kubernetes.io/modsecurity-snippet: |
SecRuleEngine On
SecDebugLog /tmp/modsec_debug.log

注意
如果同时使用 enable-owasp-core-rules 和 modsecurity-snippet 注解，则只有 modsecurity-snippet 会生效。如果要包括 OWASP 核心规则集 或 推荐的配置，只需使用 include 语句：

Nginx 0.24.1 及以下

nginx.ingress.kubernetes.io/modsecurity-snippet: |
Include /etc/nginx/owasp-modsecurity-crs/nginx-modsecurity.conf
Include /etc/nginx/modsecurity/modsecurity.conf

Nginx 0.25.0 及更高版本

nginx.ingress.kubernetes.io/modsecurity-snippet: |
Include /etc/nginx/owasp-modsecurity-crs/nginx-modsecurity.conf

InfluxDB

使用 influxdb-* 注解，我们可以使用 nginx-influxdb-module 将请求发送到暴露 UDP 套接字的 InfluxDB 后端，从而监视通过 Location 的请求。

nginx.ingress.kubernetes.io/enable-influxdb: "true"
nginx.ingress.kubernetes.io/influxdb-measurement: "nginx-reqs"
nginx.ingress.kubernetes.io/influxdb-port: "8089"
nginx.ingress.kubernetes.io/influxdb-host: "127.0.0.1"
nginx.ingress.kubernetes.io/influxdb-server-name: "nginx-ingress"

对于 influxdb-host 参数，您有两个选择：

• 使用配置为启用 UDP 协议 的 InfluxDB 服务器。
• 将 Telegraf 作为 Sidecar 代理部署到 Ingress 控制器，该控制器配置为使用 套接字侦听器输入 侦听 UDP，并使用任何 输出插件（例如 InfluxDB、Apache Kafka、Prometheus 等）进行写入。（推荐）

重要的是要记住，此阶段没有 DNS 解析器，因此您必须将 IP 地址配置为 nginx.ingress.kubernetes.io/influxdb-host。如果将 Influx 或 Telegraf 部署为 Sidecar（同一 Pod 中的另一个容器），这将变得很简单，因为您可以直接使用 127.0.0.1。

后端协议

使用 backend-protocol 注解可以指示 NGINX 应如何与后端服务通信。（secure-backends 在旧版本中替换）有效值：HTTP、HTTPS、GRPC、GRPCS 和 AJP。

默认情况下，NGINX 使用 HTTP。

示例

nginx.ingress.kubernetes.io/backend-protocol: "HTTPS"

使用正则表达式

注意
当将此注解与 nginx.ingress.kubernetes.io/affinity 类型为 NGINX 的注解一起使用时 cookie，nginx.ingress.kubernetes.io/session-cookie-path 还必须设置；会话 Cookie 路径不支持正则表达式。

使用 nginx.ingress.kubernetes.io/use-regex 注解将指示 Ingress 上定义的路径是否使用正则表达式。默认值为 false。

下面将指示正在使用正则表达式路径：

nginx.ingress.kubernetes.io/use-regex: "true"

以下内容将指示未使用正则表达式路径：

nginx.ingress.kubernetes.io/use-regex: "false"

当此注解设置为 true 时，不区分大小写的正则表达式 Location 修饰符 将在给定主机的所有路径上强制执行，无论它们定义在什么 Ingress 上。

此外，如果在给定主机的任何 Ingress 上使用了 rewrite-target 注解，则不区分大小写的正则表达式 Location 修饰符 将在给定主机的所有路径上强制执行，无论它们定义在什么 Ingress 上。

在使用此修饰符之前，请阅读有关 入口路径匹配的信息。

Satisfy

默认情况下，请求将需要满足所有身份验证要求才能被允许。通过使用此注解，基于配置值，允许满足任何或所有身份验证要求的请求。

nginx.ingress.kubernetes.io/satisfy: "any"

Mirror

允许将请求镜像到镜像后端。镜像后端的响应将被忽略。此功能很有用，可以查看请求在“测试”后端中的反应。

可以通过以下方式设置镜像后端：

nginx.ingress.kubernetes.io/mirror-target: https://test.env.com/$request_uri

默认情况下，请求正文发送到镜像后端，但可以通过应用以下命令将其关闭：

nginx.ingress.kubernetes.io/mirror-request-body: "off"

注意
Mirror 指令将应用于入口资源内的所有路径。

发送到镜像的请求链接到原始请求。如果您的镜像后端速度较慢，则原始请求将受到限制。

有关镜像模块的更多信息，请参见 ngx_http_mirror_module。

说明
本文档部分示例中使用了 networking.k8s.io/v1beta1 API 版本，该版本在 Kubernetes 1.22 及更高版本中已弃用。在新版本集群中请使用 networking.k8s.io/v1。