Nginx Ingress注解Annotations

https://kubernetes.github.io/ingress-nginx/user-guide/nginx-configuration/annotations/

Nginx Ingress 注解使用在 Ingress 资源实例中，用以设置当前 Ingress 资源实例中 Nginx 虚拟主机的相关配置，对应配置的是 Nginx 当前虚拟主机的 server 指令域内容。在与 Nginx Ingress 配置映射具有相同功能配置时，将按照所在指令域层级遵循 Nginx 配置规则覆盖。

Nginx Ingress注解按照配置功能有如下分类。

1、Nginx原生配置指令

支持在注解中添加 Nginx 原生配置指令。配置说明如下表所示。

配置样例如下：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22

apiVersion: extensions/v1beta1
kind: Ingress
metadata:
    name: web-nginxbar-org
    annotations:
        nginx.ingress.kubernetes.io/server-snippet: |
            location / {
                return 302 /coffee;
            }
spec:
    rules:
    - host: web.nginxbar.org
      http:
            paths:
            - path: /tea
              backend:
                  serviceName: tea-svc
                  servicePort: 80
            - path: /coffee
            backend:
                serviceName: coffee-svc
                servicePort: 80

2、通用配置

Nginx 虚拟主机中的通用配置。通用配置说明如下表所示。

配置样例如下：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

apiVersion: extensions/v1beta1
kind: Ingress
metadata:
    name: web-nginxbar-org
    namespace: default
    annotations:
        nginx.ingress.kubernetes.io/rewrite-target: /tea/$1
        nginx.ingress.kubernetes.io/enable-rewrite-log: "true"
spec:
    rules:
    - host: web.nginxbar.org   # 此service的访问域名
      http:
        paths:
        - backend:
            serviceName: nginx-web
            servicePort: 8080
        path: /coffee/(.+)

3、访问控制

用以设置基于流量、请求连接数、请求频率的访问控制。访问控制配置说明如下表所示。

4、认证管理

Nginx Ingress 提供了基本认证、摘要认证和外部认证 3 种方式，为被代理服务器提供认证支持。认证管理配置说明如下表所示。

基本认证配置如下：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34

# 创建基本认证用户名nginxbar、密码123456，输出文件名必须是auth
htpasswd -bc auth nginxbar 123456

# 创建资源对象secret保存账号和密码
kubectl create secret generic basic-auth --from-file=auth

# 查看创建的basic-auth
kubectl get secret basic-auth -o yaml

# 创建基本认证的Ingress实例
cat>auth-nginxbar-org.yaml<<EOF
apiVersion: extensions/v1beta1
kind: Ingress
metadata:
    name: auth-nginxbar-org
    namespace: default
    annotations:
        # 设置认证类型
        nginx.ingress.kubernetes.io/auth-type: basic
        # 关联账号和密码
        nginx.ingress.kubernetes.io/auth-secret: basic-auth
        # 显示认证提示信息
        nginx.ingress.kubernetes.io/auth-realm: 'Authentication Required for web.nginxbar.org'
spec:
    rules:
    - host: auth.nginxbar.org   # 此service的访问域名
      http:
          paths:
          - backend:
              serviceName: nginx-web
              servicePort: 8080
EOF

kubectl create -f auth-nginxbar-org.yaml

认证转发配置样例如下：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

apiVersion: extensions/v1beta1
kind: Ingress
metadata:
    name: auth-nginxbar-org
    namespace: default
    annotations:
        nginx.ingress.kubernetes.io/auth-url: "http://$host/auth2"
        nginx.ingress.kubernetes.io/auth-signin: "http://$host/auth/start"
        nginx.ingress.kubernetes.io/auth-method: "POST"
        nginx.ingress.kubernetes.io/auth-cache-key: "foo",
        nginx.ingress.kubernetes.io/auth-cache-duration": "200 202 401 30m"
        nginx.ingress.kubernetes.io/auth-snippet: |
            proxy_set_header Foo-Header 42;
spec:
    rules:
    - host: auth.nginxbar.org   # 此service的访问域名
      http:
        paths:
        - backend:
            serviceName: nginx-web
            servicePort: 8080

5、跨域访问

跨域访问功能配置说明如下表所示。

配置样例如下：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22

apiVersion: extensions/v1beta1
kind: Ingress
metadata:
    name: web-nginxbar-org
    namespace: default
    annotations:
        nginx.ingress.kubernetes.io/cors-allow-headers: >-
            DNT,X-CustomHeader,Keep-Alive,User-Agent,X-Requested-With,
            If-Modified-Since,Cache-Control,Content-Type,Authorization
        nginx.ingress.kubernetes.io/cors-allow-methods: 'PUT, GET, POST, OPTIONS'
        nginx.ingress.kubernetes.io/cors-allow-origin: '*'
        nginx.ingress.kubernetes.io/enable-cors: "true"
        nginx.ingress.kubernetes.io/cors-max-age: 600
