Ingress

Un objet API qui gère l'accès externe aux services d'un cluster, typiquement HTTP.

L'Ingress peut fournir un équilibrage de charge, une terminaison SSL ainsi qu'un hébergement virtuel basé sur un nom.

Terminologie

Par souci de clarté, ce guide définit les termes suivants :

• Nœud (Node) : une machine de travail de Kubernetes, qui fait partie d'un cluster.
• Cluster : un ensemble de nœuds qui exécutent des applications conteneurisées gérées par Kubernetes. Dans cet exemple, comme dans la plupart des déploiements Kubernetes courants, les nœuds du cluster ne sont pas exposés sur l'Internet public.
• Routeur de bordure (edge router) : un routeur qui applique la politique de pare-feu de votre cluster. Il peut s'agir d'une passerelle gérée par un fournisseur de cloud ou d'un équipement physique.
• Réseau du cluster : un ensemble de liens, logiques ou physiques, qui permettent la communication au sein d'un cluster selon le modèle réseau de Kubernetes.
• Service : un Service Kubernetes qui identifie un ensemble de Pods à l'aide de sélecteurs de labels. Sauf mention contraire, on suppose que les Services ont des adresses IP virtuelles routables uniquement dans le réseau du cluster.

Qu'est-ce qu'un Ingress ?

Un Ingress expose des routes HTTP et HTTPS depuis l'extérieur du cluster vers des services du cluster. Le routage du trafic est contrôlé par des règles définies sur la ressource Ingress.

Voici un exemple simple dans lequel un Ingress envoie tout son trafic vers un seul Service :

Un Ingress peut être configuré pour donner aux Services des URL accessibles de l'extérieur, équilibrer la charge du trafic, assurer la terminaison SSL / TLS et proposer un hébergement virtuel basé sur le nom. Un contrôleur d'Ingress est chargé de mettre en œuvre l'Ingress, généralement avec un équilibreur de charge (load balancer), mais il peut aussi configurer votre routeur de bordure ou des frontaux supplémentaires pour aider à gérer le trafic.

Un Ingress n'expose pas de ports ni de protocoles arbitraires. Pour exposer à Internet des services autres que HTTP et HTTPS, on utilise généralement un Service de type Service.Type=NodePort ou Service.Type=LoadBalancer.

Prérequis

Vous devez disposer d'un contrôleur d'Ingress pour qu'un Ingress soit pris en compte. La simple création d'une ressource Ingress n'a aucun effet.

Vous avez le choix entre de nombreux contrôleurs d'Ingress.

Idéalement, tous les contrôleurs d'Ingress devraient respecter la spécification de référence. En pratique, les différents contrôleurs d'Ingress fonctionnent de manière légèrement différente.

La ressource Ingress

Exemple de ressource Ingress minimale :

service/networking/minimal-ingress.yaml

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: minimal-ingress
spec:
  ingressClassName: nginx-example
  rules:
  - http:
      paths:
      - path: /testpath
        pathType: Prefix
        backend:
          service:
            name: test
            port:
              number: 80

Un Ingress a besoin des champs apiVersion, kind, metadata et spec. Le nom d'un objet Ingress doit être un nom de sous-domaine DNS valide. Pour des informations générales sur l'utilisation des fichiers de configuration, consultez déployer des applications, configurer des conteneurs et gérer des ressources. Les contrôleurs d'Ingress utilisent souvent des annotations pour configurer leur comportement. Consultez la documentation du contrôleur d'Ingress que vous avez choisi pour savoir quelles annotations sont attendues ou prises en charge.

La spec de l'Ingress contient toutes les informations nécessaires pour configurer un équilibreur de charge ou un serveur proxy. Elle contient surtout une liste de règles comparées à toutes les requêtes entrantes. La ressource Ingress ne prend en charge que des règles pour diriger du trafic HTTP(S).

Si ingressClassName est omis, une classe d'Ingress par défaut devrait être définie.

Certains contrôleurs d'Ingress fonctionnent même sans définition d'une IngressClass par défaut. Même si vous utilisez un contrôleur d'Ingress capable de fonctionner sans IngressClass, le projet Kubernetes recommande tout de même de définir une IngressClass par défaut.

Règles d'Ingress

Chaque règle HTTP contient les informations suivantes :

