Configuration du contrôleur de trafic entrant natif OCI

Acheminer les demandes en fonction de l'hôte

Vous pouvez configurer le contrôleur de trafic entrant natif OCI pour qu'il achemine une demande entrante en fonction du nom de domaine dans l'en-tête d'hôte de la demande (hôte vers lequel la demande a été initialement envoyée).

Pour acheminer une demande vers un service et un port dorsaux particuliers en fonction de l'hôte, créez une règle de routage dans le manifeste Ingress. Si l'hôte correspond à la règle de routage, le contrôleur de trafic entrant natif OCI achemine la demande vers le service dorsal et le port associés.

Par exemple, vous pouvez définir la règle suivante pour acheminer les demandes envoyées initialement à http://foo.bar.com vers un service dorsal nommé ServiceA sur le port 80. Tout le trafic entrant initialement envoyé à http://foo.bar.com est acheminé vers ServiceA sur le port 80.

kind: Ingress
...
spec:
  rules:
  - host: "foo.bar.com"
    http:
      paths:
        - pathType: Prefix
          path: /
          backend:
            serviceName: ServiceA
            servicePort: 80

Acheminer les demandes vers différents services dorsaux en fonction du chemin

Vous pouvez configurer le contrôleur de trafic entrant natif OCI pour acheminer les demandes entrantes vers différents services dorsaux, en fonction des éléments du chemin vers lequel les demandes ont été initialement envoyées.

Pour acheminer une demande vers un service et un port dorsaux particuliers en fonction du chemin, créez une règle de routage dans le manifeste Ingress. Si le chemin correspond à la règle de routage, le contrôleur de trafic entrant natif OCI achemine la demande vers le service dorsal et le port associés. Vous pouvez spécifier plusieurs chemins dans la même règle pour acheminer des demandes vers différents serveurs dorsaux.

Par exemple, vous pouvez définir la règle suivante pour acheminer les demandes en fonction du chemin vers lequel la demande a été initialement envoyée :

• Si le chemin commence par /app1, le contrôleur de trafic entrant natif OCI achemine la demande vers un service dorsal nommé ServiceA sur le port 80.
• Si le chemin commence par /app2, le contrôleur de trafic entrant natif OCI achemine la demande vers un service dorsal nommé ServiceB sur le port 443.

Comme la règle ne spécifie pas d'hôte, elle s'applique à tout le trafic entrant.

kind: Ingress
...
spec:
  rules:
    - http:
      paths:
        - pathType: Prefix
          path: /app1
          backend:
            serviceName: ServiceA
            servicePort: 80
        - pathType: Prefix
          path: /app2
          backend:
            serviceName: ServiceB
            servicePort: 443

Acheminer les demandes en fonction de l'hôte et du chemin

Vous pouvez configurer le contrôleur de trafic entrant natif OCI pour qu'il achemine une demande entrante en fonction à la fois du nom de domaine dans l'en-tête d'hôte de la demande (l'hôte vers lequel la demande a été envoyée initialement) et des éléments du chemin vers lequel la demande initiale a été envoyée.

Pour acheminer une demande vers un service et un port dorsaux particuliers en fonction de l'hôte et du chemin, créez une règle de routage dans le manifeste Ingress. Si l'hôte et le chemin correspondent à la règle de routage, le contrôleur de trafic entrant natif OCI achemine la demande vers le service dorsal et le port associés.

Par exemple, vous pouvez définir la règle suivante pour acheminer les demandes envoyées initialement à http://foo.bar.com/app1 vers un service dorsal nommé foo sur le port 80 :

kind: Ingress
...
spec:
  rules:
  - host: "foo.bar.com"
    http:
      paths:
        - pathType: Prefix
          path: /app1
          backend:
            serviceName: foo
            servicePort: 80

Acheminer les demandes vers un système dorsal par défaut

Vous pouvez configurer le contrôleur de trafic entrant natif OCI pour acheminer les demandes entrantes vers un système dorsal par défaut. Vous pouvez configurer un système dorsal par défaut pour traiter les demandes qui ne correspondent à aucune règle de routage.

