Nginx Ingress配置词典 - 容器服务 Kubernetes 版 ACK

您可以通过配置Nginx Ingress的ConfigMap资源或使用Nginx Ingress注释来进行配置。本文列出了Nginx Ingress常用的注释和ConfigMap字段的具体说明与使用方法。

索引

资源	配置项

资源	配置项
ConfigMap	ConfigMap默认配置说明
ConfigMap	配置项说明
Annotation	负载均衡算法
	Cookie亲和性
	重定向
	Rewrite重写
	限流
	容灾
	灰度发布
	超时相关配置
	跨域
	重试逻辑
	IP访问控制
	流量镜像
	安全防护
	安全认证

ConfigMap默认配置说明

您可以通过kubectl edit cm -n kube-system nginx-configuration命令，对ConfigMap进行编辑。以下是ConfigMap默认配置和说明。更多配置信息请参见官方文档。

apiVersion: v1
kind: ConfigMap
metadata:
 name: nginx-configuration
 namespace: <Namespace>  # 默认为kube-system
 labels:
   app: ingress-nginx
data:
   log-format-upstream: '$remote_addr - [$remote_addr] - $remote_user [$time_local] "$request" $status $body_bytes_sent "$http_referer" "$http_user_agent" $request_length $request_time [$proxy_upstream_name] $upstream_addr $upstream_response_length $upstream_response_time $upstream_status $req_id $host [$proxy_alternative_upstream_name]'
   proxy-body-size: 20m
   proxy-connect-timeout: "10"
   max-worker-connections: "65536"
   enable-underscores-in-headers: "true"
   reuse-port: "true"
   worker-cpu-affinity: "auto"
   server-tokens: "false"
   ssl-redirect: "false"
   allow-backend-server-header: "true"
   ignore-invalid-headers: "true"
   generate-request-id: "true"
   upstream-keepalive-timeout: "900"

以下是配置项说明。

配置项	描述

配置项	描述
log-format-upstream	配置日志格式，修改后需同步修改 `kube-system/k8s-nginx-ingress AliyunLogConfig` 配置，并对齐SLS采集的日志格式。配置示例参见通过日志服务SLS的Controller Pod查看访问日志。
proxy-body-size	设置客户端请求正文允许的最大大小。详情请参见Nginx的client_max_body_size。
proxy-connect-timeout	设置与代理服务器建立连接的超时，同时设置gRPC连接的grpc_connect_timeout。不能超过75秒，配置值仅为数值，无单位。
max-worker-connections	每个工作进程可打开的最大同时连接数。设置为0则使用 `max-worker-open-files` 的值。
enable-underscores-in-headers	是否支持包含下划线的Header。
reuse-port	为每个工作进程创建一个单独的监听套接字，允许在工作进程之间分配传入连接。使用 `SO_REUSEPORT` 套接字选项。
worker-cpu-affinity	自动将工作进程绑定到可用的CPU，进行性能调优。适用于高性能场景。
server-tokens	在响应中发送Nginx服务器标头，在错误页面中显示Nginx版本。设置为`false`表示禁用该功能。
ssl-redirect	如果服务器具有TLS证书，则全局配置将强制使用HTTPS，并进行301重定向。
allow-backend-server-header	允许从后端返回标头Server，而不是通用的Nginx字符串。
ignore-invalid-headers	是否忽略包含无效名称的Header字段。
generate-request-id	如果请求中不存在`X-Request-ID`，则生成随机值。
upstream-keepalive-timeout	设置与上游服务器的空闲保持活动连接的超时时间。对应Nginx的`keepalive_timeout`指令配置。默认不配置，为60秒。

Ingress支持Annotation

在使用Nginx Ingress Controller时，可以根据应用的具体需求来调整其配置。您可以通过添加注释（Annotations）来改变 Nginx的行为。以下是常用的注释配置。如需了解更多注释请参见Nginx Ingress Annotation。

负载均衡算法

Nginx Ingress提供多种负载均衡算法来优化后端服务的流量分发。根据应用程序的特点和需求，您可以选择不同的负载均衡策略。

注释	描述

