Migrer du contrôleur Ingress communautaire vers F5 NGINX Ingress Controller

Amir RawdatIngénieur solutions

Note de la rédaction – Cet article est un extrait de notre livre numérique complet, « Gestion du trafic Kubernetes avec F5 NGINX : guide pratique ». Téléchargez-le gratuitement dès aujourd’hui.

De nombreuses organisations qui mettent en place Kubernetes pour la première fois commencent par utiliser le contrôleur Ingress NGINX développé et maintenu par la communauté Kubernetes (kubernetes/ingress-nginx). Toutefois, à mesure que leurs déploiements Kubernetes gagnent en maturité, certaines organisations constatent qu’elles ont besoin de fonctionnalités avancées ou souhaitent bénéficier d’un support commercial tout en conservant NGINX comme plan de données.

Une option consiste à migrer vers le contrôleur Ingress NGINX développé et maintenu par F5 NGINX (nginxinc/kubernetes-ingress). Nous fournissons ici des instructions complètes afin de vous éviter certaines complications liées aux différences entre les deux projets.

Vous ne savez pas exactement ce qui distingue ces options ? Consultez l’article « Guide pour choisir un contrôleur Ingress, 4e partie : les options de contrôleur Ingress NGINX » sur notre blog.

Afin de distinguer les deux projets dans la suite de cet article, nous désignons le contrôleur Ingress NGINX géré par la communauté Kubernetes (kubernetes/ingress-nginx) comme le « contrôleur Ingress communautaire » et celui géré par F5 NGINX (nginxinc/kubernetes-ingress) comme le « contrôleur Ingress NGINX ».

Il existe deux façons de migrer du contrôleur Ingress communautaire vers NGINX Ingress Controller :

• Option 1 : migrer à l’aide des ressources NGINX Ingress
  Il s’agit de la solution optimale, car les ressources NGINX Ingress prennent en charge l’ensemble plus étendu de fonctionnalités réseau Ingress nécessaires aux environnements Kubernetes de production. Pour en savoir plus sur les ressources NGINX Ingress, regardez notre webinaire, « Déploiements Kubernetes avancés avec NGINX Ingress Controller ».
• Option 2 : migrer à l’aide de la ressource Ingress Kubernetes
  Cette option est recommandée si vous souhaitez utiliser la ressource standard Ingress Kubernetes pour définir les règles d’équilibrage de charge Ingress.

Option 1 : migrer à l’aide des ressources Ingress NGINX

Avec cette option de migration, vous utilisez la ressource Ingress standard de Kubernetes pour définir les fonctionnalités de base et les ressources Ingress NGINX pour enrichir votre configuration avec des fonctionnalités accrues et une plus grande facilité d’utilisation.

Les définitions de ressources personnalisées (CRD) pour les ressources NGINX Ingress – VirtualServer, VirtualServerRoute, TransportServer, GlobalConfiguration et Policy – vous permettent de déléguer facilement le contrôle de différentes parties de la configuration à différentes équipes (telles que les équipes AppDev et de sécurité), tout en renforçant la sécurité et la validation de la configuration.

Configuration de la terminaison SSL et du routage HTTP basé sur les chemins

Le tableau établit la correspondance entre la configuration de la terminaison SSL et du routage de couche 7 basé sur les chemins dans le champ « spec » de la ressource Ingress Kubernetes standard et celle du champ « spec » de la ressource NGINX VirtualServer. La syntaxe et l’indentation diffèrent légèrement entre les deux ressources, mais celles-ci assurent les mêmes fonctions Ingress de base.

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

Configuration de l’équilibrage de charge TCP/UDP et du relais TLS

Avec le contrôleur Ingress communautaire, un objet d’API Kubernetes de type « ConfigMap » est le seul moyen d’exposer des services TCP et UDP.

Avec NGINX Ingress Controller, les ressources « TransportServer » offrent un large éventail d’options pour l’équilibrage de charge TCP/UDP et TLS Passthrough. Les ressources TransportServer sont utilisées conjointement avec les ressources « GlobalConfiguration » pour contrôler les connexions entrantes et sortantes.

Pour plus d’informations, consultez l’article « Prise en charge des services TCP, UDP et TLS Passthrough dans les ressources NGINX Ingress » sur notre blog.

