Partager via

Contrôleur d’entrée NGINX avancé et configurations d’entrée avec le module complémentaire de routage d’application

  • Article

Le module complémentaire de routage d’application prend en charge deux façons de configurer des contrôleurs d’entrée et des objets d’entrée :

Prérequis

Un cluster AKS avec le module complémentaire de routage d’application.

Se connecter à votre cluster AKS

Pour vous connecter au cluster Kubernetes à partir de votre ordinateur local, vous utilisez kubectl, le client de ligne de commande Kubernetes. Vous pouvez l’installer localement avec la commande az aks install-cli. Si vous utilisez Azure Cloud Shell, kubectl est déjà installé.

Configurez kubectl afin qu’il se connecte à votre cluster Kubernetes en utilisant la commande az aks get-credentials.

az aks get-credentials -resource-group <ResourceGroupName> --name <ClusterName>

Configuration du contrôleur d’entrée NGINX

Le module complémentaire de routage d’applications utilise une définition de ressource personnalisée (CRD) Kubernetes appelée NginxIngressController pour configurer des contrôleurs d’entrée NGINX. Vous pouvez créer d’autres contrôleurs d’entrée ou modifier une configuration existante.

Voici une référence aux propriétés que vous pouvez définir pour configurer une NginxIngressController.

Propriété Description
ingressClassName Nom du IngressClass qui sera utilisé pour le contrôleur d’entrée NGINX. La valeur par défaut est le nom du NginxIngressController s’il n’est pas spécifié.
controllerNamePrefix Nom utilisé pour préfixer les ressources du contrôleur d’entrée NGINX managées. La valeur par défaut est nginx.
loadBalancerAnnotations Ensemble d’annotations pour contrôler le comportement du service du contrôleur d’entrée NGINX en définissant annotations d’équilibreur de charge
mise à l’échelle Options de configuration pour la façon dont le contrôleur d’entrée NGINX est mis à l’échelle.
scaling.minReplicas Limite inférieure pour le nombre de réplicas du contrôleur d’entrée. Il est par défaut de 2 pods.
scaling.maxReplicas Limite supérieure pour le nombre de réplicas du contrôleur d’entrée. Il est par défaut de 100 pods.
scaling.threshold Définit la rapidité avec laquelle les pods du contrôleur d’entrée NGINX doivent être mis à l’échelle en fonction de la charge de travail. Rapid signifie que le contrôleur d’entrée sera mis à l’échelle rapidement et agressivement pour gérer des pics de trafic soudains et significatifs. Steady hiérarchise la rentabilité avec moins de réplicas gérant plus de travail. Balanced est un bon mélange entre les deux qui fonctionne pour la plupart des cas d’usage. S’il n’est pas spécifié, ce champ est défini par défaut sur Balanced.
defaultBackendService Le service Kubernetes auquel le contrôleur d’entrée NGINX doit par défaut gérer tous les chemins d’URL et héberge le contrôleur Ingress-NGINX ne comprend pas (c’est-à-dire toutes les requêtes qui ne sont pas mappées avec une entrée). Le contrôleur dirige le trafic vers le premier port du service. S’il n’est pas spécifié, cela utilise le principal par défaut intégré.
defaultBackendService.namespace Namespace du service.
defaultBackendService.name Nom du service.
defaultSSLCertificate Le secret référencé par cette propriété contient le certificat par défaut à utiliser lors de l’accès au service principal par défaut. Si cette propriété n’est pas fournie, NGINX utilise un certificat auto-signé. Si la section tls: n’est pas définie sur une entrée, NGINX fournit le certificat par défaut, mais ne force pas la redirection HTTPS.
defaultSSLCertificate.forceSSLRedirect Force une redirection pour les Ingresses qui ne spécifient pas de section tls:.
defaultSSLCertificate.keyVaultURI URI Azure Key Vault où se trouve le certificat SSL par défaut. Le module complémentaire doit être configuré pour utiliser le coffre de clés.
defaultSSLCertificate.secret Configure le nom et l’espace de noms où se trouve le secret SSL par défaut sur le cluster.
defaultSSLCertificate.secret.name Nom du secret.
defaultSSLCertificate.secret.namespace Namespace du secret.

Configurations courantes

Contrôler la configuration par défaut du contrôleur d’entrée NGINX (préversion)

Remarque

Le contrôle de la configuration du contrôleur d’entrée NGINX lors de l’activation du module complémentaire est disponible dans API 2024-06-02-preview, Kubernetes version 1.30 ou ultérieure, et la version 7.0.0b5 ou ultérieure de l’extension Azure CLI aks-preview. Pour vérifier la version de votre cluster AKS, consultez Rechercher les mises à niveau disponibles de cluster AKS.

