BLOG | NGINX

Migration du contrôleur d'entrée communautaire vers le contrôleur d'entrée F5 NGINX

NGINX-Partie-de-F5-horiz-black-type-RGB
Miniature d'Amir Rawdat
Amir Rawdat
Publié le 19 mai 2022

Éditeur – Cet article est un extrait de notre livre électronique complet, Managing Kubernetes Traffic with F5 NGINX : Un guide pratique . Téléchargez-le gratuitement aujourd'hui .

De nombreuses organisations qui configurent Kubernetes pour la première fois commencent avec le contrôleur NGINX Ingress développé et maintenu par la communauté Kubernetes ( kubernetes/ingress-nginx ). Cependant, à mesure que les déploiements Kubernetes arrivent à maturité, certaines organisations constatent qu'elles ont besoin de fonctionnalités avancées ou souhaitent un support commercial tout en conservant NGINX comme plan de données.

Une option consiste à migrer vers le contrôleur d'entrée NGINX développé et maintenu par F5 NGINX ( nginxinc/kubernetes-ingress ), et nous fournissons ici des instructions complètes afin que vous puissiez éviter certaines complications résultant des différences entre les deux projets.

Vous ne savez pas en quoi ces options diffèrent ? Lisez le guide pour choisir un contrôleur d'entrée, partie 4 : Options du contrôleur d'entrée NGINX sur notre blog.

Pour faire la distinction entre les deux projets dans le reste de cet article, nous désignons le contrôleur d'entrée NGINX maintenu par la communauté Kubernetes ( kubernetes/ingress-nginx ) par le terme « contrôleur d'entrée communautaire » et celui maintenu par F5 NGINX ( nginxinc/kubernetes-ingress ) par le terme « contrôleur d'entrée NGINX ».

Il existe deux manières de migrer du contrôleur d'entrée de la communauté vers le contrôleur d'entrée NGINX :

Option 1 : Migrer à l'aide des ressources d'entrée NGINX

Avec cette option de migration, vous utilisez la ressource Kubernetes Ingress standard pour définir les capacités racine et les ressources NGINX Ingress pour améliorer votre configuration avec des capacités accrues et une 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é) et de fournir une meilleure sécurité et validation de la configuration.

Configuration de la terminaison SSL et du routage basé sur le chemin HTTP

Le tableau mappe la configuration de la terminaison SSL et du routage basé sur le chemin de couche 7 dans le champ spec de la ressource Kubernetes Ingress standard avec le champ spec de la ressource NGINX VirtualServer . La syntaxe et l’indentation diffèrent légèrement dans les deux ressources, mais elles accomplissent les mêmes fonctions Ingress de base.

Ressource d'entrée Kubernetes Ressource du serveur virtuel NGINX 
Version de l'API : networking.k8s.io/v1kind : Entrée
métadonnées :
nom : nginx-test
spécification :
tls :
- hôtes :
- foo.bar.com
secretName : tls-secret
règles :
- hôte : foo.bar.com
http :
chemins :
- chemin : /login
backend : 
serviceName : login-svc
servicePort : 80
- chemin : /facturation
nom_service : facturation-svc
port_service : 80

Version de l'API : networking.k8s.io/v1kind : Serveur virtuel
métadonnées :
nom : nginx-test
spécification :
hôte : foo.bar.com
tls :
secret : tls-secret
flux en amont :
- nom : login
service : login-svc
port : 80
- nom : facturation 
service : facturation-svc
port : 80
routes : 
- chemin : /login
action :
pass : login 
- chemin : /billing 
action : 
pass : billing

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

Avec le contrôleur Ingress communautaire, un objet API Kubernetes ConfigMap est le seul moyen d'exposer les services TCP et UDP .

Avec NGINX Ingress Controller, les ressources TransportServer définissent une large gamme 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 Prise en charge des services de relais TCP, UDP et TLS dans les ressources NGINX Ingress sur notre blog.

Convertir les annotations du contrôleur d'entrée communautaire en ressources d'entrée NGINX