注释

描述

nginx.ingress.kubernetes.io/load-balance

用于设置后端服务的普遍负载均衡算法。

round_robin（默认）：轮询调度，是最常用的负载均衡算法，适用于大多数场景。
ewma：Peak EWMA算法，适合需要快速响应时间的应用。

nginx.ingress.kubernetes.io/upstream-hash-by

一致性Hash是一种特殊的Hash算法，通过构建环状哈希空间，替代普通的线性Hash空间。在增删节点时，只需根据顺时针原则迁移部分路由，其他路由保持不变，从而有效减少重新路由，实现负载均衡。

以下是一致性Hash负载均衡配置YAML示例。

1.22及以上版本集群

1.22以下版本集群

apiVersion: networking.k8s.io/v1
kind: Ingress 
metadata: 
  name: ingress-test
  namespace: default
  annotations:
    nginx.ingress.kubernetes.io/upstream-hash-by: "$request_uri"               # 根据请求的URI进行hash。
    nginx.ingress.kubernetes.io/upstream-hash-by: "$request_uri$host"          # 根据请求的URI和域名进行hash。
    nginx.ingress.kubernetes.io/upstream-hash-by: "${request_uri}-text-value"  # 根据请求的URI和一个自定义文本值进行hash。
spec:
  rules:
    - host: ''
      http:
        paths:
          - path: '/'
            backend:
              service:
                name: <YOUR_SERVICE_NAME>  #替换为您的目标服务名称
                port:
                  number: <YOUR_SERVICE_PORT>  #替换为您的目标服务端口
            property:
              ingress.beta.kubernetes.io/url-match-mode: STARTS_WITH
            pathType: ImplementationSpecific
  ingressClassName: nginx

apiVersion: networking.k8s.io/v1beta1
kind: Ingress
metadata:
  name: ingress-test
  namespace: default
  annotations:
    kubernetes.io/ingress.class: nginx
    nginx.ingress.kubernetes.io/upstream-hash-by: "$request_uri"               # 根据请求的URI进行hash。
    nginx.ingress.kubernetes.io/upstream-hash-by: "$request_uri$host"          # 根据请求的URI和域名进行hash。
    nginx.ingress.kubernetes.io/upstream-hash-by: "${request_uri}-text-value"  # 根据请求的URI和一个自定义文本值进行hash。
spec:
  rules:
    - host: ''
      http:
        paths:
          - path: '/'
            backend:
              serviceName: <YOUR_SERVICE_NAME>  #替换为您的目标服务名称
              servicePort: <YOUR_SERVICE_PORT>  #替换为您的目标服务端口

Cookie亲和性

以下是基于Cookie的会话亲和性的注释和说明。

注解	描述

注解	描述
nginx.ingress.kubernetes.io/affinity	指定亲和性类型。默认值为`cookie`，仅支持`cookie`亲和性。
nginx.ingress.kubernetes.io/affinity-mode	定义亲和性模式，可选值如下： `balanced`：在请求分配时，将流量在多个实例间平衡，确保负载分布均匀。 `persistent`：将来自同一客户端的请求持续发送到同一后端实例，确保数据一致性和会话保持。默认值：`balanced`。
nginx.ingress.kubernetes.io/session-cookie-name	指定Cookie的值作为Hash Key。
nginx.ingress.kubernetes.io/session-cookie-path	定义将在Cookie上设置的路径，默认为`/`。如果`nginx.ingress.kubernetes.io/use-regex`设置为`true`，会话Cookie路径不支持正则表达式。
nginx.ingress.kubernetes.io/session-cookie-max-age	设置生成的Cookie的有效期，单位为秒。
nginx.ingress.kubernetes.io/session-cookie-expires	定义Cookie的过期时间，值为从创建到过期所经过的秒数。

以下是配置Cookie亲和性注释YAML示例。

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: nginx-test
  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:
  ingressClassName: nginx
  rules:
  - host: stickyingress.example.com
    http:
      paths:
      - path: /
        pathType: Prefix
        backend:
          service:
            name: http-svc
            port: 
              number: 80

重定向