Par exemple, vous pouvez définir la valeur defaultBackend suivante pour acheminer les demandes qui ne correspondent pas à d'autres règles du manifeste Ingress vers un service dorsal nommé ServiceC sur le port 8080.

Notez que si vous ne spécifiez aucune autre règle dans un manifeste Ingress, vous devez spécifier une valeur defaultBackend.

kind: Ingress
...
spec:
  rules:
    - http:
      paths:
        - pathType: Prefix
          path: /app1
          backend:
            serviceName: ServiceA
            servicePort: 80
        - pathType: Prefix
          path: /app2
          backend:
            serviceName: ServiceB
            servicePort: 443
  defaultBackend:
    service:
      name: ServiceC
      port:
        number: 8080

Personnaliser le comportement général à l'aide d'annotations

Vous pouvez ajouter des annotations aux manifestes de ressource IngressClass ou Ingress pour personnaliser le comportement général du contrôleur de trafic entrant natif OCI.

Personnaliser le comportement des vérifications d'état à l'aide d'annotations

Vous pouvez ajouter des annotations au manifeste de ressources Ingress pour personnaliser les vérifications d'état effectuées par l'équilibreur de charge créé par le contrôleur de trafic entrant natif OCI. Pour plus d'informations sur les vérifications de l'état de l'équilibreur de charge, voir Vérifications d'état pour les équilibreurs de charge.

Option 1 : Le contrôleur de trafic entrant natif OCI obtient un certificat à partir du service de certificats à l'aide d'une clé secrète Kubernetes

Pour configurer le contrôleur de trafic entrant natif OCI afin d'obtenir un certificat à partir du service de certificats OCI :

1. Obtenez une paire de clés publique et privée TLS et un certificat.

   Dans les environnements de production, vous obtenez un certificat TLS auprès de l'autorité de certification choisie en soumettant une demande de signature de certificat. Au cours du processus de demande de certificat, une clé publique et la clé privée correspondante sont générées.

   Dans les environnements de développement et de test, vous pouvez créer un certificat auto-signé et générer vous-même une clé privée à l'aide d'un outil tel que OpenSSL. Par exemple (en utilisant OpenSSL 3.0 ou une version ultérieure) :

   1. Générez une paire de clés publique et privée en entrant les commandes suivantes :

      openssl genrsa -out rootCA.key 4096

      openssl req -x509 -addext basicConstraints=critical,CA:TRUE -new -nodes -key rootCA.key -sha256 -days 1024 -out rootCA.crt -subj /CN=RootCA

   2. Générez un certificat en entrant les commandes suivantes :

      openssl genrsa -out server.key 4096

      openssl req -new -sha256 -key server.key -subj /C=US/ST=CA/O=MyOrg,Inc./CN=my.example.com -out server.csr

      openssl x509 -req -in server.csr -CA rootCA.crt -CAkey rootCA.key -CAcreateserial -out server.crt -days 500 -sha256

   Dans ce cas :

   • rootCA.key contient la paire de clés de l'autorité de certification racine.
   • rootCA.crt contient le certificat AC racine.
   • server.key contient la paire de clés pour générer le certificat du serveur.
   • server.csr contient la demande de signature de certificat pour le certificat du serveur.
   • server.crt contient le certificat de serveur généré.
