Demander un certificat

Ce document décrit la procédure à suivre pour demander un certificat à l'aide de Certificate Authority Service (CAS).

Pour établir une communication sécurisée et de confiance dans votre environnement Google Distributed Cloud (GDC) isolé, demandez un certificat avec ou sans ACME au service Certificate Authority Service.

Ce document s'adresse aux membres du groupe d'opérateurs d'application, tels que les développeurs d'applications ou les data scientists, qui gèrent les cycles de vie des certificats dans leur projet. Pour en savoir plus, consultez la documentation sur les audiences pour GDC sous air gap.

Avant de commencer

Avant de pouvoir demander un certificat, vous devez demander les autorisations nécessaires et préparer votre environnement.

Demander des rôles IAM

Pour créer, afficher et supprimer des demandes de certificat, contactez l'administrateur de l'organisation IAM pour qu'il vous attribue le rôle Demandeur de certificat CA Service (certificate-authority-service-certificate-requester) dans l'espace de noms du projet de l'autorité de certification.

Préparer votre environnement

Demander un certificat à l'aide d'une autorité de certification avec le mode ACME activé

Si l'autorité de certification est hébergée en mode ACME, elle affiche l'URL du serveur ACME dans son état une fois qu'elle est prête.

Récupérez l'URL du serveur ACME de l'autorité de certification à partir de votre environnement Distributed Cloud :

kubectl get certificateauthorities CA_NAME -n USER_PROJECT_NAMESPACE -ojson | jq -r '.status.acme.uri'

Remplacez les éléments suivants :

  • CA_NAME : nom de l'autorité de certification, qui peut être une autorité de certification racine ou secondaire
  • USER_PROJECT_NAMESPACE : nom de l'espace de noms où se trouve le projet utilisateur

Demander un certificat à l'aide d'une autorité de certification avec le mode ACME désactivé

Pour créer une demande de certificat avec le mode ACME désactivé, vous devez créer et appliquer une ressource CertificateRequest à votre instance Distributed Cloud sous air gap. Pour ce faire, il existe deux moyens :

  • Créez un CertificateResource et incluez une CSR dans la ressource.
  • Créez un CertificateResource à l'aide d'une clé privée générée automatiquement par GDC et fournissez les configurations de certificat en tant que valeurs personnalisées.

Demander un certificat à l'aide d'une CSR

  1. Créez une ressource CertificateRequest et enregistrez-la dans un fichier YAML nommé cert-request.yaml. Utilisez votre clé privée pour créer une demande de signature de certificat (CSR) et l'ajouter à votre ressource.

    Vous pouvez éventuellement émettre le certificat avec un ensemble préconfiguré de paramètres X.509 en saisissant le nom du modèle dans le champ certificateTemplate.

    apiVersion: pki.security.gdc.goog/v1
kind: CertificateRequest
metadata:
  name: CERT_REQ_NAME
  namespace: USER_PROJECT_NAMESPACE
