Zertifikat anfordern

In diesem Dokument werden die Schritte zum Anfordern eines Zertifikats mit dem Certificate Authority Service (CAS) beschrieben.

Wenn Sie Vertrauen aufbauen und die Kommunikation in Ihrer Google Distributed Cloud (GDC) mit Air Gap sichern möchten, fordern Sie ein ACME-aktiviertes oder ‑deaktiviertes Zertifikat vom Certificate Authority Service an.

Dieses Dokument richtet sich an Zielgruppen in der Gruppe der Anwendungsoperatoren, z. B. Anwendungsentwickler oder Data Scientists, die Zertifikatslebenszyklen in ihrem Projekt verwalten. Weitere Informationen finden Sie unter Dokumentation zu Zielgruppen für GDC mit Air Gap.

Hinweis

Bevor Sie ein Zertifikat anfordern können, müssen Sie die erforderlichen Berechtigungen anfordern und Ihre Umgebung vorbereiten.

IAM-Rollen anfordern

Wenn Sie Zertifikatanfragen erstellen, ansehen und löschen möchten, bitten Sie Ihren IAM-Administrator der Organisation, Ihnen die Rolle CA Service Certificate Requester (certificate-authority-service-certificate-requester) im Projektnamespace der Zertifizierungsstelle zuzuweisen.

Umgebung vorbereiten

Zertifikat mit aktivierter ACME-Funktion von der Zertifizierungsstelle anfordern

Wenn die Zertifizierungsstelle im ACME-Modus gehostet wird, gibt sie die ACME-Server-URL in ihrem Status aus, nachdem sie bereit ist.

Rufen Sie die ACME-Server-URL der Zertifizierungsstelle aus Ihrer Distributed Cloud-Umgebung ab:

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

Ersetzen Sie Folgendes:

  • CA_NAME: der Name der Zertifizierungsstelle, die eine Stamm- oder untergeordnete Zertifizierungsstelle sein kann
  • USER_PROJECT_NAMESPACE: der Name des Namespaces, in dem sich das Nutzerprojekt befindet

Zertifikat mit deaktivierter ACME-Funktion von der Zertifizierungsstelle anfordern

Wenn Sie eine Zertifikatanfrage mit deaktivierter ACME-Funktion erstellen möchten, müssen Sie eine CertificateRequest-Ressource erstellen und auf Ihre Distributed Cloud-Instanz mit Air Gap anwenden. Dazu gibt es zwei mögliche Vorgehensweisen:

  • Erstellen Sie eine CertificateResource und fügen Sie der Ressource eine CSR hinzu.
  • Erstellen Sie eine CertificateResource mit einem automatisch generierten privaten GDC-Schlüssel und geben Sie die Zertifikatkonfigurationen als benutzerdefinierte Werte an.

Zertifikat mit einer CSR anfordern

  1. Erstellen Sie eine CertificateRequest-Ressource und speichern Sie sie als YAML-Datei mit dem Namen cert-request.yaml. Erstellen Sie mit Ihrem privaten Schlüssel eine Zertifikatsignierungsanfrage (Certificate Signing Request, CSR) und fügen Sie sie Ihrer Ressource hinzu.

    Optional können Sie das Zertifikat mit einem vorkonfigurierten Satz von X.509-Parametern ausstellen, indem Sie den Namen der Vorlage in das Feld certificateTemplate eingeben.

    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

    Ersetzen Sie die folgenden Variablen:

    Variable Beschreibung
    CERT_REQ_NAME der Name der CertificateRequest-Ressource
    USER_PROJECT_NAMESPACE der Name des Namespaces, in dem sich das Nutzerprojekt befindet
    CA_NAME der Name der Zertifizierungsstelle, die eine Stamm- oder untergeordnete Zertifizierungsstelle sein kann
    CSR die Zertifikatsignierungsanfrage, die mit der Zertifizierungsstelle signiert werden soll
    SECRET_NAME der Name des Kubernetes-Secrets, das den privaten Schlüssel und signierte CA-Zertifikat enthält

    Ersetzen Sie die folgenden optionalen Variablen:

    Variable Beschreibung
    TEMPLATE_NAME der Name der vordefinierten Zertifikatvorlage, die Sie verwenden möchten. Eine Liste der verfügbaren Vorlagen und Details zu Konflikten finden Sie unter Vordefinierte Zertifikatvorlagen.
    VALIDITY_START_TIME der Zeitpunkt, ab dem das Zertifikat gültig ist. Dieser Wert muss das Format YYYY-MM-DDTHH:MM:SSZ haben (z. B. 2025-10-19T21:45:30Z). Wenn er nicht festgelegt ist, ist das Zertifikat sofort nach der Ausstellung gültig .
    VALIDITY_END_TIME der Zeitpunkt, zu dem das Zertifikat abläuft. Dieser Wert muss das Format YYYY-MM-DDTHH:MM:SSZ haben (z. B. 2026-01-17T18:25:40Z). Wenn er nicht festgelegt ist, läuft das Zertifikat 90 Tage nach dem Startzeitpunkt ab.
    SUBJECT_OVERRIDE ein benutzerdefiniertes Subjekt, das im ausgestellten Zertifikat verwendet werden soll und die Subjektinformationen in der CSR überschreibt. Geben Sie diesen Wert als rohes, ASN.1 DER-codiertes X.509-Subjekt an.

  2. Wenden Sie die benutzerdefinierte Ressource auf Ihre Distributed Cloud-Instanz an:

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

    Ersetzen Sie MANAGEMENT_API_SERVER_KUBECONFIG durch den Pfad zur kubeconfig-Datei des Management API-Servers.

  3. Prüfen Sie, ob die Zertifikatanfrage bereit ist:

    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))'

    Ersetzen Sie Folgendes:

    • MANAGEMENT_API_SERVER_KUBECONFIG: der Pfad zur kubeconfig-Datei des Management API-Servers
    • USER_PROJECT_NAMESPACE: der Name des Namespaces, in dem sich das Nutzerprojekt befindet
    • CERT_REQ_NAME : der Name der CertificateRequest-Ressource

    Die Ausgabe sieht etwa so aus:

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

  4. Rufen Sie den Namen des Zertifikat-Secrets ab:

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

    Ersetzen Sie Folgendes:

    • MANAGEMENT_API_SERVER_KUBECONFIG: der Pfad zur kubeconfig-Datei des Management API-Servers
    • USER_PROJECT_NAMESPACE: der Name des Namespaces, in dem sich das Nutzerprojekt befindet
    • CERT_REQ_NAME : der Name der CertificateRequest-Ressource

    Die Ausgabe zeigt den SECRET_NAME mit dem signierten Zertifikat:

    test-jwk-1