Lorsque vous activez le module complémentaire de routage des applications avec NGINX, il crée un contrôleur d’entrée appelé default dans le app-routing-namespace configuré avec un équilibreur de charge Azure public. Ce contrôleur d’entrée utilise un nom de classe d’entrée de webapprouting.kubernetes.azure.com.

Vous pouvez également la contrôler si la valeur par défaut obtient une adresse IP publique ou interne, ou si elle est créée lors de l’activation du module complémentaire.

Voici les options de configuration possibles :

  • None : le contrôleur d’entrée Nginx par défaut n’est pas créé et ne sera pas supprimé s’il existe déjà. Les utilisateurs doivent supprimer manuellement la ressource personnalisée NginxIngressController par défaut s’ils le souhaitent.
  • Internal : le contrôleur d’entrée Nginx par défaut est créé avec un équilibreur de charge interne. Toutes les modifications apportées aux annotations sur la ressource personnalisée NginxIngressController pour qu’elle soit externe seront remplacées.
  • External : le contrôleur d’entrée Nginx par défaut est créé avec un équilibreur de charge externe. Toutes les modifications apportées aux annotations sur la ressource personnalisée NginxIngressController pour qu’elle soit interne seront remplacées.
  • AnnotationControlled (par défaut) : le contrôleur d’entrée Nginx par défaut est créé avec un équilibreur de charge externe. Les utilisateurs peuvent modifier la ressource personnalisée par défaut NginxIngressController pour configurer les annotations de l’équilibreur de charge.

Contrôler la configuration du contrôleur d’entrée par défaut lors de la création du cluster

Pour activer le routage d’applications sur un nouveau cluster, utilisez la commande az aks create, en spécifiant les indicateurs --enable-app-routing et --app-routing-default-nginx-controller. Vous devez définir <DefaultIngressControllerType> sur l’une des options de configuration décrites précédemment.

az aks create \
--resource-group <ResourceGroupName> \
--name <ClusterName> \
--location <Location> \
--enable-app-routing \
--app-routing-default-nginx-controller <DefaultIngressControllerType>

Mettre à jour la configuration par défaut du contrôleur d’entrée sur un cluster existant

Pour mettre à jour la configuration par défaut du contrôleur d’entrée du routage d’applications sur un cluster existant, utilisez la commande az aks approuting update, en spécifiant l’indicateur --nginx. Vous devez définir <DefaultIngressControllerType> sur l’une des options de configuration décrites précédemment.

az aks approuting update --resource-group <ResourceGroupName> --name <ClusterName> --nginx <DefaultIngressControllerType>

Créer un autre contrôleur d’entrée NGINX public accessible

Pour créer un autre contrôleur d’entrée NGINX avec un équilibreur de charge Azure public :

  1. Copiez le manifeste YAML suivant dans un nouveau fichier nommé nginx-public-controller.yaml et enregistrez le fichier sur votre ordinateur local.

    apiVersion: approuting.kubernetes.azure.com/v1alpha1
kind: NginxIngressController
metadata:
  name: nginx-public
spec:
  ingressClassName: nginx-public
  controllerNamePrefix: nginx-public

  2. Créez les ressources du contrôleur d’entrée NGINX à l’aide de la commande kubectl apply.

    kubectl apply -f nginx-public-controller.yaml

    L’exemple de sortie suivant présente la ressource créée :

    nginxingresscontroller.approuting.kubernetes.azure.com/nginx-public created

Créer un contrôleur d’entrée NGINX interne avec une adresse IP privée

Pour créer un contrôleur d’entrée NGINX avec un équilibreur de charge Azure interne avec une adresse IP privée :

  1. Copiez le manifeste YAML suivant dans un nouveau fichier nommé nginx-internal-controller.yaml et enregistrez le fichier sur votre ordinateur local.

    apiVersion: approuting.kubernetes.azure.com/v1alpha1
kind: NginxIngressController
metadata:
  name: nginx-internal
spec:
  ingressClassName: nginx-internal
  controllerNamePrefix: nginx-internal
  loadBalancerAnnotations: 
    service.beta.kubernetes.io/azure-load-balancer-internal: "true"

  2. Créez les ressources du contrôleur d’entrée NGINX à l’aide de la commande kubectl apply.

    kubectl apply -f nginx-internal-controller.yaml

    L’exemple de sortie suivant présente la ressource créée :

    nginxingresscontroller.approuting.kubernetes.azure.com/nginx-internal created

Créer un contrôleur d’entrée NGINX avec une adresse IP statique