2. Créez une ressource de clé secrète Kubernetes de l'une des façons suivantes :

   • À l'aide de la commande kubectl create secret generic, entrez :

     kubectl create secret generic <k8s-secret-name> --type=kubernetes.io/tls --from-file=ca.crt=<path-and-filename>.crt --from-file=tls.crt=<path-and-filename>.crt --from-file=tls.key=<path-and-filename>.key

     où :

     • <k8s-secret-name> est le nom de votre choix pour la clé secrète Kubernetes
     • --from-file=ca.crt=<path-and-filename>.crt indique le chemin d'accès au fichier contenant le certificat de l'autorité de certification racine. Par exemple, --from-file=ca.crt=rootCA.crt
     • --from-file=tls.crt=<path-and-filename>.crt indique le chemin d'accès au fichier contenant le certificat de serveur généré. Par exemple, --from-file=tls.crt=server.crt
     • --from-file=tls.key=<path-and-filename>.key indique le chemin d'accès au fichier contenant la clé privée générée. Par exemple, --from-file=tls.key=server.key

     Par exemple :

     kubectl create secret generic example-tls-secret --type=kubernetes.io/tls --from-file=ca.crt=rootCA.crt --from-file=tls.crt=server.crt --from-file=tls.key=server.key

   • À l'aide d'un fichier manifeste de ressource Secret :

     1. Définissez la clé secrète Kubernetes dans un fichier .yaml, dans le format suivant :

        apiVersion: v1
        kind: Secret
        metadata:
          name: <k8s-secret-name>
        type: kubernetes.io/tls
        data:
          ca.crt: <base64-encoded-certificate-chain>
          tls.crt: <base64-encoded-server-certificate>
          tls.key: <base64-encoded-private-key>

        où :

        • name: <k8s-secret-name> est le nom de votre choix pour la ressource de clé secrète Kubernetes.
        • ca.crt: <base64-encoded-certificate-chain> est le contenu du fichier (ou des fichiers) contenant des certificats intermédiaires qui forment une chaîne de certificats remontant du certificat de feuille jusqu'à l'autorité de certification. Notez que vous pouvez omettre ca.cert, à condition d'inclure toute la chaîne de certificats comme valeur de tls.cert (dans ce cas, démarrez la chaîne de certificats avec le contenu du fichier contenant le certificat de serveur généré, suivi des certificats restants).
        • tls.crt: <base64-encoded-server-certificate> est le contenu du fichier contenant le certificat de serveur généré.
        • tls.key: <base64-encoded-private-key> est le contenu du fichier contenant la clé privée générée.

        Par exemple :

        apiVersion: v1
        kind: Secret
        metadata:
          name: example-tls-secret
        type: kubernetes.io/tls
        data:
          ca.crt : MIIFGERTegcDFRTuSDGfghREdE______Jre
          tls.crt: MIIC2DCCAcCgAwIBAgIBATANBg______kqh
          tls.key: MIIEpgIBAAKCAQEA7yn3bRHQ5F______HMQ

     2. Créez la ressource de clé secrète en entrant kubectl create -f <filename>.yaml

3. Ajoutez la clé secrète Kubernetes à un manifeste de ressources Ingress :
   1. Définissez une nouvelle ressource de trafic entrant dans un fichier .yaml. Voir Créer une ressource entrante.
   2. Dans la section spec: du manifeste, ajoutez un élément tls: qui spécifie à la fois l'hôte devant recevoir le trafic HTTPS et le nom de la clé secrète Kubernetes, dans le format suivant :

      kind: Ingress
      ...
      spec:
        tls:
        - hosts:
            - <host-name>
          secretName: <k8s-secret-name>

      Par exemple :

      kind: Ingress
      ...
      spec:
        tls:
        - hosts:
            - my.example.com
          secretName: example-tls-secret

   3. Dans la section rules: du manifeste, ajoutez une règle pour l'hôte qui doit recevoir le trafic HTTPS et spécifiez 443 comme port sur lequel écouter le trafic HTTPS.

      Par exemple :

      apiVersion: networking.k8s.io/v1
      kind: Ingress
      metadata:
        name: acme-tls-secret-ingress
      spec:
        tls:
        - hosts:
            - my.example.com
          secretName: example-tls-secret
        rules:
        - host: "my.example.com"
          http:
            paths:
            - pathType: Prefix
              path: "/TLSPath"
              backend:
                service:
                  name: tls-test
                  port:
                    number: 443

   4. Créez la ressource en entrant kubectl create -f <filename>.yaml

Lorsque vous créez la ressource entrante, le contrôleur de trafic entrant natif OCI utilise la clé secrète Kubernetes pour obtenir un certificat de type Importé et un ensemble AC (ensemble Autorité de certification), à partir du service de certificats OCI. Le contrôleur de trafic entrant natif OCI associe le certificat au module d'écoute et l'ensemble AC au jeu dorsal.

