Utiliser des certificats SSL gérés par Google

Cette page explique comment utiliser les objets Ingress pour créer des équilibreurs de charge externes avec des certificats SSL gérés par Google. Ces certificats sont des certificats de validation de domaine (DV) que Google provisionne, renouvelle et gère pour vos noms de domaine. Ces certificats ne représentent pas votre identité personnelle ou celle de votre organisation.

Pour savoir comment créer des certificats gérés par Google avec Google Cloud, consultez la page sur les certificats gérés par Google.

Les certificats SSL gérés par Google pour GKE sont compatibles avec les clusters publics et privés.

Versions d'API

Vous configurez des certificats SSL gérés par Google à l'aide d'une ressource personnalisée ManagedCertificate disponible dans différentes versions d'API, en fonction de la version de votre cluster Google Kubernetes Engine (GKE) :

  • L'API ManagedCertificate v1beta2 est disponible dans GKE 1.15 et versions ultérieures.
  • L'API v1 ManagedCertificate est disponible dans GKE 1.17.9-gke.6300 et versions ultérieures.

Bien que les clusters GKE soient actuellement compatibles avec l'API ManagedCertificate v1beta1, cette version de l'API est obsolète et sera supprimée dans les prochaines versions de GKE. Nous vous recommandons d'utiliser une version plus récente de l'API.

Migrer entre les versions d'API

Les objets ManagedCertificate sont automatiquement promus à une version plus récente de l'API lorsqu'ils sont mis à jour dans un cluster compatible avec cette version. Les ressources sont régulièrement mises à jour. Vous n'avez donc rien à faire pour effectuer leur migration.

Créer un objet Ingress avec un certificat géré par Google

Pour configurer un certificat SSL géré par Google et l'associer à un objet Ingress, procédez comme suit :

  • Créez un objet ManagedCertificate dans le même espace de noms que l'objet Ingress.
  • Associez l'objet ManagedCertificate à une entrée en ajoutant l'annotation networking.gke.io/managed-certificates à l'entrée. Cette annotation est une liste d'objets ManagedCertificate séparés par une virgule.

Limites

Les certificats gérés par Google sont moins flexibles que ceux que vous obtenez et gérez vous-même. Les certificats gérés par Google acceptent jusqu'à 100 domaines ne comportant pas de caractères génériques. Contrairement aux certificats autogérés, les certificats gérés par Google ne sont pas compatibles avec les domaines génériques.

Si vous avez besoin de certificats autogérés ou si vous possédez déjà des certificats SSL que vous souhaitez configurer sur votre objet Ingress, consultez la section Configurer HTTPS (TLS) entre le client et l’équilibreur de charge.

Le nombre et le type des certificats compatibles avec un objet Ingress sont définis par les limites des certificats SSL gérés par Google.

Les mises à jour des certificats gérés par Google ne sont pas acceptées.

Pour effectuer des modifications manuelles avec un temps d'arrêt minimal, consultez la section Mettre à jour manuellement un certificat géré par Google.

Prérequis

  • Vous devez détenir le nom de domaine. Celui-ci ne doit pas dépasser 63 caractères. Vous pouvez utiliser Google Domains ou un autre service d'enregistrement.
  • La valeur de "kubernetes.io/ingress.class" doit être "gce".
  • Créez une adresse IP externe réservée (statique). La réservation d'une adresse IP statique garantit que celle-ci restera en votre possession même si vous supprimez l'objet Ingress. En l'absence de réservation, l'adresse IP pourrait changer, vous obligeant alors à reconfigurer les enregistrements DNS de votre domaine. Utilisez l'outil de ligne de commande gcloud ou Cloud Console pour créer une adresse IP réservée.

    gcloud

    Pour créer une adresse IP réservée, exécutez la commande suivante :

    gcloud compute addresses create ADDRESS_NAME --global
    

    Remplacez ADDRESS_NAME par le nom de l'adresse IP réservée que vous créez.

    Pour trouver l'adresse IP statique que vous avez créée, exécutez la commande suivante :

    gcloud compute addresses describe ADDRESS_NAME --global
    

    Le résultat ressemble à ce qui suit :

    address: 203.0.113.32
    ...
    

    Console

    Pour créer une adresse IP réservée, procédez comme suit :

    1. Accédez à la page Adresses IP externes dans Cloud Console.

      Accéder à la page "Adresses IP externes"

    2. Indiquez un nom pour l'adresse IP (par exemple, example-ip-address).

    3. Indiquez si vous souhaitez obtenir une adresse IPv4 ou IPv6.

    4. Sélectionnez l'option Global pour Type.

    5. Cliquez sur Réserver. L'adresse IP s'affiche dans la colonne Adresse externe.

    Config Connector

    Remarque : Cette étape nécessite Config Connector. Suivez les instructions d'installation pour l'installer sur votre cluster.

    apiVersion: compute.cnrm.cloud.google.com/v1beta1
    kind: ComputeAddress
    metadata:
      name: example-ip-address
    spec:
      location: global
    Pour déployer ce manifeste, téléchargez le fichier sur votre ordinateur sous le nom compute-address.yaml, puis exécutez la commande suivante :

    kubectl apply -f compute-address.yaml
    