• Un hôte facultatif. Dans cet exemple, aucun hôte n'est indiqué : la règle s'applique donc à tout le trafic HTTP entrant par l'adresse IP indiquée. Si un hôte est fourni (par exemple foo.bar.com), les règles s'appliquent à cet hôte.
• Une liste de chemins (par exemple /testpath), chacun associé à un backend défini par un service.name et un service.port.name ou un service.port.number. L'hôte et le chemin doivent tous deux correspondre au contenu d'une requête entrante pour que l'équilibreur de charge dirige le trafic vers le Service référencé.
• Un backend est une combinaison d'un nom de Service et d'un port, comme décrit dans la documentation des Services, ou un backend de ressource personnalisée défini au moyen d'une CRD. Les requêtes HTTP (et HTTPS) adressées à l'Ingress qui correspondent à l'hôte et au chemin de la règle sont envoyées au backend indiqué.

Un defaultBackend est souvent configuré dans un contrôleur d'Ingress pour traiter toutes les requêtes qui ne correspondent à aucun chemin de la spec.

DefaultBackend

Un Ingress sans règles envoie tout le trafic vers un unique backend par défaut, et .spec.defaultBackend est le backend qui doit traiter les requêtes dans ce cas. Le defaultBackend est habituellement une option de configuration du contrôleur d'Ingress et n'est pas indiqué dans vos ressources Ingress. Si .spec.rules n'est pas défini, .spec.defaultBackend doit l'être. Si defaultBackend n'est pas défini, c'est le contrôleur d'Ingress qui décide du traitement des requêtes qui ne correspondent à aucune règle (consultez la documentation de votre contrôleur d'Ingress pour savoir comment il gère ce cas).

Si aucun des hôtes ou chemins des objets Ingress ne correspond à la requête HTTP, le trafic est acheminé vers votre backend par défaut.

Backends de ressource

Un backend Resource est une référence (ObjectRef) vers une autre ressource Kubernetes du même namespace que l'objet Ingress. Resource et Service s'excluent mutuellement : la validation échoue si les deux sont indiqués. Un backend Resource sert couramment à faire entrer des données dans un backend de stockage objet contenant des ressources statiques.

service/networking/ingress-resource-backend.yaml

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: ingress-resource-backend
spec:
  defaultBackend:
    resource:
      apiGroup: k8s.example.com
      kind: StorageBucket
      name: static-assets
  rules:
    - http:
        paths:
          - path: /icons
            pathType: ImplementationSpecific
            backend:
              resource:
                apiGroup: k8s.example.com
                kind: StorageBucket
                name: icon-assets

Après avoir créé l'Ingress ci-dessus, vous pouvez l'afficher avec la commande suivante :

kubectl describe ingress ingress-resource-backend

Name:             ingress-resource-backend
Namespace:        default
Address:
Default backend:  APIGroup: k8s.example.com, Kind: StorageBucket, Name: static-assets
Rules:
  Host        Path  Backends
  ----        ----  --------
  *
              /icons   APIGroup: k8s.example.com, Kind: StorageBucket, Name: icon-assets
Annotations:  <none>
Events:       <none>

Types de chemins

Chaque chemin d'un Ingress doit avoir un type de chemin correspondant. Les chemins sans pathType explicite échouent à la validation. Trois types de chemins sont pris en charge :

• ImplementationSpecific : avec ce type de chemin, la correspondance dépend de l'IngressClass. Les implémentations peuvent le traiter comme un pathType distinct ou de la même manière que les types de chemins Prefix ou Exact.

• Exact : correspond exactement au chemin de l'URL, en tenant compte de la casse.

• Prefix : correspond selon un préfixe du chemin de l'URL découpé par /. La correspondance tient compte de la casse et se fait élément par élément. Un élément de chemin désigne la liste des libellés du chemin découpé par le séparateur /. Une requête correspond au chemin p si chaque p est un préfixe, élément par élément, de p dans le chemin de la requête.

  Note:

  Si le dernier élément du chemin est une sous-chaîne du dernier élément du chemin de la requête, il n'y a pas de correspondance (par exemple, /foo/bar correspond à /foo/bar/baz, mais pas à /foo/barbaz).

Exemples

Correspondances multiples

Dans certains cas, plusieurs chemins d'un Ingress correspondent à une requête. La priorité est alors donnée au chemin correspondant le plus long. Si deux chemins correspondent toujours à égalité, la priorité est donnée aux chemins de type exact plutôt qu'aux chemins de type préfixe.

Jokers dans les noms d'hôte

Les hôtes peuvent être des correspondances précises (par exemple « foo.bar.com ») ou un joker (par exemple « *.foo.com »). Une correspondance précise exige que l'en-tête HTTP host corresponde au champ host. Une correspondance avec joker exige que l'en-tête HTTP host soit égal au suffixe de la règle avec joker.

