NGINX Ingress控制器

插件简介

Kubernetes通过kube-proxy服务实现了Service的对外发布及负载均衡，它的各种方式都是基于传输层实现的。在实际的互联网应用场景中，不仅要实现单纯的转发，还有更加细致的策略需求，如果使用真正的负载均衡器更会增加操作的灵活性和转发性能。

基于以上需求，Kubernetes引入了资源对象Ingress，Ingress为Service提供了可直接被集群外部访问的虚拟主机、负载均衡、SSL代理、HTTP路由等应用层转发功能。

Kubernetes官方发布了基于Nginx的Ingress控制器，CCE的NGINX Ingress控制器插件直接使用社区模板与镜像。Nginx Ingress控制器会将Ingress生成一段Nginx的配置，并将Nginx配置通过ConfigMap进行储存，这个配置会通过Kubernetes API写到Nginx的Pod中，然后完成Nginx的配置修改和更新，详细工作原理请参见工作原理。

开源社区地址：https://github.com/kubernetes/ingress-nginx

• 2.3.3及以上版本的Nginx Ingress默认仅支持TLS v1.2及v1.3版本，如果客户端TLS版本低于v1.2，会导致客户端与Nginx Ingress协商时报错。如果需要支持更多TLS版本，请参见TLS/HTTPS。
• 安装该插件时，您可以通过“nginx配置参数”添加配置，此处的设置将会全局生效，该参数直接通过配置nginx.conf生成，将影响管理的全部Ingress，相关参数可通过ConfigMaps查找，如果您配置的参数不包含在ConfigMaps所列出的选项中将不会生效。
• 安装该插件后，您在CCE控制台创建Ingress时可以选择对接Nginx控制器，并通过“注解”设置Nginx Ingress功能，支持的注解字段详情请参见Annotations。
• 请勿手动修改和删除CCE自动创建的ELB和监听器，否则将出现工作负载异常；若您已经误修改或删除，请卸载Nginx Ingress插件后重装。

工作原理

Nginx Ingress由资源对象Ingress、Ingress控制器、Nginx三部分组成，Ingress控制器用以将Ingress资源实例组装成Nginx配置文件（nginx.conf），并重新加载Nginx使变更的配置生效。当它监听到Service中Pod变化时通过动态变更的方式实现Nginx上游服务器组配置的变更，无须重新加载Nginx进程。工作原理如图1所示。

• Ingress：一组基于域名或URL把请求转发到指定Service实例的访问规则，是Kubernetes的一种资源对象，Ingress实例被存储在对象存储服务etcd中，通过接口服务被实现增、删、改、查的操作。
• Ingress控制器（Ingress Controller）：用以实时监控资源对象Ingress、Service、End-point、Secret（主要是TLS证书和Key）、Node、ConfigMap的变化，自动对Nginx进行相应的操作。
• Nginx：实现具体的应用层负载均衡及访问控制。

图1 Nginx Ingress工作原理

注意事项

• 对于v1.23版本前的集群，通过API接口创建的Ingress在注解中必须添加kubernetes.io/ingress.class: "nginx"。如果集群中安装了多套NGINX Ingress控制器，需将nginx替换为自定义的控制器名称，用于识别Ingress对接的控制器实例。
• 独享型ELB规格必须支持网络型（TCP/UDP），且网络类型必须支持私网（有私有IP地址）。
• 运行Nginx Ingress控制器实例的节点以及该节点上运行的容器，无法访问Nginx Ingress，请将工作负载Pod与Nginx Ingress控制器实例进行反亲和部署，具体操作步骤请参见工作负载与Nginx Ingress控制器实例反亲和部署。
• Nginx Ingress控制器实例在升级时会预留10s的宽限时间，用于删除ELB后端的Nginx Ingress控制器。
• Nginx Ingress控制器实例的优雅退出时间为300s，若插件升级时存在超过300s的长连接，长连接会被断开，出现服务短暂中断。

前提条件

在安装此插件之前，您需要存在一个可用集群，且集群中包含一个可用节点。若没有可用集群 ，请参照购买Standard/Turbo集群中的步骤创建。

安装插件

1. 登录CCE控制台，单击集群名称进入集群，在左侧导航栏中选择“插件中心”，在右侧找到NGINX Ingress控制器插件，单击“安装”。
2. 在安装插件页面，根据需求选择“规格配置”。

   您可根据需求调整插件实例数和资源配额。实例数为1时插件不具备高可用能力，当插件实例所在节点异常时可能导致插件功能无法正常使用，请谨慎选择。

