Migração do Community Ingress Controller para o F5 NGINX Ingress Controller

Amir RawdatEngenheiro de Soluções

Editor – Este post é um trecho do nosso eBook completo, Gerenciamento do tráfego do Kubernetes com o F5 NGINX: um guia prático. Baixe-o gratuitamente hoje mesmo.

Muitas organizações que estão configurando o Kubernetes pela primeira vez começam com o controlador NGINX Ingress desenvolvido e mantido pela comunidade do Kubernetes (kubernetes/ingress-nginx). No entanto, à medida que as implantações do Kubernetes amadurecem, algumas organizações percebem que precisam de recursos avançados ou desejam suporte comercial, mantendo o NGINX como plano de dados.

Uma opção é migrar para o NGINX Ingress Controller desenvolvido e mantido pela F5 NGINX (nginxinc/kubernetes-ingress). Aqui, fornecemos instruções completas para que você possa evitar algumas complicações decorrentes das diferenças entre os dois projetos.

Não sabe ao certo qual é a diferença entre essas opções? Leia Um guia para escolher um controlador de Ingress, parte 4: opções de controladores de Ingress NGINX em nosso blog.

Para diferenciar os dois projetos no restante deste artigo, chamaremos o NGINX Ingress Controller mantido pela comunidade Kubernetes (kubernetes/ingress-nginx) de “controlador de Ingress da comunidade” e aquele mantido pela F5 NGINX (nginxinc/kubernetes-ingress) de “NGINX Ingress Controller”.

Há duas maneiras de migrar do controlador Ingress da comunidade para o NGINX Ingress Controller:

• Opção 1: migrar usando recursos do NGINX Ingress
  Esta é a solução ideal, pois os recursos do NGINX Ingress oferecem suporte ao conjunto mais amplo de recursos de rede do Ingress necessários em ambientes Kubernetes de nível de produção. Para saber mais sobre os recursos do NGINX Ingress, assista ao nosso webinar Implantações avançadas do Kubernetes com o NGINX Ingress Controller.
• Opção 2: migrar usando o recurso Ingress do Kubernetes
  Esta opção é recomendada se você pretende usar o recurso padrão Ingress do Kubernetes para definir regras de balanceamento de carga do Ingress.

Opção 1: migrar usando recursos de Ingress do NGINX

Com esta opção de migração, você usa o recurso Ingress padrão do Kubernetes para definir os recursos básicos e os recursos Ingress do NGINX para aprimorar sua configuração, ampliando os recursos e facilitando o uso.

As definições de recursos personalizados (CRDs) para recursos do NGINX Ingress – VirtualServer, VirtualServerRoute, TransportServer, GlobalConfiguration e Policy – permitem delegar facilmente o controle sobre várias partes da configuração a diferentes equipes (como as equipes de AppDev e segurança), além de proporcionar maior segurança e validação da configuração.

Configuração do encerramento SSL e do roteamento baseado em caminhos HTTP

A tabela relaciona a configuração da terminação SSL e do roteamento de camada 7 baseado em caminhos no campo spec do recurso Ingress padrão do Kubernetes à configuração do campo spec no recurso VirtualServer do NGINX. A sintaxe e a indentação diferem ligeiramente entre os dois recursos, mas ambos desempenham as mesmas funções básicas de Ingress.

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

Configurando o balanceamento de carga TCP/UDP e o passthrough de TLS

Com o controlador Ingress da comunidade, um objeto da API ConfigMap do Kubernetes é a única maneira de expor serviços TCP e UDP.

Com o NGINX Ingress Controller, os recursos TransportServer definem uma ampla variedade de opções para balanceamento de carga de TCP/UDP e passagem direta de TLS. Os recursos TransportServer são usados em conjunto com os recursos GlobalConfiguration para controlar conexões de entrada e saída.

Para obter mais informações, consulte Suporte a serviços de passagem de TCP, UDP e TLS em recursos do NGINX Ingress em nosso blog.

