Entrée

NCP créera un équilibreur de charge de couche 7 pour les entrées avec spécification TLS et un équilibreur de charge de couche 7 pour les entrées sans spécification TLS. Vous pouvez également créer des CRD (CustomResourceDefinitions) pour gérer la mise à l'échelle d'entrée.

Notez les points suivants :

• Tous les entrées obtiennent une adresse IP unique.
• Une adresse IP est allouée à la ressource d'entrée à partir du pool d'adresses IP externe spécifié par l'option external_ip_pools dans la section [nsx_v3] de ncp.ini. L'équilibreur de charge est exposé sur cette adresse IP et les ports HTTP et HTTPS (80 et 443).
• Une adresse IP est allouée à la ressource d'entrée à partir du pool d'adresses IP externe spécifié par l'option external_ip_pools_lb dans la section [nsx_v3] de ncp.ini. Si l'option external_ip_pools_lb n'existe pas, le pool spécifié par external_ip_pools est utilisé. L'équilibreur de charge est exposé sur cette adresse IP et les ports HTTP et HTTPS (80 et 443).
• Vous pouvez spécifier un pool d'adresses IP différent en modifiant la configuration et en redémarrant NCP.
• Vous pouvez spécifier un certificat par défaut pour TLS. Voir ci-dessous pour plus d'informations sur la création et le placement d'un certificat dans l'espace NCP.
• Les entrées sans spécification TLS sont hébergées sur le serveur virtuel HTTP (port 80).
• Les entrées avec spécification TLS sont hébergées sur le serveur virtuel HTTPS (port 443). L'équilibreur de charge agit comme serveur SSL et termine la connexion SSL client.
• La modification d'une entrée par l'ajout ou la suppression d'une section TLS n'est pas prise en charge. Lorsque la clé tls est supprimée de la spécification des entrées, les règles d'entrée sont transférées vers le serveur virtuel HTTP (port 80) à partir du serveur virtuel HTTPS (port 443). De même, lorsque la clé tls est ajoutée à la spécification des entrées, les règles d'entrée sont transférées vers le serveur virtuel HTTPS (port 443) à partir du serveur virtuel HTTP (port 80).
• En présence de règles en double dans les définitions d'entrée pour un cluster unique, seule la première règle s'applique. Les autres entrées avec les règles en double seront annotées avec une erreur. Par exemple, si vous créez deux entrées avec les mêmes host et path, et qu'une entrée est TLS alors que l'autre est non-TLS et que kubernetes.io/ingress.allow-http est false, les deux règles seront créées sur des serveurs virtuels différents et ne seront pas en conflit entre elles. Toutefois, si kubernetes.io/ingress.allow-http est true, l'entrée qui est appliquée ultérieurement sera annotée avec une erreur. Pour plus d'informations, reportez-vous à la section ci-dessous.
• Une seule entrée avec serveur principal par défaut est prise en charge par cluster. Le trafic ne correspondant à aucune règle d'entrée est transféré au serveur principal par défaut.
• En présence de plusieurs entrées avec un serveur principal par défaut, seule la première est configurée. Les autres sont annotées avec une erreur. Pour plus d'informations, reportez-vous à la section ci-dessous.
• Les règles sont appliquées dans l'ordre suivant :
  1. Règles avec host et path spécifiés.
     1. Règles avec Exact pathType.
     2. Règles avec Prefix pathType.
     3. Règles avec Regex pathType.
  2. Règles avec host ou path spécifié.
     1. Règles avec Exact pathType.
     2. Règles avec Prefix pathType.
     3. Règles avec Regex pathType.

  Remarque : si plusieurs chemins d'accès correspondent à une demande, la priorité sera attribuée au chemin d'accès correspondant le plus long.

  À propos de pathType :

  • À partir de Kubernetes 1.19, pathType est obligatoire.
  • Si use-regex est défini, il ne prend effet que si pathType est ImplementationSpecific.
  • Si use-regex n'est pas défini, ImplementationSpecific est traité de la même manière que Exact. pathType est prioritaire sur les autres annotations NCP.
  • Deux chemins d'accès correspondants avec différents pathType peuvent coexister.
  • Pour le type de Prefix, /foo correspondra /foo/, /foo/bar mais pas /foo ou /foobar. Pour faire correspondre /foo, ajoutez le chemin d'accès Exact /foo à la règle d'entrée.