以下是Nginx Ingress重定向注释。

注解	描述

注解	描述
nginx.ingress.kubernetes.io/ssl-redirect	将HTTP请求重定向为HTTPS。配置示例请参见配置HTTP重定向至HTTPS。
nginx.ingress.kubernetes.io/force-ssl-redirect	将HTTP请求重定向为HTTPS。 `true`：重定向到HTTPS。 `false`：不重定向到HTTPS。默认值：`false`。
nginx.ingress.kubernetes.io/permanent-redirect	永久重定向的目标URL，必须包含Scheme（HTTP或HTTPS）。
nginx.ingress.kubernetes.io/permanent-redirect-code	永久重定向的HTTP状态码，默认值为301。
nginx.ingress.kubernetes.io/temporal-redirect	临时重定向的目标URL，必须包含Scheme（HTTP或者HTTPS）。
nginx.ingress.kubernetes.io/app-root	修改应用根路径，对于访问`/`的请求将会被重定向为设置的新路径。

以下是永久重定向的目标URL配置示例，展示如何通过Ingress规则将访问foo.com的请求重定向至bar.com。

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: ingress-nginx
  annotations:
    kubernetes.io/ingress.class: "nginx"
    nginx.ingress.kubernetes.io/permanent-redirect: "https://bar.com"
spec:
  ingressClassName: nginx
  rules:
  - host: foo.com
    http:
      paths:
      - path: "/"
        pathType: ImplementationSpecific
        backend:
         service:
            name: httpbin
            port:
              number: 8000

Rewrite重写

以下是Nginx Ingress重写Rewrite注释。

注解	描述

注解	描述
nginx.ingress.kubernetes.io/rewrite-target	重写Path，支持捕获组（Capture Group）。配置示例请参见配置URL重定向的路由服务。
nginx.ingress.kubernetes.io/upstream-vhost	重写Host。

以下是Rewrite重写Host配置示例，将请求example.com/test在转发至后端服务之前，重写为test.com/test。

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  annotations:
    nginx.ingress.kubernetes.io/upstream-vhost: "test.com"
  name: demo
spec:
  ingressClassName: nginx
  rules:
    - host: example.com
      http:
        paths:
          - backend:
              service:
                name: demo-service
                port: 
                  number: 80
            path: /test
            pathType: ImplementationSpecific

限流

为了确保服务的稳定性，可以通过配置限流策略来控制每个客户端IP的请求频率和并发连接数。以下是相关的注解及其说明：

注解	描述

注解	描述
nginx.ingress.kubernetes.io/limit-connections	单个IP地址允许的最大并发连接数。超过此限制的请求会返回503错误。
nginx.ingress.kubernetes.io/limit-rate	每秒允许发送到单个连接的最大千字节数。设置为零禁用速率限制。需要启用代理缓冲才能使用此功能。
nginx.ingress.kubernetes.io/limit-whitelist	从速率限制中排除的客户端IP地址范围，格式为逗号分隔的CIDR列表。
nginx.ingress.kubernetes.io/limit-rpm	每分钟从单个IP地址接收的最大请求数。突发限制设置为此限制乘以突发乘数（默认乘数为5）。超出限值后将返回limit-req-status-code（默认值为503）。
nginx.ingress.kubernetes.io/limit-rps	每秒从单个IP地址接收的最大请求数。突发限制设置为此限制乘以突发乘数（默认乘数为5）。超出限值后返回limit-req-status-code（默认值为503）。
nginx.ingress.kubernetes.io/limit-burst-multiplier	指定突发请求数量的乘数。默认突发乘数为5，该注解用于覆盖默认乘数。

以下是限流配置示例。

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: ingress-nginx
  annotations:
    kubernetes.io/ingress.class: "nginx"
    nginx.ingress.kubernetes.io/limit-rate: 100K
    nginx.ingress.kubernetes.io/limit-whitelist: 10.1.10.100
    nginx.ingress.kubernetes.io/limit-rps: 1
    nginx.ingress.kubernetes.io/limit-rpm: 30