Converter anotações do Community Ingress Controller em recursos do NGINX Ingress

Implantações do Kubernetes em nível de produção geralmente precisam ampliar as regras básicas de Ingress para implementar casos de uso avançados, incluindo implantações canário e blue-green, limitação de tráfego, manipulação do tráfego de entrada e saída, entre outros.

O controlador Ingress da comunidade implementa muitos desses casos de uso com anotações do Kubernetes. No entanto, muitas dessas anotações são criadas com extensões Lua personalizadas relacionadas a definições muito específicas de recursos do NGINX Ingress e, por isso, não são adequadas para implementar funcionalidades avançadas em um ambiente de produção estável e com suporte.

Nas seções a seguir, mostramos como converter as anotações do controlador Ingress da comunidade em recursos do NGINX Ingress Controller.

• Implantações canário
• Controle de tráfego
• Manipulação de cabeçalhos
• Proxy e balanceamento de carga
• Autenticação mTLS
• Persistência de sessão (exclusiva do NGINX Plus)

Implantações canário

Mesmo ao enviar alterações frequentes de código para suas cargas de trabalho de contêineres em produção, você precisa continuar atendendo aos usuários existentes. As implantações canário e azul-verde permitem fazer isso e podem ser realizadas no plano de dados do NGINX Ingress Controller para obter atualizações estáveis e previsíveis em ambientes Kubernetes de nível de produção.

A tabela mostra os campos nos recursos VirtualServer e VirtualServerRoute do NGINX que correspondem às anotações do controlador Ingress da comunidade para implantações canário.

O controlador Ingress da comunidade avalia as anotações de canário nesta ordem de precedência:

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 o NGINX Ingress Controller os avalie da mesma forma, eles devem aparecer nessa ordem no manifesto do NGINX VirtualServer ou VirtualServerRoute.

				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
				

Controle de tráfego

Em ambientes de microsserviços, nos quais as aplicações são efêmeras por natureza e, portanto, mais propensas a retornar respostas de erro, as equipes de DevOps fazem amplo uso de políticas de controle de tráfego — como circuit breaking e limitação de taxa e de conexões — para evitar condições de erro quando as aplicações não estão íntegras ou não funcionam conforme o esperado.

A tabela mostra os campos nos recursos VirtualServer e VirtualServerRoute do NGINX que correspondem às anotações do controlador Ingress da comunidade para limitação de taxa, erros HTTP personalizados, um backend padrão personalizado e reescrita de URI.

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"
				

Conforme indicado na tabela, até o momento, os recursos do NGINX Ingress não incluem campos que correspondam diretamente às quatro anotações a seguir do controlador Ingress da comunidade, portanto, é necessário usar snippets. O suporte direto às quatro anotações por meio de recursos de Policy está planejado para versões futuras do 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

Manipulação de cabeçalhos

A manipulação de cabeçalhos HTTP é útil em muitos casos de uso, pois eles contêm informações adicionais importantes e relevantes para os sistemas envolvidos em uma transação HTTP. Por exemplo, o controlador Ingress da comunidade permite habilitar e configurar cabeçalhos de compartilhamento de recursos entre origens (CORS), usados em aplicações AJAX nas quais o código JavaScript de front-end executado em um navegador se conecta a uma aplicação de backend ou a um servidor web.

A tabela mostra os campos nos recursos VirtualServer e VirtualServerRoute do NGINX que correspondem às anotações do controlador Ingress da comunidade para manipulação de cabeçalhos.

				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 e balanceamento de carga

Há outras funcionalidades de proxy e balanceamento de carga que você pode querer configurar no NGINX Ingress Controller, dependendo do caso de uso específico. Essas funcionalidades incluem a definição do algoritmo de balanceamento de carga, bem como das configurações de tempo limite e armazenamento em buffer para conexões que passam pelo proxy.