service/networking/ingress-wildcard-host.yaml

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: ingress-wildcard-host
spec:
  rules:
  - host: "foo.bar.com"
    http:
      paths:
      - pathType: Prefix
        path: "/bar"
        backend:
          service:
            name: service1
            port:
              number: 80
  - host: "*.foo.com"
    http:
      paths:
      - pathType: Prefix
        path: "/foo"
        backend:
          service:
            name: service2
            port:
              number: 80

Classe d'Ingress

Les Ingress peuvent être mis en œuvre par différents contrôleurs, souvent avec des configurations différentes. Chaque Ingress devrait indiquer une classe, c'est-à-dire une référence à une ressource IngressClass qui contient une configuration supplémentaire, dont le nom du contrôleur chargé de mettre en œuvre la classe.

service/networking/external-lb.yaml

apiVersion: networking.k8s.io/v1
kind: IngressClass
metadata:
  name: external-lb
spec:
  controller: example.com/ingress-controller
  parameters:
    apiGroup: k8s.example.com
    kind: IngressParameters
    name: external-lb

Le champ .spec.parameters d'une IngressClass vous permet de référencer une autre ressource qui fournit la configuration associée à cette IngressClass.

Le type précis de paramètres à utiliser dépend du contrôleur d'Ingress que vous indiquez dans le champ .spec.controller de l'IngressClass.

Portée d'une IngressClass

Selon votre contrôleur d'Ingress, vous pourrez peut-être utiliser des paramètres définis pour tout le cluster, ou pour un seul namespace.

• Cluster
• Namespace

---
apiVersion: networking.k8s.io/v1
kind: IngressClass
metadata:
  name: external-lb-1
spec:
  controller: example.com/ingress-controller
  parameters:
    # The parameters for this IngressClass are specified in a
    # ClusterIngressParameter (API group k8s.example.net) named
    # "external-config-1". This definition tells Kubernetes to
    # look for a cluster-scoped parameter resource.
    scope: Cluster
    apiGroup: k8s.example.net
    kind: ClusterIngressParameter
    name: external-config-1

---
apiVersion: networking.k8s.io/v1
kind: IngressClass
metadata:
  name: external-lb-2
spec:
  controller: example.com/ingress-controller
  parameters:
    # The parameters for this IngressClass are specified in an
    # IngressParameter (API group k8s.example.com) named "external-config",
    # that's in the "external-configuration" namespace.
    scope: Namespace
    apiGroup: k8s.example.com
    kind: IngressParameter
    namespace: external-configuration
    name: external-config

Annotation obsolète

Avant l'ajout de la ressource IngressClass et du champ ingressClassName dans Kubernetes 1.18, les classes d'Ingress étaient indiquées par une annotation kubernetes.io/ingress.class sur l'Ingress. Cette annotation n'a jamais été définie formellement, mais elle était largement prise en charge par les contrôleurs d'Ingress.

Le champ ingressClassName, plus récent, remplace cette annotation, sans en être un équivalent direct. Alors que l'annotation servait généralement à référencer le nom du contrôleur d'Ingress chargé de mettre en œuvre l'Ingress, le champ est une référence à une ressource IngressClass qui contient une configuration d'Ingress supplémentaire, dont le nom du contrôleur d'Ingress.

IngressClass par défaut

Vous pouvez marquer une IngressClass donnée comme classe par défaut de votre cluster. Définir l'annotation ingressclass.kubernetes.io/is-default-class sur true sur une ressource IngressClass garantit que cette IngressClass par défaut sera attribuée aux nouveaux Ingress qui n'indiquent pas de champ ingressClassName.

Commencez par définir une IngressClass par défaut. Il est toutefois recommandé d'indiquer l'IngressClass par défaut :

service/networking/default-ingressclass.yaml

apiVersion: networking.k8s.io/v1
kind: IngressClass
metadata:
  labels:
    app.kubernetes.io/component: controller
  name: example-class
  annotations:
    ingressclass.kubernetes.io/is-default-class: "true"
spec:
  controller: k8s.io/example-class

Types d'Ingress

Ingress reposant sur un seul Service

Il existe déjà des concepts Kubernetes qui permettent d'exposer un seul Service (voir les alternatives). Vous pouvez aussi le faire avec un Ingress en indiquant un backend par défaut sans règles.

service/networking/test-ingress.yaml

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: test-ingress
spec:
  defaultBackend:
    service:
      name: test
      port:
        number: 80