spec:
  rules:
  - host: iphone.example.com 
    http:
      paths:
      - path: 
        backend:
          serviceName: iphone-backend-svc
          servicePort: 80

容灾

为了确保服务的高可用性和稳定性，Nginx Ingress提供了容灾（Fallback）机制，以处理服务节点不可用或特定错误响应的情况。以下是关于相关注解的说明：

注解	描述

注解

描述

nginx.ingress.kubernetes.io/default-backend

容灾服务。当Ingress定义的服务没有可用节点时，请求会自动转发到该容灾服务。

您可以通过组件管理的Nginx Ingress的组件中进行全局配置。

nginx.ingress.kubernetes.io/custom-http-errors

该注解和default-backend一起工作。当后端服务返回指定HTTP响应码，原始请求会被再次转发至容灾服务。

重要

转发至容灾服务时，请求的Path会被重写为/，该行为与Ingress-nginx保持一致

与ConfigMap中的custom-http-errors配置相同，此注解将设置Nginx proxy-intercept-errors，仅对于与此Ingress关联的NGINX路径有效。

不同的Ingress可以为其各自的服务指定不同的错误码集合。如果同时在全局和注解中指定custom-http-errors，此注解中的错误码设置将覆盖全局设置，针对相应Ingress的主机名和路径生效。

灰度发布

灰度发布和蓝绿发布是广泛采用的策略，以确保应用的平滑升级和高可用性。通过以下注释配置可以实现灵活的流量管理，从而满足不同发布需求。更多详情请参见通过Nginx Ingress实现灰度发布和蓝绿发布。

注解	描述

注解	描述
nginx.ingress.kubernetes.io/canary	开启或关闭灰度发布。
nginx.ingress.kubernetes.io/canary-by-header	基于Request Header Key 流量切分。
nginx.ingress.kubernetes.io/canary-by-header-value	基于Request Header Value 流量切分，Value为精确匹配。
nginx.ingress.kubernetes.io/canary-by-header-pattern	基于Request Header Value 流量切分，Value为正则匹配。
nginx.ingress.kubernetes.io/canary-by-cookie	基于Request Cookie Key 流量切分。
nginx.ingress.kubernetes.io/canary-weight	基于权重流量切分。
nginx.ingress.kubernetes.io/canary-weight-total	权重总和。

超时相关配置

以下是Ingress Nginx的超时配置选项，包括全局超时配置和特定资源的自定义超时设置。使用合适的配置可以优化连接性能和可靠性。

全局超时配置

通过kubectl edit cm -n kube-system nginx-configuration命令，编辑以下配置项配置全局超时。

配置项	描述	默认值

配置项	描述	默认值
`proxy-connect-timeout`	设置与代理服务器建立连接的超时时间。	默认5s，但通常不能超过75s。
`proxy-read-timeout`	设置从代理服务器读取响应的超时。该超时仅在两个连续的读取操作之间设置，而不是为整个响应的传输设置。	60s
`proxy-send-timeout`	设置向代理服务器传输请求的超时。该超时只在两个连续的写操作之间设置，而不是为整个请求的传输设置。	60s
`proxy-stream-next-upstream-timeout`	限制允许将连接传递到下一个服务器的时间。	默认为 600s，设置为0值则关闭此限制。
`proxy-stream-timeout`	设置客户端或代理服务器连接上两个连续的读或写操作之间的超时。如果在这个时间内没有传输数据，连接就会关闭	600s
`upstream-keepalive-timeout`	设置一个超时时间，在这个时间内，与上游服务器的空闲连接将保持开放。	社区默认值：60s ACK默认值：900s
`worker-shutdown-timeout`	设置优雅停机的超时时间。	240s
`proxy-protocol-header-timeout`	设置接收代理协议头文件的超时值。默认的5秒可以防止TLS直通处理程序无限期地等待一个中断的连接。	5s
`ssl-session-timeout`	设置 SSL 会话缓存中的会话参数的有效时间。会话过期时间是相对于创建时间而言的。每个会话缓存会占用大约0.25MB的空间。	10m
`client-body-timeout`	定义读取客户端请求正文的超时。	60s
`client-header-timeout`	定义读取客户端请求头的超时。	60s