Lorsque le module d'écoute écoutant sur le port 443 reçoit une demande HTTPS à l'hôte spécifié, il utilise le certificat d'arrêt TLS. Le module d'écoute utilise ensuite la règle de routage pour transmettre la demande au jeu dorsal. Le jeu dorsal crée une nouvelle connexion TLS avec les serveurs dorsaux exécutés sur la grappe (en utilisant l'ensemble AC comme autorité de certification pour la nouvelle connexion).

Option 2 : Vous obtenez un certificat auprès du service Certificats

Pour configurer le contrôleur de trafic entrant natif OCI afin qu'il utilise un certificat que vous avez obtenu du service de certificats OCI :

1. Créez un certificat dans le service de certificats OCI de l'une des façons suivantes :
   • en important un certificat émis par une autorité de certification tierce (le certificat sera de type Importé)
   • en émettant le certificat en interne à partir d'une autorité de certification du service de certificats (le certificat sera de type Émis par une autorité de certification interne)

   Ne créez pas de certificat à gérer à l'externe (de type Émis par une autorité de certification interne, géré à l'externe). Pour plus d'informations, voir Création d'un certificat.

2. Notez l'OCID du certificat.
3. Ajoutez l'OCID du certificat à un manifeste de ressource Ingress :
   1. Définissez une nouvelle ressource de trafic entrant dans un fichier .yaml. Voir Créer une ressource entrante.
   2. Dans la section metadata:, ajoutez un élément annotations: qui spécifie l'OCID du certificat que vous avez créé dans le service de certificats OCI, dans le format suivant :

      kind: Ingress
      metadata:
        name: <i-name>
        annotations:
          oci-native-ingress.oraclecloud.com/certificate-ocid: <certificate-ocid>
      spec:
      ...

      où :

      • name: <i-name> est le nom de votre choix pour la ressource entrante.
      • oci-native-ingress.oraclecloud.com/certificate-ocid: <certificate-ocid> est l'OCID du certificat que vous avez créé dans le service de certificats OCI.

      Par exemple :

      kind: Ingress
      metadata:
        name: acme-tls-certificate-ingress
        annotations:
          oci-native-ingress.oraclecloud.com/certificate-ocid: ocid1.certificate.oc1.iad.amaaaaaa______gabc
      spec:
      ...

   3. Dans la section rules: du manifeste de ressources Ingress, ajoutez une règle pour l'hôte qui doit recevoir le trafic HTTPS et spécifiez 443 comme port sur lequel écouter le trafic HTTPS.

      Par exemple :

      apiVersion: networking.k8s.io/v1
      kind: Ingress
      metadata:
        name: acme-tls-certificate-ingress
        annotations:
          oci-native-ingress.oraclecloud.com/certificate-ocid: ocid1.certificate.oc1.iad.amaaaaaa______gabc
      spec:
        rules:
        - host: "my.example.com"
          http:
            paths:
            - pathType: Prefix
              path: "/TLSPath"
              backend:
                service:
                  name: tls-test
                  port:
                    number: 443

   4. Créez la ressource en entrant kubectl create -f <filename>.yaml

Ce qui se passe lorsque vous créez la ressource entrante dépend de la façon dont vous avez créé le certificat dans le service de certificats OCI :

• Si vous avez créé le certificat en important un certificat émis par une autorité de certification de tierce partie, le certificat est de type Importé. Le contrôleur de trafic entrant natif OCI associe le certificat au module d'écoute, crée un ensemble AC à partir de la chaîne de certificats et associe l'ensemble AC au jeu dorsal. Notez que vous ne pouvez pas configurer des certificats de type Importé pour qu'ils fassent l'objet d'une rotation automatique.
• Si vous avez créé le certificat en l'émettant en interne à partir d'une autorité de certification du service de certificats, le certificat est de type Émis par une autorité de certification interne. Le contrôleur de trafic entrant natif OCI associe le certificat au module d'écoute, obtient l'OCID de l'autorité de certification et associe cet OCID au jeu dorsal. Notez que vous pouvez configurer des certificats de type Émis par une autorité de certification interne pour qu'ils fassent l'objet d'une rotation automatique.

