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

ingress-nginx配置(注解)

Kubernetes批注添加到特定的Ingress对象，以自定义其行为。

小费

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

注意

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

Name	type
nginx.ingress.kubernetes.io/app-root	string
nginx.ingress.kubernetes.io/affinity	cookie
nginx.ingress.kubernetes.io/affinity-mode	"balanced" or "persistent"
nginx.ingress.kubernetes.io/auth-realm	string
nginx.ingress.kubernetes.io/auth-secret	string
nginx.ingress.kubernetes.io/auth-secret-type	string
nginx.ingress.kubernetes.io/auth-type	basic or digest
nginx.ingress.kubernetes.io/auth-tls-secret	string
nginx.ingress.kubernetes.io/auth-tls-verify-depth	number
nginx.ingress.kubernetes.io/auth-tls-verify-client	string
nginx.ingress.kubernetes.io/auth-tls-error-page	string
nginx.ingress.kubernetes.io/auth-tls-pass-certificate-to-upstream	"true" or "false"
nginx.ingress.kubernetes.io/auth-url	string
nginx.ingress.kubernetes.io/auth-cache-key	string
nginx.ingress.kubernetes.io/auth-cache-duration	string
nginx.ingress.kubernetes.io/auth-proxy-set-headers	string
nginx.ingress.kubernetes.io/auth-snippet	string
nginx.ingress.kubernetes.io/enable-global-auth	"true" or "false"
nginx.ingress.kubernetes.io/backend-protocol	string
nginx.ingress.kubernetes.io/canary	"true" or "false"
nginx.ingress.kubernetes.io/canary-by-header	string
nginx.ingress.kubernetes.io/canary-by-header-value	string
nginx.ingress.kubernetes.io/canary-by-header-pattern	string
nginx.ingress.kubernetes.io/canary-by-cookie	string
nginx.ingress.kubernetes.io/canary-weight	number
nginx.ingress.kubernetes.io/client-body-buffer-size	string
nginx.ingress.kubernetes.io/configuration-snippet	string
nginx.ingress.kubernetes.io/custom-http-errors	[]int
nginx.ingress.kubernetes.io/default-backend	string
nginx.ingress.kubernetes.io/enable-cors	"true" or "false"
nginx.ingress.kubernetes.io/cors-allow-origin	string
nginx.ingress.kubernetes.io/cors-allow-methods	string
nginx.ingress.kubernetes.io/cors-allow-headers	string
nginx.ingress.kubernetes.io/cors-allow-credentials	"true" or "false"
nginx.ingress.kubernetes.io/cors-max-age	number
nginx.ingress.kubernetes.io/force-ssl-redirect	"true" or "false"
nginx.ingress.kubernetes.io/from-to-www-redirect	"true" or "false"
nginx.ingress.kubernetes.io/http2-push-preload	"true" or "false"
nginx.ingress.kubernetes.io/limit-connections	number
nginx.ingress.kubernetes.io/limit-rps	number
nginx.ingress.kubernetes.io/permanent-redirect	string
nginx.ingress.kubernetes.io/permanent-redirect-code	number
nginx.ingress.kubernetes.io/temporal-redirect	string
nginx.ingress.kubernetes.io/proxy-body-size	string
nginx.ingress.kubernetes.io/proxy-cookie-domain	string
nginx.ingress.kubernetes.io/proxy-cookie-path	string
nginx.ingress.kubernetes.io/proxy-connect-timeout	number
nginx.ingress.kubernetes.io/proxy-send-timeout	number
nginx.ingress.kubernetes.io/proxy-read-timeout	number
nginx.ingress.kubernetes.io/proxy-next-upstream	string
nginx.ingress.kubernetes.io/proxy-next-upstream-timeout	number
nginx.ingress.kubernetes.io/proxy-next-upstream-tries	number
nginx.ingress.kubernetes.io/proxy-request-buffering	string
nginx.ingress.kubernetes.io/proxy-redirect-from	string
nginx.ingress.kubernetes.io/proxy-redirect-to	string
nginx.ingress.kubernetes.io/proxy-http-version	"1.0" or "1.1"
nginx.ingress.kubernetes.io/proxy-ssl-secret	string
nginx.ingress.kubernetes.io/proxy-ssl-ciphers	string
nginx.ingress.kubernetes.io/proxy-ssl-name	string
nginx.ingress.kubernetes.io/proxy-ssl-protocols	string
nginx.ingress.kubernetes.io/proxy-ssl-verify	string
nginx.ingress.kubernetes.io/proxy-ssl-verify-depth	number
nginx.ingress.kubernetes.io/enable-rewrite-log	"true" or "false"
nginx.ingress.kubernetes.io/rewrite-target	URI
nginx.ingress.kubernetes.io/satisfy	string
nginx.ingress.kubernetes.io/server-alias	string
nginx.ingress.kubernetes.io/server-snippet	string
nginx.ingress.kubernetes.io/service-upstream	"true" or "false"
nginx.ingress.kubernetes.io/session-cookie-name	string
nginx.ingress.kubernetes.io/session-cookie-path	string
nginx.ingress.kubernetes.io/session-cookie-change-on-failure	"true" or "false"
nginx.ingress.kubernetes.io/session-cookie-samesite	string
nginx.ingress.kubernetes.io/session-cookie-conditional-samesite-none	"true" or "false"
nginx.ingress.kubernetes.io/ssl-redirect	"true" or "false"
nginx.ingress.kubernetes.io/ssl-passthrough	"true" or "false"
nginx.ingress.kubernetes.io/upstream-hash-by	string
nginx.ingress.kubernetes.io/x-forwarded-prefix	string
nginx.ingress.kubernetes.io/load-balance	string
nginx.ingress.kubernetes.io/upstream-vhost	string
nginx.ingress.kubernetes.io/whitelist-source-range	CIDR
nginx.ingress.kubernetes.io/proxy-buffering	string
nginx.ingress.kubernetes.io/proxy-buffers-number	number
nginx.ingress.kubernetes.io/proxy-buffer-size	string
nginx.ingress.kubernetes.io/proxy-max-temp-file-size	string
nginx.ingress.kubernetes.io/ssl-ciphers	string
nginx.ingress.kubernetes.io/connection-proxy-header	string
nginx.ingress.kubernetes.io/enable-access-log	"true" or "false"
nginx.ingress.kubernetes.io/enable-opentracing	"true" or "false"
nginx.ingress.kubernetes.io/enable-influxdb	"true" or "false"
nginx.ingress.kubernetes.io/influxdb-measurement	string
nginx.ingress.kubernetes.io/influxdb-port	string
nginx.ingress.kubernetes.io/influxdb-host	string
nginx.ingress.kubernetes.io/influxdb-server-name	string
nginx.ingress.kubernetes.io/use-regex	bool
nginx.ingress.kubernetes.io/enable-modsecurity	bool
nginx.ingress.kubernetes.io/enable-owasp-core-rules	bool
nginx.ingress.kubernetes.io/modsecurity-transaction-id	string
nginx.ingress.kubernetes.io/modsecurity-snippet	string
nginx.ingress.kubernetes.io/mirror-request-body	string
nginx.ingress.kubernetes.io/mirror-target	string

