从社区版Ingress Controller迁移到F5 NGINX Ingress Controller

NGINX | 2022年5月19日
Amir Rawdat
Amir Rawdat解决方案工程师

编者按：本文摘自我们的综合电子书《使用F5 NGINX管理Kubernetes流量：实用指南》。立即免费下载。

许多首次部署Kubernetes的组织会从由Kubernetes社区开发和维护的NGINX Ingress控制器（kubernetes/ingress-nginx）入手。不过，随着Kubernetes部署日趋成熟，一些组织发现，在继续使用NGINX作为数据平面的同时，还需要高级功能或商业支持。

一种选择是迁移到由F5 NGINX开发和维护的NGINX Ingress Controller（nginxinc/kubernetes-ingress）。本文提供完整说明，帮助您避免因这两个项目之间的差异而产生的一些复杂问题。

不确定这些选项有何区别？请阅读博客文章《Ingress Controller 选择指南，第 4 部分：NGINX Ingress Controller 选项》。

为便于在本文后续内容中区分这两个项目，我们将由Kubernetes社区维护的NGINX Ingress Controller（kubernetes/ingress-nginx）称为“社区Ingress控制器”，将由F5 NGINX维护的NGINX Ingress Controller（nginxinc/kubernetes-ingress）称为“NGINX Ingress Controller”。

可通过以下两种方式从社区 Ingress 控制器迁移到 NGINX Ingress Controller：

选项1：使用NGINX Ingress资源进行迁移

使用此迁移选项时，可使用标准Kubernetes Ingress资源设置基础功能，并使用NGINX Ingress资源增强配置，从而扩展功能并提高易用性。

NGINX Ingress资源的自定义资源定义（CRD），包括VirtualServer, VirtualServerRoute、TransportServer、GlobalConfiguration和Policy，可帮助您轻松地将配置中不同部分的控制权委派给不同团队（例如AppDev团队和安全团队），同时提高配置的安全性并加强验证。

配置SSL终止和基于HTTP路径的路由

下表对照了标准Kubernetes Ingress资源的spec字段与NGINX spec资源的VirtualServer字段中SSL终止和第7层基于路径的路由配置。这两种资源的语法和缩进略有不同，但实现的基本Ingress功能相同。

Kubernetes Ingress资源 NGINX VirtualServer资源 
apiVersion: networking.k8s.io/v1kind: Ingressmetadata:  name: nginx-testspec:  tls:    - hosts:      - foo.bar.com      secretName: tls-secret  rules:    - host: foo.bar.com      http:        paths:        - path: /login          backend:             serviceName: login-svc            servicePort: 80        - path: /billing            serviceName: billing-svc            servicePort: 80

apiVersion: networking.k8s.io/v1kind: VirtualServermetadata:  name: nginx-testspec:  host: foo.bar.com   tls:    secret: tls-secret  upstreams:    - name: login      service: login-svc      port: 80    - name: billing       service: billing-svc      port: 80  routes:   - path: /login    action:      pass: login   - path: /billing     action:       pass: billing

配置TCP/UDP负载均衡和TLS透传

使用社区版Ingress控制器时，Kubernetes ConfigMap API对象是公开TCP和UDP服务的唯一方式。

使用NGINX Ingress Controller时，TransportServer资源可定义多种TCP/UDP和TLS直通负载均衡选项。TransportServer资源与GlobalConfiguration资源结合使用，以控制入站和出站连接。

有关更多信息，请参阅博客文章《NGINX Ingress资源对TCP、UDP和TLS直通服务的支持》。

将社区版Ingress Controller注解转换为NGINX Ingress资源

生产级Kubernetes部署通常需要扩展基本Ingress规则，以实现高级用例，包括金丝雀部署、蓝绿部署、流量限速、入站和出站流量操控等。

社区版Ingress控制器使用Kubernetes注解实现了其中许多用例。但是，这些注解中有许多是使用自定义Lua扩展构建的，仅适用于非常具体的NGINX Ingress资源定义，因此不适合在稳定且受支持的生产环境中实现高级功能。

以下各节将介绍如何将社区版Ingress控制器注解转换为NGINX Ingress Controller资源。

金丝雀部署