Si vous le créez avec kubectl apply -f, vous devriez pouvoir afficher l'état de l'Ingress que vous avez ajouté :

kubectl get ingress test-ingress

NAME           CLASS         HOSTS   ADDRESS         PORTS   AGE
test-ingress   external-lb   *       203.0.113.123   80      59s

203.0.113.123 est l'adresse IP allouée par le contrôleur d'Ingress pour satisfaire cet Ingress.

Fanout simple

Une configuration en fanout achemine le trafic d'une seule adresse IP vers plusieurs Services, en fonction de l'URI HTTP demandée. Un Ingress vous permet de réduire au minimum le nombre d'équilibreurs de charge. Prenons par exemple la configuration suivante :

Elle nécessiterait un Ingress comme celui-ci :

service/networking/simple-fanout-example.yaml

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: simple-fanout-example
spec:
  rules:
  - host: foo.bar.com
    http:
      paths:
      - path: /foo
        pathType: Prefix
        backend:
          service:
            name: service1
            port:
              number: 4200
      - path: /bar
        pathType: Prefix
        backend:
          service:
            name: service2
            port:
              number: 8080

Une fois l'Ingress créé avec kubectl apply -f :

kubectl describe ingress simple-fanout-example

Name:             simple-fanout-example
Namespace:        default
Address:          178.91.123.132
Default backend:  default-http-backend:80 (10.8.2.3:8080)
Rules:
  Host         Path  Backends
  ----         ----  --------
  foo.bar.com
               /foo   service1:4200 (10.8.0.90:4200)
               /bar   service2:8080 (10.8.0.91:8080)
Events:
  Type     Reason  Age                From                     Message
  ----     ------  ----               ----                     -------
  Normal   ADD     22s                loadbalancer-controller  default/test

Le contrôleur d'Ingress provisionne un équilibreur de charge propre à son implémentation qui satisfait l'Ingress, à condition que les Services (service1, service2) existent. Une fois que c'est fait, vous pouvez voir l'adresse de l'équilibreur de charge dans le champ Address.

Hébergement virtuel basé sur le nom

Les hôtes virtuels basés sur le nom permettent d'acheminer le trafic HTTP vers plusieurs noms d'hôte partageant la même adresse IP.

L'Ingress suivant indique à l'équilibreur de charge sous-jacent d'acheminer les requêtes en fonction de l'en-tête Host.

service/networking/name-virtual-host-ingress.yaml

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: name-virtual-host-ingress
spec:
  rules:
  - host: foo.bar.com
    http:
      paths:
      - pathType: Prefix
        path: "/"
        backend:
          service:
            name: service1
            port:
              number: 80
  - host: bar.foo.com
    http:
      paths:
      - pathType: Prefix
        path: "/"
        backend:
          service:
            name: service2
            port:
              number: 80

Si vous créez une ressource Ingress sans définir d'hôte dans les règles, tout trafic web adressé à l'adresse IP de votre contrôleur d'Ingress peut correspondre sans qu'un hôte virtuel basé sur le nom soit nécessaire.

Par exemple, l'Ingress suivant achemine le trafic demandé pour first.bar.com vers service1, celui pour second.bar.com vers service2, et tout trafic dont l'en-tête Host de la requête ne correspond ni à first.bar.com ni à second.bar.com vers service3.

service/networking/name-virtual-host-ingress-no-third-host.yaml

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: name-virtual-host-ingress-no-third-host
spec:
  rules:
  - host: first.bar.com
    http:
      paths:
      - pathType: Prefix
        path: "/"
        backend:
          service:
            name: service1
            port:
              number: 80
  - host: second.bar.com
    http:
      paths:
      - pathType: Prefix
        path: "/"
        backend:
          service:
            name: service2
            port:
              number: 80
  - http:
      paths:
      - pathType: Prefix
        path: "/"
        backend:
          service:
            name: service3
            port:
              number: 80

TLS

Vous pouvez sécuriser un Ingress en indiquant un Secret qui contient une clé privée et un certificat TLS. La ressource Ingress ne prend en charge qu'un seul port TLS, le 443, et suppose que la terminaison TLS se fait au point d'entrée (le trafic vers le Service et ses Pods circule en clair). Si la section de configuration TLS d'un Ingress indique plusieurs hôtes, ils sont multiplexés sur le même port selon le nom d'hôte indiqué via l'extension TLS SNI (à condition que le contrôleur d'Ingress prenne en charge SNI). Le Secret TLS doit contenir des clés nommées tls.crt et tls.key, qui contiennent le certificat et la clé privée à utiliser pour TLS. Par exemple :