Les déploiements Kubernetes de niveau production doivent souvent étendre les règles d’entrée de base pour implémenter des cas d’utilisation avancés, notamment les déploiements Canary et Blue-Green, la limitation du trafic, la manipulation du trafic entrant-sortant, etc.

Le contrôleur Ingress communautaire implémente bon nombre de ces cas d'utilisation avec des annotations Kubernetes. Cependant, bon nombre de ces annotations sont créées avec des extensions Lua personnalisées qui se rapportent à des définitions de ressources NGINX Ingress très spécifiques et ne sont donc pas adaptées à la mise en œuvre de fonctionnalités avancées dans un environnement de production stable et pris en charge.

Dans les sections suivantes, nous montrons comment convertir les annotations du contrôleur Ingress de la communauté en ressources du contrôleur Ingress NGINX.

Déploiements Canary

Même si vous appliquez des modifications de code fréquentes à vos charges de travail de conteneur de production, vous devez continuer à servir vos utilisateurs existants. Les déploiements Canary et Blue-Green vous permettent de le faire, et vous pouvez les exécuter sur le plan de données NGINX Ingress Controller pour obtenir des mises à jour stables et prévisibles dans les environnements Kubernetes de niveau production.

Le tableau affiche les champs des ressources NGINX VirtualServer et VirtualServerRoute qui correspondent aux annotations du contrôleur d'entrée de la communauté pour les déploiements Canary .

Le contrôleur Ingress de la communauté évalue les annotations canari dans cet ordre de priorité :

  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.

Contrôleur d'entrée communautaire Contrôleur d'entrée NGINX 
nginx.ingress.kubernetes.io/canary: "true"nginx.ingress.kubernetes.io/canary-by-header: "httpHeader"

correspondances :- conditions : - en-tête : httpHeader valeur : jamais action : passer : echo - en-tête : httpHeader valeur : toujours action : passer : echo-canary action : passer : echo

nginx.ingress.kubernetes.io/canary : « true » nginx.ingress.kubernetes.io/canary-by-header : « httpHeader » nginx.ingress.kubernetes.io/canary-by-header-value : « ma-valeur »

correspondances : - conditions : - en-tête : httpHeader valeur : ma-valeur action : pass : echo-canary action : pass : echo

nginx.ingress.kubernetes.io/canary: "true"nginx.ingress.kubernetes.io/canary-by-cookie: "cookieName"

correspondances : - conditions :
- cookie : cookieName
valeur : jamais
action :
pass : echo 
- cookie : cookieName
valeur : toujours
action :
pass : echo-canary
action :
pass : echo

nginx.ingress.kubernetes.io/canary: "true"nginx.ingress.kubernetes.io/canary-weight: "10"

fractionnements :- poids: 90 action : passe : écho - poids : 10 action : passe : écho-canari

Contrôle de la circulation

Dans les environnements de microservices, où les applications sont éphémères par nature et donc plus susceptibles de renvoyer des réponses d'erreur, les équipes DevOps utilisent largement les politiques de contrôle du trafic – telles que la coupure de circuit et la limitation du débit et de la connexion – pour éviter les conditions d'erreur lorsque les applications ne sont pas saines ou ne fonctionnent pas comme prévu.

Le tableau affiche les champs des ressources NGINX VirtualServer et VirtualServerRoute qui correspondent aux annotations du contrôleur d'entrée de la communauté pour la limitation du débit , les erreurs HTTP personnalisées , un backend par défaut personnalisé et la réécriture d'URI .

Contrôleur d'entrée communautaire Contrôleur d'entrée NGINX 
nginx.ingress.kubernetes.io/custom-http-errors: " code " nginx.ingress.kubernetes.io/default-backend: " default-svc "

errorPages :- codes: [ code ] redirection: code: 301 url : default-svc

nginx.ingress.kubernetes.io/limit-connections : « nombre »

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: " nombre " nginx.ingress.kubernetes.io/limit-rate-after: " nombre "

emplacement-extraits : | limit_rate nombre ; limit_rate_after nombre ;

