Container Service for Kubernetes:Advanced NGINX Ingress configurations

Prérequis

Avant de commencer, assurez-vous d'avoir :

• Installé le contrôleur NGINX Ingress. Pour plus d'informations, consultez la section Installation du contrôleur NGINX Ingress.

• Un client kubectl connecté au cluster. Pour plus d'informations, consultez la section Obtention du fichier KubeConfig du cluster et connexion au cluster avec kubectl.

• Un service exposé par un NGINX Ingress. Pour plus d'informations, consultez la section Création et utilisation d'un NGINX Ingress pour exposer un service.

Méthodes de configuration

Le contrôleur NGINX Ingress dans Container Service for Kubernetes (ACK) est entièrement compatible avec la communauté open source. Pour plus d'informations, consultez la documentation Configuration NGINX.

Trois méthodes de configuration sont prises en charge :

Configuration de la redirection d'URL

Par défaut, le contrôleur NGINX Ingress transfère les requêtes en fonction du chemin complet de la requête. Par exemple, une requête vers /service1/api est transférée directement vers /service1/api sur le pod backend. Si le chemin du service backend est /api, une erreur 404 est renvoyée car le chemin ne correspond pas. Utilisez l'annotation nginx.ingress.kubernetes.io/rewrite-target pour réécrire le chemin de la requête vers le répertoire correct.

Créez un NGINX Ingress en fonction de la version de votre cluster.

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: foo.bar.com
  namespace: default
  annotations:
    # URL redirection.
    nginx.ingress.kubernetes.io/rewrite-target: /$2
spec:
  rules:
  - host: foo.bar.com
    http:
      paths:
    # If the Ingress controller version is 0.22.0 or later, you must use a regular expression to define the path in the path field and use it with a capturing group in the rewrite-target annotation.
      - path: /svc(/|$)(.*)
        backend:
          service:
            name: web1-service
            port:
              number: 80
        pathType: ImplementationSpecific

apiVersion: networking.k8s.io/v1beta1
kind: Ingress
metadata:
  name: foo.bar.com
  namespace: default
  annotations:
    # URL redirection.
    nginx.ingress.kubernetes.io/rewrite-target: /$2
spec:
  rules:
  - host: foo.bar.com
    http:
      paths:
      # If the Ingress controller version is 0.22.0 or later, you must use a regular expression to define the path in the path field and use it with a capturing group in the rewrite-target annotation.
      - path: /svc(/|$)(.*)
        backend:
          serviceName: web1-service
          servicePort: 80

Après le déploiement de l'Ingress, vérifiez la configuration :

1. Récupérez l'adresse de l'Ingress.

   kubectl get ingress

   Résultat attendu :

   NAME           CLASS   HOSTS                ADDRESS          PORTS   AGE
   foo.bar.com    nginx   foo.bar.com        172.16.XX.XX       80      46m

2. Testez la règle de réécriture. Remplacez ADDRESS par l'adresse IP obtenue à l'étape précédente.

   curl -k -H "Host: foo.bar.com"  http://<ADDRESS>/svc/foo

   Résultat attendu :

   web1: /foo

Configuration de règles de réécriture avancées

Pour une réécriture d'URL de base, utilisez l'annotation nginx.ingress.kubernetes.io/rewrite-target comme décrit dans la section Configuration de la redirection d'URL.

Pour des exigences de réécriture complexes, utilisez les annotations suivantes afin d'ajouter des extraits personnalisés à la configuration NGINX :

Exemple :

annotations:
     nginx.ingress.kubernetes.io/server-snippet: |
         rewrite ^/v4/(.*)/card/query http://foo.bar.com/v5/#!/card/query permanent;
     nginx.ingress.kubernetes.io/configuration-snippet: |
         rewrite ^/v6/(.*)/card/query http://foo.bar.com/v7/#!/card/query permanent;

Pour afficher la configuration NGINX générée, exécutez la commande suivante. Remplacez le nom du pod par le nom réel du pod du contrôleur NGINX Ingress dans votre cluster.

kubectl exec nginx-ingress-controller-xxxxx --namespace kube-system -- cat /etc/nginx/nginx.conf

