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

Article
01/30/2024

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.

NginxIngressController CRD a un champ loadBalancerAnnotations pour contrôler le comportement du service du contrôleur d’entrée NGINX en définissant annotations d’équilibreur de charge.

Contrôleur d’entrée NGINX par défaut

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.

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 :

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

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 :

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"

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 :

Créez un groupe de ressources Azure à l’aide de la commande az group create.
```
az group create --name myNetworkResourceGroup --location eastus
```
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.
Vérifiez que l’identité de cluster utilisée par le cluster AKS dispose d’autorisations déléguées au groupe de ressources de l’adresse IP publique à l’aide de la commande [az role assignment create][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}
```
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"
```
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

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

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"

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

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. Cela est particulièrement utile avec routage basé sur le chemin d’accès où vous pouvez 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.

Share via

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

Prérequis

Se connecter à votre cluster AKS

Configuration du contrôleur d’entrée NGINX

Contrôleur d’entrée NGINX par défaut

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

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

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

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

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

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

Nettoyer les contrôleurs d’entrée

Configuration par ressource d’entrée via des annotations

Taille maximale personnalisée du corps

Délai d’expiration de connexion personnalisé

Protocole de back-end

Désactiver la redirection SSL

Réécriture d’URL

Étapes suivantes

Ressources supplémentaires

Share via

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

Prérequis

Se connecter à votre cluster AKS

Configuration du contrôleur d’entrée NGINX

Contrôleur d’entrée NGINX par défaut

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

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

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

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

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

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

Nettoyer les contrôleurs d’entrée

Configuration par ressource d’entrée via des annotations

Taille maximale personnalisée du corps

Délai d’expiration de connexion personnalisé

Protocole de back-end

CORS (Cross Origin Resource Sharing)

Désactiver la redirection SSL

Réécriture d’URL

Étapes suivantes

Ressources supplémentaires