Configuration du contrôleur d'entrée natif OCI

Acheminer les demandes en fonction de l'hôte

Vous pouvez configurer le contrôleur d'entrée natif OCI pour acheminer une demande entrante en fonction du nom de domaine dans l'en-tête d'hôte de la demande (hôte auquel la demande a été envoyée à l'origine).

Pour acheminer une demande vers un port et un service back-end 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 d'entrée natif OCI achemine la demande vers le port et le service back-end associés.

Par exemple, vous pouvez définir la règle suivante pour acheminer les demandes initialement envoyées à http://foo.bar.com vers un service back-end 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 back-end en fonction du chemin

Vous pouvez configurer le contrôleur d'entrée natif OCI pour acheminer les demandes entrantes vers différents services back-end, en fonction des éléments du chemin vers lequel les demandes ont été envoyées à l'origine.

Pour acheminer une demande vers un port et un service back-end donnés 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 d'entrée natif OCI achemine la demande vers le port et le service back-end associés. Vous pouvez indiquer plusieurs chemins dans la même règle pour acheminer les demandes vers différents back-ends.

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 d'entrée natif OCI achemine la demande vers un service back-end nommé ServiceA sur le port 80.
• Si le chemin commence par /app2, le contrôleur d'entrée natif OCI achemine la demande vers un service back-end 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 d'entrée natif OCI pour acheminer une demande entrante en fonction du nom de domaine dans l'en-tête d'hôte de la demande (hôte auquel la demande a été envoyée à l'origine) et des éléments du chemin vers lequel la demande d'origine a été envoyée.

Pour acheminer une demande vers un port et un service back-end 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 d'entrée natif OCI achemine la demande vers le port et le service back-end associés.

Par exemple, vous pouvez définir la règle suivante pour acheminer les demandes initialement envoyées à http://foo.bar.com/app1 vers un service back-end 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 back-end par défaut

Vous pouvez configurer le contrôleur d'entrée natif OCI pour acheminer les demandes entrantes vers un back-end par défaut. Vous pouvez configurer un back-end par défaut pour gérer les demandes qui ne correspondent à aucune règle de routage.

Par exemple, vous pouvez définir l'élément defaultBackend suivant pour acheminer les demandes qui ne correspondent pas aux autres règles du manifeste Ingress vers un service back-end nommé ServiceC sur le port 8080.

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 d'entrée natif OCI.

Personnalisation du comportement de la vérification de l'état à l'aide d'annotations

Vous pouvez ajouter des annotations au manifeste de ressource Ingress pour personnaliser les vérifications de l'état effectuées par l'équilibreur de charge créé par le contrôleur d'entrée natif OCI. Pour plus d'informations sur les vérifications de l'état des équilibreurs de charge, reportez-vous à Vérifications de l'état pour les équilibreurs de charge.

Option 1 : le contrôleur d'entrée natif OCI obtient le certificat du service Certificates à l'aide d'une clé secrète Kubernetes

Pour configurer le contrôleur d'entrée natif OCI afin d'obtenir un certificat à partir du service OCI Certificates, procédez comme suit :

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. Pendant le 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 (avec OpenSSL 3.0 ou 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 saisissant 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 cet exemple :

   • rootCA.key contient la paire de clés de l'autorité de certification racine.
   • rootCA.crt contient le certificat CA racine.
   • server.key contient la paire de clés permettant de générer le certificat de serveur.
   • server.csr contient la demande de signature de certificat pour le certificat de 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 manières suivantes :

   • A l'aide de la commande kubectl create secret generic, saisissez :

     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 du fichier contenant le certificat d'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 du 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

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

     1. Définissez la clé secrète Kubernetes dans un fichier .yaml, au 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> représente le contenu du ou des fichiers contenant des certificats intermédiaires qui forment une chaîne de certificat allant du certificat feuille à l'autorité de certification. Vous pouvez omettre ca.cert, à condition d'inclure toute la chaîne de certificats en tant que 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 saisissant kubectl create -f <filename>.yaml

3. Ajoutez la clé secrète Kubernetes à un manifeste de ressource Ingress :
   1. Définissez une nouvelle ressource entrante dans un fichier .yaml. Reportez-vous à Création d'une ressource entrante.
   2. Dans la section spec: du manifeste, ajoutez un élément tls: qui indique à la fois l'hôte qui doit recevoir le trafic HTTPS et le nom de la clé secrète Kubernetes, au 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 indiquez 443 comme port d'écoute du 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 saisissant kubectl create -f <filename>.yaml

Lorsque vous créez la ressource entrante, le contrôleur d'entrée natif OCI utilise la clé secrète Kubernetes pour obtenir un certificat de type Importé et un package d'autorité de certification (bundle d'autorité de certification) à partir du service OCI Certificates. Le contrôleur d'entrée natif OCI associe le certificat au processus d'écoute et le package d'autorité de certification à l'ensemble de back-ends.

Lorsque le processus d'écoute qui écoute sur le port 443 reçoit une demande HTTPS vers l'hôte spécifié, il utilise le certificat pour la terminaison TLS. Le processus d'écoute utilise ensuite la règle de routage pour transmettre la demande à l'ensemble de back-ends. L'ensemble de back-ends crée une connexion TLS avec les back-ends exécutés sur le cluster (en utilisant le package d'autorité de certification comme autorité de confiance pour la nouvelle connexion).

Option 2 : obtenir un certificat auprès du service Certificates

Pour configurer le contrôleur d'entrée natif OCI de sorte qu'il utilise un certificat obtenu à partir du service OCI Certificates, procédez comme suit :

1. Créez un certificat dans le service OCI Certificates de l'une des manières suivantes :
   • en important un certificat émis par une CA tierce (le certificat sera de type Imported)
   • en émettant le certificat en interne à partir d'une CA de service Certificates (le certificat sera de type Emis par une CA interne)

   Ne créez pas de certificat à gérer en externe (de type Emis par une autorité de certification interne, géré en 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 entrante dans un fichier .yaml. Reportez-vous à Création d'une ressource entrante.
   2. Dans la section metadata:, ajoutez un élément annotations: qui indique l'OCID du certificat que vous avez créé dans le service OCI Certificates, au 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 OCI Certificates.

      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 ressource Ingress, ajoutez une règle pour l'hôte qui doit recevoir le trafic HTTPS et indiquez 443 comme port d'écoute du 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 saisissant 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 OCI Certificates :

• Si vous avez créé le certificat en important un certificat émis par une autorité de certification tierce, le certificat est de type Imported. Le contrôleur d'entrée natif OCI associe le certificat au processus d'écoute, crée un package d'autorité de certification à partir de la chaîne de certificats et associe le package d'autorité de certification à l'ensemble de back-ends. Notez que vous ne pouvez pas configurer la rotation automatique des certificats de type Importé.
• Si vous avez créé le certificat en émettant le certificat en interne à partir d'une CA de service Certificates, le certificat est de type Emis par une CA interne. Le contrôleur entrant natif OCI associe le certificat au processus d'écoute, obtient l'OCID de l'autorité de certification et associe cet OCID à l'ensemble de back-ends. Notez que vous pouvez configurer la rotation automatique des certificats de type Emis par l'autorité de certification interne.

Lorsque le processus d'écoute qui écoute sur le port 443 reçoit une demande HTTPS vers l'hôte spécifié, il utilise le certificat pour la terminaison TLS. Le processus d'écoute utilise ensuite la règle de routage pour transmettre la demande à l'ensemble de back-ends. L'ensemble de back-ends crée une connexion TLS avec les back-ends exécutés sur le cluster (à l'aide du package d'autorité de certification ou de l'autorité de certification identifiée par son OCID, en tant qu'autorité de confiance pour la nouvelle connexion).

Application de balises définies à l'équilibreur de charge

Les balises définies sont configurées et gérées par un administrateur de balises. Une balise définie est composée d'un espace de noms de balise, d'une clé et d'une valeur. Pour pouvoir appliquer une balise définie à une ressource, vous devez configurer l'espace de noms de balise et la définition de clé de balise dans une location.

Pour indiquer que le contrôleur d'entrée natif OCI doit appliquer des balises définies à l'équilibreur de charge, utilisez l'annotation oci-native-ingress.oraclecloud.com/defined-tags dans le manifeste IngressClass, au 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 balise auquel la balise appartient.
• <tag-key> est le nom d'une balise définie à appliquer à l'équilibreur de charge.
• <tag-value> est soit une valeur pour la balise provenant d'une liste de valeurs prédéfinie, soit une nouvelle valeur, soit vide (selon la configuration de la balise définie).

La valeur de l'annotation oci-native-ingress.oraclecloud.com/defined-tags est une chaîne JSON, ce qui vous permet d'indiquer plusieurs espaces de noms de balise, clés de balise et valeurs de balise 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:
  ...

Si vous modifiez l'une des balises de l'annotation oci-native-ingress.oraclecloud.com/defined-tags du manifeste IngressClass, le contrôleur d'entrée natif OCI réapplique à l'équilibreur de charge toutes les balises définies spécifiées par l'annotation. Toutefois, si une balise définie contient une variable de balise, le contrôleur d'entrée natif OCI applique uniquement la balise définie à l'équilibreur de charge si la balise n'est pas déjà présente.

Pour permettre au contrôleur d'entrée natif OCI d'appliquer des balises définies à un équilibreur de charge, une stratégie IAM appropriée doit exister afin de permettre au contrôleur d'entrée natif OCI d'utiliser l'espace de noms de balise approprié. Pour plus d'informations, reportez-vous à :

• Octroi de droits d'accès au contrôleur d'entrée natif OCI en tant que programme autonome
• Octroi de droits d'accès au module complémentaire de cluster de contrôleurs d'entrée natifs OCI

Application de balises à format libre à l'équilibreur de charge

Les balises à format libre ne sont pas gérées par un administrateur de balises. Une balise à format libre se compose d'une clé et d'une valeur. Contrairement aux balises définies, les balises à format libre ne font pas partie d'un espace de noms de balise.

Pour indiquer que le contrôleur d'entrée natif OCI doit appliquer des balises à format libre à l'équilibreur de charge, utilisez l'annotation oci-native-ingress.oraclecloud.com/freeform-tags dans le manifeste IngressClass, au 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 de la balise à format libre à appliquer à l'équilibreur de charge.
• <tag-value> est la valeur de la balise à format 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 d'indiquer plusieurs clés de balise et valeurs de balise 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:
  ...

Si vous modifiez l'une des balises de l'annotation oci-native-ingress.oraclecloud.com/freeform-tags du manifeste IngressClass, le contrôleur d'entrée natif OCI réapplique à l'équilibreur de charge toutes les balises à format libre spécifiées par l'annotation.

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

Les valeurs de balise par défaut sont configurées pour un compartiment spécifique. Les valeurs de balise par défaut sont propres au compartiment. Les valeurs de balise par défaut indiquent les balises définies qui sont appliquées automatiquement à toutes les ressources créées dans un compartiment spécifique au moment de la création.

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

• Vous enlevez manuellement une valeur de balise par défaut qui a été automatiquement appliquée à un équilibreur de charge.
• Vous indiquez une valeur de balise par défaut en tant que balise définie, à l'aide de l'annotation oci-native-ingress.oraclecloud.com/defined-tags (dans ce cas, le contrôleur d'entrée natif OCI traite la valeur de balise par défaut comme toute autre balise définie).

Notez que les valeurs par défaut de balise avec des valeurs appliquées par l'utilisateur ne sont pas prises en charge. Si une valeur de balise par défaut avec une valeur appliquée par l'utilisateur a été configurée pour un compartiment dans lequel le contrôleur d'entrée 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 indiquer la valeur de balise par défaut en tant que balise définie.

Pour les équilibreurs de charge créés à l'aide d'une version de contrôleur d'entrée native OCI antérieure à la version 1.4.0, ou lorsque vous utilisez l'annotation oci-native-ingress.oraclecloud.com/id pour indiquer que le contrôleur d'entrée natif OCI doit gérer un équilibreur de charge existant, les valeurs de balise par défaut ne sont pas prises en charge. Dans les deux cas, pour appliquer ou conserver une valeur de balise par défaut, utilisez l'annotation oci-native-ingress.oraclecloud.com/defined-tags pour indiquer la valeur de balise par défaut en tant que balise définie.