博客 | NGINX

从社区入口控制器迁移到 F5 NGINX 入口控制器

NGINX-F5-horiz-black-type-RGB 的一部分
Amir Rawdat 缩略图
阿米尔·罗达特
2022 年 5 月 19 日发布

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

许多组织首次设置 Kubernetes 时都是从 Kubernetes 社区开发和维护的 NGINX Ingress 控制器 ( kubernetes/ingress-nginx ) 开始的。 然而，随着 Kubernetes 部署的成熟，一些组织发现他们需要高级功能或想要商业支持，同时保留 NGINX 作为数据平面。

一种选择是迁移到由 F5 NGINX 开发和维护的 NGINX Ingress Controller（ nginxinc/kubernetes-ingress ），这里我们提供了完整的说明，以便您可以避免因两个项目之间的差异而导致的一些复杂情况。

不确定这些选项有何不同？ 阅读入口控制器选择指南第 4 部分： NGINX 入口控制器选项 在我们的博客上。

为了在本文的其余部分区分这两个项目，我们将 Kubernetes 社区维护的 NGINX Ingress Controller（ kubernetes/ingress-nginx ）称为“社区 Ingress 控制器”，将 F5 NGINX 维护的 NGINX Ingress Controller（ nginxinc/kubernetes-ingress ）称为“NGINX Ingress 控制器”。

从社区 Ingress Controller 迁移到 NGINX Ingress Controller 有两种方法：

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

使用此迁移选项，您可以使用标准 Kubernetes Ingress 资源来设置根功能和NGINX Ingress 资源，以增强您的配置，提高功能和易用性。

NGINX Ingress 资源的自定义资源定义 (CRD) - VirtualServer、VirtualServerRoute 、 TransportServer 、 GlobalConfiguration和Policy - 使您能够轻松地将配置各个部分的控制权委托给不同的团队（例如 AppDev 和安全团队），并提供更高的配置安全性和验证。

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

该表将标准 Kubernetes Ingress 资源的spec字段中的 SSL 终止和第 7 层基于路径的路由的配置与 NGINX VirtualServer资源中的spec字段进行映射。 这两个资源的语法和缩进略有不同，但它们完成相同的基本 Ingress 功能。

Kubernetes Ingress 资源 NGINX 虚拟服务器资源 
api版本：networking.k8s.io/v1kind： 入口
元数据：
名称：nginx-test
规范：
tls：
-主机：
-foo.bar.com
秘密名称：tls-secret
规则：
-主机：foo.bar.com
http：
路径：
-路径：/login
后端：
服务名称：login-svc
服务端口： 80
- 路径：/billing
服务名称：billing-svc
服务端口： 80

api版本：networking.k8s.io/v1kind： 虚拟服务器
元数据：
名称：nginx-test
规范：
主机：foo.bar.com
tls：
秘密：tls-secret
上游：
-名称：login
服务：login-svc
端口： 80
- 名称：billing
服务：billing-svc
端口： 80
路线：
- 路径：/login
操作：
密码：login
- 路径：/billing
操作：
密码：billing

配置 TCP/UDP 负载平衡和 TLS 直通

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

借助 NGINX Ingress Controller， TransportServer资源为 TCP/UDP 和 TLS Passthrough 负载均衡定义了广泛的选项。 TransportServer 资源与GlobalConfiguration资源结合使用来控制入站和出站连接。

有关更多信息，请参阅我们博客上的NGINX Ingress 资源中对 TCP、UDP 和 TLS 直通服务的支持。

将社区 Ingress 控制器注释转换为 NGINX Ingress 资源

生产级 Kubernetes 部署通常需要扩展基本的 Ingress 规则来实现高级用例，包括金丝雀和蓝绿部署、流量限制、入口和出口流量处理等。

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

在以下部分中，我们将展示如何将社区 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 清单中。

社区入口控制器 NGINX Ingress Controller 
nginx.ingress.kubernetes.io/canary：“true”nginx.ingress.kubernetes.io/canary-by-header：“httpHeader”

匹配：- 条件： - 标头：httpHeader 值：从不操作：传递：echo - 标头：httpHeader 值：始终操作：传递：echo-canary 操作：传递：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 ”

匹配：- 条件：- 标头：httpHeader 值： my-value操作：传递：echo-canary 操作：传递：echo