• Caractères génériques du nom d'hôte
  Lorsque vous spécifiez un nom d'hôte, vous pouvez spécifier le nom exact, tel que abc.exemple.com, ou utiliser un caractère générique, tel que *.exemple.com. Notez que le caractère générique correspondra à une ou plusieurs étiquettes DNS. Le tableau suivant montre les résultats de correspondance si vous spécifiez *.exemple.com.

  En-tête de l'hôte	Résultat de la correspondance
  abc.exemple.com	Correspondance
  abc.def.exemple.com	Correspondance
  exemple.com	Aucune correspondance

• (Cela s'applique si vous utilisez le mode de stratégie.) Si une entrée TLS est créée avec un serveur principal par défaut, il est recommandé de configurer le serveur principal par défaut pour répondre aux demandes HTTP et HTTPS, car :
  • L'équilibreur de charge arrête TLS et envoie des demandes HTTP au serveur principal par défaut s'il existe une entrée TLS (dans le cluster en cas d'utilisation de Kubernetes/TKGI, ou dans le même espace de noms en cas d'utilisation du projet Pacifique) avec l'hôte qui correspond à l'hôte dans la demande.
  • L'équilibreur de charge rechiffre et envoie une demande HTTPS au serveur principal s'il n'y a pas d'entrée TLS (dans le cluster en cas d'utilisation de Kubernetes/TKGI, ou dans le même espace de noms en cas d'utilisation du projet Pacifique) avec l'hôte qui correspond à l'hôte dans la demande.
• La ressource IngressClass est prise en charge.
• L'attribut pathType est pris en charge.
• L'authentification du client JWT (JSON Web Token) est prise en charge. Cette fonctionnalité requiert NSX 3.0.0 ou une version ultérieure.

À partir de Kubernetes 1.18, l'annotation kubernetes.io/ingress.class est obsolète et remplacée par la ressource IngressClass. Pour spécifier NSX comme contrôleur d'entrée dans la ressource IngressClass, définissez le paramètre du contrôleur sur k8s.io/nsx. Par exemple :

apiVersion: networking.k8s.io/v1
kind: IngressClass
metadata:
  name: nsx-lb
  annotations:
    ingressclass.kubernetes.io/is-default-class: true
spec:
  controller: k8s.io/nsx

Pour spécifier un contrôleur d'entrée tiers, définissez le paramètre du contrôleur sur k8s.io/<controller name>. Par exemple :

apiVersion: networking.k8s.io/v1
kind: IngressClass
metadata:
  name: nginx-lb
  annotations:
    ingressclass.kubernetes.io/is-default-class: false
spec:
  controller: k8s.io/ingress-nginx

Pour définir IngressClass comme valeur par défaut pour le cluster, définissez l'annotation ingressclass.kubernetes.io/is-default-class sur true. Voir l'exemple ci-dessus.

Vous ne devez pas utiliser l'annotation kubernetes.io/ingress.class et la ressource IngressClass.

Si vous configurez manuellement un objet Endpoints, assurez-vous de définir le paramètre targetRef. La valeur doit être l'UID de l'espace principal. Par exemple :

apiVersion: networking.k8s.io/v1
kind: Endpoints
metadata:
  name: tea-svc
subsets:
  - addresses:
    - ip: 172.26.0.2
      targetRef:
        uid: 4378e0ae-5837-49c6-a0b2-178dced8eb1e
...

Annotations de fonctionnalités

Le tableau suivant répertorie les annotations prises en charge par NCP :

Annotation	Description	Valeurs prises en charge	Valeur par défaut
kubernetes.io/ingress.allow-http	Active les demandes HTTP en plus de HTTPS	true, false	true
ncp/use-regex	Active la correspondance du modèle de chemin	true, false	false
ingress.kubernetes.io/rewrite-target	Réécrit le chemin d'accès de la demande entrante	Chemin commençant par « / » Chemin avec un espace réservé numéroté pour un groupe capturé dans une expression régulière, par exemple, /$1	Aucune valeur par défaut
ncp/http-redirect	Redirige les demandes HTTP vers HTTPS	true, false	false
kubernetes.io/ingress.class	Indique quel contrôleur d'entrée est responsable de cette entrée	nsx, nginx, etc.	nsx
nsx/loadbalancer	Place une entrée sur un équilibreur de charge dédié	Nom d'un LoadBalancer CRD	Aucune valeur par défaut
ncp/allowed-source-range	Limite l'accès d'entrées par adresse IP source de la demande	Liste de CIDR, d'adresses IP ou de plages d'adresses IP séparés par des virgules.	Aucune valeur par défaut
ncp/ssl-mode	Sélectionne le mode SSL pour toutes les règles dans une entrée	déchargement, rechiffrement, relais	déchargement
ncp/jwt-alg	Détermine l'algorithme à utiliser pour valider la signature JWT. Active l'authentification client JWT lorsqu'elle est définie avec ncp/jwt-secret.	HS256, RS256	Aucune valeur par défaut
ncp/jwt-secret	Spécifie le nom du secret Kubernetes qui contient le secret JWT ou la clé publique utilisée pour la validation de la signature. Active l'authentification client JWT lorsqu'elle est définie avec ncp/jwt-alg.	Nom d'un secret Kubernetes	Aucune valeur par défaut
ncp/jwt-token	Emplacement supplémentaire pour rechercher JWT dans la demande HTTP.	_arg_<param_name>, _cookie_<cookie_name>	Aucune valeur par défaut
ncp/jwt-realm	Spécifie l'en-tête de domaine renvoyé avec 401 lorsque l'authentification a échoué.	Chaîne indiquant le domaine	Nom d'hôte de la règle d'entrée
ncp/jwt-preserve	Option pour préserver JWT et transmettre au serveur principal après une authentification réussie.	true, false	true
ncp/connection_multiplexing_enabled	Active le multiplexage TCP.	true, false	false
ncp/connection_multiplexing_number	Si le multiplexage TCP est activé, cela spécifie le nombre de connexions TCP inactives disponibles.	0 - 2127483647	6

Détails à propos des annotations :

• Correspondance Regex (expression régulière) de chemin d'accès
  • Vous pouvez activer ou désactiver la correspondance d'expression régulière du paramètre d'entrée path (mais pas host) à l'aide de l'annotation ncp/use-regex. Si cette valeur est définie sur false, la correspondance exacte du chemin d'accès sera effectuée en réalisant la correspondance equals. Si cette valeur est définie sur true, la correspondance d'expression régulière sera effectuée en ajoutant le début du caractère de chaîne (^) et la fin du caractère de chaîne ($) au chemin afin que l'URI de la demande complète corresponde au modèle. Notez que lorsque vous utilisez l'opérateur OR (|), spécifiez toujours l'étendue avec des parenthèses afin que ^ et $ s'appliquent à tous les opérandes. Par exemple, path: /(tea|coffee|milk). Exemple de spécification d'entrée :

    apiVersion: networking.k8s.io/v1
    kind: Ingress
    metadata:
      name: cafe-ingress
      annotations:
        kubernetes.io/ingress.class: "nsx"
        #/tea/cup will be served by tea-svc:80
        ncp/use-regex: "True"
    spec:
      rules:
      - host: cafe.example.com
        http:
          paths:
          # for this tea and coffee NCP will configure regex rule
          - path: /tea/(.*)
            pathType: ImplementationSpecific
            backend:
              service:
                name: tea-svc
                port:
                  number: 80
          - path: /coffee/(.*)
            pathType: ImplementationSpecific
            backend:
              service:
                name: coffee-svc
                port:
                  number: 80
          # for juice and alcohol NCP will configure Exact and Prefix rules
          - path: /juice
            pathType: Exact
            backend:
              service:
                name: juice-svc
                port:
                  number: 80
          - path: /alcohol
            pathType: Prefix
            backend:
              service:
                name: bar
                  number: 80

  • Mise à jour des entrées avant la mise à niveau de NCP
    Cela est requis uniquement si vous avez des entrées nécessitant une correspondance de tous les sous-chemins utilisant les caractères '.' et '*'.

    1. Mettez à jour les entrées pour inclure l'annotation ncp/use-regex: true.
    2. Pour toutes les correspondances de sous-chemins, si vous disposez de chemins d'accès tels que /coffee/* ou /*, modifiez-les en /coffee/.* et /.*.

       /coffee/.* correspondra à /coffee/, /coffee/a, /coffee/b, /coffee/a/b, etc. /.* correspondra à /coffee, /tea, /coffee/a, etc. L'omission du chemin d'accès produira le même comportement que path: /.*.

• Dans l'exemple suivant de l'annotation ingress.kubernetes.io/rewrite-target, les chemins d'accès /tea et /coffee seront réécrits en / avant que l'URL ne soit envoyée au service principal.

  apiVersion: networking.k8s.io/v1
  kind: Ingress
  metadata:
    name: cafe-ingress
    annotations:
      ingress.kubernetes.io/rewrite-target: /
  spec:
    rules:
    - host: cafe.example.com
      http:
        paths:
        - path: /tea
          pathType: ImplementationSpecific
          backend:
            service:
              name: tea-svc
              port:
                number: 80
        - path: /coffee
          pathType: ImplementationSpecific
          backend:
            service:
              name: coffee-svc
              port:
                number: 80

  Si path est spécifié à l'aide d'une expression régulière, les groupes capturés sont enregistrés dans des espaces réservés numérotés au format $1, $2, etc. Ces espaces réservés peuvent être utilisés comme paramètres dans l'annotation ingress.kubernetes.io/rewrite-target. Les groupes de capture et les espaces réservés nommés ne sont pas pris en charge. Par exemple,

  apiVersion: networking.k8s.io/v1
  kind: Ingress
  metadata:
    name: cafe-ingress
    annotations:
      kubernetes.io/ingress.class: "nsx"
      ncp/use-regex: "true"
      #/tea/cup will be rewritten to /cup before sending request to endpoint
      ingress.kubernetes.io/rewrite-target: /$1
  spec:
    rules:
    - host: cafe.example.com
      http:
        paths:
        - path: /tea/(.*)
          pathType: ImplementationSpecific
          backend:
            service:
              name: tea-svc
              port:
                number: 80
        - path: /coffee/(.*)
          pathType: ImplementationSpecific
          backend:
            service:
              name: coffee-svc
              port:
                number: 80

• À propos de l'annotation kubernetes.io/ingress.allow-http :
  • Si l'annotation est définie sur false, des règles seront créées pour le serveur virtuel HTTPS.
  • Si l'annotation est définie sur true ou manquante, des règles seront créées pour les serveurs virtuels HTTP et HTTPS. Notez que les règles HTTPS sont également créées si la section TLS est présente dans la spécification d'entrée.
• À propos de l'annotation ncp/http-redirect :
  • Si l'annotation est définie sur false, le trafic HTTP entrant (port 80) vers le serveur virtuel HTTP ne sera pas redirigé vers le serveur virtuel HTTPS.
  • Si l'annotation est définie sur true, le trafic HTTP entrant (port 80) vers le serveur virtuel HTTP sera redirigé vers le serveur virtuel HTTPS (port 443).

  Cette annotation n'est valide que si la section TLS est présente. Cette annotation est prioritaire sur kubernetes.io/ingress.allow-http. Lorsqu'elle est définie sur true, elle redirige le trafic HTTP vers HTTPS, quelle que soit la manière dont kubernetes.io/ingress.allow-http est défini.

• À propos de l'annotation kubernetes.io/ingress.class :
  • Si la valeur est nsx, cette entrée sera gérée par NCP. Si une autre valeur est spécifiée, l'entrée sera ignorée par NCP. Pour plus d'informations, consultez la section Contrôleurs d'entrée tiers.
• Pour plus d'informations sur l'annotation nsx/loadbalancer, consultez la section LoadBalancer CRD pour gérer la mise à l'échelle de l'entrée.
• À propos de l'annotation ncp/allowed-source-range :
  • Prise en charge en mode de stratégie uniquement.
  • Lorsque cette option est définie, une demande entrante sera acceptée uniquement si son adresse IP source est incluse dans cette annotation. Dans le cas contraire, le trafic sera abandonné.
  • Vous pouvez spécifier une combinaison de CIDR, d'adresses IP et de plages d'adresses IP. Par exemple, 1.1.1.1/24, 2.2.2.2, 3.3.3.3-4.4.4.4.
  • Exemple YAML :

    apiVersion: networking.k8s.io/v1
    kind: Ingress
    metadata:
      name: cafe-ingress
      annotations:
        kubernetes.io/ingress.class: "nsx"
        #Source IP addresses allowed to access ingress URL
        ncp/allowed-source-range: "192.168.128.0/17, 192.168.64.0-192.168.64.255, 192.168.16.32"
    spec:
      tls:
      - hosts:
        - cafe.example.com
      rules:
      - host: cafe.example.com
        http:
          paths:
          - path: /tea
            pathType: ImplementationSpecific
            backend:
              service:
                name: tea-svc
                port:
                  number: 80
          - path: /coffee
            pathType: ImplementationSpecific
            backend:
              service:
                name: coffee-svc
                port:
                  number: 80

• À propos de l'annotation ncp/ssl-mode :
  • Prise en charge en mode de stratégie uniquement.
  • Cette annotation s'applique à toutes les règles dans une entrée et l'équilibreur de charge fonctionnera en mode SSL sélectionné pour ces règles.

    Si ncp/ssl-mode est défini sur reencrypt ou sur passthrough, kubernetes.io/ingress.allow-http doit être défini sur False. Cette annotation ne peut pas être définie sur passthrough si l'annotation ingress.kubernetes.io/rewrite-target ncp/use-regex ou ncp/allowed-source-range est définie.

    Si ncp/ssl-mode est défini sur passthrough, l'attribut path dans la spécification de rules n'est pas pris en charge.

• À propos de l'authentification client JWT :
  • Pour activer l'authentification client JWT pour toutes les règles sous une entrée, ncp/jwt-alg et ncp/jwt-secret doivent être définis sur une valeur valide. Lorsque ce paramètre est activé, le trafic HTTP entrant est transmis uniquement au serveur principal en cas de jeton Web JSON valide. Dans le cas contraire, le trafic sera rejeté avec l'état 401.
  • Cette fonctionnalité n'est pas compatible avec les annotations suivantes :
    • kubernetes.io/ingress.allow-http: true
    • ncp/http-redirect: true
    • ncp/ssl-mode: passthrough
  • ncp/jwt-alg :
    • Algorithmes symétriques pris en charge : HS256
    • Algorithmes asymétriques pris en charge : RS256
  • ncp/jwt-secret :
    • Une clé symétrique ou un certificat public doit être configuré dans un secret Kubernetes avec le nom spécifié dans cette annotation sous le même espace de noms que l'entrée.
    • Pour les algorithmes symétriques, le secret doit être stocké dans le champ jwt.key.
    • Pour les algorithmes asymétriques, le certificat public doit être stocké dans le champ tls.crt.
    • L'authentification client JWT sera désactivée si le secret symétrique ou le certificat public n'est pas stocké dans les emplacements mentionnés ci-dessus ou si les données stockées dans le secret ne sont pas valides.
  • ncp/jwt-token :
    • Vous ne pouvez configurer qu'un seul élément dans cette annotation.
    • _arg_<param_name> : pour JWT transmis en tant que paramètre d'URI. Spécifiez le nom du paramètre qui contient JWT.
    • _cookie_<cookie_name> : pour JWT transmis en tant que cookie. Spécifiez le nom du cookie qui contient JWT.
• À propos des annotations ncp/connection_multiplxing_enabled et ncp/connection_multiplxing_number :
  • Le multiplexage TCP ne peut pas coexister avec HTTP NTLM. Dans NSX, si un pool d'équilibreur de charge avec le multiplexage TCP activé est lié à un serveur de couche 7 sur lequel NTLM est activé, la configuration NTLM est prioritaire sur le multiplexage TCP.
  • Exemple YAML :

    apiVersion: networking.k8s.io/v1
    kind: Ingress
    metadata:
      name: cafe-ingress
      annotations:
        ncp/connection_multiplexing_enabled: "true"
        ncp/connection_multiplexing_number: 100
    spec:
      tls:
      - hosts:
        - cafe.example.com
      rules:
      - host: cafe.example.com
        http:
          paths:
          - path: /tea
            backend:
              service:
                name: tea-svc
                port:
                  number: 80
          - path: /coffee
            backend:
              service:
                name: coffee-svc
                port:
                  number: 80

Erreurs

Les erreurs sont annotées dans la ressource d'entrée. L'erreur clé est ncp/error.loadbalancer et la clé d'avertissement est ncp/warning.loadbalancer. L'erreur et l'avertissement possibles sont :

• ncp/error.loadbalancer : DEFAULT_BACKEND_IN_USE

  Cette erreur indique qu'il existe déjà une entrée avec un serveur principal par défaut. L'entrée sera inactive. Cette erreur se produira si (1) cette entrée est pour HTTP et qu'il existe une autre entrée pour HTTP avec un serveur principal par défaut, (2) cette entrée est pour HTTPS et une autre entrée pour HTTPS avec un serveur principal par défaut existe, ou (3) cette entrée est pour HTTP et HTTPS, et une autre entrée pour HTTP et HTTPS avec un serveur principal par défaut existe. Pour corriger l'erreur, supprimez et recréez l'entrée avec une spécification correcte.

• ncp/warning.loadbalancer : SECRET_NOT_FOUND

  Cette erreur indique que le secret spécifié dans la spécification d'entrée n'existe pas, ou si ncp/jwt-alg et ncp/jwt-secret sont annotés mais que le secret est introuvable sous le même espace de noms que l'entrée. L'entrée sera partiellement active. Pour corriger l'erreur, créez le secret manquant. Notez qu'une fois qu'un avertissement est dans l'annotation, il ne sera pas effacé pendant le cycle de vie de la ressource d'entrée.

• ncp/warning.loadbalancer : INVALID_INGRESS
  Cette erreur indique que l'une des conditions suivantes est vraie. L'entrée sera inactive. Pour corriger l'erreur, supprimez et recréez l'entrée avec une spécification correcte.

  • Une règle d'entrée est en conflit avec une autre règle d'entrée dans le même cluster Kubernetes. Les conflits sont déterminés uniquement pour les entrées avec la même stratégie de correspondance, c'est-à-dire la même valeur d'annotation ncp/use-regex.
  • L'annotation kubernetes.io/ingress.allow-http est définie sur false et l'entrée n'a pas de section TLS.
  • L'annotation ncp/http-redirect est définie sur true et l'entrée n'a pas de section TLS.
  • host et path ne sont pas spécifiés dans une règle d'entrée. Une telle règle d'entrée a la même fonctionnalité que le serveur principal par défaut d'entrée. Utilisez plutôt le serveur principal d'entrée par défaut.
  • L'entrée contient des annotations JWL qui ne peuvent pas être traitées correctement. Par exemple :
    • ncp/jwt-alg ou ncp/jwt-secret est manquant.
    • ncp/jwt-alg est configuré avec un algorithme non pris en charge.
    • .ncp/jwt-alg et ncp/jwt-secret sont configurés avec d'autres annotations d'activation HTTP ou avec le relais SSL.