BLOG | NGINX

Migración del controlador de ingreso de la comunidad al controlador de ingreso de F5 NGINX

Miniatura de Amir Rawdat
Amir Rawdat
Publicado el 19 de mayo de 2022

Editor : Esta publicación es un extracto de nuestro completo libro electrónico, Gestión del tráfico de Kubernetes con F5 NGINX: Una guía práctica . Descárgalo gratis hoy .

Muchas organizaciones que configuran Kubernetes por primera vez comienzan con el controlador de ingreso NGINX desarrollado y mantenido por la comunidad de Kubernetes ( kubernetes/ingress-nginx ). Sin embargo, a medida que las implementaciones de Kubernetes maduran, algunas organizaciones descubren que necesitan funciones avanzadas o desean soporte comercial mientras mantienen NGINX como el plano de datos.

Una opción es migrar al controlador de ingreso NGINX desarrollado y mantenido por F5 NGINX ( nginxinc/kubernetes-ingress ), y aquí brindamos instrucciones completas para que pueda evitar algunas complicaciones que resultan de las diferencias entre los dos proyectos.

¿No está seguro de en qué se diferencian estas opciones? Lea la Guía para elegir un controlador de ingreso, parte 4: Opciones del controlador de ingreso NGINX en nuestro blog.

Para distinguir entre los dos proyectos en el resto de esta publicación, nos referimos al controlador de ingreso NGINX mantenido por la comunidad de Kubernetes ( kubernetes/ingress-nginx ) como el “controlador de ingreso de la comunidad” y al mantenido por F5 NGINX ( nginxinc/kubernetes-ingress ) como “controlador de ingreso NGINX”.

Hay dos formas de migrar del controlador de Ingress de la comunidad al controlador de Ingress de NGINX:

Opción 1: Migrar usando recursos de ingreso de NGINX

Con esta opción de migración, utiliza el recurso Ingress de Kubernetes estándar para configurar las capacidades raíz y los recursos Ingress de NGINX para mejorar su configuración con mayores capacidades y facilidad de uso.

Las definiciones de recursos personalizadas (CRD) para los recursos de NGINX Ingress ( VirtualServer, VirtualServerRoute , TransportServer , GlobalConfiguration y Policy ) le permiten delegar fácilmente el control sobre varias partes de la configuración a diferentes equipos (como los equipos de desarrollo de aplicaciones y seguridad), además de proporcionar mayor seguridad y validación de la configuración.

Configuración de la terminación SSL y el enrutamiento basado en rutas HTTP

La tabla asigna la configuración de la terminación SSL y el enrutamiento basado en rutas de capa 7 en el campo de especificación del recurso Ingress de Kubernetes estándar con el campo de especificación en el recurso NGINX VirtualServer . La sintaxis y la sangría difieren ligeramente en los dos recursos, pero logran las mismas funciones básicas de Ingress.

Recurso de ingreso de Kubernetes Recurso de servidor virtual 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

Configuración del equilibrio de carga TCP/UDP y el paso a través de TLS

Con el controlador Ingress de la comunidad, un objeto API ConfigMap de Kubernetes es la única forma de exponer servicios TCP y UDP .

Con NGINX Ingress Controller, los recursos de TransportServer definen una amplia gama de opciones para el equilibrio de carga de paso a través de TCP/UDP y TLS. Los recursos de TransportServer se utilizan junto con los recursos de GlobalConfiguration para controlar las conexiones entrantes y salientes.

Para obtener más información, consulte Compatibilidad con servicios de paso a través de TCP, UDP y TLS en los recursos de ingreso de NGINX en nuestro blog.

Convertir las anotaciones del controlador de Ingress de la comunidad en recursos de Ingress de NGINX

Las implementaciones de Kubernetes de nivel de producción a menudo necesitan ampliar las reglas de ingreso básicas para implementar casos de uso avanzados, incluidas implementaciones canarias y azul-verde, limitación de tráfico, manipulación del tráfico de ingreso y egreso, y más.

El controlador de Ingress de la comunidad implementa muchos de estos casos de uso con anotaciones de Kubernetes. Sin embargo, muchas de estas anotaciones se crean con extensiones Lua personalizadas que pertenecen a definiciones de recursos de NGINX Ingress muy específicas y, como resultado, no son adecuadas para implementar funcionalidades avanzadas en un entorno de producción estable y compatible.

