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

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 :

• Configuration du contrôleur d’entrée NGINX telles que la création de plusieurs contrôleurs, la configuration d’équilibreurs de charge privés et la définition d’adresses IP statiques.
• Ressource configuration par entrée par le biais d’annotations.

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.

Configurations courantes

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

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.

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

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

"ingressProfile": {
  "webAppRouting": {
    "nginx": {
        "defaultIngressControllerType": "None|Internal|External|AnnotationControlled"
    }
}

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.

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.

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.

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 :

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 :

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 :

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 :

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 :

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 :

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.