Zertifikat anfordern

In diesem Dokument wird beschrieben, wie Sie ein Zertifikat mit dem Certificate Authority Service (CAS) anfordern.

Wenn Sie Vertrauen und sichere Kommunikation in Ihrer Google Distributed Cloud (GDC)-Umgebung mit Air Gap herstellen möchten, fordern Sie beim Certificate Authority Service ein ACME-fähiges oder deaktiviertes Zertifikat an.

Dieses Dokument richtet sich an Zielgruppen innerhalb 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 Zertifikatsanfragen 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 Projekt-Namespace der Zertifizierungsstelle zuzuweisen.

Umgebung vorbereiten

Zertifikat mit einer Zertifizierungsstelle mit aktiviertem ACME-Modus anfordern

Wenn die Zertifizierungsstelle im ACME-Modus gehostet wird, wird die ACME-Server-URL im Status ausgegeben, sobald 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 Namespace, in dem sich das Nutzerprojekt befindet

Zertifikat mit deaktiviertem ACME-Modus von der Zertifizierungsstelle anfordern

Wenn Sie eine Zertifikatsanfrage mit deaktiviertem ACME-Modus 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 ein CertificateResource mit einem automatisch generierten privaten GDC-Schlüssel und geben Sie die Zertifikatskonfigurationen 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 Anfrage für die Signierung des Zertifikats (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 Namespace, 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 das signierte CA-Zertifikat enthält

    Ersetzen Sie die folgenden optionalen Variablen:

    Variable Beschreibung
    TEMPLATE_NAME Der Name der vordefinierten Zertifikatsvorlage, 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 als gültig gilt. 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 Startdatum 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 Zertifikatsanfrage 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 Namespace, in dem sich das Nutzerprojekt befindet
    • CERT_REQ_NAME ist 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 Zertifikats-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 Namespace, in dem sich das Nutzerprojekt befindet
    • CERT_REQ_NAME ist der Name der CertificateRequest-Ressource.

    Die Ausgabe zeigt das 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 ausgewählten 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 Namespace, 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 das signierte CA-Zertifikat enthält

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

    Variable Beschreibung
    COMMON_NAME Der allgemeine Name des Zertifikats
    ORGANIZATION Organisation, die auf dem Zertifikat verwendet werden soll
    LOCALITY den Ort des Zertifikats
    STATE Bundesland oder Provinz, die im Zertifikat verwendet werden sollen
    COUNTRY das Land des Zertifikats
    DNS_NAMES Eine Liste von dNSName subjectAltNames, die für das Zertifikat festgelegt werden sollen
    IP_ADDRESS Eine Liste von ipAddress subjectAltNames, die für das Zertifikat festgelegt werden sollen
    RFC822_NAMES Eine Liste von rfc822Name subjectAltNames, die für das Zertifikat festgelegt werden sollen
    URIS Eine Liste von uniformResourceIdentifier subjectAltNames, die für das Zertifikat festgelegt werden sollen
    TEMPLATE_NAME Der Name der vordefinierten Zertifikatsvorlage, 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 als gültig gilt. 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 Startdatum 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 Zertifikatsanfrage 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 Namespace, in dem sich das Nutzerprojekt befindet
    • CERT_REQ_NAME ist 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 Zertifikats-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 Namespace, in dem sich das Nutzerprojekt befindet
    • CERT_REQ_NAME: der Name der CertificateRequest-Ressource

    Die Ausgabe zeigt das SECRET_NAME mit dem signierten Zertifikat:

    test-jwk-1

Zertifikatsanfragen 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 Namespace, in dem sich das Nutzerprojekt befindet

Im Folgenden finden 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 des CertificateRequest, den Sie löschen möchten. Sie können Zertifikatsanfragen auflisten, um den Namen zu finden.

  2. Löschen Sie die Ressource CertificateRequest:

    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 Namespace, in dem sich das Nutzerprojekt befindet
    • CERT_REQ_NAME: der Name der CertificateRequest-Ressource

Limits für Zertifikatsanfragen und Bereinigung

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

Kontingent für Zertifikatsanfragen

CAS erzwingt ein Kontingent für die Anzahl der benutzerdefinierten CertificateRequest-Ressourcen pro Organisation. Das Standardlimit beträgt 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 nicht benötigte CertificateRequest-Ressourcen löschen. Wenn Sie das Kontingent anpassen möchten, wenden Sie sich an ein Mitglied der Gruppe der Infrastrukturbetreiber in Ihrer Organisation. Sie können das Kontingent überschreiben, indem sie der Anleitung im Runbook PLATAUTH-G2102 folgen.

Automatisierte Bereinigung

Sie können die automatische Bereinigung aktivieren, um abgelaufene CertificateRequest-Ressourcen zu löschen. Mit dieser Funktion können Sie Ressourcen freigeben, indem Sie sie nach einem konfigurierbaren Kulanzzeitraum entfernen. Der Kulanzzeitraum definiert die Zeitspanne zwischen dem Ablauf eines Zertifikats und dem Löschen der CertificateRequest-Ressource.

Die automatische Bereinigung ist standardmäßig deaktiviert. Ein Mitglied der Infrastrukturbetreibergruppe in Ihrer Organisation kann dieses Feature aktivieren und den Kulanzzeitraum konfigurieren. Folgen Sie dazu der Anleitung im Runbook PLATAUTH-G2103. Die Funktion bleibt deaktiviert, wenn der Kulanzzeitraum nicht festgelegt oder auf null gesetzt ist.