En las siguientes secciones mostramos cómo convertir las anotaciones del controlador de Ingress de la comunidad en recursos del controlador de Ingress NGINX.

Despliegues de Canary

Incluso mientras envía cambios de código frecuentes a sus cargas de trabajo de contenedores de producción, debe continuar brindando servicio a sus usuarios existentes. Las implementaciones Canary y Blue-Green le permiten hacer esto y puede realizarlas en el plano de datos del controlador de ingreso NGINX para lograr actualizaciones estables y predecibles en entornos de Kubernetes de nivel de producción.

La tabla muestra los campos en los recursos NGINX VirtualServer y VirtualServerRoute que corresponden a las anotaciones del controlador de ingreso de la comunidad para implementaciones canarias .

El controlador de Ingress de la comunidad evalúa las anotaciones canarias en este orden de precedencia:

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

Para que NGINX Ingress Controller los evalúe de la misma manera, deben aparecer en ese orden en el manifiesto NGINX VirtualServer o VirtualServerRoute.

Controlador de ingreso a la comunidad 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

Control de tráfico

En entornos de microservicios, donde las aplicaciones son efímeras por naturaleza y, por lo tanto, tienen más probabilidades de devolver respuestas de error, los equipos de DevOps hacen un uso extensivo de políticas de control de tráfico (como interrupción de circuitos y limitación de velocidad y conexión) para evitar condiciones de error cuando las aplicaciones no funcionan correctamente o no funcionan como se espera.

La tabla muestra los campos en los recursos NGINX VirtualServer y VirtualServerRoute que corresponden a las anotaciones del controlador de ingreso de la comunidad para limitación de velocidad , errores HTTP personalizados , un backend predeterminado personalizado y reescritura de URI .

Controlador de ingreso a la comunidad 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"

Como se indica en la tabla, al momento de escribir este artículo los recursos de Ingress de NGINX no incluyen campos que traduzcan directamente las siguientes cuatro anotaciones del controlador de Ingress de la comunidad, y debe usar fragmentos. Se planea brindar soporte directo para las cuatro anotaciones, mediante recursos de políticas , para futuras versiones de NGINX Ingress Controller.

  • 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

Manipulación de encabezados

La manipulación de los encabezados HTTP es útil en muchos casos de uso, ya que contienen información adicional que es importante y relevante para los sistemas involucrados en una transacción HTTP. Por ejemplo, el controlador de Ingress de la comunidad permite habilitar y configurar encabezados de uso compartido de recursos de origen cruzado (CORS), que se usan con aplicaciones AJAX, donde el código JavaScript de front-end de un navegador se conecta a una aplicación de back-end o un servidor web.

La tabla muestra los campos en los recursos NGINX VirtualServer y VirtualServerRoute que corresponden a las anotaciones del controlador de Ingress de la comunidad para la manipulación del encabezado .

Controlador de ingreso a la comunidad 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"

Proxy y equilibrio de carga

Hay otras funcionalidades de proxy y equilibrio de carga que quizás desee configurar en NGINX Ingress Controller dependiendo del caso de uso específico. Estas funcionalidades incluyen la configuración del algoritmo de equilibrio de carga, así como la configuración de tiempo de espera y almacenamiento en búfer para conexiones mediante proxy.

La tabla muestra las declaraciones en el campo ascendente de los recursos NGINX VirtualServer y VirtualServerRoute que corresponden a las anotaciones del controlador de ingreso de la comunidad para el equilibrio de carga NGINX personalizado , los tiempos de espera del proxy , el almacenamiento en búfer del proxy y las conexiones de enrutamiento a la dirección IP y el puerto del clúster de un servicio .

Controlador de ingreso a la comunidad 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

Autenticación mTLS

Una malla de servicios es particularmente útil en un entorno estricto de confianza cero, donde las aplicaciones distribuidas dentro de un clúster se comunican de forma segura mediante la autenticación mutua. ¿Qué pasa si necesitamos imponer el mismo nivel de seguridad al tráfico que entra y sale del clúster (tráfico norte-sur)?

Podemos configurar la autenticación mTLS en la capa del controlador de ingreso para que los sistemas finales de las conexiones externas se autentiquen entre sí presentando un certificado válido.

