博客 | NGINX

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

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 虚拟服务器资源 
apiVersion: networking.k8s.io/v1kind: Ingress
metadata:
  name: nginx-test
spec:
  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: VirtualServer
metadata:
  name: nginx-test
spec:
  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 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"

matches:- conditions:
  - header: httpHeader
      value: never
  action:
    pass: echo 
  - header: httpHeader
      value: always
  action:
    pass: echo-canary
action:
  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-canary
action:
  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 重写。

社区入口控制器 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 资源不包含直接翻译以下四个社区 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, 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 资源的上游字段中的语句，这些语句对应于社区 Ingress 控制器注释，用于自定义 NGINX 负载均衡、代理超时、代理缓冲以及到服务的集群 IP 地址和端口的路由连接。

社区入口控制器 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 控制器注释相对应的字段，用于客户端证书认证和后端证书认证。

社区入口控制器 NGINX Ingress Controller 

nginx.ingress.kubernetes.io/auth-tls-secret: secretName
nginx.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 Plus 的 NGINX Ingress Controller 独有的 NGINX Policy资源中的字段，与社区 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 ，并可能依赖于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/load-balance1

nginx.org/lb-method
默认：

 

random two least_conn

nginx.ingress.kubernetes.io/proxy-buffering: "on|off"

nginx.org/proxy-buffering: "True|False"

proxy_buffering

nginx.ingress.kubernetes.io/proxy-buffers-number: "number"nginx.ingress.kubernetes.io/proxy-buffer-size: "xk"

nginx.org/proxy-buffers: "number 4k|8k"nginx.org/proxy-buffer-size: "4k|8k"

proxy_buffers
proxy_buffer_size

nginx.ingress.kubernetes.io/proxy-connect-timeout: "seconds"

nginx.org/proxy-connect-timeout: : "secondss"

proxy_connect_timeout

nginx.ingress.kubernetes.io/proxy-read-timeout: "seconds"

nginx.org/proxy-read-timeout: "secondss"

proxy_read_timeout

nginx.ingress.kubernetes.io/proxy-send-timeout: "seconds"

nginx.org/proxy-send-timeout: "secondss"

proxy_send_timeout

nginx.ingress.kubernetes.io/rewrite-target: "URI"

nginx.org/rewrites: "serviceName=svc rewrite=URI"

rewrite

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

nginx.org/server-snippets: |
不适用 
nginx.ingress.kubernetes.io/ssl-redirect: "true|false"

ingress.kubernetes.io/ssl-redirect: "True|False"
不适用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: "seconds"
nginx.ingress.kubernetes.io/session-cookie-path: "/route"

nginx.com/sticky-cookie-services: "serviceName=example-svc cookie_name expires=time path=/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 
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 资源或带有注释和 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 内容。”