spec:
    rules:
    - host: web.nginxbar.org
      http:
        paths:
        - backend:
            serviceName: nginx-web
            servicePort: 8080
          path: /

6、代理配置

Nginx 代理相关功能配置说明如下表所示。

7、负载均衡

为方便上游服务器组的动态管理，Nginx Ingress 基于 Lua 实现了一致性哈希、基于子集的一致性哈希、轮询调度及峰值指数加权移动平均（Peak Exponentially Weighted Moving-Average，Peak EWMA）负载均衡算法。负载均衡配置说明如下表所示。

子集模式的一致性哈希负载算法是将上游服务器组中的被代理服务器分成固定数量的分组，然后把每个分组当作一致性哈希计算的虚拟节点。默认一致性哈希是按照每个被代理服务器为虚拟节点进行计算的。

Peak EWMA 负载均衡算法，是对每个 Pod 请求的往返延时（Round-Trip Time，RTT）计算移动平均值，并用该 Pod 的未完成请求数对这个平均值加权计算，计算值最小的 Pod 端点将被分配新的请求。

8、会话保持配置

设置基于 cookie 的会话亲缘关系，也就是会话保持功能。启用基于 cookie 的会话保持功能时，可以使同一客户端的请求始终转发给同一后端服务器。Nginx Ingress 对启用会话保持功能的 Service 集群使用一致性哈希负载算法，即使后端 Pod 数量变化，也不会对会话保持功能产生太大的影响。会话保持配置说明如下表所示。

配置样例如下：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

apiVersion: extensions/v1beta1
kind: Ingress
metadata:
    name: web-nginxbar-org
    annotations:
        nginx.ingress.kubernetes.io/affinity: "cookie"
        nginx.ingress.kubernetes.io/session-cookie-name: "route"
        nginx.ingress.kubernetes.io/session-cookie-expires: "172800"
        nginx.ingress.kubernetes.io/session-cookie-max-age: "172800"

spec:
    rules:
    - host: web.nginxbar.org
      http:
        paths:
        - backend:
            serviceName: nginx-web
            servicePort: 8080
        path: /

9、HTTPS配置

HTTPS 功能的配置说明如下表所示。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35

# 创建TLS证书
openssl req -x509 -nodes -days 365 -newkey rsa:2048 -keyout /data/apps/certs/dashboard.key -out /data/apps/certs/dashboard.crt -subj "/CN=dashboard.nginxbar.org/O=dashboard.nginxbar.org"
kubectl -n kube-system  create secret tls ingress-secret --key /data/apps/certs/dashboard.key --cert /data/apps/certs/dashboard.crt

# 创建HTTPS服务
cat>dashboard-ingress.yaml<<EOF
apiVersion: extensions/v1beta1
kind: Ingress
metadata:
    name: dashboard-ingress
    namespace: kube-system
    annotations:
        nginx.ingress.kubernetes.io/ingress.class: nginx
        # 使用HTTPS协议代理后端服务器
        nginx.ingress.kubernetes.io/backend-protocol: "HTTPS"
        # 启用SSL透传
        nginx.ingress.kubernetes.io/ssl-passthrough: "true"
spec:
    tls:
    - hosts:
        - dashboard.nginxbar.org
        secretName: ingress-secret
    rules:
        - host: dashboard.nginxbar.org
          http:
            paths:
            - path: /
              backend:
                serviceName: kubernetes-dashboard
                servicePort: 443
EOF

kubectl create -f dashboard-ingress.yaml

curl -k -H "Host:dashboard.nginxbar.org" https://10.103.196.209

Nginx-ingress 在用户没有提供证书的情况下会提供一个内置的默认 TLS 证书，如果 secretName 参数没有配置或配置错误，Nginx 会使用系统默认的证书，所以配置后仍需检查确认。

HTTPS 客户端证书身份认证配置样例如下：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31

# 创建客户端证书资源对象default/ca-secret

apiVersion: extensions/v1beta1
kind: Ingress
metadata:
    annotations:
        # 启用客户端证书验证
        nginx.ingress.kubernetes.io/auth-tls-verify-client: "on"
        # 绑定客户端证书的资源对象名称，是命名空间default的ca-secret
        nginx.ingress.kubernetes.io/auth-tls-secret: "default/ca-secret"
        # 客户端证书链的验证深度为1
        nginx.ingress.kubernetes.io/auth-tls-verify-depth: "1"
        # 设置客户端证书验证错误时的跳转页面
        nginx.ingress.kubernetes.io/auth-tls-error-page: "http://www.mysite.com/error-cert.html"
        # 指定证书传递到上游服务器
        nginx.ingress.kubernetes.io/auth-tls-pass-certificate-to-upstream: "true"
    name: nginx-test
    namespace: default