3. 设置插件支持的“参数配置”。
   • 控制器名称：自定义控制器名称，该名称为Ingress控制器的唯一标识，同一个集群中不同的控制器名称必须唯一，且不能设置为cce（cce是ELB Ingress Controller的唯一标识）。创建Ingress时，可通过指定控制器名称，声明该Ingress由此控制器进行管理。
   • 插件安装的命名空间：选择Ingress控制器所在的命名空间。
   • 负载均衡器：支持对接共享型或独享型负载均衡实例，如果无可用实例，请先创建。负载均衡器需要拥有至少两个监听器配额，且端口 80 和 443 没有被监听器占用。
     选择共享型负载均衡实例，支持开启“获取客户端IP”功能，开启后使用Nginx Ingress访问应用服务端，服务端即可获取客户端的源IP。而使用独享型负载均衡实例时默认开启获取客户端IP，无需配置。

     

     该功能在v1.23.17-r0、v1.25.12-r0、v1.27.9-r0、v1.28.7-r0、v1.29.3-r0及以上版本的集群支持开启。

     开启/关闭“获取客户端IP”的过程中，如果已经配置了后端服务，则访问流量会中断，请谨慎操作。

   • 开启准入校验：针对Ingress资源的准入控制，以确保控制器能够生成有效的配置。开启后将会对Nginx类型的Ingress资源配置做准入校验，若校验失败，请求将被拦截。关于准入校验详情，请参见准入控制。
     

     • 开启准入校验后，会在一定程度上影响Ingress资源的请求响应速度。
     • 仅2.4.1及以上版本的插件支持开启准入校验。
   • nginx配置参数：配置nginx.conf文件，将影响管理的全部Ingress。您可以选择使用“界面化配置”或“YAML配置”，其中“界面化配置”在2.2.75、2.6.26、3.0.1及以上版本的NGINX Ingress控制器插件中支持。

     如果您需要配置社区支持的自定义参数，请选择“YAML配置”，相关参数可通过ConfigMaps查找。此处以设置keep-alive-requests参数为例，设置保持活动连接的最大请求数为100。

     {
         "keep-alive-requests": "100"
     }

     

     • 如果您配置的参数不包含在ConfigMaps所列出的选项中，配置将不会生效。
     • 配置参数的值必须为字符串格式，否则无法安装成功。
     CCE在2.2.75、2.6.26、3.0.1及以上版本的NGINX Ingress控制器插件中默认支持可视化页面配置以下配置参数。

     配置参数名称	nginx配置参数	说明	默认值
     Work最大连接数	max-worker-connections	每个NGINX工作进程能够同时处理的最大连接数。这个参数是用来控制工作进程的负载量的，高并发环境下需要设置较高的值以确保系统稳定性。注意，此处不仅包含客户端连接，还包括到后端服务器的连接。	65536
     Keepalive链接最大请求数	keep-alive-requests	用于控制单个keepalive连接可以处理的最大请求数。当达到最大请求数时，连接将被关闭。	100
     上游服务器最大保持连接数	upstream-keepalive-connections	激活与上游服务器连接的缓存。该参数设置每个工作进程中保留在缓存中的闲置keepalive连接的最大数量。当超过这个数字时，最久未使用的连接将被关闭。	320
     上游服务器最大连接时间	upstream-keepalive-timeout	上游服务器与后端服务器建立的keepalive连接的超时时间，单位是秒。表示NGINX在这段时间内可以保持连接以供重用，这样可以减少建立新连接所需的开销，在高QPS场景下能显著提高性能。	900
     请求超时时间	proxy-connect-timeout	客户端到代理服务器间建立连接的超时时间，单位是秒。如果在10秒内无法连接到后端服务器，NGINX将返回502 (Bad Gateway) 错误。适合需要连接速度较快的应用场景。	10
     请求体最大值	proxy-body-size	指定NGINX代理发送到后端服务器时，可以接受的请求体的最大值。这个值限制了上传文件或者提交大数据表单的大小。如果请求体超过了这个值，将返回413 (Payload Too Large) 错误。	20m
     允许后端返回Server标头信息	allow-backend-server-header	通常情况下，NGINX会剥离后端服务器的Server头部信息，也就是服务器向客户端发送的标识信息。如设置为true，则NGINX将允许后端服务器的Server头部信息直接传递给客户端。从安全角度来看，最好将其关闭来避免泄露服务器类型及版本的信息。	关闭
     允许标头中带下划线	enable-underscores-in-headers	某些HTTP头部可能包含下划线（例如X_Custom-Header），但是依据RFC标准不建议这样使用，因此许多服务器默认不允许这样做。如果您有需要使用这种头部信息的情况，比如某些第三方服务或客户端使用了下划线命名的头部信息，可以启用这个参数。	关闭
     生成请求ID	generate-request-id	每个请求被收到时，NGINX会生成一个唯一的请求ID，这个ID通常会被记录到日志中，或者通过头部信息传递到后端服务器。这对于请求的追踪和调试来说非常有用，尤其是在分布式系统中定位问题。	开启
     忽略无效标头	ignore-invalid-headers	在接收到包含无效头部的HTTP请求时，NGINX默认会拒绝该请求。这个配置项开启后，NGINX将会忽略这些无效的头部信息并继续处理请求。在面对一些不完全符合HTTP标准的客户端时比较有用。	开启
     启用端口重用	reuse-port	启用SO_REUSEPORT选项允许多进程/线程绑定到相同的IP/Port组合，这样可以有效地提高服务器的并发性能，特别是多核CPU情况下。它允许在同一个端口上接受更多的新连接。	开启
     响应体中携带Server信息	server-tokens	关闭NGINX默认在响应头中加入的Server信息，这个信息通常会包含NGINX版本。禁用这个选项有助于隐藏服务器的信息，从而增强安全性，避免潜在的攻击者利用版本信息来进行攻击。	关闭
     支持HTTP协议自动重定向为HTTPS	ssl-redirect	禁用从HTTP自动重定向到HTTPS。例如，默认情况下如果您只希望在某些条件下（如登录页面）使用HTTPS而其他页面使用HTTP，那么您可以禁用这个选项来避免默认的重定向行为。	关闭
     工作线程CPU亲和性	worker-cpu-affinity	自动分配工作进程到特定的CPU核心，提高多核系统的性能。比如在多核服务器上，可以使某些工作进程固定在特定的CPU核上；这样可以减少上下文切换，提高处理效率。	自动亲和

   • 开启指标采集：插件版本不低于2.4.12时，支持采集Prometheus监控指标。具体操作详情请参见监控NGINX Ingress控制器指标。
   • 服务器默认证书：选择一个IngressTLS或kubernetes.io/tls类型的密钥，用于配置Nginx Ingress控制器启动时的默认证书。如果无可选密钥，您可以单击“创建TLS类型的密钥证书”进行新建，详情请参见创建密钥。关于默认证书更多说明请参见Default SSL Certificate。
   • 404服务：默认使用插件自带的404服务。支持自定义404服务，填写“命名空间/服务名称”，如果服务不存在，插件会安装失败。
   • 日志采集：开启日志采集后，可快速进行日志查询与分析，并对接仪表盘进行可视化展示。详情请参见采集NGINX Ingress访问日志。
   • 添加TCP/UDP服务：Nginx Ingress默认仅支持转发外部HTTP和HTTPS流量，通过添加TCP/UDP端口映射，可实现转发外部TCP/UDP流量到集群内服务。关于添加TCP/UDP服务的更多信息，请参见暴露TCP/UDP服务。
     • 协议：选择TCP或UDP。
     • 服务端口：ELB监听器使用的端口，端口范围为1-65535。
     • 目标服务命名空间：请选择Service所在的命名空间。
     • 目标服务名称：请选择已有Service。页面列表中的查询结果已自动过滤不符合要求的Service。
     • 目标服务访问端口：可选择目标Service的访问端口。
     

     • 集群版本为v1.19.16-r5、v1.21.8-r0、v1.23.6-r0及以上时，支持设置TCP/UDP混合协议能力。
     • 集群版本为v1.19.16-r5、v1.21.8-r0、v1.23.6-r0、v1.25.2-r0及以上时，支持设置TCP/UDP混合协议使用相同的对外端口。
   • 扩展参数配置（可选）：可选配置，插件的额外扩展参数配置。当扩展参数配置与界面配置冲突时，将以扩展参数配置为准。
     • extraArgs：额外可配置的nginx-ingress-controller组件的启动参数，社区支持的启动参数请参考文档。
     • extraInitContainers：nginx-ingress-controller的初始化容器配置。在2.2.82、2.6.32、3.0.8及以上插件版本中支持，默认使用优化性能的内核参数配置。
     • maxmindLicenseKey：Maxmind许可证密钥，可用于下载GeoLite2数据库。在2.2.82、2.6.32、3.0.8及以上插件版本中支持，该参数为Nginx Ingress设置配置use-geoip2能力的必填参数。