即使频繁向生产容器工作负载推送代码更改，也必须继续为现有用户提供服务。金丝雀部署和蓝绿部署可帮助您做到这一点。您可以在NGINX Ingress Controller数据平面上执行这些部署，从而在生产级Kubernetes环境中实现稳定且可预测的更新。

下表列出了NGINX VirtualServer和VirtualServerRoute资源中与社区版Ingress控制器的以下注解相对应的字段：金丝雀部署。

社区版Ingress控制器按以下优先级顺序评估金丝雀注解：

  1. nginx.ingress.kubernetes.io/canary-by-header
  2. nginx.ingress.kubernetes.io/canary-by-cookie
  3. nginx.ingress.kubernetes.io/canary-by-weight

要让NGINX Ingress Controller以相同方式评估这些项，它们必须按该顺序出现在NGINX VirtualServer或VirtualServerRoute清单中。

社区版Ingress Controller NGINX Ingress Controller 
				nginx.ingress.kubernetes.io/canary: "true"nginx.ingress.kubernetes.io/canary-by-header: "httpHeader"
				
				matches:- conditions:  - header: httpHeader      value: never  action:    pass: echo   - header: httpHeader      value: always  action:    pass: echo-canaryaction:  pass: echo
				
				nginx.ingress.kubernetes.io/canary: "true"nginx.ingress.kubernetes.io/canary-by-header: "httpHeader"nginx.ingress.kubernetes.io/canary-by-header-value: "my-value"
				
				matches:- conditions:  - header: httpHeader      value: my-value  action:    pass: echo-canary action:  pass: echo
				
nginx.ingress.kubernetes.io/canary: "true"nginx.ingress.kubernetes.io/canary-by-cookie: "cookieName"
				
				matches:- conditions:  - cookie: cookieName      value: never  action:    pass: echo   - cookie: cookieName      value: always  action:    pass: echo-canaryaction:  pass: echo
				
nginx.ingress.kubernetes.io/canary: "true"nginx.ingress.kubernetes.io/canary-weight: "10"
				
splits:- weight: 90   action:    pass: echo- weight: 10    action:     pass: echo-canary

流量控制

在微服务环境中，应用本身具有短暂性，因此更容易返回错误响应。DevOps团队广泛采用流量控制策略（例如熔断、速率限制和连接数限制），以防应用运行状况不佳或未按预期运行时出现错误。

下表列出了NGINX VirtualServer和VirtualServerRoute资源中与社区版Ingress控制器注解对应的字段，这些注解用于速率限制、自定义HTTP错误、自定义默认后端和URI重写。

Community Ingress Controller NGINX Ingress Controller 
nginx.ingress.kubernetes.io/custom-http-errors: "code"nginx.ingress.kubernetes.io/default-backend: "default-svc"
				
				errorPages:- codes: [code]    redirect:      code: 301      url: default-svc
				
				nginx.ingress.kubernetes.io/limit-connections: "number"
				
				http-snippets: |    limit_conn_zone $binary_remote_addr zone=zone_name:size;routes:- path: /path    location-snippets: |      limit_conn zone_name number;
				
				nginx.ingress.kubernetes.io/limit-rate: "number"nginx.ingress.kubernetes.io/limit-rate-after: "number"
				
location-snippets: |    limit_rate number;    limit_rate_after number;
				
nginx.ingress.kubernetes.io/limit-rpm: "number"nginx.ingress.kubernetes.io/limit-burst-multiplier: "multiplier"
				
				rateLimit:    rate: numberr/m    burst: number * multiplier    key: ${binary_remote_addr}    zoneSize: size
				
nginx.ingress.kubernetes.io/limit-rps: "number"nginx.ingress.kubernetes.io/limit-burst-multiplier: "multiplier"
				
rateLimit:    rate: numberr/s    burst: number * multiplier    key: ${binary_remote_addr}    zoneSize: size
				
				nginx.ingress.kubernetes.io/limit-whitelist: "CIDR"
				
				http-snippets: |server-snippets: |
				
nginx.ingress.kubernetes.io/rewrite-target: "URI"
				
rewritePath: "URI"