Configurer un certificat géré par Google

  1. Créer un objet ManagedCertificate. Cette ressource spécifie les domaines du certificat SSL. Les domaines avec des caractères génériques ne sont pas acceptés.

    Le fichier manifeste suivant décrit un objet ManagedCertificate. Enregistrez le manifeste sous le nom managed-cert.yaml.

    apiVersion: networking.gke.io/v1
    kind: ManagedCertificate
    metadata:
      name: managed-cert
    spec:
      domains:
        - DOMAIN_NAME1
        - DOMAIN_NAME2
    

    Remplacez les éléments suivants :

    • DOMAIN_NAME1 et DOMAIN_NAME2 : des noms de domaine que vous possédez. Par exemple, example.com et www.example.com.
  2. Appliquez le fichier manifeste à votre cluster :

    kubectl apply -f managed-cert.yaml
    
  3. Créez un service de type NodePort pour exposer votre application à Internet.

    Le fichier manifeste suivant décrit un service de type NodePort. Enregistrez le manifeste sous le nom mc-service.yaml.

    apiVersion: v1
    kind: Service
    metadata:
      name: mc-service
    spec:
      selector:
        app: mc-service
      type: NodePort
      ports:
        - protocol: TCP
          port: 80
          targetPort: 8080
    
  4. Appliquez le fichier manifeste à votre cluster :

    kubectl apply -f mc-service.yaml
    
  5. Créez une ressource Ingress.

    Le fichier manifeste suivant décrit un objet Ingress qui utilise la ressource ManagedCertificate que vous avez créée. Enregistrez le manifeste sous le nom managed-cert-ingress.yaml.

    apiVersion: networking.k8s.io/v1
    kind: Ingress
    metadata:
      name: managed-cert-ingress
      annotations:
        kubernetes.io/ingress.global-static-ip-name: ADDRESS_NAME
        networking.gke.io/managed-certificates: managed-cert
        kubernetes.io/ingress.class: "gce"
    spec:
      defaultBackend:
        service:
          name: mc-service
          port:
            number: SERVICE_PORT
    

    Remplacez les éléments suivants :

    • ADDRESS_NAME est le nom de votre adresse IP réservée.
    • SERVICE_PORT est la valeur de ports.port dans votre fichier manifeste de service.
  6. Appliquez le fichier manifeste à votre cluster :

    kubectl apply -f managed-cert-ingress.yaml
    
  7. Obtenez l'adresse IP de l'équilibreur de charge :

    kubectl get ingress
    

    Le résultat ressemble à ce qui suit :

    NAME              HOSTS     ADDRESS         PORTS     AGE
    example-ingress   *         203.0.113.32     80       54s
    

    L'adresse IP de l'équilibreur de charge est affichée dans la colonne ADDRESS. Si vous utilisez une adresse IP statique réservée, elle servira d'adresse à l'équilibreur de charge.

    Si l'adresse ne figure pas dans la liste, attendez la fin de la configuration de l'entrée.

  8. Configurez les enregistrements DNS de vos domaines pour qu'ils pointent vers l'adresse IP de l'équilibreur de charge. Si vous utilisez Cloud DNS, consultez la section Gérer les enregistrements pour plus d'informations.

  9. Attendez que le certificat géré par Google soit provisionné. Cette opération peut prendre jusqu'à 60 minutes. Vous pouvez vérifier l'état du certificat à l'aide de la commande suivante :

    kubectl describe managedcertificate managed-cert
    

    Le résultat ressemble à ce qui suit :

    Name:         managed-cert
    Namespace:    default
    Labels:       <none>
    Annotations:  <none>
    API Version:  networking.gke.io/v1
    Kind:         ManagedCertificate
    (...)
    Spec:
     Domains:
       DOMAIN_NAME1
       DOMAIN_NAME2
    Status:
     CertificateStatus: Active
    (...)
    

    La valeur du champ Status.CertificateStatus indique que le certificat est provisionné. Si Status.CertificateStatus n'est pas Active, le certificat n'est pas encore provisionné.

  10. Vérifiez que le protocole SSL fonctionne en accédant à vos domaines à l'aide du préfixe https://. Votre navigateur vous indique que la connexion est sécurisée et que vous pouvez afficher les détails du certificat.