nginx.ingress.kubernetes.io/canary：“true”nginx.ingress.kubernetes.io/canary-by-cookie：“cookie名称”

匹配：- 条件：
- cookie：cookieName
值：从不
操作：
传递：echo
- cookie：cookieName
值：始终
操作：
传递：echo-canary
操作：
传递：echo

nginx.ingress.kubernetes.io/canary：“true”nginx.ingress.kubernetes.io/canary重量： “10”

分裂：- 重量： 90 动作： 传递： 回声 - 重量： 10 动作：传递：echo-canary

交通管制

在微服务环境中，应用本质上是短暂的，因此更有可能返回错误响应，DevOps 团队广泛使用流量控制策略（例如断路、速率和连接限制）以防止应用不健康或未按预期运行时出现错误情况。

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

社区入口控制器 NGINX Ingress Controller 
nginx.ingress.kubernetes.io/custom-http-errors：“代码” nginx.ingress.kubernetes.io/default-backend：“default-svc”

错误页面：- 代码： [代码] 重定向： 代码： 301 url：默认-svc

nginx.ingress.kubernetes.io/limit-connections：“数字”

http-snippets ：| limit_conn_zone $binary_remote_addr zone= zone_name ：大小；路线：-路径：/路径location-snippets ：| limit_conn zone_name数量；

nginx.ingress.kubernetes.io/limit-rate：“数字” nginx.ingress.kubernetes.io/limit-rate-after：“数字”

位置片段：| limit_rate数字；limit_rate_after数字；

nginx.ingress.kubernetes.io/limit-rpm：“数字” nginx.ingress.kubernetes.io/limit-burst-multiplier：“乘数”

rateLimit ：速率：数量r/m 突发：数量*乘数键：${binary_remote_addr} zoneSize：尺寸

nginx.ingress.kubernetes.io/limit-rps：“数字” nginx.ingress.kubernetes.io/limit-burst-multiplier：“乘数”

rateLimit：速率：数字r/s突发：数字*乘数键：${binary_remote_addr} zoneSize：尺寸

nginx.ingress.kubernetes.io/limit-whitelist： “ CIDR ”

http 代码片段：|服务器代码片段：|

nginx.ingress.kubernetes.io/rewrite-target： “ URI ”

重写路径： “ URI ”

如表所示，截至撰写本文时，NGINX Ingress 资源不包含直接翻译以下四个社区 Ingress 控制器注释的字段，您必须使用代码片段。 我们计划在 NGINX Ingress Controller 的未来版本中利用Policy资源直接支持这四个注释。

  • nginx.ingress.kubernetes.io/limit-connections
  • nginx.ingress.kubernetes.io/限制速率
  • nginx.ingress.kubernetes.io/limit-rate-after
  • nginx.ingress.kubernetes.io/limit-whitelist

标题操作

在许多用例中，操作 HTTP 标头很有用，因为它们包含对于涉及 HTTP 事务的系统来说重要且相关的附加信息。 例如，社区 Ingress 控制器支持启用和设置跨域资源共享(CORS) 标头，这些标头用于 AJAX应用，其中来自浏览器的前端 JavaScript 代码连接到后端应用程序或 Web 服务器。

该表显示了 NGINX VirtualServer 和 VirtualServerRoute资源中与社区 Ingress 控制器标头操作注释相对应的字段。

社区入口控制器 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，选项” nginx.ingress.kubernetes.io/cors-allow-origin：“*” nginx.ingress.kubernetes.io/cors-max-age：“秒”

responseHeaders ：添加：- 名称： Access-Control-Allow-Credentials 值：“true” - 名称： 访问控制允许标头值： “X-Forwarded-For”-名称： 访问控制允许方法值： “PUT、GET、POST、OPTIONS” - 名称： Access-Control-Allow-Origin 值：“*”-名称： Access-Control-Max-Age 值：“秒”

代理和负载平衡

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

该表显示了 NGINX VirtualServer 和 VirtualServerRoute 资源的上游字段中的语句，这些语句对应于社区 Ingress 控制器注释，用于自定义 NGINX 负载均衡、代理超时、代理缓冲以及到服务的集群 IP 地址和端口的路由连接。

社区入口控制器 NGINX Ingress Controller 
nginx.ingress.kubernetes.io/负载平衡