Zertifikat mit einem automatisch generierten Schlüssel anfordern

  1. Erstellen Sie eine CertificateRequest-Ressource und speichern Sie sie als YAML-Datei mit dem Namen cert-request.yaml. Geben Sie die gewünschten Werte für das Zertifikat ein.

    Optional können Sie das Zertifikat mit einem vorkonfigurierten Satz von X.509-Parametern ausstellen, indem Sie den Namen der Vorlage in das Feld certificateTemplate eingeben.

    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

    Ersetzen Sie die folgenden Variablen:

    Variable Beschreibung
    CERT_REQ_NAME der Name der CertificateRequest-Ressource
    USER_PROJECT_NAMESPACE der Name des Namespaces, in dem sich das Nutzerprojekt befindet
    CA_NAME der Name der Zertifizierungsstelle, die eine Stamm- oder untergeordnete Zertifizierungsstelle sein kann
    SECRET_NAME der Name des Kubernetes-Secrets, das den privaten Schlüssel und signierte CA-Zertifikat enthält

    Ersetzen Sie die folgenden optionalen Variablen. Sie müssen mindestens eines der Felder aus dem Block spec.certificateConfig.subjectConfig der CertificateRequest-Ressource angeben:

    Variable Beschreibung
    COMMON_NAME der allgemeine Name des Zertifikats
    ORGANIZATION die Organisation, die im Zertifikat verwendet werden soll
    LOCALITY der Ort des Zertifikats
    STATE das Bundesland oder die Provinz, das bzw. die im Zertifikat verwendet werden soll
    COUNTRY das Land des Zertifikats
    DNS_NAMES eine Liste von dNSName subjectAltNames, die im Zertifikat festgelegt werden sollen
    IP_ADDRESS eine Liste von ipAddress subjectAltNames, die im Zertifikat festgelegt werden sollen
    RFC822_NAMES eine Liste von rfc822Name subjectAltNames, die im Zertifikat festgelegt werden sollen
    URIS eine Liste von uniformResourceIdentifier subjectAltNames, die im Zertifikat festgelegt werden sollen
    TEMPLATE_NAME der Name der vordefinierten Zertifikatvorlage, die Sie verwenden möchten. Eine Liste der verfügbaren Vorlagen und Details zu Konflikten finden Sie unter Vordefinierte Zertifikatvorlagen.
    VALIDITY_START_TIME der Zeitpunkt, ab dem das Zertifikat gültig ist. Dieser Wert muss das Format YYYY-MM-DDTHH:MM:SSZ haben (z. B. 2025-10-19T21:45:30Z). Wenn er nicht festgelegt ist, ist das Zertifikat sofort nach der Ausstellung gültig .
    VALIDITY_END_TIME der Zeitpunkt, zu dem das Zertifikat abläuft. Dieser Wert muss das Format YYYY-MM-DDTHH:MM:SSZ haben (z. B. 2026-01-17T18:25:40Z). Wenn er nicht festgelegt ist, läuft das Zertifikat 90 Tage nach dem Startzeitpunkt ab.
    SUBJECT_OVERRIDE ein benutzerdefiniertes Subjekt, das im ausgestellten Zertifikat verwendet werden soll und die Subjektinformationen in der CSR überschreibt. Geben Sie diesen Wert als rohes, ASN.1 DER-codiertes X.509-Subjekt an.

  2. Wenden Sie die benutzerdefinierte Ressource auf Ihre Distributed Cloud-Instanz an:

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

    Ersetzen Sie MANAGEMENT_API_SERVER_KUBECONFIG durch den Pfad zur kubeconfig-Datei des Management API-Servers.

  3. Prüfen Sie, ob die Zertifikatanfrage bereit ist:

    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))'

    Ersetzen Sie Folgendes:

    • MANAGEMENT_API_SERVER_KUBECONFIG: der Pfad zur kubeconfig-Datei des Management API-Servers
    • USER_PROJECT_NAMESPACE: der Name des Namespaces, in dem sich das Nutzerprojekt befindet
    • CERT_REQ_NAME : der Name der CertificateRequest-Ressource

    Die Ausgabe sieht etwa so aus:

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

  4. Rufen Sie den Namen des Zertifikat-Secrets ab:

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

    Ersetzen Sie Folgendes:

    • MANAGEMENT_API_SERVER_KUBECONFIG: der Pfad zur kubeconfig-Datei des Management API-Servers
    • USER_PROJECT_NAMESPACE: der Name des Namespaces, in dem sich das Nutzerprojekt befindet
    • CERT_REQ_NAME: der Name der CertificateRequest-Ressource

    Die Ausgabe zeigt den SECRET_NAME mit dem signierten Zertifikat:

    test-jwk-1