nginx.ingress.kubernetes.io/limit-rpm: " nombre " nginx.ingress.kubernetes.io/limit-burst-multiplier: " multiplicateur "

rateLimit : débit : nombre r/m burst : nombre * multiplicateur clé : ${binary_remote_addr} zoneSize : taille

nginx.ingress.kubernetes.io/limit-rps : « nombre » nginx.ingress.kubernetes.io/limit-burst-multiplier : « multiplicateur »

rateLimit : débit : nombre r/s burst : nombre * multiplicateur clé : ${binary_remote_addr} zoneSize : taille

nginx.ingress.kubernetes.io/limit-whitelist : " CIDR "

extraits http : | extraits du serveur : |

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

chemin de réécriture : " URI "

Comme indiqué dans le tableau, au moment de la rédaction de cet article, les ressources NGINX Ingress n'incluent pas de champs qui traduisent directement les quatre annotations suivantes du contrôleur Ingress de communauté, et vous devez utiliser des extraits. La prise en charge directe des quatre annotations, à l’aide des ressources de stratégie , est prévue pour les futures 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 de l'en-tête

La manipulation des en-têtes HTTP est utile dans de nombreux cas d'utilisation, 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 de communauté prend en charge l'activation et la définition des en-têtes de partage de ressources inter-origines (CORS), qui sont utilisés avec les applications AJAX, où le code JavaScript frontal d'un navigateur se connecte à une application principale ou à un serveur Web.

Le tableau affiche les champs des ressources NGINX VirtualServer et VirtualServerRoute qui correspondent aux annotations du contrôleur d'entrée de la communauté pour la manipulation des en-têtes .

Contrôleur d'entrée communautaire Contrôleur d'entrée NGINX 
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 : " secondes "

responseHeaders : ajouter : - nom : Valeur Access-Control-Allow-Credentials : « true » - nom : Valeur Access-Control-Allow-Headers : « X-Forwarded-For » - nom : Valeur Access-Control-Allow-Methods : « PUT, GET, POST, OPTIONS » - nom : Valeur Access-Control-Allow-Origin : « * » - nom : Valeur Access-Control-Max-Age : « secondes »

Proxy et équilibrage de charge

Il existe d’autres fonctionnalités de proxy et d’équilibrage de charge que vous souhaiterez peut-être configurer dans NGINX Ingress Controller en fonction du cas d’utilisation spécifique. Ces fonctionnalités incluent la définition de l’algorithme d’équilibrage de charge ainsi que les paramètres de délai d’expiration et de mise en mémoire tampon pour les connexions proxy.

Le tableau affiche les instructions dans le champ en amont des ressources NGINX VirtualServer et VirtualServerRoute qui correspondent aux annotations du contrôleur d'entrée de communauté pour l'équilibrage de charge NGINX personnalisé , les délais d'expiration du proxy , la mise en mémoire tampon du proxy et les connexions de routage vers l'adresse IP et le port du cluster d'un service .

Contrôleur d'entrée communautaire Contrôleur d'entrée NGINX 
nginx.ingress.kubernetes.io/load-balance

méthode lb

nginx.ingress.kubernetes.io/proxy-buffering

mise en mémoire tampon

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

tampons

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

délai de connexion expiré

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

en amont

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

prochain délai d'attente en amont

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

délai de lecture dépassé

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

délai d'envoi expiré

nginx.ingress.kubernetes.io/service-upstream

utiliser-cluster-ip

Authentification mTLS

Un service mesh est particulièrement utile dans un environnement de confiance zéro strict, où les applications distribuées au sein d’un cluster communiquent de manière sécurisée en s’authentifiant mutuellement. Que se passerait-il 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 de la couche Ingress Controller afin que les systèmes d’extrémité des connexions externes s’authentifient mutuellement en présentant un certificat valide.

Le tableau affiche les champs des ressources de stratégie NGINX qui correspondent aux annotations du contrôleur d’entrée de la communauté pour l’authentification du certificat client et l’authentification du certificat back-end .