磅法

nginx.ingress.kubernetes.io/proxy-buffering

缓冲

nginx.ingress.kubernetes.io/proxy-buffers-numbernginx.ingress.kubernetes.io/proxy-buffer-size

緩衝器

nginx.ingress.kubernetes.io/proxy-connect-timeout

连接超时

nginx.ingress.kubernetes.io/proxy-next-upstream

下一个上游

nginx.ingress.kubernetes.io/proxy-next-upstream-timeout

下一个上游超时

nginx.ingress.kubernetes.io/proxy-read-timeout

读取超时

nginx.ingress.kubernetes.io/proxy-send-timeout

发送超时

nginx.ingress.kubernetes.io/service-upstream

使用集群 IP

mTLS 身份验证

服务网格在严格的零信任环境中特别有用，其中集群内的分布式应用通过相互认证进行安全通信。 如果我们需要对进出集群的流量（南北流量）实施相同级别的安全措施怎么办？

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

该表显示了 NGINX Policy资源中与社区 Ingress 控制器注释相对应的字段，用于客户端证书认证和后端证书认证。

社区入口控制器 NGINX Ingress Controller 

nginx.ingress.kubernetes.io/auth-tls-secret：秘密名称
nginx.ingress.kubernetes.io/auth-tls-verify-client：“开启”
nginx.ingress.kubernetes.io/auth-tls-verify-depth： “1”

ingressMTLS ：clientCertSecret：secretName 验证客户端：“开启” 验证深度： 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-协议： “TLSv1.2”
nginx.ingress.kubernetes.io/proxy-ssl-ciphers： “默认”
nginx.ingress.kubernetes.io/proxy-ssl-name：“服务器名称”
nginx.ingress.kubernetes.io/proxy-ssl-服务器名称：“开|关”

egressMTLS ：tlsSecret：secretName验证服务器：true|false验证深度： 1个协议： TLSv1.2 密码： 默认 sslName：服务器名称 serverName：true|false

会话持久性（NGINX Plus 独有）

该表展示了基于 NGINX Plus 的 NGINX Ingress Controller 独有的 NGINX Policy资源中的字段，与社区 Ingress controller 用于会话持久性（亲和性）的注解相对应。

社区入口控制器 NGINX Ingress Controller 
nginx.ingress.kubernetes.io/affinity：“cookie” nginx.ingress.kubernetes.io/session-cookie-name：“cookie名称” 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 ：启用：true 名称：cookieName 过期时间： x h 路径：/route 安全：true

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

从社区 Ingress 控制器迁移到 NGINX Ingress Controller 的第二种选择是在标准 Kubernetes Ingress 资源中仅使用注释和ConfigMap ，并可能依赖于master/minion “风格处理。 这会将所有配置保留在 Ingress 对象中。

笔记： 使用此方法，不要改变 Ingress 资源的spec字段。

带注释的高级配置

下表概述了与 NGINX Ingress Controller 支持的注释直接对应的社区 Ingress Controller 注释。

社区入口控制器 NGINX Ingress Controller NGINX 指令 
nginx.ingress.kubernetes.io/configuration-snippet : |

nginx.org/location-snippets : |
不适用 
nginx.ingress.kubernetes.io/负载平衡1

nginx.org/lb 方法
默认：

 

随机两个 least_conn

nginx.ingress.kubernetes.io/proxy-buffering ：“开|关”

nginx.org/proxy-buffering ： “真|假”

代理缓冲

nginx.ingress.kubernetes.io/proxy-buffers-number ：“数字” nginx.ingress.kubernetes.io/proxy-buffer-size：“xk ”

nginx.org/proxy-buffers ：“数字4k|8k” nginx.org/proxy-buffer-size ： “4k|8k”

proxy_buffers代理缓冲区大小

nginx.ingress.kubernetes.io/proxy-connect-timeout ：“秒”

nginx.org/proxy-connect-timeout: : “秒”

代理连接超时

nginx.ingress.kubernetes.io/proxy-read-timeout ：“秒”

nginx.org/proxy-read-timeout ：“秒”

proxy_read_timeout

nginx.ingress.kubernetes.io/proxy-send-timeout ：“秒”

nginx.org/proxy-send-timeout ：“秒”

proxy_send_timeout