Convertir les annotations du contrôleur Ingress communautaire en ressources Ingress NGINX

Les déploiements Kubernetes de niveau production nécessitent souvent d’étendre les règles Ingress de base afin de mettre en œuvre des cas d’usage avancés, notamment les déploiements Canary et bleu-vert, la limitation du trafic, la manipulation du trafic entrant et sortant, et bien plus encore.

Le contrôleur Ingress communautaire met en œuvre bon nombre de ces cas d’utilisation à l’aide d’annotations Kubernetes. Cependant, nombre de ces annotations reposent sur des extensions Lua personnalisées propres à des définitions très spécifiques de ressources Ingress NGINX et ne conviennent donc pas à la mise en œuvre de fonctionnalités avancées dans un environnement de production stable et bénéficiant d’un support.

Dans les sections suivantes, nous expliquons comment convertir les annotations du contrôleur Ingress communautaire en ressources du contrôleur NGINX Ingress.

• Déploiements Canary
• Contrôle du trafic
• Manipulation des en-têtes
• Mise en proxy et équilibrage de charge
• Authentification mTLS
• Persistance de session (exclusivité NGINX Plus)

Déploiements canaris

Même lorsque vous déployez fréquemment des modifications de code sur vos charges de travail conteneurisées en production, vous devez continuer à servir vos utilisateurs existants. Les déploiements Canary et bleu-vert vous permettent de le faire. Vous pouvez les effectuer sur le plan de données de NGINX Ingress Controller afin de garantir des mises à jour stables et prévisibles dans des environnements Kubernetes adaptés à la production.

Le tableau présente les champs des ressources NGINX « VirtualServer et VirtualServerRoute » qui correspondent aux annotations du contrôleur Ingress communautaire pour les déploiements Canary.

Le contrôleur Ingress communautaire évalue les annotations de déploiement canari selon l’ordre de priorité suivant :

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

Pour que NGINX Ingress Controller les évalue de la même manière, ils doivent apparaître dans cet ordre dans le manifeste 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
				

Contrôle du trafic

Dans les environnements de microservices, où les applications sont par nature éphémères et donc plus susceptibles de renvoyer des réponses d’erreur, les équipes DevOps ont largement recours à des politiques de contrôle du trafic, telles que les coupe-circuits et la limitation du débit et du nombre de connexions, afin d’éviter les erreurs lorsque les applications sont défaillantes ou ne fonctionnent pas comme prévu.

Le tableau présente les champs des ressources NGINX « VirtualServer et VirtualServerRoute » qui correspondent aux annotations du contrôleur Ingress communautaire pour la limitation du débit, les erreurs HTTP personnalisées, un backend par défaut personnalisé et la réécriture d’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"
				

Comme indiqué dans le tableau, à l’heure où nous écrivons ces lignes, les ressources Ingress de NGINX ne comportent aucun champ permettant de transposer directement les quatre annotations suivantes du contrôleur Ingress communautaire ; vous devez donc utiliser des extraits de configuration. La prise en charge directe de ces quatre annotations au moyen de ressources « Policy » est prévue dans de prochaines versions 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

Manipulation des en-têtes

La manipulation des en-têtes HTTP est utile dans de nombreux cas, car ils contiennent des informations supplémentaires importantes et pertinentes pour les systèmes impliqués dans une transaction HTTP. Par exemple, le contrôleur Ingress communautaire permet d’activer et de configurer les en-têtes de partage de ressources entre origines (CORS), utilisés avec les applications AJAX lorsque le code JavaScript frontal exécuté dans un navigateur se connecte à une application backend ou à un serveur web.

Le tableau présente les champs des ressources NGINX « VirtualServer et VirtualServerRoute » qui correspondent aux annotations du contrôleur Ingress communautaire relatives à la manipulation des en-têtes.

				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 et équilibrage de charge

Selon votre cas d’usage, vous pouvez configurer d’autres fonctionnalités de proxy et de répartition de charge dans NGINX Ingress Controller. Celles-ci comprennent notamment le choix de l’algorithme de répartition de charge, ainsi que la configuration des délais d’expiration et de la mise en mémoire tampon pour les connexions faisant l’objet d’un proxy.