4. 设置插件实例的部署策略。
   

   • 调度策略对于DaemonSet类型的插件实例不会生效。
   • 设置多可用区部署或节点亲和策略时，需保证集群中存在满足调度策略的节点且拥有足够的资源，否则插件实例将无法运行。

   表1 插件调度配置

   参数	参数说明
   多可用区部署	优先模式：优先将插件的Deployment实例调度到不同可用区的节点上，如集群下节点不满足多可用区，插件实例将调度到单可用区下的不同节点。 均分模式：插件Deployment实例均匀调度到当前集群下各可用区，增加新的可用区后建议扩容插件实例以实现跨可用区高可用部署；均分模式限制不同可用区间插件实例数相差不超过1，单个可用区资源不足会导致后续其他实例无法调度。 说明： 均分模式仅支持kube-system和monitoring命名空间。 强制模式：插件Deployment实例强制调度到不同可用区的节点上，每个可用区下最多运行一个实例。如集群下节点不满足多可用区，插件实例将无法全部运行。节点故障后，插件实例存在无法迁移风险。
   节点亲和	不配置：插件实例不指定节点亲和调度。 指定节点调度：指定插件实例部署的节点。若不指定，将根据集群默认调度策略进行随机调度。 指定节点池调度：指定插件实例部署的节点池。若不指定，将根据集群默认调度策略进行随机调度。 自定义亲和策略：填写期望插件部署的节点标签实现更灵活的调度策略，若不填写将根据集群默认调度策略进行随机调度。 同时设置多条自定义亲和策略时，需要保证集群中存在同时满足所有亲和策略的节点，否则插件实例将无法运行。
   容忍策略	容忍策略与节点的污点能力配合使用，允许（不强制）插件的 Deployment 实例调度到带有与之匹配的污点的节点上，也可用于控制插件的 Deployment 实例所在的节点被标记污点后插件的 Deployment 实例的驱逐策略。 插件会对实例添加针对node.kubernetes.io/not-ready和node.kubernetes.io/unreachable污点的默认容忍策略，容忍时间窗为60s。 详情请参见设置容忍策略。