spec:
    rules:
    - host: mydomain.com
        http:
            paths:
            - backend:
                serviceName: http-svc
                servicePort: 80
            path: /
    tls:
    - hosts:
        - mydomain.com
        secretName: tls-secret

10、“金丝雀”发布

“金丝雀”发布又称为灰度发布，灰度发布功能可以将用户请求按照指定的策略进行分割，并转发到不同的代理服务器组，通过不同的代理服务器部署应用不同版本可进行对照比较，因该方式对于新版本而言类似于使用“金丝雀”的方式进行测试，所以也叫“金丝雀”发布。
Nginx Ingress 支持 Header、cookie 和权重 3 种方式，可单独使用，也可以组合使用。“金丝雀”发布配置说明如下表所示。

“金丝雀”路由规则同时存在时的优先顺序是 canary-by-header、canary-by-cookie、canary-weight。

配置样例如下：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42

# 创建主机web.nginxbar.org的Ingress资源配置
apiVersion: extensions/v1beta1
kind: Ingress
metadata:
    name: web-nginxbar-org
    namespace: default
    annotations:
        nginx.ingress.kubernetes.io/ingress.class: "nginx"
spec:
    rules:
    - host: web.nginxbar.org   # 此service的访问域名
      http:
        paths:
        - backend:
            serviceName: nginx-web
            servicePort: 8080

# 创建主机web.nginxbar.org金丝雀组的Ingress资源配置
apiVersion: extensions/v1beta1
kind: Ingress
metadata:
    name: web-nginxbar-org-canary
    namespace: default
    annotations:
        nginx.ingress.kubernetes.io/ingress.class: "nginx"
        nginx.ingress.kubernetes.io/canary: "true",
        # 根据请求头字段CanaryByHeader的值进行判断
        nginx.ingress.kubernetes.io/canary-by-header: "CanaryByHeader",
        # 请求头字段CanaryByHeader的值为DoCanary时，路由到“金丝雀”服务器组
        nginx.ingress.kubernetes.io/canary-by-header-value: "DoCanary",
        # 根据Cookie字段CanaryByCookie的值进行判断
        nginx.ingress.kubernetes.io/canary-by-cookie: "CanaryByCookie",
        # 随机10%的请求路由到“金丝雀”服务器组
        nginx.ingress.kubernetes.io/canary-weight: "10",
spec:
    rules:
    - host: web.nginxbar.org   # 此service的访问域名
      http:
        paths:
        - backend:
            serviceName: nginx-web-canary
            servicePort: 8080

11、lua-resty-waf模块

lua-resty-waf 是一个基于 OpenResty 的高性能 Web 应用防火墙，对当前虚拟主机的访问可以按照相关防火墙规则进行访问过滤。模块配置说明如下表所示。

12、ModSecurity模块配置

ModSecurity 是一个开源的 Web 应用防火墙。必须首先通过在 ConfigMap 中启用 Mod-Security 来加载 ModSecurity 模块。这将为所有路径启用 ModSecurity 过滤，可以手动在 Ingress 资源实例中禁用此功能。ModSecurity 模块配置说明如下表所示。

配置样例如下：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

apiVersion: extensions/v1beta1
kind: Ingress
metadata:
    name: web-nginxbar-org
    annotations:
        nginx.ingress.kubernetes.io/enable-modsecurity: "true"
        nginx.ingress.kubernetes.io/enable-owasp-core-rules: "true"
        nginx.ingress.kubernetes.io/modsecurity-transaction-id: "$request_id"
        nginx.ingress.kubernetes.io/modsecurity-snippet: |
        SecRuleEngine On
        SecDebugLog /tmp/modsec_debug.log
spec:
    rules:
    - host: web.nginxbar.org
      http:
        paths:
        - backend:
            serviceName: nginx-web
            servicePort: 8080
            path: /

13、Influxdb模块配置

通过使用 Nginx Influxdb 模块，可以用 UDP 协议将请求记录实时发送到后端的 Influxdb 服务器。Influxdb 模块配置说明如下表所示。

配置样例如下：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