如表所示，截至本文撰写时，NGINX Ingress资源尚未包含可直接转换以下4个社区Ingress控制器注解的字段，因此必须使用代码片段。NGINX Ingress Controller计划在未来版本中使用Policy资源直接支持这4个注解。

  • nginx.ingress.kubernetes.io/limit-connections
  • nginx.ingress.kubernetes.io/limit-rate
  • nginx.ingress.kubernetes.io/limit-rate-after
  • nginx.ingress.kubernetes.io/limit-whitelist

标头操作

HTTP标头包含对参与HTTP事务的系统至关重要的相关附加信息，因此在许多用例中，操作HTTP标头都很有用。例如，社区版Ingress控制器支持启用和设置跨源资源共享（CORS）标头。这类标头用于AJAX应用程序，即浏览器中的前端JavaScript代码连接到后端应用或Web服务器的场景。

下表列出了NGINX VirtualServer和VirtualServerRoute资源中与社区版Ingress控制器的标头操作注解相对应的字段。

社区版 Ingress Controller NGINX Ingress Controller 
				nginx.ingress.kubernetes.io/enable-cors: "true"nginx.ingress.kubernetes.io/cors-allow-credentials: "true"nginx.ingress.kubernetes.io/cors-allow-headers: "X-Forwarded-For" nginx.ingress.kubernetes.io/cors-allow-methods: "PUT, GET, POST, OPTIONS"nginx.ingress.kubernetes.io/cors-allow-origin: "*"nginx.ingress.kubernetes.io/cors-max-age: "seconds"
				
				responseHeaders:  add:     - name: Access-Control-Allow-Credentials      value: "true"     - name: Access-Control-Allow-Headers      value: "X-Forwarded-For"    - name: Access-Control-Allow-Methods      value: "PUT, GET, POST, OPTIONS"    - name: Access-Control-Allow-Origin      value: "*"    - name: Access-Control-Max-Age      value: "seconds"

代理和负载均衡

根据具体用例，您可能还需要在NGINX Ingress Controller中配置其他代理和负载均衡功能，包括设置负载均衡算法，以及代理连接的超时和缓冲设置。

下表列出了NGINX VirtualServer和VirtualServerRoute资源的upstream字段中与社区版Ingress控制器注解对应的语句，这些注解用于自定义NGINX负载均衡、代理超时、代理缓冲以及将连接路由到服务的Cluster IP地址和端口。

社区版Ingress控制器 NGINX Ingress Controller 
nginx.ingress.kubernetes.io/load-balance
				
				lb-method
				
				nginx.ingress.kubernetes.io/proxy-buffering
				
buffering
				
				nginx.ingress.kubernetes.io/proxy-buffers-numbernginx.ingress.kubernetes.io/proxy-buffer-size
				
				buffers
				
				nginx.ingress.kubernetes.io/proxy-connect-timeout
				
				connect-timeout
				
				nginx.ingress.kubernetes.io/proxy-next-upstream
				
				next-upstream
				
				nginx.ingress.kubernetes.io/proxy-next-upstream-timeout
				
				next-upstream-timeout
				
				nginx.ingress.kubernetes.io/proxy-read-timeout
				
read-timeout
				
				nginx.ingress.kubernetes.io/proxy-send-timeout
				
				send-timeout
				
				nginx.ingress.kubernetes.io/service-upstream
				
				use-cluster-ip

mTLS身份验证

在严格的零信任环境中，服务网格尤其有用。在这种环境中，集群内的分布式应用通过相互身份验证进行安全通信。如果需要对进出集群的流量（南北向流量）实施同等级别的安全保护，该怎么办？

可以在Ingress Controller层配置mTLS身份验证，使外部连接的端系统通过出示有效证书进行相互身份验证。

下表列出了NGINX Policy资源中与社区版Ingress Controller的以下注解相对应的字段：客户端证书身份验证和后端证书身份验证。

社区版Ingress控制器 NGINX Ingress Controller 
				nginx.ingress.kubernetes.io/auth-tls-secret: secretNamenginx.ingress.kubernetes.io/auth-tls-verify-client: "on"nginx.ingress.kubernetes.io/auth-tls-verify-depth: "1"
				
				ingressMTLS:   clientCertSecret: secretName   verifyClient: "on"   verifyDepth: 1
				