特定资源自定义超时配置

以下是特定资源自定义超时配置注释，以及相关的参数配置。

配置项	描述

配置项	描述
`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-request-buffering`	是否启用请求缓冲功能。 `on`启用请求缓冲。如果启用了请求缓冲功能，则会在接收到完整的请求数据之后才将其转发到后端工作负载，否则可能会在接收到部分请求数据时就开始转发请求。HTTP/1.1 Chunked编码的请求不受此参数限制，始终会进行缓冲。 `off`则禁用请求缓冲。如果禁用，发送过程中出现发送错误，就不会选择下一个工作负载进行重试。

跨域

在Nginx Ingress 控制器中设置跨域资源共享（CORS）可以帮助你控制何种资源可以被跨域访问。更多详情请参见Nginx Ingress跨域配置说明

注解	描述

注解	描述
nginx.ingress.kubernetes.io/enable-cors	开启或关闭跨域。
nginx.ingress.kubernetes.io/cors-allow-origin	允许的第三方站点。
nginx.ingress.kubernetes.io/cors-allow-methods	允许的请求方法，如GET、POST、PUT等。
nginx.ingress.kubernetes.io/cors-allow-headers	允许的请求Header。
nginx.ingress.kubernetes.io/cors-expose-headers	允许的暴露给浏览器的响应Header。
nginx.ingress.kubernetes.io/cors-allow-credentials	是否允许携带凭证信息。
nginx.ingress.kubernetes.io/cors-max-age	预检结果的最大缓存时间。

重试逻辑

以下用于配置请求重试逻辑的注解。配置这些注解可以帮助提升服务的高可用性和容错能力。

注解	描述

注解	描述
nginx.ingress.kubernetes.io/proxy-next-upstream-tries	如果满足重试条件，则可用重试次数，默认值为3。
nginx.ingress.kubernetes.io/proxy-next-upstream-timeout	请求重试的超时时间，单位秒。默认未配置超时时间。
nginx.ingress.kubernetes.io/proxy-next-upstream	配置重试策略或者重试条件，可以使用多个组合用空格分隔，例如设置为`http_500`、`http_502`、支持下列策略： `error`：连接失败，直接返回。 `timeout`：连接超时，直接返回。 `invalid_response`：无效返回状态码，直接返回。 `http_xxx`：xxx可以替换为状态码，例如设置为http_500的含义是上游返回500时选择下一个工作负载。支持的状态码为：500、502、503、504、403、404、429。 `off`：关闭重试机制，不论任何错误都直接返回。

IP访问控制

通过以下注解配置Nginx Ingress中的IP黑白名单。

注解	描述

注解	描述
nginx.ingress.kubernetes.io/whitelist-source-range	IP白名单，支持IP地址或CIDR地址块，以英文半角逗号（,）分隔。
nginx.ingress.kubernetes.io/denylist-source-range	IP黑名单，支持IP地址或CIDR地址块，以英文半角逗号（,）分隔。

以下是配置IP白名单注释示例。

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: ingress-nginx
  annotations:
    kubernetes.io/ingress.class: "nginx"
    nginx.ingress.kubernetes.io/whitelist-source-range: 10.1.10.2
spec:
  rules:
  - host: iphone.exmaple.com 
    http:
      paths:
      - path: 
        backend:
          serviceName: iphone-example-svc
          servicePort: 80

您还可以使用命令kubectl edit cm -n kube-system nginx-configuration通过编辑配置中的whitelist-source-range 来进行全局设置。

流量镜像

通过配置以下注释，您可以实现对应用的流量复制。可以在不影响生产环境的情况下帮助您识别潜在的问题，提高应用的稳定性。配置详情参见通过Ingress Controller来实现应用的流量复制。

注解	描述

注解	描述
nginx.ingress.kubernetes.io/mirror-target	指定流量目标地址。支持Service或外部地址，例如，您可以设置为`https://test.env.com/$request_uri`，其中`$request_uri` 代表将原始请求的URI添加到目标URL的末尾。
nginx.ingress.kubernetes.io/mirror-request-body	是否镜像请求流量的Body。
nginx.ingress.kubernetes.io/mirror-host	指定用于转发请求Host信息。