重写示例。

相似性示例。

Cookie Affinity

如果使用cookie亲缘关系类型，则还可以指定将用于通过注释路由请求的cookie的名称nginx.ingress.kubernetes.io/session-cookie-name。默认是创建一个名为“ 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属性粘饼干。浏览器接受的值是None，Lax和Strict。某些浏览器会拒绝带有的cookie SameSite=None，包括在SameSite=None规范之前创建的cookie （例如Chrome 5X）。其他浏览器错误地将SameSite=Nonecookie视为SameSite=Strict（例如，在OSX 14上运行的Safari）。要从SameSite=None浏览器中忽略这些不兼容的内容，请添加注释nginx.ingress.kubernetes.io/session-cookie-conditional-samesite-none: "true"。

HTTP身份验证类型：基本或摘要访问身份验证。

nginx.ingress.kubernetes.io/auth-secret: secretName

Secret的名称，其中包含用户名和密码，这些用户名和密码被授予path对Ingress规则中定义的的访问权限。此注释还接受替代形式“名称空间/ secretName”，在这种情况下，秘密查找在引用的名称空间而不是Ingress名称空间中执行。

nginx.ingress.kubernetes.io/auth-secret-type: [auth-file|auth-map]

本auth-secret可以有两种形式：

• auth-file-默认情况下，密钥auth内的htpasswd文件为秘密
• auth-map -机密密钥是用户名，值是哈希密码

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

请检查身份验证示例。

一致哈希值。键可以包含文本，变量或其任何组合。此功能允许请求粘性而不是客户端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示例。

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

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

客户端证书示例。

注意

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 -拉

密码。密码以OpenSSL库可以理解的格式指定。

nginx.ingress.kubernetes.io/proxy-ssl-name：允许设置proxy_ssl_name。这允许覆盖用于验证代理HTTPS服务器的证书的服务器名称。建立与代理HTTPS服务器的连接时，也会通过SNI传递此值。

nginx.ingress.kubernetes.io/proxy-ssl-protocols：启用对代理HTTPS服务器的请求的指定协议。

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

用法示例：

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

custom-http-errors注释，它还将处理错误响应。

https://enable-cors.org

该server_name文档。

http://nginx.org

proxy_cache_valid。您可以指定多个逗号分隔的值：200 202 10m, 401 5m。默认为200 202 401 5m。

nginx.ingress.kubernetes.io/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中设置，则控制器会将所有请求重定向到提供身份验证的现有服务。如果您想为该入口禁用此行为，则可以enable-global-auth: "false"在NGINX ConfigMap中使用。 nginx.ingress.kubernetes.io/enable-global-auth：指示是否应将GlobalExternalAuth配置应用于此Ingress规则。默认值设置为"true"。

注意

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

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标头值设置客户端IP地址。

TLS / HTTPS。

注意

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

注意

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

＃257。

已知的问题

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

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

ConfigMap中使用。

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

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

CIDR列表，例如 10.0.0.0/24,172.10.0.1。

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

注意

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

代理服务器响应的Location和Refresh标头字段中设置应更改的文本

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

默认情况下，每个注释的值为“ off”。

client_max_body_size。

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

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

应在代理服务器响应的“ Set-Cookie”标头字段的domain属性中更改的文本。

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

应在代理服务器响应的“ Set-Cookie”标头字段的path属性中更改的文本。

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

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"

proxy_http_versionNginx反向代理将用于与后端通信的。默认情况下，它设置为“ 1.1”。

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

启用的密码。

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

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

ModSecurity是一个开源Web应用程序防火墙。可以为一组特定的入口位置启用它。首先必须通过在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

nginx-influxdb-module将请求发送到暴露UDP套接字的InfluxDB后端，从而监视通过位置的请求。

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（同一吊舱中的另一个容器），这将变得很简单，因为您可以直接使用127.0.0.1。

位置修饰符将在给定主机的所有路径上强制执行，无论它们定义在什么Ingress上。

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

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

ngx_http_mirror_module