La configuration ci-dessus génère la sortie nginx.conf suivante :

# start server foo.bar.com
    server {
        server_name foo.bar.com ;
        listen 80;
        listen [::]:80;
        set $proxy_upstream_name "-";
    # server-snippet configuration.
        rewrite ^/v4/(.*)/card/query http://foo.bar.com/v5/#!/card/query permanent;
        ...
    # configuration-snippet configuration.
      rewrite ^/v6/(.*)/card/query http://foo.bar.com/v7/#!/card/query permanent;
      ...
    }
    # end server foo.bar.com

Les annotations snippet prennent également en charge les configurations globales. Pour plus d'informations, consultez la section server-snippet. Pour la référence complète de la directive rewrite de NGINX, consultez la documentation officielle de NGINX.

Configurer un certificat HTTPS

Utilisez la sémantique TLS native d'Ingress pour configurer un certificat HTTPS pour votre service.

1. Préparez votre certificat TLS.

   1. Générez un certificat auto-signé et une clé privée. ``bash openssl req -x509 -nodes -days 365 -newkey rsa:2048 -keyout tls.key -out tls.crt -subj "/CN=foo.bar.com/O=foo.bar.com" ``

   2. Créez un Kubernetes Secret à partir du certificat et de la clé privée. Référencez ce Secret dans l'Ingress.

      kubectl create secret tls tls-test-ingress --key tls.key --cert tls.crt

   Le CN (Common Name) du certificat doit correspondre à l'hôte configuré dans l'Ingress. S'ils ne correspondent pas, le contrôleur NGINX Ingress ne peut pas charger le certificat.

2. Créez une ressource Ingress qui référence le Secret dans le champ tls. Kubernetes 1.19 ou version ultérieure

   Clusters that run Kubernetes 1.19 or later

   apiVersion: networking.k8s.io/v1
   kind: Ingress
   metadata:
     name: test-test-ingress
   spec:
     # Reference the TLS certificate.
     tls:
     - hosts:
       - foo.bar.com # The domain name that corresponds to the certificate.
       secretName: tls-test-ingress
     rules:
     - host: tls-test-ingress.com
       http:
         paths:
         - path: /foo
           backend:
             service:
               name: web1-svc
               port:
                 number: 80
           pathType: ImplementationSpecific

   Clusters that run Kubernetes versions earlier than 1.19

   apiVersion: networking.k8s.io/v1beta1
   kind: Ingress
   metadata:
     name: test-test-ingress
   spec:
     # Reference the TLS certificate.
     tls:
     - hosts:
       - foo.bar.com # The domain name that corresponds to the certificate.
       secretName: tls-test-ingress
     rules:
     - host: tls-test-ingress.com
       http:
         paths:
         - path: /foo
           backend:
             serviceName: web1-svc
             servicePort: 80

3. Mettez à jour votre fichier /etc/hosts ou utilisez un nom de domaine réel pour accéder au service TLS à l'adresse https://tls-test-ingress.com/foo.

Configurer l'authentification mutuelle HTTPS

L'authentification mutuelle HTTPS (mTLS) exige que le serveur et le client présentent tous deux des certificats, offrant ainsi une sécurité de connexion plus élevée que le TLS unidirectionnel. Le contrôleur NGINX Ingress prend en charge le mTLS via des annotations.

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  annotations:
    nginx.ingress.kubernetes.io/auth-tls-verify-client: "on"
    nginx.ingress.kubernetes.io/auth-tls-secret: "default/ca-secret"
    nginx.ingress.kubernetes.io/auth-tls-verify-depth: "1"
    nginx.ingress.kubernetes.io/auth-tls-pass-certificate-to-upstream: "true"
  name: nginx-test
  namespace: default
spec:
  rules:
  - host: foo.bar.com
    http:
      paths:
      - backend:
          service:
            name: http-svc
            port:
              number: 80
        path: /
        pathType: ImplementationSpecific
  tls:
  - hosts:
    - foo.bar.com
    secretName: tls-secret