Passer de certificats autogérés à des certificats gérés par Google

Lorsque vous migrez une entrée pour qu'elle utilise des certificats SSL gérés par Google au lieu de certificats SSL autogérés, ne supprimez pas vos certificats SSL autogérés avant que ceux gérés par Google soient actifs. Ces derniers deviennent automatiquement actifs une fois provisionnés. Lorsque les certificats SSL gérés par Google sont actifs, vous pouvez supprimer vos certificats SSL autogérés.

Suivez la procédure suivante pour passer de certificats SSL autogérés à des certificats SSL gérés par Google :

  1. Ajoutez un nouveau certificat géré par Google à l'entrée, comme décrit dans la section Configurer un certificat géré par Google.
  2. Attendez que l'état du certificat géré par Google devienne "Actif". Vérifiez l'état du certificat à l'aide de la commande suivante :

    kubectl describe managedcertificate managed-cert
    
  3. Une fois que l'état est défini sur Active, mettez à jour l'objet Ingress pour supprimer les références au certificat autogéré.

Supprimer un certificat géré par Google

Pour supprimer un certificat géré par Google de votre cluster, vous devez supprimer l'objet ManagedCertificate ainsi que l'annotation de l'objet Ingress qui y fait référence.

  1. Supprimez l'objet ManagedCertificate :

    kubectl delete -f managed-cert.yaml
    

    Le résultat ressemble à ce qui suit :

    managedcertificate.networking.gke.io "managed-cert" deleted
    
  2. Supprimez l'annotation de l'entrée :

    kubectl annotate ingress managed-cert-ingress networking.gke.io/managed-certificates-
    

    Vous remarquerez le signe moins, -, à la fin de la commande.

  3. Libérez l'adresse IP statique que vous avez réservée pour votre équilibreur de charge.

    Vous pouvez utiliser l'outil de ligne de commande gcloud, Cloud Console ou Config Connector pour libérer une adresse IP réservée.

    gcloud

    Utilisez la commande suivante pour libérer l'adresse IP réservée :

    gcloud compute addresses delete ADDRESS_NAME --global
    

    Remplacez ADDRESS_NAME par le nom de l'adresse IP.

    Console

    Pour libérer l'adresse IP réservée, procédez comme suit :

    1. Accédez à la page Adresses IP externes dans Cloud Console.

      Accéder à la page "Adresses IP externes"

    2. Cochez la case en regard de l'adresse IP que vous souhaitez libérer.

    3. Cliquez sur Libérer l'adresse IP.

    Config Connector

    Remarque : Cette étape nécessite Config Connector. Suivez les instructions d'installation pour l'installer sur votre cluster.

    apiVersion: compute.cnrm.cloud.google.com/v1beta1
    kind: ComputeAddress
    metadata:
      name: example-ip-address
    spec:
      location: global

    Pour déployer ce manifeste, téléchargez le fichier sur votre ordinateur sous le nom compute-address.yaml, puis exécutez la commande suivante :

    kubectl delete -f compute-address.yaml
    

Dépannage

Cette section explique comment résoudre les problèmes liés aux certificats gérés par Google.

Vérifier les événements sur les ressources ManagedCertificate et Ingress

Si vous dépassez le nombre de certificats autorisés, un événement avec le motif TooManyCertificates est ajouté à ManagedCertificate. Vous pouvez vérifier les événements d'un objet ManagedCertificate à l'aide de la commande suivante :

kubectl describe managedcertificate CERTIFICATE_NAME

Remplacez CERTIFICATE_NAME par le nom de votre ManagedCertificate.