Contrôleur d'entrée communautaire Contrôleur d'entrée NGINX 

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 : "DEFAUT"
nginx.ingress.kubernetes.io/proxy-ssl-name : "nom-du-serveur"
nginx.ingress.kubernetes.io/proxy-ssl-server-name : "on|off"

egressMTLS : tlsSecret : secretName verifyServer : vrai|faux verifyDepth : 1 protocoles : Chiffres TLSv1.2 : PAR DÉFAUT sslName : nom-du-serveur serverName : true|false

Persistance de session (exclusivité NGINX Plus)

Le tableau affiche les champs des ressources de stratégie NGINX qui sont exclusifs au contrôleur d'entrée NGINX basé sur NGINX Plus et correspondent aux annotations du contrôleur d'entrée de la communauté pour la persistance de session (affinité).

Contrôleur d'entrée communautaire Contrôleur d'entrée NGINX 
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 : activer : vrai nom : cookieName expire : x h chemin : /route sécurisé : vrai

Option 2 : Migrer à l'aide de la ressource Kubernetes Ingress

La deuxième option pour migrer du contrôleur Ingress de la communauté vers le contrôleur Ingress NGINX consiste à utiliser uniquement des annotations et des ConfigMaps dans la ressource Ingress Kubernetes standard et à s'appuyer potentiellement sur un traitement de type « master/minion ». Cela conserve toute la configuration dans l'objet Ingress.

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

Configuration avancée avec annotations

Le tableau suivant décrit les annotations du contrôleur Ingress de la communauté qui correspondent directement aux annotations prises en charge par NGINX Ingress Controller.

Contrôleur d'entrée communautaire Contrôleur d'entrée NGINX Directive NGINX 
nginx.ingress.kubernetes.io/configuration-snippet : |

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

nginx.org/lb-method
Défaut:

 

aléatoire deux least_conn

nginx.ingress.kubernetes.io/proxy-buffering : « activé|désactivé »

nginx.org/proxy-buffering : "Vrai|Faux"

tampon_proxy

nginx.ingress.kubernetes.io/proxy-buffers-number : « nombre » nginx.ingress.kubernetes.io/proxy-buffer-size : « x k »

nginx.org/proxy-buffers : " nombre 4k|8k " nginx.org/proxy-buffer-size : « 4k|8k »

proxy_buffers taille_tampon_proxy

nginx.ingress.kubernetes.io/proxy-connect-timeout : « secondes »

nginx.org/proxy-connect-timeout : : « secondes »

délai_de_connexion_proxy_expiré

nginx.ingress.kubernetes.io/proxy-read-timeout : « secondes »

nginx.org/proxy-read-timeout : « secondes s »

délai d'attente de lecture du proxy

nginx.ingress.kubernetes.io/proxy-send-timeout : « secondes »

nginx.org/proxy-send-timeout : « secondes s »

délai d'expiration d'envoi du proxy

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

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

récrire

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

nginx.org/server-snippets : |
N / A 
nginx.ingress.kubernetes.io/ssl-redirect : « vrai|faux »

ingress.kubernetes.io/ssl-redirect : "Vrai|Faux"
N / A2

1Le contrôleur Ingress communautaire utilise Lua pour implémenter certains de ses algorithmes d’équilibrage de charge. NGINX Ingress Controller n’a pas d’équivalent pour tous.

2Redirige le trafic HTTP vers HTTPS. Le contrôleur Ingress communautaire implémente cela avec du code Lua, tandis que le contrôleur Ingress NGINX utilise les conditions if NGINX natives.

Le tableau suivant décrit les annotations du contrôleur d’entrée de la communauté qui correspondent directement aux annotations prises en charge par le contrôleur d’entrée NGINX basé sur NGINX Plus.

Contrôleur d'entrée communautaire Contrôleur d'entrée 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 : " secondes " nginx.ingress.kubernetes.io/session-cookie-path : "/ route "

nginx.com/sticky-cookie-services : "serviceName= exemple-svc cookie_name expire= heure chemin=/ route "

Note: Le contrôleur d'entrée NGINX basé sur NGINX Plus dispose d'annotations supplémentaires pour les fonctionnalités que le contrôleur d'entrée de la communauté ne prend pas du tout en charge, notamment les contrôles de santé actifs et l'authentification à l'aide de jetons Web JSON (JWT).