Lorsque le module d'écoute écoutant sur le port 443 reçoit une demande HTTPS à l'hôte spécifié, il utilise le certificat d'arrêt TLS. Le module d'écoute utilise ensuite la règle de routage pour transmettre la demande au jeu dorsal. Le jeu dorsal crée une nouvelle connexion TLS avec les serveurs dorsaux exécutés sur la grappe (à l'aide de l'ensemble AC ou de l'autorité de certification identifiée par son OCID en tant qu'autorité de certification pour la nouvelle connexion).

Application de marqueurs définis à l'équilibreur de charge

Les marqueurs définis sont configurés et gérés par un administrateur de marqueurs. Un marqueur défini se compose d'un espace de noms de marqueur, d'une clé et d'une valeur. L'espace de noms de marqueur et la définition de clé de marqueur doivent être configurés dans une location avant d'appliquer un marqueur défini à une ressource.

Pour spécifier que le contrôleur de trafic entrant natif OCI doit appliquer des marqueurs définis à l'équilibreur de charge, utilisez l'annotation oci-native-ingress.oraclecloud.com/defined-tags dans le manifeste IngressClass, dans le format suivant :

apiVersion: networking.k8s.io/v1
kind: IngressClass
metadata:
  name: <ic-name>
  annotations:
    oci-native-ingress.oraclecloud.com/defined-tags: '{"<tag-namespace>": {"<tag-key>": "<tag-value>"}}'
spec:
  ...

où :

• <tag-namespace> est l'espace de noms de marqueur auquel le marqueur appartient.
• <tag-key> est le nom d'un marqueur défini à appliquer à l'équilibreur de charge.
• <tag-value> est une valeur pour le marqueur à partir d'une liste de valeurs prédéfinie, ou une nouvelle valeur, ou vide (selon la configuration du marqueur défini).

La valeur de l'annotation oci-native-ingress.oraclecloud.com/defined-tags est une chaîne JSON, ce qui vous permet de spécifier plusieurs espaces de noms de marqueur, clés de marqueur et valeurs de marqueur au format JSON.

Par exemple :

apiVersion: networking.k8s.io/v1
kind: IngressClass
metadata:
  name: my-ingress-class
  annotations:
    oci-native-ingress.oraclecloud.com/defined-tags: '{"Operations": {"CostCenter": "42", "Department": "001"}, "Sales": {"Region": "US"}}'
spec:
  ...

La modification d'un des marqueurs dans l'annotation oci-native-ingress.oraclecloud.com/defined-tags du manifeste IngressClass entraîne la réapplication du contrôleur de trafic entrant natif OCI à l'équilibreur de charge de tous les marqueurs définis spécifiés par l'annotation. Toutefois, si un marqueur défini contient une variable de marqueur, le contrôleur de trafic entrant natif OCI ne réapplique le marqueur défini à l'équilibreur de charge que si le marqueur n'est pas déjà présent.

Notez que pour permettre au contrôleur de trafic entrant natif OCI d'appliquer des marqueurs définis à un équilibreur de charge, une politique IAM appropriée doit exister pour permettre au contrôleur de trafic entrant natif OCI d'utiliser l'espace de noms de marqueur approprié. Pour plus d'informations, voir :

• Octroi d'autorisations au contrôleur de trafic entrant natif OCI en tant que programme autonome
• Octroi d'autorisations au module complémentaire de grappe du contrôleur de trafic entrant natif OCI

Application de marqueurs à structure libre à l'équilibreur de charge

Les marqueurs à structure libre ne sont pas gérés par un administrateur de marqueurs. Un marqueur à structure libre se compose d'une clé et d'une valeur. Contrairement aux marqueurs définis, les marqueurs à structure libre n'appartiennent pas à un espace de noms de marqueur.