spec:
  certificateAuthorityRef:
    name: CA_NAME
    namespace: USER_PROJECT_NAMESPACE
  csr: CSR
  certificateTemplate: TEMPLATE_NAME
  signedCertificateSecret: SECRET_NAME
  notBefore: VALIDITY_START_TIME
  notAfter: VALIDITY_END_TIME
  subjectOverride: SUBJECT_OVERRIDE

    Remplacez les variables suivantes :

    Variable Description
    CERT_REQ_NAME Nom de la ressource CertificateRequest
    USER_PROJECT_NAMESPACE Nom de l'espace de noms où réside le projet utilisateur
    CA_NAME Nom de l'autorité de certification, qui peut être une autorité de certification racine ou subordonnée
    CSR la demande de signature de certificat à signer à l'aide de l'autorité de certification
    SECRET_NAME Nom du secret Kubernetes contenant la clé privée et le certificat CA signé

    Remplacez les variables facultatives suivantes :

    Variable Description
    TEMPLATE_NAME le nom du modèle de certificat prédéfini que vous souhaitez utiliser. Pour obtenir la liste des modèles disponibles et des détails sur les conflits, consultez Modèles de certificats prédéfinis.
    VALIDITY_START_TIME Heure à partir de laquelle le certificat est considéré comme valide. Cette valeur doit être au format YYYY-MM-DDTHH:MM:SSZ (par exemple, 2025-10-19T21:45:30Z). Si elle n'est pas définie, le certificat est valide dès sa délivrance.
    VALIDITY_END_TIME Heure d'expiration du certificat. Cette valeur doit être au format YYYY-MM-DDTHH:MM:SSZ (par exemple, 2026-01-17T18:25:40Z). Si elle n'est pas définie, le certificat expire 90 jours après son heure de début.
    SUBJECT_OVERRIDE un objet personnalisé à utiliser dans le certificat émis, en remplaçant les informations d'objet dans la CSR. Indiquez cette valeur en tant que sujet X.509 brut encodé en ASN.1 DER.

  2. Appliquez la ressource personnalisée à votre instance Distributed Cloud :

    kubectl apply -f cert-request.yaml --kubeconfig MANAGEMENT_API_SERVER_KUBECONFIG

    Remplacez MANAGEMENT_API_SERVER_KUBECONFIG par le chemin d'accès au fichier kubeconfig du serveur d'API Management.

  3. Vérifiez que la demande de certificat est prête :

    kubectl --kubeconfig MANAGEMENT_API_SERVER_KUBECONFIG -n USER_PROJECT_NAMESPACE get certificaterequest.pki.security.gdc.goog/CERT_REQ_NAME -ojson | jq -r ' .status.conditions[] | select( .type as $id | "Ready" | index($id))'

    Remplacez les éléments suivants :

    • MANAGEMENT_API_SERVER_KUBECONFIG : chemin d'accès au fichier kubeconfig du serveur de l'API Management.
    • USER_PROJECT_NAMESPACE : nom de l'espace de noms où se trouve le projet utilisateur
    • CERT_REQ_NAME : nom de la ressource CertificateRequest

    Le résultat ressemble à ce qui suit :

    {
  "lastTransitionTime": "2025-01-27T12:22:59Z",
  "message": "Certificate is issued",
  "observedGeneration": 1,
  "reason": "Issued",
  "status": "True",
  "type": "Ready"
}

  4. Obtenez le nom du secret du certificat :

    kubectl --kubeconfig MANAGEMENT_API_SERVER_KUBECONFIG -n USER_PROJECT_NAMESPACE get certificaterequest.pki.security.gdc.goog/CERT_REQ_NAME -ojson | jq -r '.spec.signedCertificateSecret'

    Remplacez les éléments suivants :

    • MANAGEMENT_API_SERVER_KUBECONFIG : chemin d'accès au fichier kubeconfig du serveur de l'API Management.
    • USER_PROJECT_NAMESPACE : nom de l'espace de noms où se trouve le projet utilisateur
    • CERT_REQ_NAME : nom de la ressource CertificateRequest

    Le résultat affiche le SECRET_NAME contenant le certificat signé :

    test-jwk-1

Demander un certificat à l'aide d'une clé générée automatiquement

  1. Créez une ressource CertificateRequest et enregistrez-la dans un fichier YAML nommé cert-request.yaml. Renseignez les valeurs choisies pour le certificat.

    Vous pouvez éventuellement émettre le certificat avec un ensemble préconfiguré de paramètres X.509 en saisissant le nom du modèle dans le champ certificateTemplate.

    apiVersion: pki.security.gdc.goog/v1
kind: CertificateRequest
metadata:
  name: CERT_REQ_NAME
  namespace: USER_PROJECT_NAMESPACE