Si vous associez un ManagedCertificate v1 non existant à un objet Ingress, un événement avec le motif MissingCertificate est ajouté à l'objet Ingress. Vous pouvez vérifier les événements d'une ressource Ingress à l'aide de la commande suivante :

kubectl describe ingress INGRESS_NAME

Remplacez INGRESS_NAME par le nom de votre ressource Ingress.

Certificat géré non provisionné lorsque le domaine est associé aux adresses IP de plusieurs équilibreurs de charge

Lorsque votre domaine est associé aux adresses IP de plusieurs équilibreurs de charge (plusieurs objets Ingress), vous devez créer un seul objet ManagedCertificate et l'associer à tous les objets Ingress. Si vous créez plusieurs objets ManagedCertificate et que vous associez chacun d'entre eux à un objet Ingress distinct, l'autorité de certification risque de ne pas pouvoir valider la propriété de votre domaine et certains de vos certificats risquent de ne pas être provisionnés. Pour que la validation aboutisse, le certificat doit être visible sous toutes les adresses IP auxquelles votre domaine est associé.

En particulier, lorsque votre domaine est associé à une adresse IPv4 et une adresse IPv6 configurées avec différents objets Ingress, vous devez créer un seul objet ManagedCertificate et l'associer aux deux objets Ingress.

Perturbations de la communication entre les certificats gérés par Google et l'objet Ingress

Les certificats gérés communiquent avec l'objet Ingress à l'aide de l'annotation kubernetes.io/pre-shared-cert. Vous pouvez perturber cette communication, par exemple si vous :

  • exécutez un processus automatisé supprimant l'annotation kubernetes.io/pre-shared-cert ;
  • stockez un instantané de l'objet Ingress, puis le supprimez et restaurez à partir de l'instantané. Dans l'intervalle, la ressource SslCertificate répertoriée dans l'annotation pre-shared-cert peut avoir été supprimée. L'entrée ne fonctionne pas si des certificats associés sont manquants.

Si la communication entre des certificats gérés par Google et l'objet Ingress est interrompue, supprimez le contenu de l'annotation kubernetes.io/pre-shared-cert et attendez que le système effectue le rapprochement. Pour éviter que le problème ne se reproduise, assurez-vous que l'annotation n'est pas modifiée ni supprimée par inadvertance.

Erreurs de validation lors de la création d'un certificat géré par Google

Les définitions ManagedCertificate sont validées avant la création de l'objet ManagedCertificate. Si la validation échoue, l'objet ManagedCertificate n'est pas créé et un message d'erreur apparaît. Vous trouverez ci-dessous les différents messages d'erreur ainsi que les raisons pour lesquelles ils apparaissent :

spec.domains in body should have at most 100 items

Votre fichier manifeste ManagedCertificate regroupe plus de 100 domaines dans le champ spec.domains. Les certificats gérés par Google n'acceptent que 100 domaines au maximum.

spec.domains in body should match '^(([a-zA-Z0-9]+|[a-zA-Z0-9][-a-zA-Z0-9]*[a-zA-Z0-9])\.)+[a-zA-Z][-a-zA-Z0-9]*[a-zA-Z0-9]\.?$'

Vous avez spécifié un nom de domaine non valide ou un nom de domaine avec des caractères génériques dans le champ spec.domains. L'objet ManagedCertificate n'est pas compatible avec les domaines comportant des caractères génériques (par exemple, *.example.com).

spec.domains in body should be at most 63 chars long

Vous avez spécifié un nom de domaine trop long. Les certificats gérés par Google n'acceptent pas les noms de domaine dépassant 63 caractères.

Mettre à jour manuellement un certificat géré par Google

Pour mettre à jour manuellement le certificat afin que le certificat de l'ancien domaine continue de fonctionner jusqu'à ce que le certificat du nouveau domaine soit provisionné, procédez comme suit :

  1. Créez un certificat ManagedCertificate pour le nouveau domaine.
  2. Associez le certificat ManagedCertificate à l'objet Ingress sans supprimer l'ancien certificat.
  3. Attendez que le certificat ManagedCertificate devienne actif.
  4. Dissociez l'ancien certificat de l'objet Ingress et supprimez-le.

Lorsque vous créez un certificat ManagedCertificate, Google Cloud crée un certificat SSL géré par Google. Vous ne pouvez pas mettre à jour ce certificat. Si vous mettez à jour ManagedCertificate, Google Cloud supprime et recrée le certificat SSL géré par Google.

Étape suivante