Nginx Ingress配置词典

索引

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"

以下是配置项说明。

Ingress支持Annotation

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

负载均衡算法

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

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

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的会话亲和性的注释和说明。

以下是配置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重定向注释。

以下是永久重定向的目标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注释。

以下是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的请求频率和并发连接数。以下是相关的注解及其说明：

以下是限流配置示例。

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实现灰度发布和蓝绿发布。

超时相关配置

以下是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跨域配置说明

重试逻辑

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

IP访问控制

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

以下是配置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 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认证的注释，确保只有授权用户才能访问应用程序接口。

配置示例：

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

   htpasswd -c auth joker

   查看生成的密码文件。

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

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

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

3. 在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