apiVersion: networking.k8s.io/v1beta1
kind: Ingress
metadata:
  annotations:
    nginx.ingress.kubernetes.io/auth-tls-verify-client: "on"
    nginx.ingress.kubernetes.io/auth-tls-secret: "default/ca-secret"
    nginx.ingress.kubernetes.io/auth-tls-verify-depth: "1"
    nginx.ingress.kubernetes.io/auth-tls-pass-certificate-to-upstream: "true"
  name: nginx-test
  namespace: default
spec:
  rules:
  - host: foo.bar.com
    http:
      paths:
      - backend:
          serviceName: http-svc
          servicePort: 80
        path: /
  tls:
  - hosts:
    - foo.bar.com
    secretName: tls-secret

ingress.networking.k8s.io/nginx-test configured

Acheminer le trafic vers un backend HTTPS

Par défaut, le contrôleur d'entrée NGINX transfère les requêtes vers les conteneurs backend via HTTP. Si votre conteneur backend utilise HTTPS, ajoutez l'annotation nginx.ingress.kubernetes.io/backend-protocol: "HTTPS" pour acheminer le trafic via HTTPS.

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: backend-https
  annotations:
    # Note: You must specify that the backend service is an HTTPS service.
    nginx.ingress.kubernetes.io/backend-protocol: "HTTPS"
spec:
  tls:
  - hosts:
    - <YOUR-HOST-NAME>
    secretName: <YOUR-SECRET-CERT-NAME>
  rules:
  - host: <YOUR-HOST-NAME>
    http:
      paths:
      - path: /
        backend:
          service:
            name: <YOUR-SERVICE-NAME>
            port:
              number: <YOUR-SERVICE-PORT>
        pathType: ImplementationSpecific

apiVersion: networking.k8s.io/v1beta1
kind: Ingress
metadata:
  name: backend-https
  annotations:
    # Note: You must specify that the backend service is an HTTPS service.
    nginx.ingress.kubernetes.io/backend-protocol: "HTTPS"
spec:
  tls:
  - hosts:
    - <YOUR-HOST-NAME>
    secretName: <YOUR-SECRET-CERT-NAME>
  rules:
  - host: <YOUR-HOST-NAME>
    http:
      paths:
      - path: /
        backend:
          serviceName: <YOUR-SERVICE-NAME>
          servicePort: <YOUR-SERVICE-PORT>

Configurer des noms de domaine avec des expressions régulières

Les ressources Ingress de Kubernetes ne prennent pas nativement en charge les expressions régulières dans le champ host. Utilisez l'annotation nginx.ingress.kubernetes.io/server-alias pour ajouter une correspondance de nom de domaine basée sur une expression régulière.

1. Déployez l'Ingress suivant. Cet exemple utilise l'expression régulière ~^www\.\d+\.example\.com. Kubernetes 1.19 ou version ultérieure

   Clusters exécutant Kubernetes 1.19 ou version ultérieure

   apiVersion: networking.k8s.io/v1
   kind: Ingress
   metadata:
     name: ingress-regex
     namespace: default
     annotations:
       nginx.ingress.kubernetes.io/server-alias: '~^www\.\d+\.example\.com$, abc.example.com'
   spec:
     rules:
     - host: foo.bar.com
       http:
         paths:
         - path: /foo
           backend:
             service:
               name: http-svc1
               port:
                 number: 80
           pathType: ImplementationSpecific

   Clusters exécutant des versions de Kubernetes antérieures à la 1.19

   apiVersion: networking.k8s.io/v1beta1
   kind: Ingress
   metadata:
     name: ingress-regex
     namespace: default
     annotations:
       nginx.ingress.kubernetes.io/server-alias: '~^www\.\d+\.example\.com$, abc.example.com'
   spec:
     rules:
     - host: foo.bar.com
       http:
         paths:
         - path: /foo
           backend:
             serviceName: http-svc1
             servicePort: 80