Pour spécifier que le contrôleur de trafic entrant natif OCI doit appliquer des marqueurs à structure libre à l'équilibreur de charge, utilisez l'annotation oci-native-ingress.oraclecloud.com/freeform-tags dans le manifeste IngressClass, dans le format suivant :

apiVersion: networking.k8s.io/v1
kind: IngressClass
metadata:
  name: <ic-name>
  annotations:
    oci-native-ingress.oraclecloud.com/freeform-tags: '{"<tag-key>": "<tag-value>"}'
spec:
  ...

où :

• <tag-key> est le nom du marqueur à structure libre à appliquer à l'équilibreur de charge.
• <tag-value> est une valeur pour le marqueur à structure libre à appliquer à l'équilibreur de charge.

La valeur de l'annotation oci-native-ingress.oraclecloud.com/freeform-tags est une chaîne JSON, ce qui vous permet de spécifier plusieurs clés de marqueur et valeurs de marqueur au format JSON.

Par exemple :

apiVersion: networking.k8s.io/v1
kind: IngressClass
metadata:
  name: my-ingress-class
  annotations:
    oci-native-ingress.oraclecloud.com/freeform-tags: '{"Project": "Red", "Version": "Alpha"}'
spec:
  ...

La modification d'un des marqueurs dans l'annotation oci-native-ingress.oraclecloud.com/freeform-tags du manifeste IngressClass entraîne la réapplication du contrôleur de trafic entrant natif OCI à l'équilibreur de charge de tous les marqueurs à structure libre spécifiés par l'annotation.

Application des valeurs par défaut de marqueur à l'équilibreur de charge

Les valeurs par défaut de marqueur sont configurées pour un compartiment spécifique. Les valeurs par défaut de marqueur sont propres au compartiment. Les marqueurs par défaut spécifient des marqueurs définis qui sont appliqués automatiquement à toutes les ressources créées dans un compartiment particulier au moment de leur création.

Lors de l'utilisation du contrôleur de trafic entrant natif OCI version 1.4.0 (ou ultérieure), les valeurs par défaut de marqueur sont automatiquement appliquées aux équilibreurs de charge créés par le contrôleur de trafic entrant natif OCI. Par la suite, le contrôleur de trafic entrant natif OCI conserve une valeur par défaut de marqueur appliquée à un équilibreur de charge, sauf si l'une des conditions suivantes est remplie :

• Vous supprimez manuellement une valeur par défaut de marqueur qui a été appliquée automatiquement à un équilibreur de charge.
• Vous spécifiez une valeur par défaut de marqueur comme marqueur défini, à l'aide de l'annotation oci-native-ingress.oraclecloud.com/defined-tags (dans ce cas, le contrôleur de trafic entrant natif OCI traite la valeur par défaut de marqueur comme tout autre marqueur défini).

Notez que les valeurs par défaut de marqueur avec des valeurs appliquées par l'utilisateur ne sont pas prises en charge. Si une valeur de marqueur par défaut avec une valeur appliquée par l'utilisateur a été configurée pour un compartiment dans lequel le contrôleur de trafic entrant natif OCI doit créer ou gérer un équilibreur de charge, vous devez utiliser l'annotation oci-native-ingress.oraclecloud.com/defined-tags pour spécifier la valeur par défaut de marqueur en tant que marqueur défini.

Pour les équilibreurs de charge créés à l'aide d'une version du contrôleur de trafic entrant natif OCI antérieure à la version 1.4.0, ou lors de l'utilisation de l'annotation oci-native-ingress.oraclecloud.com/id pour spécifier que le contrôleur de trafic entrant natif OCI doit gérer un équilibreur de charge existant, notez que les valeurs par défaut de marqueur ne sont pas prises en charge. Dans les deux cas, pour appliquer ou conserver une valeur par défaut de marqueur, utilisez l'annotation oci-native-ingress.oraclecloud.com/defined-tags pour spécifier la valeur par défaut de marqueur en tant que marqueur défini à la place.