Le tableau présente les directives du champ upstream des ressources VirtualServer et VirtualServerRoute de NGINX qui correspondent aux annotations du contrôleur Ingress communautaire pour l’équilibrage de charge NGINX personnalisé, les délais d’expiration du proxy, la mise en mémoire tampon du proxy et le routage des connexions vers l’adresse IP du cluster et le port d’un service.

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
				

Authentification mTLS

Un maillage de services est particulièrement utile dans un environnement strict de confiance zéro, où les applications distribuées au sein d’un cluster communiquent de manière sécurisée en s’authentifiant mutuellement. Et si nous devions imposer le même niveau de sécurité au trafic entrant et sortant du cluster (trafic nord-sud) ?

Nous pouvons configurer l’authentification mTLS au niveau du contrôleur Ingress afin que les systèmes situés aux extrémités des connexions externes s’authentifient mutuellement en présentant un certificat valide.

Le tableau présente les champs des ressources Policy de NGINX qui correspondent aux annotations du contrôleur Ingress communautaire pour l’authentification par certificat client et l’authentification par certificat du serveur 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
				

Persistance de session (exclusivité NGINX Plus)

Le tableau présente les champs des ressources Policy NGINX qui sont propres à NGINX Ingress Controller basé sur NGINX Plus et qui correspondent aux annotations du contrôleur Ingress communautaire relatives à la persistance de session (affinité).

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
				

Option 2 : migrer à l’aide de la ressource Ingress de Kubernetes

La deuxième option pour migrer du contrôleur Ingress communautaire vers NGINX Ingress Controller consiste à utiliser uniquement des annotations et des ConfigMaps dans la ressource Ingress standard de Kubernetes, et éventuellement à s’appuyer sur un traitement de type « maître/minion ». Ainsi, toute la configuration reste dans l’objet Ingress.

Remarque : Avec cette méthode, ne modifiez pas le champ spec de la ressource Ingress.

Configuration avancée avec des annotations

Le tableau suivant présente les annotations du contrôleur Ingress communautaire qui correspondent directement aux annotations prises en charge par 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"
				

¹Le contrôleur Ingress communautaire utilise Lua pour implémenter certains de ses algorithmes d’équilibrage de charge. NGINX Ingress Controller ne dispose pas d’un équivalent pour chacun d’entre eux.

²Redirige le trafic HTTP vers HTTPS. Le contrôleur Ingress communautaire met en œuvre cette fonctionnalité avec du code Lua, tandis que NGINX Ingress Controller utilise les conditions if natives de NGINX.

Le tableau suivant présente les annotations du contrôleur Ingress communautaire qui correspondent directement aux annotations prises en charge par le contrôleur Ingress NGINX basé sur 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"
				

Remarque : le contrôleur Ingress NGINX basé sur NGINX Plus dispose d’annotations supplémentaires pour des fonctionnalités que le contrôleur Ingress communautaire ne prend pas du tout en charge, notamment les contrôles d’intégrité actifs et l’authentification à l’aide de jetons Web JSON (JWT).

Configuration globale avec les ConfigMaps

Le tableau suivant établit la correspondance entre les clés ConfigMap du contrôleur Ingress communautaire et les clés ConfigMap équivalentes du contrôleur Ingress NGINX. Notez que certains noms de clés ConfigMap sont identiques. Par ailleurs, le contrôleur Ingress communautaire et le contrôleur Ingress NGINX possèdent chacun des clés ConfigMap qui n’existent pas chez l’autre (non indiquées dans le tableau).

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

Résumé

Vous pouvez migrer du contrôleur Ingress communautaire vers NGINX Ingress Controller en utilisant soit des ressources NGINX Ingress personnalisées, soit la ressource Ingress standard de Kubernetes avec des annotations et des ConfigMaps. La première option prend en charge un éventail plus large de fonctionnalités réseau et convient donc mieux aux environnements Kubernetes de production.

Cet article est un extrait de notre e-book complet, « Gestion du trafic Kubernetes avec F5 NGINX : guide pratique ». Téléchargez-le gratuitement dès aujourd’hui.

Essayez par vous-même le contrôleur Ingress NGINX basé sur NGINX Plus grâce à un essai gratuit de 30 jours dès aujourd’hui, ou contactez-nous pour discuter de vos cas d’utilisation.

À propos de l’auteur

Amir RawdatIngénieur solutions

Autres articles de Amir Rawdat