5. 单击“安装”。

安装多个NGINX Ingress控制器

1. 登录CCE控制台，单击集群名称进入集群，在左侧导航栏中选择“插件中心”，在右侧找到已经安装的NGINX Ingress控制器插件，单击“新增”。
2. 在安装插件页面，重新配置NGINX Ingress控制器参数，参数说明详情请参见安装插件。
3. 参数配置完成后，单击“安装”。
4. 等待插件安装指令下发完成，您可以返回“插件中心”，单击“管理”，在插件详情页查看已安装的控制器实例。

组件说明

工作负载与Nginx Ingress控制器实例反亲和部署

运行Nginx Ingress控制器实例的节点以及该节点上运行的容器，无法访问Nginx Ingress，为避免这个问题发生，需要将工作负载与Nginx Ingress控制器实例反亲和部署，即工作负载Pod无法调度至Nginx Ingress控制器实例运行的节点。

apiVersion: apps/v1
kind: Deployment
metadata:
  name: nginx
spec:
  replicas: 1
  selector:
    matchLabels:
      app: nginx
  strategy:
    type: RollingUpdate
  template:
    metadata:
      labels:
        app: nginx
    spec:
      containers:
      - image: nginx:aplpine
        imagePullPolicy: IfNotPresent
        name: nginx
      imagePullSecrets:
      - name: default-secret
      affinity:
        podAntiAffinity:
          requiredDuringSchedulingIgnoredDuringExecution:
            - labelSelector:
                matchExpressions:    #通过Nginx Ingress控制器实例的标签实现反亲和
                  - key: app
                    operator: In
                    values:
                      - nginx-ingress   #如果集群中安装了多套Nginx Ingress控制器，对应的标签值为nginx-ingress-<控制器名称>
                  - key: component
                    operator: In
                    values:
                      - controller
              namespaces:
                - kube-system
              topologyKey: kubernetes.io/hostname

相关操作

使用模板包自定义部署多个Nginx Ingress Controller

版本记录