nginx.ingress.kubernetes.io/rewrite-target ： “ URI ”

nginx.org/rewrites ：“服务名称= svc rewrite= URI ”

改写

nginx.ingress.kubernetes.io/server-snippet : |

nginx.org/server-snippets ：|
不适用 
nginx.ingress.kubernetes.io/ssl-redirect ：“true|false”

ingress.kubernetes.io/ssl-redirect ： “真|假”
不适用2

1社区 Ingress 控制器使用 Lua 来实现一些负载平衡算法。 NGINX Ingress Controller 没有为所有这些提供等效解决方案。

2将 HTTP 流量重定向到 HTTPS。 社区 Ingress controller 使用 Lua 代码实现了这一点，而 NGINX Ingress Controller 使用原生 NGINX if条件实现。

下表概述了与基于 NGINX Plus 的 NGINX Ingress Controller 支持的注释直接对应的社区 Ingress 控制器注释。

社区入口控制器 基于 NGINX Plus 的 NGINX Ingress 控制器 
nginx.ingress.kubernetes.io/affinity：“cookie ” nginx.ingress.kubernetes.io/session-cookie-name：“cookie_name ” nginx.ingress.kubernetes.io/session-cookie-expires ：“秒” nginx.ingress.kubernetes.io/session-cookie-path：“/route ”

nginx.com/sticky-cookie-services ：“服务名称= example-svc cookie_name过期时间= time路径=/ route ”

笔记： 基于 NGINX Plus 的 NGINX Ingress Controller 对社区 Ingress Controller 根本不支持的功能进行了额外的注释，包括主动健康检查和使用 JSON Web Tokens (JWT) 进行身份验证。

使用 ConfigMaps 进行全局配置

下表将社区 Ingress 控制器 ConfigMap 键映射到其直接对应的 NGINX Ingress 控制器 ConfigMap 键。 请注意，少数 ConfigMap 键名是相同的。 此外，社区 Ingress 控制器和 NGINX Ingress Controller 都具有 ConfigMaps 键，而对方没有（未在表中显示）。

社区入口控制器 NGINX Ingress Controller 
禁用访问日志

访问注销

错误日志级别

错误日志级别

高温

高温

hsts-包括子域名

hsts-包括子域名

hsts 最大年龄

hsts 最大年龄

http 片段

http 片段

保持活动

保持连接超时

保持活动请求

保活请求

负载均衡

磅法

位置片段

位置片段

日志格式转义 JSON ：“true”

日志格式转义：“json”

日志格式流

流日志格式

日志格式上游

日志格式

主要片段

主要片段

最大工作连接数 

工人连接

最大工作者打开文件数

worker-rlimit-nofile

代理主体大小

客户端最大主体尺寸

代理缓冲

代理缓冲

代理缓冲区编号：“数字”代理缓冲区大小：“大小”

代理缓冲区：数字大小

代理连接超时

代理连接超时

代理读取超时

代理读取超时

代理发送超时

代理发送超时

服务器名称-哈希桶大小

服务器名称哈希桶大小

服务器名称哈希最大大小

服务器名称哈希最大大小

服务器片段

服务器片段

服务器令牌

服务器令牌

SSL 密码

SSL 密码

ssl-dh-参数

ssl-dhparam 文件

SSL 协议

SSL 协议

SSL 重定向

SSL 重定向

上游保持连接

保持活动

使用-http2

http2

使用代理协议

代理协议

变量哈希桶大小

变量哈希桶大小

工作者 CPU 亲和性

工作者 CPU 亲和性

工作进程

工作进程

工人关闭超时

工人关闭超时

概括

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

这篇文章摘录自我们的综合电子书《使用 F5 NGINX 管理 Kubernetes 流量》： 实用指南。 今天免费下载。

立即免费试用基于 NGINX Plus 的 NGINX Ingress Controller 30 天，或者联系我们讨论您的用例。

阅读有关 F5 NGINX 的更多博客文章 ›

“这篇博文可能引用了不再可用和/或不再支持的产品。 有关 F5 NGINX 产品和解决方案的最新信息，请探索我们的NGINX 产品系列。 NGINX 现在是 F5 的一部分。 所有之前的 NGINX.com 链接都将重定向至 F5.com 上的类似 NGINX 内容。”