Demander un certificat

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

Pour établir la confiance et sécuriser la communication dans votre Google Distributed Cloud (GDC) sous air gap, demandez un certificat ACME activé ou désactivé au service Certificate Authority Service.

Ce document est destiné aux audiences du groupe d'opérateurs d'application, telles 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 IAM de votre organisation afin qu'il vous attribue le rôle Demandeur de certificat du service d'autorité de certification (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 génère 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 dans 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 subordonnée
  • USER_PROJECT_NAMESPACE: nom de l'espace de noms dans lequel réside 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 une CertificateResource et incluez une requête de signature de certificat dans la ressource.
  • Créez une 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 requête de signature de certificat

  1. Créez une ressource CertificateRequest et enregistrez-la en tant que fichier YAML nommé cert-request.yaml. Utilisez votre clé privée pour créer une requête de signature de certificat et ajoutez-la à votre ressource.

    Si vous le souhaitez, vous pouvez é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 dans lequel 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 Requête 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 Nom du modèle de certificat prédéfini que vous souhaitez utiliser. Pour obtenir la liste des modèles disponibles et des informations 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 immédiatement après son émission.
    VALIDITY_END_TIME Heure à laquelle le certificat expire. 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 Objet personnalisé à utiliser dans le certificat émis, remplaçant les informations d'objet de la requête de signature de certificat. Fournissez cette valeur en tant qu'objet X.509 brut encodé au format 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 d'API Management
    • USER_PROJECT_NAMESPACE: nom de l'espace de noms dans lequel réside 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 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 d'API Management
    • USER_PROJECT_NAMESPACE: nom de l'espace de noms dans lequel réside 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 en tant que fichier YAML nommé cert-request.yaml. Renseignez les valeurs choisies pour le certificat.

    Si vous le souhaitez, vous pouvez é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 dans lequel 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 Nom commun du certificat
    ORGANIZATION Organisation à utiliser sur le certificat
    LOCALITY Localité du certificat
    STATE État ou province à utiliser sur le certificat
    COUNTRY 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 Liste des uniformResourceIdentifier subjectAltNames à définir sur le certificat
    TEMPLATE_NAME Nom du modèle de certificat prédéfini que vous souhaitez utiliser. Pour obtenir la liste des modèles disponibles et des informations 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 immédiatement après son émission.
    VALIDITY_END_TIME Heure à laquelle le certificat expire. 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 Objet personnalisé à utiliser dans le certificat émis, remplaçant les informations d'objet de la requête de signature de certificat. Fournissez cette valeur en tant qu'objet X.509 brut encodé au format 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 d'API Management
    • USER_PROJECT_NAMESPACE: nom de l'espace de noms dans lequel réside 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 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 d'API Management
    • USER_PROJECT_NAMESPACE: nom de l'espace de noms dans lequel réside 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 d'API Management
  • USER_PROJECT_NAMESPACE: nom de l'espace de noms dans lequel réside le projet utilisateur

L'exemple suivant montre une 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 du service d'autorité de certification.

  1. Recherchez le nom de la CertificateRequest que vous souhaitez supprimer. Vous pouvez lister les demandes de certificat pour vous aider à 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 d'API Management
    • USER_PROJECT_NAMESPACE: nom de l'espace de noms dans lequel réside le projet utilisateur
    • CERT_REQ_NAME : nom de la ressource CertificateRequest

Limites et nettoyage des demandes de certificat

Pour assurer la stabilité du système et éviter une utilisation élevée des ressources, le service d'autorité de certification applique des limites au nombre de ressources personnalisées CertificateRequest et propose une fonctionnalité de nettoyage automatique facultative.

Quota de demandes de certificat

Le service d'autorité de certification applique un quota au 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 service d'autorité de certification et du serveur d'API de gestion.

Lorsque le nombre total de ressources CertificateRequest approche le quota (par exemple, à 80% et 90% de la limite), des avertissements s'affichent dans la sortie de la commande lorsque vous créez des demandes. Si vous tentez de créer une CertificateRequest une fois le quota atteint, la demande 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 cette erreur se produit, vous devrez peut-être supprimer les ressources CertificateRequest anciennes ou inutiles. Pour ajuster le quota, contactez un membre du groupe d'opérateurs d'infrastructure de votre organisation. Il peut remplacer le quota en suivant les instructions du runbook PLATAUTH-G2102.

Nettoyage automatique

Vous pouvez activer le nettoyage automatique pour supprimer les ressources CertificateRequest expirées. 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 est défini sur zéro.