spec:
  certificateAuthorityRef:
    name: CA_NAME
    namespace: USER_PROJECT_NAMESPACE
  certificateConfig:
    subjectConfig:
      commonName: COMMON_NAME
      organization: ORGANIZATION
      locality: LOCALITY
      state: STATE
      country: COUNTRY
      dnsNames:
      - DNS_NAMES
      ipAddresses:
      - IP_ADDRESSES
      rfc822Names:
      - RFC822NAMES
      uris:
      - URIS
  certificateTemplate: TEMPLATE_NAME
  signedCertificateSecret: SECRET_NAME
  notBefore: VALIDITY_START_TIME
  notAfter: VALIDITY_END_TIME
  subjectOverride: SUBJECT_OVERRIDE

    Remplacez les variables suivantes :

    Variable Description
    CERT_REQ_NAME Nom de la ressource CertificateRequest
    USER_PROJECT_NAMESPACE Nom de l'espace de noms où réside le projet utilisateur
    CA_NAME Nom de l'autorité de certification, qui peut être une autorité de certification racine ou subordonnée
    SECRET_NAME Nom du secret Kubernetes contenant la clé privée et le certificat CA signé

    Remplacez les variables facultatives suivantes. Vous devez inclure au moins l'un des champs du bloc spec.certificateConfig.subjectConfig de la ressource CertificateRequest :

    Variable Description
    COMMON_NAME le nom commun du certificat
    ORGANIZATION organisation à utiliser sur le certificat
    LOCALITY Localité du certificat
    STATE État ou province à utiliser sur le certificat
    COUNTRY le pays du certificat ;
    DNS_NAMES Liste des dNSName subjectAltNames à définir sur le certificat
    IP_ADDRESS Liste des ipAddress subjectAltNames à définir sur le certificat
    RFC822_NAMES Liste des rfc822Name subjectAltNames à définir sur le certificat
    URIS Une liste de uniformResourceIdentifier subjectAltNames à définir sur le certificat
    TEMPLATE_NAME le nom du modèle de certificat prédéfini que vous souhaitez utiliser. Pour obtenir la liste des modèles disponibles et des détails sur les conflits, consultez Modèles de certificats prédéfinis.
    VALIDITY_START_TIME Heure à partir de laquelle le certificat est considéré comme valide. Cette valeur doit être au format YYYY-MM-DDTHH:MM:SSZ (par exemple, 2025-10-19T21:45:30Z). Si elle n'est pas définie, le certificat est valide dès sa délivrance.
    VALIDITY_END_TIME Heure d'expiration du certificat. Cette valeur doit être au format YYYY-MM-DDTHH:MM:SSZ (par exemple, 2026-01-17T18:25:40Z). Si elle n'est pas définie, le certificat expire 90 jours après son heure de début.
    SUBJECT_OVERRIDE un objet personnalisé à utiliser dans le certificat émis, en remplaçant les informations d'objet dans la CSR. Indiquez cette valeur en tant que sujet X.509 brut encodé en ASN.1 DER.

  2. Appliquez la ressource personnalisée à votre instance Distributed Cloud :

    kubectl apply -f cert-request.yaml --kubeconfig MANAGEMENT_API_SERVER_KUBECONFIG

    Remplacez MANAGEMENT_API_SERVER_KUBECONFIG par le chemin d'accès au fichier kubeconfig du serveur d'API Management.

  3. Vérifiez que la demande de certificat est prête :

    kubectl --kubeconfig MANAGEMENT_API_SERVER_KUBECONFIG -n USER_PROJECT_NAMESPACE get certificaterequest.pki.security.gdc.goog/CERT_REQ_NAME -ojson | jq -r ' .status.conditions[] | select( .type as $id | "Ready" | index($id))'

    Remplacez les éléments suivants :

    • MANAGEMENT_API_SERVER_KUBECONFIG : chemin d'accès au fichier kubeconfig du serveur de l'API Management.
    • USER_PROJECT_NAMESPACE : nom de l'espace de noms où se trouve le projet utilisateur
    • CERT_REQ_NAME : nom de la ressource CertificateRequest

    Le résultat ressemble à ce qui suit :

    {
  "lastTransitionTime": "2025-01-27T12:22:59Z",
  "message": "Certificate is issued",
  "observedGeneration": 1,
  "reason": "Issued",
  "status": "True",
  "type": "Ready"
}

  4. Obtenez le nom du secret du certificat :

    kubectl --kubeconfig MANAGEMENT_API_SERVER_KUBECONFIG -n USER_PROJECT_NAMESPACE get certificaterequest.pki.security.gdc.goog/CERT_REQ_NAME -ojson | jq -r '.spec.signedCertificateSecret'

    Remplacez les éléments suivants :

    • MANAGEMENT_API_SERVER_KUBECONFIG : chemin d'accès au fichier kubeconfig du serveur de l'API Management.
    • USER_PROJECT_NAMESPACE : nom de l'espace de noms où se trouve le projet utilisateur
    • CERT_REQ_NAME : nom de la ressource CertificateRequest.

    Le résultat affiche le SECRET_NAME contenant le certificat signé :

    test-jwk-1