apiVersion: v1
kind: Secret
metadata:
  name: testsecret-tls
  namespace: default
data:
  tls.crt: base64 encoded cert
  tls.key: base64 encoded key
type: kubernetes.io/tls

Référencer ce Secret dans un Ingress indique au contrôleur d'Ingress de sécuriser avec TLS le canal entre le client et l'équilibreur de charge. Vous devez vous assurer que le Secret TLS que vous avez créé provient d'un certificat contenant un Common Name (CN), aussi appelé nom de domaine complet (FQDN), pour https-example.foo.com.

service/networking/tls-example-ingress.yaml

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: tls-example-ingress
spec:
  tls:
  - hosts:
      - https-example.foo.com
    secretName: testsecret-tls
  rules:
  - host: https-example.foo.com
    http:
      paths:
      - path: /
        pathType: Prefix
        backend:
          service:
            name: service1
            port:
              number: 80

Équilibrage de charge

Un contrôleur d'Ingress démarre avec des réglages de politique d'équilibrage de charge qu'il applique à tous les Ingress, comme l'algorithme d'équilibrage de charge, le schéma de pondération des backends, etc. Les concepts d'équilibrage de charge plus avancés (par exemple les sessions persistantes ou les pondérations dynamiques) ne sont pas encore exposés via l'Ingress. Vous pouvez en revanche obtenir ces fonctionnalités grâce à l'équilibreur de charge utilisé pour un Service.

Notez aussi que, même si les contrôles de santé (health checks) ne sont pas exposés directement via l'Ingress, il existe dans Kubernetes des concepts parallèles, comme les sondes de disponibilité (readiness probes), qui permettent d'obtenir le même résultat. Consultez la documentation propre à votre contrôleur pour savoir comment il gère les contrôles de santé.

Mettre à jour un Ingress

Pour mettre à jour un Ingress existant afin d'ajouter un nouvel hôte, vous pouvez modifier la ressource :

kubectl describe ingress test

Name:             test
Namespace:        default
Address:          178.91.123.132
Default backend:  default-http-backend:80 (10.8.2.3:8080)
Rules:
  Host         Path  Backends
  ----         ----  --------
  foo.bar.com
               /foo   service1:80 (10.8.0.90:80)
Events:
  Type     Reason  Age                From                     Message
  ----     ------  ----               ----                     -------
  Normal   ADD     35s                loadbalancer-controller  default/test

kubectl edit ingress test

Un éditeur s'ouvre avec la configuration existante au format YAML. Modifiez-la pour ajouter le nouvel hôte :

spec:
  rules:
  - host: foo.bar.com
    http:
      paths:
      - backend:
          service:
            name: service1
            port:
              number: 80
        path: /foo
        pathType: Prefix
  - host: bar.baz.com
    http:
      paths:
      - backend:
          service:
            name: service2
            port:
              number: 80
        path: /foo
        pathType: Prefix
..

Une fois vos modifications enregistrées, kubectl met à jour la ressource dans le serveur d'API, ce qui indique au contrôleur d'Ingress de reconfigurer l'équilibreur de charge.

Vérifiez-le :

kubectl describe ingress test

Name:             test
Namespace:        default
Address:          178.91.123.132
Default backend:  default-http-backend:80 (10.8.2.3:8080)
Rules:
  Host         Path  Backends
  ----         ----  --------
  foo.bar.com
               /foo   service1:80 (10.8.0.90:80)
  bar.baz.com
               /foo   service2:80 (10.8.0.91:80)
Events:
  Type     Reason  Age                From                     Message
  ----     ------  ----               ----                     -------
  Normal   ADD     45s                loadbalancer-controller  default/test

Vous pouvez obtenir le même résultat en exécutant kubectl replace -f sur un fichier YAML d'Ingress modifié.

Basculement entre zones de disponibilité

Les techniques de répartition du trafic entre domaines de défaillance diffèrent d'un fournisseur de cloud à l'autre. Consultez la documentation du contrôleur d'Ingress concerné pour plus de détails.

Alternatives

Vous pouvez exposer un Service de plusieurs manières qui n'impliquent pas directement la ressource Ingress :

• Utilisez Service.Type=LoadBalancer
• Utilisez Service.Type=NodePort

A suivre

• En savoir plus sur l'API Ingress
• En savoir plus sur les contrôleurs d'Ingress