nginx.ingress.kubernetes.io/proxy-ssl-secret: "secretName"nginx.ingress.kubernetes.io/proxy-ssl-verify: "on|off"nginx.ingress.kubernetes.io/proxy-ssl-verify-depth: "1"nginx.ingress.kubernetes.io/proxy-ssl-protocols: "TLSv1.2"nginx.ingress.kubernetes.io/proxy-ssl-ciphers: "DEFAULT"nginx.ingress.kubernetes.io/proxy-ssl-name: "server-name"nginx.ingress.kubernetes.io/proxy-ssl-server-name: "on|off"
				
egressMTLS:   tlsSecret: secretName   verifyServer: true|false   verifyDepth: 1   protocols: TLSv1.2   ciphers: DEFAULT   sslName: server-name   serverName: true|false

会话持久性（NGINX Plus 专属）

下表列出了NGINX Policy资源中的相关字段。这些字段仅适用于基于NGINX Plus的NGINX Ingress Controller，并与社区版Ingress控制器中用于会话持久性（亲和性）的注解相对应。

社区版Ingress Controller NGINX Ingress Controller 
nginx.ingress.kubernetes.io/affinity: "cookie"nginx.ingress.kubernetes.io/session-cookie-name: "cookieName"nginx.ingress.kubernetes.io/session-cookie-expires: "x"nginx.ingress.kubernetes.io/session-cookie-path: "/route"nginx.ingress.kubernetes.io/session-cookie-secure: "true"
				
sessionCookie:  enable: true  name: cookieName  expires: xh  path: /route  secure: true

选项2：使用Kubernetes Ingress资源进行迁移

从社区版Ingress控制器迁移到NGINX Ingress Controller的第二种方案是，仅在标准Kubernetes Ingress资源中使用注解和ConfigMap，并可能依赖主节点/从节点式处理。这样可将所有配置保留在Ingress对象中。

注意：使用此方法时，请勿更改Ingress资源的spec字段。

使用注解进行高级配置

下表列出了社区版Ingress控制器中与NGINX Ingress Controller所支持注解直接对应的注解。

Community Ingress Controller NGINX Ingress Controller NGINX Directive
N/A
Default:

 

				random two least_conn
				
nginx.org/rewrites: "serviceName=svc rewrite=URI"
N/A
N/A2

1社区版Ingress控制器使用Lua实现部分负载均衡算法。NGINX Ingress Controller并未针对所有这些算法提供等效实现。

2将HTTP流量重定向到HTTPS。社区版Ingress控制器使用Lua代码实现此功能，而NGINX Ingress Controller则使用NGINX原生的if条件。

下表列出了社区版Ingress控制器中与基于NGINX Plus的NGINX Ingress Controller所支持注解直接对应的注解。

社区版 Ingress Controller 基于 NGINX Plus 的 NGINX Ingress Controller 
				nginx.com/sticky-cookie-services: "serviceName=example-svc cookie_name expires=time path=/route"

注意：基于NGINX Plus的NGINX Ingress Controller还为社区版Ingress控制器完全不支持的功能提供了额外的注解，包括主动健康检查和使用JSON Web Token进行身份验证（JWT）。

使用ConfigMap进行全局配置

下表列出了社区版Ingress控制器ConfigMap键与其直接对应的NGINX Ingress Controller ConfigMap键。请注意，其中少数ConfigMap键的名称相同。此外，社区版Ingress控制器和NGINX Ingress Controller各自都有一些对方没有的ConfigMap键（表中未列出）。