Configuration globale avec ConfigMaps

Le tableau suivant mappe les clés ConfigMap du contrôleur d'entrée de la communauté à leurs clés ConfigMap du contrôleur d'entrée NGINX directement correspondantes. Notez qu’une poignée de noms de clés ConfigMap sont identiques. De plus, le contrôleur d’entrée de la communauté et le contrôleur d’entrée NGINX disposent tous deux de clés ConfigMaps que l’autre n’a pas (non affichées dans le tableau).

Contrôleur d'entrée communautaire Contrôleur d'entrée NGINX 
désactiver-le-journal-d'accès

accès-déconnexion

niveau de journal des erreurs

niveau de journal des erreurs

hst

hst

hsts-include-sous-domaines

hsts-include-sous-domaines

hsts-max-âge

hsts-max-âge

http-extrait

Extraits http

garder en vie

Délai d'attente de la fonction Keepalive

demandes de maintien en vie

demandes de maintien en vie

équilibrage de charge

méthode lb

emplacement-extrait

extraits de localisation

log-format-escape-json : "true"

échappement-du-format-du-journal : "json"

flux de format de journal

format de journal de flux

format-journal-en-amont

format de journal

extrait principal

extraits principaux

nombre-maximal-de-connexions-de-travailleurs 

connexions des travailleurs

max-worker-open-fichiers

travailleur-rlimit-nofile

taille du corps du proxy

taille-max-du-corps-du-client

mise en mémoire tampon du proxy

mise en mémoire tampon du proxy

proxy-buffers-number : " nombre " proxy-buffer-size : " taille "

proxy-buffers : nombre taille

délai d'expiration de la connexion proxy

délai d'expiration de la connexion proxy

délai d'attente de lecture du proxy

délai d'attente de lecture du proxy

délai d'expiration d'envoi du proxy

délai d'expiration d'envoi du proxy

nom-du-serveur-hash-taille-du-bucket

noms-de-serveur-hash-bucket-size

nom-du-serveur-hash-taille-max

noms-de-serveur-hash-taille-max

extrait de serveur

extraits de serveur

jetons de serveur

jetons de serveur

chiffrements ssl

chiffrements ssl

paramètre ssl-dh

fichier ssl-dhparam

protocoles ssl

protocoles ssl

redirection ssl

redirection ssl

connexions keepalive en amont

rester en vie

utiliser-http2

http2

utiliser-protocole-proxy

protocole proxy

variables-hash-bucket-size

variables-hash-bucket-size

affinité entre le travailleur et le processeur

affinité entre le travailleur et le processeur

processus de travail

processus de travail

délai d'arrêt du travailleur

délai d'arrêt du travailleur

Résumé

Vous pouvez migrer du contrôleur Ingress de la communauté vers le contrôleur Ingress NGINX à l'aide de ressources Ingress NGINX personnalisées ou de la ressource Ingress Kubernetes standard avec des annotations et des ConfigMaps. La première option prend en charge un ensemble plus large de fonctionnalités réseau et est donc plus adaptée aux environnements Kubernetes de niveau production.

Cet article est un extrait de notre eBook complet, Gérer le trafic Kubernetes avec F5 NGINX : Un guide pratique . Téléchargez-le gratuitement dès aujourd'hui .

Essayez dès aujourd'hui le contrôleur d'entrée NGINX basé sur NGINX Plus dans le cadre d'un essai gratuit de 30 jours ou contactez-nous pour discuter de vos cas d'utilisation .

Lire plus d'articles de blog sur F5 NGINX ›

« Cet article de blog peut faire référence à des produits qui ne sont plus disponibles et/ou qui ne sont plus pris en charge. Pour obtenir les informations les plus récentes sur les produits et solutions F5 NGINX disponibles, explorez notre famille de produits NGINX . NGINX fait désormais partie de F5. Tous les liens NGINX.com précédents redirigeront vers un contenu NGINX similaire sur F5.com."