apiVersion: extensions/v1beta1
kind: Ingress
metadata:
    name: web-nginxbar-org
    annotations:
        nginx.ingress.kubernetes.io/enable-influxdb: "true"
        nginx.ingress.kubernetes.io/influxdb-measurement: "nginxbar-reqs"
        nginx.ingress.kubernetes.io/influxdb-port: "8089"
        nginx.ingress.kubernetes.io/influxdb-host: "192.168.2.110"
        nginx.ingress.kubernetes.io/influxdb-server-name: "nginxbar-com"
spec:
    rules:
    - host: web.nginxbar.org
      http:
        paths:
        - backend:
            serviceName: nginx-web
            servicePort: 8080
        path: /

说明

金丝雀

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

• nginx.ingress.kubernetes.io/canary-by-header：用于通知Ingress将请求路由到Canary Ingress中指定的服务的标头。当请求标头设置always为时，它将被路由到Canary。当标头设置never为时，它将永远不会路由到金丝雀。对于任何其他值，标头将被忽略，并且按优先级将请求与其他金丝雀规则进行比较。
• nginx.ingress.kubernetes.io/canary-by-header-value：匹配的报头值，用于通知Ingress将请求路由到Canary Ingress中指定的服务。当请求标头设置为此值时，它将被路由到Canary。对于任何其他标头值，标头将被忽略，并按优先级将请求与其他金丝雀规则进行比较。此注释必须与一起使用。注释是的扩展，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-valuePCRE 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和之外，所有其他非canary注释将被忽略（从相应的主要入口继承）nginx.ingress.kubernetes.io/upstream-hash-by。

已知局限性

目前，每个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 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"。

认证方式

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

注释是：

1

nginx.ingress.kubernetes.io/auth-type: [basic|digest]

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

1

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

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

1

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

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

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

1

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-balanceConfigMap中的类似，但是每个入口配置负载平衡算法。

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

自定义NGINX上游虚拟主机

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

客户端证书认证

可以使用“入口规则”中的附加注释来启用“客户端证书认证”。

注释是：

• nginx.ingress.kubernetes.io/auth-tls-secret: secretName：包含完整的证书颁发机构链的密钥的名称，该链ca.crt可以针对此Ingress进行身份验证。此注释还接受替代形式“名称空间/ secretName”，在这种情况下，秘密查找在引用的名称空间而不是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 -拉

后端证书认证

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

• nginx.ingress.kubernetes.io/proxy-ssl-secret: secretName：使用证书tls.crt（tls.keyPEM格式的密钥）指定用于对代理HTTPS服务器进行身份验证的密钥。它还应包含ca.crtPEM格式的受信任CA证书，该证书用于验证代理HTTPS服务器的证书。此注释还接受替代形式“名称空间/ secretName”，在这种情况下，秘密查找在引用的名称空间而不是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服务器的请求的指定协议。

配置片段

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

1

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

自定义HTTP错误

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

用法示例：

1

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

默认后端

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

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

启用CORS

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

可以使用以下注释来控制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,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

HTTP2推送预加载。

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

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

服务器别名

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

注意

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

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

Server Snippet段

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

1
2
3
4
5
6
7
8
9
10
11
12
13

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;
        }

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

客户端主体缓冲区大小

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

注意

注释值必须以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

外部认证

要使用提供身份验证的现有服务，可以对Ingress规则进行注释，nginx.ingress.kubernetes.io/auth-url以指示应将HTTP请求发送到的URL。

1

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>指定在身份验证请求完成后传递给后端的标头。
• 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。每个服务器和位置都有其自己的密钥空间。因此，缓存的响应仅在按服务器和按位置的基础上有效。
• 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>指定用于外部身份验证的自定义代码段，例如

1

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未设置，则将被忽略

全局外部认证

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

限速

这些注释定义了对连接和传输速率的限制。这些可以用来减轻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地址。

永久重定向

此注释允许返回永久重定向，而不是向上游发送数据。例如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直通

注释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标头字段中设置应更改的文本

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

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

Custom max body size

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

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

1

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

代理Cookie域

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

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

代理Cookie路径

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

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

代理缓冲

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

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

1

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

代理缓冲区数

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

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

1

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

代理缓冲区大小

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

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

1

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规则中使用自定义值，请定义以下注释：

1

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

代理HTTP版本

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

1

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

SSL密码

指定启用的密码。

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

1

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

连接代理头

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

1

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

启用访问日志

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

1

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

启用重写日志

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

1

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

启用开放追踪

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

1

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

X转发前缀报头

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

1

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

ModSecurity

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

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

1

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

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

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

1

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

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

1

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

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

1

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及以下

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及更高版本

1

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

InfluxDB

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

1

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。

后端协议

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

默认情况下，NGINX使用HTTP。

例：

1

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。

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

1

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

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

1

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

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

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

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

Satisfy

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

1

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

Mirror

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

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

1

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

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

1

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

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

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

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