安全防护

为了在客户端与网关之间的通信中提供更高的安全性，以下注解可以加强通信加密。更多详情请参见Nginx Ingress Controller安全加密。

客户端与网关之间的通信加密

通过以下注解来加强客户端与网关之间的通信安全性。

注解	作用域	描述

注解

作用域

描述

nginx.ingress.kubernetes.io/ssl-cipher

域名

指定TLS的加密套件，可以指定多个（TLS的加密套件之间使用英文冒号分隔），仅当TLS握手时采用TLSv1.0-1.2生效。默认加密套件如下：

ECDHE-ECDSA-AES128-GCM-SHA256
ECDHE-RSA-AES128-GCM-SHA256
ECDHE-ECDSA-AES128-SHA
ECDHE-RSA-AES128-SHA
AES128-GCM-SHA256
AES128-SHA
ECDHE-ECDSA-AES256-GCM-SHA384
ECDHE-RSA-AES256-GCM-SHA384
ECDHE-ECDSA-AES256-SHA
ECDHE-RSA-AES256-SHA
AES256-GCM-SHA384
AES256-SHA

nginx.ingress.kubernetes.io/auth-tls-secret

域名

网关使用的CA证书，用于验证mTLS握手期间，客户端提供的证书。该注解主要应用于网关需要验证客户端身份的场景。

对应的Secret中必须包含一个名为ca.crt的文件。ca.crt文件应包含完整的证书颁发机构链。

网关与后端服务之间通信加密

通过以下注解来加强网关与后端服务之间的通信安全性。

注解	作用域	描述

注解	作用域	描述
nginx.ingress.kubernetes.io/proxy-ssl-secret	服务	网关使用的客户端证书，用于后端服务对网关进行身份认证。该配置必须使用PEM格式的证书。 Secret中必须包含以下文件： `tls.crt`: 客户端证书。 `tls.key`: 客户端证书的密钥。 `ca.crt`: 信任的CA证书，用于验证代理HTTPS服务器的证书。注释的取值格式必须为`"namespace/secretName"`。
nginx.ingress.kubernetes.io/proxy-ssl-name	服务	TLS握手期间使用的SNI。
nginx.ingress.kubernetes.io/proxy-ssl-server-name	服务	开启或关闭在TLS握手期间使用SNI。

安全认证

以下是有关Basic认证的注释，确保只有授权用户才能访问应用程序接口。

注解	作用域	描述

注解	作用域	描述
nginx.ingress.kubernetes.io/auth-type	Ingress	认证类型，支持`basic`。
nginx.ingress.kubernetes.io/auth-secret	Ingress	Secret名字，格式支持namespace/secretName，包含被授予能够访问该Ingress上定义的路由的访问权限的用户名和密码。
nginx.ingress.kubernetes.io/auth-secret-type	Ingress	Secret内容格式。 `auth-file`：Data的Key为auth，Value为用户名和密码，多账号用回车分隔。 `auth-map`：Data的Key为用户名，Value为密码。
nginx.ingress.kubernetes.io/auth-realm	Ingress	保护域。相同的保护域共享用户名和密码。

配置示例：

使用htpasswd命令行工具生成密码文件。

htpasswd -c auth joker

查看生成的密码文件。

cat auth 
# 输出示例： joker:$apr1$R.G4krs/$hh0mX8xe4A3lYKMjvlVs1/

将生成的密码文件创建为Secret：

kubectl create secret generic basic-auth --from-file=auth

在Ingress资源中应用Basic认证，配置示例如下：

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: ingress-nginx
  annotations:
    kubernetes.io/ingress.class: "nginx"
    nginx.ingress.kubernetes.io/auth-type: basic
    nginx.ingress.kubernetes.io/auth-secret: basic-auth
spec:
  rules:
  - host: iphone.example.com 
    http:
      paths:
      - path: 
        backend:
          serviceName: iphone-backend-svc
          servicePort: 80