Lister les demandes de certificat

Utilisez le paramètre certificaterequests pour lister toutes les ressources CertificateRequest :

kubectl --kubeconfig MANAGEMENT_API_SERVER_KUBECONFIG -n USER_PROJECT_NAMESPACE get certificaterequest.pki.security.gdc.goog

Remplacez les éléments suivants :

  • MANAGEMENT_API_SERVER_KUBECONFIG : chemin d'accès au fichier kubeconfig du serveur de l'API Management.
  • USER_PROJECT_NAMESPACE : nom de l'espace de noms où se trouve le projet utilisateur

Voici un exemple de commande utilisant l'espace de noms agtest-project :

kubectl --kubeconfig /root/release/root-admin/root-admin-kubeconfig  -n agtest-project get certificaterequest.pki.security.gdc.goog

Le résultat ressemble à ce qui suit :

NAME                                               READY   AGE
test-externalca-subca-cert-req-with-csr            True    17h
test-externalca-subca-cert-req-with-csr-override   True    17h

Supprimer un certificat

Pour supprimer un certificat, vous devez supprimer la ressource personnalisée CertificateRequest correspondante. Cette action supprime la ressource de la base de données CAS.

  1. Recherchez le nom de l'CertificateRequest que vous souhaitez supprimer. Vous pouvez lister les demandes de certificat pour trouver le nom.

  2. Supprimez la ressource CertificateRequest :

    kubectl --kubeconfig  MANAGEMENT_API_SERVER_KUBECONFIG -n USER_PROJECT_NAMESPACE delete certificaterequest.pki.security.gdc.goog/CERT_REQ_NAME

    Remplacez les éléments suivants :

    • MANAGEMENT_API_SERVER_KUBECONFIG : chemin d'accès au fichier kubeconfig du serveur de l'API Management.
    • USER_PROJECT_NAMESPACE : nom de l'espace de noms où se trouve le projet utilisateur
    • CERT_REQ_NAME : nom de la ressource CertificateRequest.

Limites et nettoyage des demandes de certificat

Pour maintenir la stabilité du système et éviter une utilisation élevée des ressources, CAS applique des limites au nombre de ressources personnalisées CertificateRequest et propose une fonctionnalité de nettoyage automatisé facultative.

Quota de demandes de certificat

CAS applique un quota sur le nombre de ressources personnalisées CertificateRequest par organisation, avec une limite par défaut de 5 000. Le dépassement de cette limite peut dégrader les performances du CAS et du serveur d'API Management.

Lorsque le nombre total de ressources CertificateRequest approche du quota (par exemple, à 80% et 90% de la limite), des avertissements s'affichent dans le résultat de la commande lorsque vous créez des requêtes. Si vous essayez de créer un CertificateRequest après avoir atteint le quota, la requête est refusée. Un message d'erreur semblable à celui-ci peut s'afficher :

Error from server (Forbidden): error when creating "cert-request.yaml":
admission webhook "certificaterequests.pki.security.gdc.goog" denied the
request: the number of certificate requests has exceeded the per organization
limit of {LIMIT}. Please refer to the guide PLATAUTH-G2102 for troubleshooting
this issue

Si vous rencontrez cette erreur, vous devrez peut-être supprimer les anciennes ressources CertificateRequest ou celles qui ne sont pas nécessaires. Pour ajuster le quota, contactez un membre du groupe d'opérateurs d'infrastructure de votre organisation. Ils peuvent remplacer le quota en suivant les instructions du runbook PLATAUTH-G2102.

Nettoyage automatisé

Vous pouvez activer le nettoyage automatique pour supprimer les ressources CertificateRequest arrivées à expiration. Cette fonctionnalité permet de libérer des ressources en les supprimant après un délai de grâce configurable. Le délai de grâce définit la durée entre l'expiration d'un certificat et la suppression de la ressource CertificateRequest.

Le nettoyage automatique est désactivé par défaut. Un membre du groupe d'opérateurs d'infrastructure de votre organisation peut activer cette fonctionnalité et configurer le délai de grâce en suivant les instructions du runbook PLATAUTH-G2103. La fonctionnalité reste désactivée si le délai de grâce n'est pas défini ou s'il est défini sur zéro.