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 :
    • ImplementationSpecific est traité de la même manière que Exact.
    • 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.
    • Si use-regex et pathType sont définis, et que pathType est Exact ou Prefix, NCP n'utilisera pas regex pour créer des règles d'équilibreur de charge.
  • (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-T Data Center 3.0.0 ou versions supérieures.
À partir de Kubernetes 1.18, l'annotation kubernetes.io/ingress.class est obsolète et remplacée par la ressource IngressClass. Pour spécifier le contrôleur d'entrée NSX-T dans la ressource IngressClass, définissez le paramètre du contrôleur sur k8s.io/nsx. Par exemple :
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 :
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 :
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
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 :
      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:
            - path: /tea/(.*)
              pathType: ImplementationSpecific
              backend:
                service:
                  name: tea-svc
                  port:
                    number: 80
            - path: /coffee/(.*)
              pathType: ImplementationSpecific
              backend:
                service:
                  name: coffee-svc
                  port:
                    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.
    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,
    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 :
    • 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 :
      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 :
    • 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.

      Remarque : 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.

  • À 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.

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.