Pour créer un contrôleur d’entrée NGINX avec une adresse IP statique sur Azure Load Balancer :

  1. Créez un groupe de ressources Azure à l’aide de la commande az group create.

    az group create --name myNetworkResourceGroup --location eastus

  2. Créez une adresse IP publique statique à l’aide de la commande az network public ip create.

    az network public-ip create \
    --resource-group myNetworkResourceGroup \
    --name myIngressPublicIP \
    --sku Standard \
    --allocation-method static

    Remarque

    Si vous utilisez une référence SKU d’équilibreur de charge De base dans votre cluster AKS, utilisez De base pour le paramètre --sku lors de la définition d’une adresse IP publique. Seules les adresses IP SKU De base fonctionnent avec l’équilibreur de charge SKU De base et seuls les adresses IP SKU Standard fonctionnent avec les équilibreurs de charge SKU Standard.

  3. Vérifiez que l’identité de cluster utilisée par le cluster AKS dispose de permissions déléguées sur le groupe de ressources de l’adresse IP publique à l’aide de la commande az role assignment create.

    Remarque

    Mettez à jour <ClusterName> et <ClusterResourceGroup> avec le nom de votre cluster AKS et le nom du groupe de ressources.

    CLIENT_ID=$(az aks show --name <ClusterName> --resource-group <ClusterResourceGroup> --query identity.principalId -o tsv)
RG_SCOPE=$(az group show --name myNetworkResourceGroup --query id -o tsv)
az role assignment create \
    --assignee ${CLIENT_ID} \
    --role "Network Contributor" \
    --scope ${RG_SCOPE}

  4. Copiez le manifeste YAML suivant dans un nouveau fichier nommé nginx-staticip-controller.yaml et enregistrez le fichier sur votre ordinateur local.

    Remarque

    Vous pouvez utiliser service.beta.kubernetes.io/azure-pip-name pour le nom d’adresse IP publique ou utiliser service.beta.kubernetes.io/azure-load-balancer-ipv4 pour une adresse IPv4 et service.beta.kubernetes.io/azure-load-balancer-ipv6 pour une adresse IPv6, comme illustré dans l’exemple YAML. L’annotation service.beta.kubernetes.io/azure-pip-name garantit la création de LoadBalancer de la manière la plus efficace possible et est fortement recommandée pour éviter toute limitation potentielle.

    apiVersion: approuting.kubernetes.azure.com/v1alpha1
kind: NginxIngressController
metadata:
  name: nginx-static
spec:
  ingressClassName: nginx-static
  controllerNamePrefix: nginx-static
  loadBalancerAnnotations: 
    service.beta.kubernetes.io/azure-pip-name: "myIngressPublicIP"
    service.beta.kubernetes.io/azure-load-balancer-resource-group: "myNetworkResourceGroup"

  5. Créez les ressources du contrôleur d’entrée NGINX à l’aide de la commande kubectl apply.

    kubectl apply -f nginx-staticip-controller.yaml

    L’exemple de sortie suivant présente la ressource créée :

    nginxingresscontroller.approuting.kubernetes.azure.com/nginx-static created

Vérifier que le contrôleur d’entrée a été créé

Vous pouvez vérifier l’état du contrôleur d’entrée NGINX à l’aide de la commande kubectl get nginxingresscontroller.

Remarque

Mettez à jour <IngressControllerName> avec le nom que vous avez utilisé lors de la création de « NginxIngressController ».

kubectl get nginxingresscontroller -n <IngressControllerName>

L’exemple de sortie suivant montre la ressource créée. La disponibilité du contrôleur peut prendre quelques minutes :

NAME           INGRESSCLASS   CONTROLLERNAMEPREFIX   AVAILABLE
nginx-public   nginx-public   nginx                  True

Vous pouvez également afficher les conditions pour résoudre les problèmes suivants :

kubectl get nginxingresscontroller -n <IngressControllerName> -o jsonpath='{range .items[*].status.conditions[*]}{.lastTransitionTime}{"\t"}{.status}{"\t"}{.type}{"\t"}{.message}{"\n"}{end}'

L’exemple de sortie suivant montre les conditions d’un contrôleur d’entrée sain :

2023-11-29T19:59:24Z    True    IngressClassReady       Ingress Class is up-to-date
2023-11-29T19:59:50Z    True    Available               Controller Deployment has minimum availability and IngressClass is up-to-date
2023-11-29T19:59:50Z    True    ControllerAvailable     Controller Deployment is available
2023-11-29T19:59:25Z    True    Progressing             Controller Deployment has successfully progressed