Community Ingress ControllerNGINX Ingress Controller
disable-access-log
access-log-off
error-log-level
error-log-level
hsts
hsts
hsts-include-subdomains
hsts-include-subdomains
hsts-max-age
hsts-max-age
http-snippet
http-snippets
keep-alive
keepalive-timeout
keep-alive-requests
keepalive-requests
load-balance
lb-method
location-snippet
location-snippets
log-format-escape-json: "true"
log-format-escaping: "json"
log-format-stream
stream-log-format
log-format-upstream
log-format
main-snippet
main-snippets
max-worker-connections 
worker-connections
max-worker-open-files
worker-rlimit-nofile
proxy-body-size
client-max-body-size
proxy-buffering
proxy-buffering
proxy-buffers-number: "number"proxy-buffer-size: "size"
proxy-buffers: number size
proxy-connect-timeout
proxy-connect-timeout
proxy-read-timeout
proxy-read-timeout
proxy-send-timeout
proxy-send-timeout
server-name-hash-bucket-size
server-names-hash-bucket-size
server-name-hash-max-size
server-names-hash-max-size
server-snippet
server-snippets
server-tokens
server-tokens
ssl-ciphers
ssl-ciphers
ssl-dh-param
ssl-dhparam-file
ssl-protocols
ssl-protocols
ssl-redirect
ssl-redirect
upstream-keepalive-connections
keepalive
use-http2
http2
use-proxy-protocol
proxy-protocol
variables-hash-bucket-size
variables-hash-bucket-size
worker-cpu-affinity
worker-cpu-affinity
worker-processes
worker-processes
worker-shutdown-timeout
worker-shutdown-timeout

总结

您可以使用自定义NGINX Ingress资源，或使用带注解和ConfigMap的标准Kubernetes Ingress资源，从社区版Ingress控制器迁移到NGINX Ingress Controller。前一种方式支持更广泛的网络功能，因此更适合生产级Kubernetes环境。

本文摘自我们的综合电子书《使用F5 NGINX管理Kubernetes流量：实用指南》。立即免费下载。

立即开始30天免费试用，亲自体验基于NGINX Plus的NGINX Ingress Controller，或联系我们，讨论您的用例。

分享
精选博客文章
云原生技术、平台工程和AI的当前趋势使用F5 NGINX One对应用和API交付进行全生命周期管理简化现代应用交付：F5 NGINX One 九个月回顾
标签： F5 NGINX, Tech, Kubernetes (k8S), F5 NGINX Ingress Controller, Learn, BIG-IP Container Ingress Services, Networking for Kubernetes, BIG-IP Next for Kubernetes, F5 Distributed Cloud Load Balancer & K8s Gateway

关于作者

Amir Rawdat
Amir Rawdat解决方案工程师

Amir Rawdat 的更多博客文章

相关博客文章

NGINX Plus R26 正式发布
NGINX | 2022/02/15

NGINX Plus R26 正式发布

NGINX Plus R26通过缓存JSON Web密钥集加快JWT验证，并强化TLS握手，从而提升安全性。NGINX JavaScript的新功能包括增强对异步函数的支持，以及实现WebCrypto API。

使用NGINX App Protect DoS保护gRPC应用，抵御严重的DoS攻击
NGINX | 2022/02/10

使用NGINX App Protect DoS保护gRPC应用，抵御严重的DoS攻击

gRPC具备开发人员设计和部署现代应用所需的速度与灵活性，但其开放性也使其极易受到第7层DoS攻击。NGINX App Protect DoS可保护gRPC应用免受此类破坏性攻击。

Ingress Controller 选型指南（第 2 部分）：风险与面向未来的规划
NGINX | 2021/09/13

Ingress Controller 选型指南（第 2 部分）：风险与面向未来的规划

了解选择错误的Ingress控制器可能带来的风险，以及如何从关键方面着手，让您的选择更好地适应未来需求。

NGINX Plus R19 正式发布
NGINX | 2019/09/03

NGINX Plus R19 正式发布

NGINX Plus R19扩展了监控功能，不仅提供更多指标，还新增了指标分析方式；增加试运行模式，用于测试限速效果；增强键值存储，以支持IP地址范围；并使限速更加动态。

NGINX现已正式加入F5
NGINX | 2019/05/09

NGINX现已正式加入F5

NGINX现已正式成为F5的一部分。Gus Robertson现任F5 NGINX业务部门负责人。他阐述了两家公司在人才、文化和愿景方面融合的价值，以及双方将如何携手增强NGINX的开源产品和商业产品。

使用NGINX和NGINX Plus实现高性能缓存
NGINX | 2016/08/24

使用NGINX和NGINX Plus实现高性能缓存

我将介绍NGINX在内容缓存和性能方面的工作原理，并分享一些控制NGINX内容缓存方式的技巧。

交付和保护每一个应用
F5 应用交付和安全解决方案确保部署在任何位置的每个应用和 API 都快速、可用且安全。了解如何与我们合作，始终提供卓越体验。
关注我们