La tabla muestra los campos en los recursos de políticas de NGINX que corresponden a las anotaciones del controlador de ingreso de la comunidad para la autenticación de certificados de cliente y la autenticación de certificados de back-end .

Controlador de ingreso a la comunidad 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

Persistencia de sesión (exclusiva de NGINX Plus)

La tabla muestra los campos en los recursos de políticas de NGINX que son exclusivos del controlador de ingreso de NGINX basado en NGINX Plus y corresponden a las anotaciones del controlador de ingreso de la comunidad para la persistencia de la sesión (afinidad).

Controlador de ingreso a la comunidad 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

Opción 2: Migrar usando el recurso de ingreso de Kubernetes

La segunda opción para migrar del controlador de Ingress de la comunidad al controlador de Ingress de NGINX es usar solo anotaciones y ConfigMaps en el recurso de Ingress estándar de Kubernetes y potencialmente confiar en el procesamiento de estilo “ maestro/súbdito ”. Esto mantiene toda la configuración en el objeto Ingress.

Nota:  Con este método, no altere el campo de especificación del recurso Ingress.

Configuración avanzada con anotaciones

La siguiente tabla describe las anotaciones del controlador de Ingress de la comunidad que corresponden directamente a las anotaciones compatibles con el controlador de Ingress NGINX.

Controlador de ingreso a la comunidad NGINX Ingress Controller Directiva NGINX 
nginx.ingress.kubernetes.io/configuration-snippet: |

nginx.org/location-snippets: |
N/A 
nginx.ingress.kubernetes.io/load-balance1

nginx.org/lb-method
Por defecto:

 

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: |
N/A 
nginx.ingress.kubernetes.io/ssl-redirect: "true|false"

ingress.kubernetes.io/ssl-redirect: "True|False"
N/A2

1El controlador de Ingress de la comunidad utiliza Lua para implementar algunos de sus algoritmos de equilibrio de carga. El controlador de ingreso NGINX no tiene un equivalente para todos ellos.

2Redirige el tráfico HTTP a HTTPS. El controlador de Ingress de la comunidad implementa esto con código Lua, mientras que el controlador de Ingress NGINX usa condiciones if nativas de NGINX.

La siguiente tabla describe las anotaciones del controlador de Ingress de la comunidad que corresponden directamente a las anotaciones compatibles con el controlador de Ingress NGINX basado en NGINX Plus.

Controlador de ingreso a la comunidad Controlador de ingreso NGINX basado en NGINX Plus 
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"

Nota: El controlador de ingreso NGINX basado en NGINX Plus tiene anotaciones adicionales para funciones que el controlador de ingreso de la comunidad no admite en absoluto, incluidos los controles de estado activos y la autenticación mediante tokens web JSON (JWT).

Configuración global con ConfigMaps

La siguiente tabla asigna las claves ConfigMap del controlador Ingress de la comunidad a sus claves ConfigMap del controlador Ingress NGINX directamente correspondientes. Tenga en cuenta que algunos nombres de claves de ConfigMap son idénticos. Además, tanto el controlador de Ingress de la comunidad como el controlador de Ingress NGINX tienen claves ConfigMaps que el otro no tiene (no se muestran en la tabla).

Controlador de ingreso a la comunidad 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

resumen

Puede migrar del controlador de Ingress de la comunidad al controlador de Ingress de NGINX utilizando recursos de Ingress de NGINX personalizados o el recurso de Ingress de Kubernetes estándar con anotaciones y ConfigMaps. La primera opción admite un conjunto más amplio de capacidades de red y, por lo tanto, es más adecuada para entornos de Kubernetes de nivel de producción.

Esta publicación es un extracto de nuestro completo libro electrónico, Gestión del tráfico de Kubernetes con F5 NGINX: Una guía práctica . Descárgalo gratis hoy .

Pruebe usted mismo el controlador de ingreso NGINX basado en NGINX Plus hoy mismo con una prueba gratuita de 30 días o contáctenos para analizar sus casos de uso .

Leer más publicaciones de blog sobre F5 NGINX ›

"Esta publicación de blog puede hacer referencia a productos que ya no están disponibles o que ya no reciben soporte. Para obtener la información más actualizada sobre los productos y soluciones F5 NGINX disponibles, explore nuestra familia de productos NGINX . NGINX ahora es parte de F5. Todos los enlaces anteriores de NGINX.com redirigirán a contenido similar de NGINX en F5.com.