Zertifikatanfragen auflisten

Verwenden Sie den Parameter certificaterequests, um alle CertificateRequest-Ressourcen aufzulisten:

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

Ersetzen Sie Folgendes:

  • MANAGEMENT_API_SERVER_KUBECONFIG: der Pfad zur kubeconfig-Datei des Management API-Servers
  • USER_PROJECT_NAMESPACE: der Name des Namespaces, in dem sich das Nutzerprojekt befindet

Im Folgenden sehen Sie einen Beispielbefehl mit dem Namespace agtest-project:

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

Die erwartete Ausgabe sieht in etwa so aus:

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

Zertifikat löschen

Wenn Sie ein Zertifikat löschen möchten, müssen Sie die entsprechende benutzerdefinierte CertificateRequest-Ressource löschen. Durch diese Aktion wird die Ressource aus der CAS-Datenbank entfernt.

  1. Suchen Sie den Namen der CertificateRequest, die Sie löschen möchten. Sie können Zertifikatanfragen auflisten, um den Namen zu finden.

  2. Löschen Sie die CertificateRequest-Ressource:

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

    Ersetzen Sie Folgendes:

    • MANAGEMENT_API_SERVER_KUBECONFIG: der Pfad zur kubeconfig-Datei des Management API-Servers
    • USER_PROJECT_NAMESPACE: der Name des Namespaces, in dem sich das Nutzerprojekt befindet
    • CERT_REQ_NAME: der Name der CertificateRequest-Ressource

Limits und Bereinigung von Zertifikatanfragen

Um die Systemstabilität aufrechtzuerhalten und eine hohe Ressourcennutzung zu vermeiden, erzwingt CAS Limits für die Anzahl der benutzerdefinierten CertificateRequest-Ressourcen und bietet eine optionale automatische Bereinigungsfunktion.

Kontingent für Zertifikatanfragen

CAS erzwingt ein Kontingent für die Anzahl der benutzerdefinierten CertificateRequest-Ressourcen pro Organisation. Das Standardlimit liegt bei 5.000. Das Überschreiten dieses Limits kann die Leistung von CAS und Management API Server beeinträchtigen.

Wenn sich die Gesamtzahl der CertificateRequest-Ressourcen dem Kontingent nähert (z. B. bei 80% und 90% des Limits), werden in der Befehlsausgabe Warnungen angezeigt, wenn Sie neue Anfragen erstellen. Wenn Sie versuchen, eine CertificateRequest zu erstellen, nachdem das Kontingent erreicht wurde, wird die Anfrage abgelehnt. Möglicherweise wird eine Fehlermeldung wie die folgende angezeigt:

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

Wenn dieser Fehler auftritt, müssen Sie möglicherweise alte oder unnötige RessourcenCertificateRequest löschen. Wenn Sie das Kontingent anpassen möchten, wenden Sie sich an ein Mitglied der Gruppe der Infrastrukturoperatoren in Ihrer Organisation. Diese können das Kontingent überschreiben, indem sie der Anleitung im Runbook PLATAUTH-G2102folgen.

Automatische Bereinigung

Sie können die automatische Bereinigung aktivieren, um abgelaufene CertificateRequest-Ressourcen zu löschen. Mit dieser Funktion können Ressourcen freigegeben werden, indem sie nach einer konfigurierbaren Kulanzfrist entfernt werden. Die Kulanzfrist definiert die Zeit zwischen dem Ablauf eines Zertifikats und dem Löschen der CertificateRequest-Ressource.

Die automatische Bereinigung ist standardmäßig deaktiviert. Ein Mitglied der Gruppe der Infrastruktur operatoren in Ihrer Organisation kann diese Funktion aktivieren und die Kulanzfrist konfigurieren , indem es der Anleitung im Runbook PLATAUTH-G2103 folgt. Die Funktion bleibt deaktiviert, wenn die Kulanzfrist nicht festgelegt oder auf null gesetzt ist.