Utiliser le contrôleur d’entrée dans une entrée

  1. Copiez le manifeste YAML suivant dans un nouveau fichier nommé ingress.yaml et enregistrez le fichier sur votre ordinateur local.

    Remarque

    Mettez à jour <Hostname> avec votre nom d’hôte DNS. L <IngressClassName> est celui que vous avez défini lors de la création du NginxIngressController.

    apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: aks-helloworld
  namespace: hello-web-app-routing
spec:
  ingressClassName: <IngressClassName>
  rules:
  - host: <Hostname>
    http:
      paths:
      - backend:
          service:
            name: aks-helloworld
            port:
              number: 80
        path: /
        pathType: Prefix

  2. Créez les ressources de cluster avec la commande kubectl apply.

    kubectl apply -f ingress.yaml -n hello-web-app-routing

    L’exemple de sortie suivant montre la ressource créée :

    ingress.networking.k8s.io/aks-helloworld created

Vérifier que l’entrée managée a été créée

Vous pouvez vérifier que l’entrée managée a été créée avec la commande kubectl get ingress.

kubectl get ingress -n hello-web-app-routing

L’exemple de sortie suivant montre l’entrée managée créée. La classe d’entrée, l’hôte et l’adresse IP peuvent être différentes :

NAME             CLASS                                HOSTS               ADDRESS       PORTS     AGE
aks-helloworld   webapprouting.kubernetes.azure.com   myapp.contoso.com   20.51.92.19   80, 443   4m

Nettoyer les contrôleurs d’entrée

Vous pouvez supprimer le contrôleur d’entrée NGINX à l’aide de la commande kubectl delete nginxingresscontroller.

Remarque

Mettez à jour <IngressControllerName> avec le nom que vous avez utilisé lors de la création du NginxIngressController.

kubectl delete nginxingresscontroller -n <IngressControllerName>

Configuration par ressource d’entrée via des annotations

Le contrôleur d’entrée NGINX prend en charge l’ajout d’annotations à des objets d’entrée spécifiques pour personnaliser leur comportement.

Vous pouvez annoter l’objet d’entrée en ajoutant l’annotation correspondante dans le champ metadata.annotations.

Remarque

Les clés et valeurs d’annotation ne peuvent être que des chaînes. D’autres types, tels que des valeurs booléennes ou numériques, doivent être entre guillemets, c’est-à-dire "true", "false", "100".

Voici quelques exemples d’annotations pour les configurations courantes. Consultez la documentation sur les annotations d’entrée NGINX pour obtenir une liste complète.

Taille maximale personnalisée du corps

Pour NGINX, une erreur 413 est retournée au client lorsque la taille d’une requête dépasse la taille maximale autorisée du corps de la demande du client. Pour remplacer la valeur par défaut, utilisez l’annotation :

nginx.ingress.kubernetes.io/proxy-body-size: 4m

Voici un exemple de configuration d’entrée à l’aide de cette annotation :

Remarque

Mettez à jour <Hostname> avec votre nom d’hôte DNS. Le <IngressClassName> est celui que vous avez défini lors de la création du NginxIngressController.

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: aks-helloworld
  namespace: hello-web-app-routing
  annotations:
    nginx.ingress.kubernetes.io/proxy-body-size: 4m
spec:
  ingressClassName: <IngressClassName>
  rules:
  - host: <Hostname>
    http:
      paths:
      - backend:
          service:
            name: aks-helloworld
            port:
              number: 80
        path: /
        pathType: Prefix

Délai d’expiration de connexion personnalisé

Vous pouvez modifier le délai d’attente du contrôleur d’entrée NGINX pour fermer une connexion avec votre charge de travail. Toutes les valeurs de délai d’attente sont sans unité et en secondes. Pour remplacer le délai d’expiration par défaut, utilisez l’annotation suivante pour définir un délai de lecture de proxy valide de 120 secondes :

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

Passez en revue délais d’expiration personnalisés pour obtenir d’autres options de configuration.

Voici un exemple de configuration d’entrée à l’aide de cette annotation :

Remarque

Mettez à jour <Hostname> avec votre nom d’hôte DNS. Le <IngressClassName> est celui que vous avez défini lors de la création du NginxIngressController.

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: aks-helloworld
  namespace: hello-web-app-routing
  annotations:
    nginx.ingress.kubernetes.io/proxy-read-timeout: "120"
spec:
  ingressClassName: <IngressClassName>
  rules:
  - host: <Hostname>
    http:
      paths:
      - backend:
          service:
            name: aks-helloworld
            port:
              number: 80
        path: /
        pathType: Prefix