A tabela mostra as instruções no campo upstream dos recursos VirtualServer e VirtualServerRoute do NGINX que correspondem às anotações do controlador Ingress da comunidade para balanceamento de carga personalizado do NGINX, tempos limite do proxy, buffering do proxy, e roteamento de conexões para o endereço IP e a porta do Cluster IP de um serviço.

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
				

Autenticação mTLS

Uma malha de serviços é particularmente útil em um ambiente rigoroso de confiança zero, no qual aplicações distribuídas dentro de um cluster se comunicam com segurança por meio de autenticação mútua. E se precisarmos impor esse mesmo nível de segurança ao tráfego que entra e sai do cluster (tráfego norte-sul)?

Podemos configurar a autenticação mTLS na camada do Ingress Controller para que os sistemas nas extremidades das conexões externas autentiquem um ao outro apresentando um certificado válido.

A tabela mostra os campos nos recursos de Policy do NGINX que correspondem às anotações do Ingress Controller da comunidade para autenticação por certificado do cliente e autenticação por certificado do backend.

				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
				

Persistência de sessão (exclusiva do NGINX Plus)

A tabela mostra os campos nos recursos de Policy do NGINX que são exclusivos do NGINX Ingress Controller baseado no NGINX Plus e correspondem às anotações do Ingress Controller da comunidade para persistência de sessão (afinidade).

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
				

Opção 2: migre usando o recurso Ingress do Kubernetes

A segunda opção para migrar do controlador Ingress da comunidade para o NGINX Ingress Controller é usar apenas anotações e ConfigMaps no recurso Ingress padrão do Kubernetes e, possivelmente, utilizar um processamento no estilo “mestre/minion”. Isso mantém toda a configuração no objeto Ingress.

Observação: Com esse método, não altere o campo spec do recurso Ingress.

Configuração avançada com anotações

A tabela a seguir apresenta as anotações do controlador Ingress da comunidade que correspondem diretamente às anotações compatíveis com o NGINX Ingress Controller.

				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_buffersproxy_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"
				

¹O controlador Ingress da comunidade usa Lua para implementar alguns de seus algoritmos de balanceamento de carga. O NGINX Ingress Controller não possui um equivalente para todos eles.

²Redireciona o tráfego HTTP para HTTPS. O controlador Ingress da comunidade implementa isso com código Lua, enquanto o NGINX Ingress Controller usa condições if nativas do NGINX.

A tabela a seguir apresenta as anotações do controlador Ingress da comunidade que correspondem diretamente às anotações compatíveis com o NGINX Ingress Controller baseado no 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"
				

Observação: o NGINX Ingress Controller baseado no NGINX Plus tem anotações adicionais para recursos que não são compatíveis com o Ingress Controller da comunidade, incluindo verificações ativas de integridade e autenticação usando JSON Web Tokens (JWTs).

Configuração global com ConfigMaps

A tabela a seguir relaciona as chaves do ConfigMap do controlador Ingress da comunidade às chaves diretamente correspondentes do ConfigMap do NGINX Ingress Controller. Observe que alguns nomes de chaves do ConfigMap são idênticos. Além disso, tanto o controlador Ingress da comunidade quanto o NGINX Ingress Controller têm chaves de ConfigMap que não existem no outro (não mostradas na tabela).

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

Resumo

Você pode migrar do controlador Ingress da comunidade para o NGINX Ingress Controller usando recursos personalizados do NGINX Ingress ou o recurso Ingress padrão do Kubernetes com anotações e ConfigMaps. A primeira opção oferece suporte a um conjunto mais amplo de recursos de rede e, portanto, é mais adequada para ambientes Kubernetes de nível de produção.

Este post é um trecho do nosso eBook completo, Como gerenciar o tráfego do Kubernetes com o F5 NGINX: um guia prático. Baixe-o gratuitamente hoje mesmo.

Experimente o NGINX Ingress Controller baseado no NGINX Plus com uma avaliação gratuita de 30 dias hoje mesmo ou entre em contato conosco para conversar sobre seus casos de uso.

Sobre o autor

Amir RawdatEngenheiro de Soluções

Mais publicações de Amir Rawdat