2. Vérifiez la configuration dans le contrôleur d'entrée NGINX.

   1. Répertoriez les pods du contrôleur d'entrée NGINX.

      kubectl get pods -n kube-system | grep nginx-ingress-controller

      Résultat attendu :

      nginx-ingress-controller-77cd987c4c-c****         1/1     Running   0          1h
      nginx-ingress-controller-77cd987c4c-x****         1/1     Running   0          1h

   2. Inspectez le champ server_name dans la configuration NGINX générée.

      kubectl exec -n kube-system nginx-ingress-controller-77cd987c4c-c**** cat /etc/nginx/nginx.conf | grep -C3 "foo.bar.com"

      Résultat attendu :

        # start server foo.bar.com
        server {
      --
        server {
          server_name foo.bar.com abc.example.com ~^www\.\d+\.example\.com$ ;
          listen 80  ;
          listen 443  ssl http2 ;
      --
      --
          }
        }
        # end server foo.bar.com

3. Récupérez l'adresse IP de l'Ingress.

   kubectl get ing

   Résultat attendu :

   NAME            HOSTS         ADDRESS          PORTS     AGE
   ingress-regex   foo.bar.com   101.37.XX.XX     80        11s

4. Testez l'accès au service avec différents en-têtes host. Remplacez IP_ADDRESS par l'adresse IP de l'Ingress obtenue à l'étape précédente.

   • Accès via foo.bar.com :

     curl -H "Host: foo.bar.com" <IP_ADDRESS>/foo

     Résultat attendu :

     /foo

   • Accès via www.123.example.com (correspond à l'expression régulière) :

     curl -H "Host: www.123.example.com" <IP_ADDRESS>/foo

     Résultat attendu :

     /foo

   • Accès via www.321.example.com (correspond également à l'expression régulière) :

     curl -H "Host: www.321.example.com" <IP_ADDRESS>/foo

     Résultat attendu :

     /foo

Configuration des noms de domaine génériques

NGINX Ingress prend en charge les noms de domaine génériques. L'exemple suivant configure *.ingress-regex.com pour correspondre à n'importe quel sous-domaine.

1. Déployez l'Ingress suivant.

   Clusters exécutant Kubernetes 1.19 ou une version ultérieure

   apiVersion: networking.k8s.io/v1
   kind: Ingress
   metadata:
     name: ingress-regex
     namespace: default
   spec:
     rules:
     - host: *.ingress-regex.com
       http:
         paths:
         - path: /foo
           backend:
             service:
               name: http-svc1
               port:
                 number: 80
           pathType: ImplementationSpecific

   Clusters exécutant des versions de Kubernetes antérieures à 1.19

   apiVersion: networking.k8s.io/v1beta1
   kind: Ingress
   metadata:
     name: ingress-regex
     namespace: default
   spec:
     rules:
     - host: *.ingress-regex.com
       http:
         paths:
         - path: /foo
           backend:
             serviceName: http-svc1
             servicePort: 80

2. Vérifiez le champ server_name dans la configuration NGINX. Remplacez <nginx-ingress-pod-name> par le nom réel du pod NGINX Ingress.

   kubectl exec -n kube-system <nginx-ingress-pod-name> cat /etc/nginx/nginx.conf | grep -C3 "*.ingress-regex.com"

   Résultat attendu :

   # start server *.ingress-regex.com
     server {
       server_name *.ingress-regex.com ;
       listen 80;
       listen [::]:80;
   ...
     }
     # end server *.ingress-regex.com

   Dans les versions plus récentes du contrôleur NGINX Ingress, le résultat est le suivant :

   ## start server *.ingress-regex.com
     server {
       server_name ~^(?<subdomain>[\w-]+)\.ingress-regex\.com$ ;
       listen 80;
       listen [::]:80;
   ...
     }
     ## end server *.ingress-regex.com

3. Récupérez l'adresse IP de l'Ingress.

   kubectl get ing

   Résultat attendu :

   NAME            HOSTS                 ADDRESS           PORTS     AGE
   ingress-regex   *.ingress-regex.com   101.37.XX.XX      80        11s

4. Testez l'accès avec différents sous-domaines. Remplacez IP_ADDRESS par l'adresse IP de l'Ingress obtenue à l'étape précédente.

   • Accédez via abc.ingress-regex.com :

     curl -H "Host: abc.ingress-regex.com" <IP_ADDRESS>/foo

     Résultat attendu :

     /foo

   • Accédez via 123.ingress-regex.com :

     curl -H "Host: 123.ingress-regex.com" <IP_ADDRESS>/foo

     Résultat attendu :

     /foo

   • Accédez via a1b1.ingress-regex.com :

     curl -H "Host: a1b1.ingress-regex.com" <IP_ADDRESS>/foo

     Résultat attendu :

     /foo

Mise en œuvre des déploiements canari

Utilisez les annotations canari pour acheminer un sous-ensemble du trafic vers une nouvelle version de service sans déploiement complet. Activez le routage canari en définissant nginx.ingress.kubernetes.io/canary: "true" sur l'Ingress canari, puis combinez-le avec une ou plusieurs annotations de stratégie de routage.

Priorité des règles, de la plus élevée à la plus faible : basée sur l'en-tête → basée sur le cookie → basée sur le poids. Le routage canari basé sur les cookies ne prend en charge que les valeurs always et never.

Les exemples suivants illustrent des configurations canari courantes. Pour un guide complet incluant les déploiements blue-green, consultez la section Utilisation d'un Ingress NGINX pour mettre en œuvre des déploiements canari et blue-green.

Déploiement canari basé sur le poids — acheminez 20 % du trafic vers le service canari :

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  annotations:
    kubernetes.io/ingress.class: nginx
    nginx.ingress.kubernetes.io/canary: "true"
    nginx.ingress.kubernetes.io/canary-weight: "20"

Déploiement canari basé sur l'en-tête — lorsque l'en-tête de requête ack a la valeur always, le trafic est routé vers le service canari ; lorsqu'il a la valeur never, le service canari est ignoré ; pour les autres valeurs d'en-tête, le routage suit la règle de pondération :

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  annotations:
    kubernetes.io/ingress.class: nginx
    nginx.ingress.kubernetes.io/canary: "true"
    nginx.ingress.kubernetes.io/canary-weight: "50"
    nginx.ingress.kubernetes.io/canary-by-header: "ack"

Déploiement canari basé sur l'en-tête avec une valeur personnalisée — achemine vers le service canari uniquement lorsque l'en-tête ack a exactement la valeur alibaba ; sinon, applique le routage basé sur le poids :

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  annotations:
    kubernetes.io/ingress.class: nginx
    nginx.ingress.kubernetes.io/canary: "true"
    nginx.ingress.kubernetes.io/canary-weight: "20"
    nginx.ingress.kubernetes.io/canary-by-header: "ack"
    nginx.ingress.kubernetes.io/canary-by-header-value: "alibaba"

Déploiement canari basé sur le cookie — lorsqu'aucune règle d'en-tête ne correspond et que le cookie hangzhou_region a la valeur always, le trafic est routé vers le service canari :

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  annotations:
    kubernetes.io/ingress.class: nginx
    nginx.ingress.kubernetes.io/canary: "true"
    nginx.ingress.kubernetes.io/canary-weight: "20"
    nginx.ingress.kubernetes.io/canary-by-header: "ack"
    nginx.ingress.kubernetes.io/canary-by-header-value: "alibaba"
    nginx.ingress.kubernetes.io/canary-by-cookie: "hangzhou_region"

Demander un certificat HTTPS gratuit avec cert-manager

cert-manager est un outil open source de gestion des certificats qui permet de provisionner et de renouveler automatiquement les certificats HTTPS dans un cluster.

1. Déployez cert-manager.

   kubectl apply -f https://github.com/cert-manager/cert-manager/releases/latest/download/cert-manager.yaml

2. Vérifiez que les pods cert-manager sont en cours d'exécution.

   kubectl get pods -n cert-manager

   Résultat attendu :

   NAME                     READY   STATUS    RESTARTS   AGE
   cert-manager-1           1/1     Running   0          2m11s
   cert-manager-cainjector  1/1     Running   0          2m11s
   cert-manager-webhook     1/1     Running   0          2m10s

3. Créez un ClusterIssuer utilisant le défi HTTP01 de Let's Encrypt.

   apiVersion: cert-manager.io/v1
   kind: ClusterIssuer
   metadata:
     name: letsencrypt-prod-http01
   spec:
     acme:
       server: https://acme-v02.api.letsencrypt.org/directory
       email: <your_email@example.com>  # Replace this with your email address.
       privateKeySecretRef:
         name: letsencrypt-http01
       solvers:
       - http01:
           ingress:
             class: nginx

4. Vérifiez que le ClusterIssuer est prêt.

   kubectl get clusterissuer

   Résultat attendu :

   NAME                         READY   AGE
   letsencrypt-prod-http01      True    17s

5. Créez une ressource Ingress qui fait référence au ClusterIssuer. Kubernetes 1.19 ou version ultérieure

   Le nom de domaine doit répondre aux exigences suivantes : ne pas dépasser 64 caractères, ne pas utiliser de noms de domaine génériques (wildcard) et être accessible sur le réseau public via HTTP.

   Clusters exécutant Kubernetes 1.19 ou version ultérieure

   apiVersion: networking.k8s.io/v1
   kind: Ingress
   metadata:
     name: ingress-tls
     annotations:
       kubernetes.io/ingress.class: "nginx"
       cert-manager.io/cluster-issuer: "letsencrypt-prod-http01"
   spec:
     tls:
     - hosts:
       - <YOUR_DOMAIN_NAME>        # Replace this with your domain name.
       secretName: ingress-tls
     rules:
     - host: <YOUR_DOMAIN_NAME>    # Replace this with your domain name.
       http:
         paths:
         - path: /
           backend:
             service:
               name: <YOUR_SERVICE_NAME>  # Replace this with your backend service name.
               port:
                 number: <YOUR_SERVICE_PORT>  # Replace this with your service port.
           pathType: ImplementationSpecific

   Clusters exécutant des versions de Kubernetes antérieures à 1.19

   apiVersion: extensions/v1beta1
   kind: Ingress
   metadata:
     name: ingress-tls
     annotations:
       kubernetes.io/ingress.class: "nginx"
       cert-manager.io/cluster-issuer: "letsencrypt-prod-http01"
   spec:
     tls:
     - hosts:
       - <YOUR_DOMAIN_NAME>        # Replace this with your domain name.
       secretName: ingress-tls
     rules:
     - host: <YOUR_DOMAIN_NAME>    # Replace this with your domain name.
       http:
         paths:
         - path: /
           backend:
             serviceName: <YOUR_SERVICE_NAME>  # Replace this with your backend service name.
             servicePort: <YOUR_SERVICE_PORT>  # Replace this with your service port.

6. Vérifiez que le certificat a été émis.

   kubectl get cert

   Résultat attendu :

   NAME          READY   SECRET        AGE
   ingress-tls   True    ingress-tls   52m

   Si la valeur de READY n'est pas True, exécutez la commande kubectl describe cert ingress-tls pour inspecter la procédure de traitement du certificat.

7. Vérifiez le secret TLS.

   kubectl get secret ingress-tls

   Résultat attendu :

   NAME          TYPE                DATA   AGE
   ingress-tls   kubernetes.io/tls   2      2m

8. Accédez au service à l'adresse https://<YOUR_DOMAIN_NAME> dans un navigateur.

Configurer la redirection HTTP vers HTTPS

Utilisez l'annotation nginx.ingress.kubernetes.io/ssl-redirect pour forcer la redirection du trafic HTTP vers HTTPS.

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  annotations:
    nginx.ingress.kubernetes.io/ssl-redirect: "true" # Force the redirection of HTTP traffic to HTTPS.

apiVersion: networking.k8s.io/v1beta1
kind: Ingress
metadata:
  annotations:
    nginx.ingress.kubernetes.io/ssl-redirect: "true" # Force the redirection of HTTP traffic to HTTPS.

Étapes suivantes

• Utiliser un NGINX Ingress pour mettre en œuvre des déploiements canary et bleu-vert

• Référence des annotations du contrôleur NGINX Ingress

• Documentation cert-manager