Protocole de back-end

Par défaut, le contrôleur d’entrée NGINX utilise HTTP pour atteindre les services. Pour configurer d’autres protocoles back-end tels que HTTPS ou GRPC, utilisez l’annotation :

nginx.ingress.kubernetes.io/backend-protocol: "HTTPS"

or

nginx.ingress.kubernetes.io/backend-protocol: "GRPC"

Passez en revue protocoles principaux pour obtenir d’autres options de configuration.

Voici un exemple de configuration d’entrée à l’aide de cette annotation :

Remarque

Mettez à jour <Hostname> avec votre nom d’hôte DNS. Le <IngressClassName> est celui que vous avez défini lors de la création du NginxIngressController.

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: aks-helloworld
  namespace: hello-web-app-routing
  annotations:
    nginx.ingress.kubernetes.io/backend-protocol: "HTTPS"
spec:
  ingressClassName: <IngressClassName>
  rules:
  - host: <Hostname>
    http:
      paths:
      - backend:
          service:
            name: aks-helloworld
            port:
              number: 80
        path: /
        pathType: Prefix

CORS (Cross Origin Resource Sharing)

Pour activer le partage de ressources cross-origin (CORS) dans une règle d’entrée, utilisez l’annotation :

nginx.ingress.kubernetes.io/enable-cors: "true"

Passez en revue activer le CORS pour d’autres options de configuration.

Voici un exemple de configuration d’entrée à l’aide de cette annotation :

Remarque

Mettez à jour <Hostname> avec votre nom d’hôte DNS. Le <IngressClassName> est celui que vous avez défini lors de la création du NginxIngressController.

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: aks-helloworld
  namespace: hello-web-app-routing
  annotations:
    nginx.ingress.kubernetes.io/enable-cors: "true"
spec:
  ingressClassName: <IngressClassName>
  rules:
  - host: <Hostname>
    http:
      paths:
      - backend:
          service:
            name: aks-helloworld
            port:
              number: 80
        path: /
        pathType: Prefix

Désactiver la redirection SSL

Par défaut, le contrôleur redirige (308) vers HTTPS si TLS est activé pour une entrée. Pour désactiver cette fonctionnalité pour des ressources d’entrée spécifiques, utilisez l’annotation :

nginx.ingress.kubernetes.io/ssl-redirect: "false"

Passez en revue application HTTPS côté serveur via redirection pour d’autres options de configuration.

Voici un exemple de configuration d’entrée à l’aide de cette annotation :

Remarque

Mettez à jour <Hostname> avec votre nom d’hôte DNS. Le <IngressClassName> est celui que vous avez défini lors de la création du NginxIngressController.

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: aks-helloworld
  namespace: hello-web-app-routing
  annotations:
    nginx.ingress.kubernetes.io/ssl-redirect: "false"
spec:
  ingressClassName: <IngressClassName>
  rules:
  - host: <Hostname>
    http:
      paths:
      - backend:
          service:
            name: aks-helloworld
            port:
              number: 80
        path: /
        pathType: Prefix

Réécriture d’URL

Dans certains scénarios, l’URL exposée dans le service principal diffère du chemin spécifié dans la règle d’entrée. Sans réécriture d’une requête retourne 404. Cette configuration est particulièrement utile avec le routage basé sur le chemin d’accès qui vous permet de servir deux applications web différentes sous le même domaine. Vous pouvez définir le chemin attendu par le service à l’aide de l’annotation :

nginx.ingress.kubernetes.io/rewrite-target": /$2

Voici un exemple de configuration d’entrée à l’aide de cette annotation :

Remarque

Mettez à jour <Hostname> avec votre nom d’hôte DNS. Le <IngressClassName> est celui que vous avez défini lors de la création du NginxIngressController.

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: aks-helloworld
  namespace: hello-web-app-routing
  annotations:
    nginx.ingress.kubernetes.io/rewrite-target: /$2
    nginx.ingress.kubernetes.io/use-regex: "true"
spec:
  ingressClassName: <IngressClassName>
  rules:
  - host: <Hostname>
    http:
      paths:
      - path: /app-one(/|$)(.*)
        pathType: Prefix 
        backend:
          service:
            name: app-one
            port:
              number: 80
      - path: /app-two(/|$)(.*)
        pathType: Prefix 
        backend:
          service:
            name: app-two
            port:
              number: 80

Étapes suivantes

Découvrez comment surveiller les métriques du contrôleur d’entrée-nginx incluses dans le module complémentaire de routage d’application avec avec Prometheus dans Grafana dans le cadre de l’analyse des performances et de l’utilisation de votre application.