Auf private Registrys mit privaten CA-Zertifikaten zugreifen

Auf dieser Seite erfahren Sie, wie Sie in Google Kubernetes Engine (GKE) ausgeführten Arbeitslasten den Zugriff auf private Image-Registrys gewähren. Dazu verwenden Sie den öffentlichen Schlüssel der Zertifizierungsstelle, die das Zertifikat für die Registry ausgestellt hat.

Funktionsweise

Sie speichern den öffentlichen Schlüssel der Zertifizierungsstelle, die zum Ausstellen von Zertifikaten für Ihre privaten Registries verwendet wurde, in Secret Manager und konfigurieren, welche voll qualifizierten Domainnamen (FQDNs) diesen öffentlichen Schlüssel für die Zertifikatsprüfung verwenden. GKE ruft den Schlüssel automatisch ab und aktualisiert die Registry-Konfiguration der Containerlaufzeit während des Knoten-Bootstrapping. Wenn Sie eine Arbeitslast bereitstellen, die ein Container-Image aus Ihrer privaten Registry verwendet, werden die folgenden Schritte ausgeführt:

  1. Das Kubelet auf dem Knoten versucht, das Image aus der privaten Registry abzurufen.
  2. Die Registry stellt ein serverseitiges TLS-Zertifikat bereit.
  3. Die Containerlaufzeit validiert das Registry-Zertifikat kryptografisch und sorgt dafür, dass der FQDN mit dem von Ihnen angegebenen übereinstimmt.
  4. Wenn die Validierung erfolgreich ist, ruft GKE das Image ab und plant Ihre Arbeitslast.

Vorteile

Diese Methode des Zugriffs auf private Registrys bietet folgende Vorteile:

  1. Zuverlässigkeit der Konfiguration der Containerlaufzeit verbessern: Die Verwendung von Methoden wie DaemonSets zum Festlegen der containerd-Konfiguration erhöht das Risiko einer Race-Bedingung, in der andere DaemonSets vor Ihrem Konfigurations-DaemonSet ausgeführt werden können.
  2. Sicherheitslücken bei Angriffen zur Rechteausweitung reduzieren: Es ist nicht mehr erforderlich, privilegierte DaemonSets auszuführen, die Ihre Containerlaufzeitkonfiguration ändern.
  3. Verwaltungsaufwand reduzieren: Mit Secret Manager können Sie öffentliche CA-Schlüssel an einem zentralen Ort speichern und Zugriff auf die Schlüssel mit IAM verwalten sowie die Versionsverwaltung und Annotationen implementieren. Weitere Informationen finden Sie in der Produktübersicht zu Secret Manager.
  4. Nachvollziehbarkeit verbessern: Cloud Logging erfasst bereits Logs, auch wenn Zertifikate zu einem Cluster hinzugefügt werden und wenn GKE-Knoten Images abrufen.

Preise

In diesem Dokument verwenden Sie die folgenden kostenpflichtigen Komponenten von Google Cloud:

  • GKE
  • Secret Manager
  • Logging: GKE generiert Audit-Logs zur Administratoraktivität und, falls aktiviert, Audit-Logs zum Datenzugriff für dieses Feature. Informationen zu den verschiedenen Arten von Audit-Logs finden Sie unter GKE-Audit-Logging.

Mit dem Preisrechner können Sie eine Kostenschätzung für Ihre voraussichtliche Nutzung vornehmen.

Hinweise

Führen Sie die folgenden Schritte durch, bevor Sie beginnen:

  • Aktivieren Sie die Google Kubernetes Engine API.
    • Google Kubernetes Engine API aktivieren
  • Wenn Sie die Google Cloud CLI für diese Aufgabe verwenden möchten, müssen Sie die gcloud CLI installieren und dann initialisieren. Wenn Sie die gcloud CLI bereits installiert haben, rufen Sie die neueste Version mit gcloud components update ab.

  • Enable the Secret Manager API.

    Enable the API

  • Sie müssen bereits eine private Registry und private CA-Zertifikate haben, um auf die Registry zugreifen zu können. In diesem Leitfaden wird nicht das Einrichten einer privaten Registry oder das Erstellen von Zertifikaten behandelt.

Voraussetzungen

Wenn Sie öffentliche private CA-Schlüssel für den Zugriff auf private Registrys verwenden möchten, müssen Sie die folgenden Anforderungen erfüllen:

  • Ihre Cluster müssen die GKE-Version 1.27.3-gke.1700 oder höher verwenden.
  • Sie müssen ein Knoten-Image des Typs Container-Optimized OS mit containerd verwenden, das der Standard für alle GKE-Cluster ist. Ubuntu-Knoten-Images mit containerd werden nicht unterstützt. Windows Server-Knoten-Images werden nicht unterstützt.
  • Die Knotenpools müssen den Zugriffsbereich cloud-platform haben, damit Ihre Knoten die Zertifikate herunterladen können. Weitere Informationen finden Sie unter Standardzugriffsbereiche in GKE. Dieses Dokument enthält eine Anleitung zum Festlegen des Zugriffsbereichs beim Erstellen eines Clusters oder Knotenpools.

Beschränkungen

Beachten Sie folgende Einschränkungen:

  • Sie können keine privaten CA-Zertifikate in Ubuntu-Knoten-Images verwenden.
  • Sie können in Windows Server-Knoten keine privaten CA-Zertifikate verwenden.
  • Jeder Cluster unterstützt bis zu fünf private CA-Zertifikate für private Registrys.
  • Jedes Zertifikat kann bis zu 25 voll qualifizierte Domainnamen (FQDNs) haben.
  • Jede Domain kann nur in einer einzigen Zertifikatsdatei verwendet werden. Zertifikatpakete werden jedoch unterstützt.
  • Zertifikate müssen PEM-codiert sein.
  • Der Server rotiert Zertifikate nicht automatisch. Weitere Informationen finden Sie in diesem Dokument unter Private CA-Zertifikate rotieren.
  • Für FQDNs gelten folgende Einschränkungen:
    • Die maximale FQDN-Länge beträgt 255 Zeichen, einschließlich Sonderzeichen.
    • FQDNs können nur Buchstaben, Zahlen und Bindestriche (-) verwenden.
    • Punycode wird nicht unterstützt.
    • Platzhalterzeichen werden nicht unterstützt.

Von Konfigurations-DaemonSets migrieren

In GKE Standard-Clustern können Sie privilegierte DaemonSets bereitstellen, um Ihre Containerlaufzeitkonfiguration zu ändern. Diese Methode ändert die containerd-Konfiguration direkt auf jedem Knoten.

Wenn Sie privilegierte DaemonSets verwenden, um den Zugriff auf private Registries zu konfigurieren, sollten Sie Folgendes berücksichtigen, bevor Sie dieses Dokument verwenden:

  • Durch das Speichern privater CA-Schlüssel in Secret Manager wird nur der Zugriff auf private Registrys konfiguriert. Andere Registry-bezogene Konfigurationen werden nicht unterstützt.

  • Wenn Sie diese Funktion aktivieren, verwendet Ihr Cluster das CRI-Hostpfad-Konfigurationsmodell von containerd, das mit dem vorherigen Konfigurationsmodell nicht kompatibel ist. Wenn Sie DaemonSets haben, die die containerd-Hostkonfiguration ändern, z. B. für unsichere private Registries, Spiegel oder Proxys, aktualisieren Sie die DaemonSets für die Verwendung des CRI-Hostpfadmodells.

    Informationen zu den verfügbaren Feldern im CRI-Hostpfadmodell finden Sie unter Registry-Konfiguration im GitHub-Repository von containerd.

Wenn Sie dieses Feature aktivieren, wendet GKE das CRI-Hostpfad-Konfigurationsmodell auf neue Knoten im Cluster an. Vorhandene Knoten verwenden weiterhin das vorherige Konfigurationsmodell, bis sie bei Ereignissen wie Upgrades neu erstellt werden.

DaemonSets so aktualisieren, dass sie beide Konfigurationsmodelle unterstützen

Um das Risiko zu verringern, dass Ihre Konfigurations-DaemonSets nicht auf Knoten funktionieren, die ein bestimmtes Konfigurationsmodell verwenden, sollten Sie dafür sorgen, dass Ihre DaemonSets abhängig von den containerd-Konfigurationsdateien auf dem Knoten ein bestimmtes Konfigurationsmodell bedingt verwenden. Ein Beispiel für ein DaemonSet, das diese bedingte Logik implementiert, finden Sie im GitHub-Repository GoogleCloudPlatform/k8s-node-tools im Manifest insecure-registry-config.yaml.

Öffentliche CA-Schlüssel in Secret Manager speichern

Speichern Sie die öffentlichen Schlüssel Ihrer privaten Zertifizierungsstellen, die Ihre privaten Registry-Zertifikate als Secrets in Secret Manager ausstellen. Eine Anleitung finden Sie in der Secret Manager-Dokumentation unter Secret erstellen.

Zugriff auf Secret Manager über GKE konfigurieren

Damit das IAM-Dienstkonto des Clusters die erforderlichen Berechtigungen zum Abrufen von Secrets aus Secret Manager hat, bitten Sie Ihren Administrator, dem IAM-Dienstkonto des Clusters die folgenden IAM-Rollen für das Secret zu erteilen:

Weitere Informationen zum Zuweisen von Rollen finden Sie unter Zugriff auf Projekte, Ordner und Organisationen verwalten.

Diese vordefinierten Rollen enthalten die Berechtigungen, die zum Abrufen von Secrets aus Secret Manager erforderlich sind. Erweitern Sie den Abschnitt Erforderliche Berechtigungen, um die erforderlichen Berechtigungen anzuzeigen:

Erforderliche Berechtigungen

Die folgenden Berechtigungen sind erforderlich, um Secrets aus Secret Manager abzurufen:

  • resourcemanager.projects.get
  • resourcemanager.projects.list
  • secretmanager.secrets.get
  • secretmanager.secrets.list
  • secretmanager.versions.get
  • secretmanager.versions.list
  • secretmanager.versions.access

Ihr Administrator kann dem IAM-Dienstkonto des Clusters möglicherweise auch diese Berechtigungen mit benutzerdefinierten Rollen oder anderen vordefinierten Rollen erteilen.

Wenn Sie Ihrem Cluster oder Knotenpool kein benutzerdefiniertes IAM-Dienstkonto zugeordnet haben (wird von uns empfohlen), verwendet der Cluster das Compute Engine-Standarddienstkonto. Wir empfehlen Ihnen, Ihre Cluster und Knotenpools nach Möglichkeit mit einem IAM-Dienstkonto mit minimalen Berechtigungen zu konfigurieren. Eine Anleitung finden Sie unter Dienstkonten mit geringsten Berechtigungen verwenden.

Laufzeit-Konfigurationsdatei erstellen

Damit Sie private CA-Zertifikate für private Registries in GKE verwenden können, erstellen Sie eine YAML-Datei, um die containerd-Konfiguration zu ändern.

  1. Rufen Sie Ihre Google Cloud-Projektnummer ab:

    gcloud projects describe PROJECT_ID \
    --format="value(projectNumber)"

    Die Ausgabe ist Ihre numerische Projektnummer.

  2. Speichern Sie die folgende Konfiguration als containerd-configuration.yaml:

    privateRegistryAccessConfig:
  certificateAuthorityDomainConfig:
  - gcpSecretManagerCertificateConfig:
      secretURI: "projects/PROJECT_NUMBER/secrets/SECRET_NAME/versions/SECRET_VERSION"
    fqdns:
      - "FQDN1"
      - "FQDN2"
  enabled: true

    Ersetzen Sie Folgendes:

    • PROJECT_NUMBER: Die Projektnummer, die Sie im vorherigen Schritt erhalten haben.
    • SECRET_VERSION: Die Versionsnummer Ihres Secrets im Secret Manager. Sie können optional einen Versionsalias verwenden, aber wir empfehlen, die Versionsnummer zu verwenden, um die Verwaltung zu vereinfachen.
    • FQDN1, FQDN2: Die voll qualifizierten Domainnamen für Ihre privaten Registrys. Sie können eine IPv4-Adresse auch verwenden, wenn für diese Adresse ein Zertifikat ausgestellt wurde, wir raten jedoch davon ab.

Eine Beschreibung dieser Felder finden Sie unter privateRegistryAccessConfig in der Tabelle der verfügbaren containerd-Konfigurationsoptionen.

containerd-Konfiguration auf neue Cluster anwenden

In diesem Abschnitt erfahren Sie, wie Sie eine containerd-Konfigurationsdatei anwenden, wenn Sie einen neuen GKE-Cluster erstellen.

Führen Sie dazu diesen Befehl aus:

gcloud container clusters create-auto CLUSTER_NAME \
    --location=LOCATION \
    --scopes="cloud-platform" \
    --containerd-config-from-file="PATH_TO_CONFIG_FILE"

Ersetzen Sie Folgendes:

  • CLUSTER_NAME: Der Name des neuen Clusters.
  • LOCATION: Der Compute Engine-Standort für Ihren neuen Cluster.
  • PATH_TO_CONFIG_FILE: Der Pfad zur von Ihnen erstellten Konfigurationsdatei, z. B. ~/containerd-configuration.yaml.

Sie können die Konfiguration der privaten Registry für neue Standardcluster aktivieren. Führen Sie dazu den Befehl gcloud container clusters create mit denselben Optionen aus.

containerd-Konfiguration auf vorhandene Cluster anwenden

In diesem Abschnitt erfahren Sie, wie Sie eine containerd-Konfiguration auf vorhandene Cluster und Knoten anwenden.

Zugriffsbereiche prüfen

Vorhandene Cluster müssen den Zugriffsbereich cloud-platform haben, um dieses Feature verwenden zu können. In diesem Abschnitt erfahren Sie, wie Sie Ihre Zugriffsbereiche prüfen und einen vorhandenen Cluster mit einer neuen oder geänderten Konfigurationsdatei für private Registrys aktualisieren.

Weitere Informationen zu den Standardzugriffsbereichen in neuen Clustern finden Sie unter Zugriffsbereiche in GKE.

Autopilot-Zugriffsbereiche prüfen

Führen Sie dazu diesen Befehl aus:

gcloud container clusters describe CLUSTER_NAME \
    --location=LOCATION \
    --flatten=nodeConfig \
    --format='csv[delimiter="\\n",no-heading](oauthScopes)'

Wenn Ihr Cluster nicht den Zugriffsbereich https://www.googleapis.com/auth/cloud-platform hat, erstellen Sie einen neuen Cluster mit diesem Zugriffsbereich.

Standardzugriffsbereiche prüfen

Prüfen Sie die Zugriffsbereiche eines Standardclusters in einem Knotenpool:

gcloud container node-pools describe NODE_POOL_NAME \
    --cluster=CLUSTER_NAME \
    --location=LOCATION \
    --flatten=nodeConfig \
    --format='csv[delimiter="\\n",no-heading](oauthScopes)'

Ersetzen Sie NODE_POOL_NAME durch den Namen des Knotenpools.

Wenn Ihr Cluster nicht den Zugriffsbereich https://www.googleapis.com/auth/cloud-platform hat, erstellen Sie einen neuen Knotenpool mit dem Zugriffsbereich cloud-platform und löschen Sie den vorhandenen Knotenpool.

Cluster für die Verwendung der Konfigurationsdatei aktualisieren

Führen Sie dazu diesen Befehl aus:

gcloud container clusters update CLUSTER_NAME \
    --location=LOCATION \
    --containerd-config-from-file="PATH_TO_CONFIG_FILE"

Knoten in Standardclustern neu erstellen

Wenn Ihr Standardcluster keine automatischen Upgrades verwendet, müssen Sie Ihre Knotenpools manuell neu erstellen, um die neue Konfiguration anzuwenden. Wenn Sie eine manuelle Knotenneuerstellung auslösen möchten, aktualisieren Sie Ihren Cluster auf die bereits verwendete GKE-Version.

gcloud container clusters upgrade CLUSTER_NAME \
    --location=LOCATION \
    --cluster-version=VERSION

Ersetzen Sie VERSION durch die GKE-Patchversion, die der Cluster bereits verwendet.

Prüfen, ob der Cluster auf die private Registry zugreifen kann

Führen Sie dazu diesen Befehl aus:

gcloud container clusters describe CLUSTER_NAME \
    --location=LOCATION \
    --flatten="nodePoolDefaults.nodeConfigDefaults.containerdConfig"

Die Ausgabe sieht in etwa so aus:

    containerdConfig:
      privateRegistryAccessConfig:
        certificateAuthorityDomainConfig:
        - fqdns:
          - 203.0.113.105
          gcpSecretManagerCertificateConfig:
            secretUri: projects/123456789012/secrets/example-secret-name/versions/1
        enabled: true

Arbeitslast bereitstellen, die auf ein privates Image zugreift

In diesem Abschnitt stellen Sie einen statischen Pod bereit, der auf ein Image aus Ihrer privaten Registry verweist.

  1. Speichern Sie das folgende Manifest als private-registry-pod.yaml:

    apiVersion: v1
kind: Pod
metadata:
  name: private-registry-pod
spec:
  containers:
  - name: private-image
    image: IMAGE_NAME

    Ersetzen Sie IMAGE_NAME durch den Namen Ihres privaten Images.

  2. Stellen Sie den Pod bereit:

    kubectl create -f private-registry-pod.yaml

Private CA-Zertifikate rotieren

Secret Manager und GKE können private CA-Zertifikate in Secret Manager nicht automatisch rotieren. Führen Sie die folgenden Schritte aus, um eine Zertifikatsrotation durchzuführen. Bei diesen Schritten müssen Sie vorhandene Knoten zweimal neu erstellen. Wir empfehlen, Zertifikatsrotationen während geplanter Ausfallzeiten durchzuführen, um die Auswirkungen von Arbeitslastunterbrechungen zu minimieren.

  1. Erstellen Sie ein PEM-codiertes Zertifikatspaket, das sowohl Ihre alten als auch Ihre neuen Zertifikate enthält.
  2. Fügen Sie das Bundle als neue Secret-Version in Secret Manager hinzu.
  3. Aktualisieren Sie das Feld secretURI der Laufzeitkonfigurationsdatei mit der neuen Secret-Versionsnummer.
  4. Aktualisieren Sie Ihren Cluster, um die neue Secret-Version zu verwenden.

  5. Rufen Sie den Zeitstempel des Aktualisierungsvorgangs ab:

    gcloud container operations list \
    --filter="operationType ~ UPDATE_CLUSTER AND targetLink ~ CLUSTER_NAME" \
    --sort-by=startTime \
    --limit=1 \
    --format='value(endTime)'

    Die Ausgabe sieht in etwa so aus:

    2024-01-31T09:27:30.864308964Z

  6. Suchen Sie nach Knoten, die vor Abschluss des Aktualisierungsvorgangs erstellt wurden:

    kubectl get nodes -o json | jq ".items[] |
select(.metadata.creationTimestamp | fromdateiso8601 < $(date -d
CLUSTER_UPDATE_TIMESTAMP +%s)) | .metadata.name"

    Ersetzen Sie CLUSTER_UPDATE_TIMESTAMP durch den Zeitstempel aus dem vorherigen Schritt.

    Die Ausgabe ist eine Liste von Knotennamen, die nicht mit der aktualisierten Konfiguration neu erstellt wurden. Wenn die Ausgabe leer ist, fahren Sie mit dem nächsten Schritt fort.

  7. Erstellen Sie in Secret Manager eine neue Version Ihres Secrets nur mit dem neuen Zertifikat.

  8. Wiederholen Sie die vorherigen Schritte, um Ihren Cluster zu aktualisieren, den Vorgangszeitstempel abzurufen und zu prüfen, ob Ihre Knoten die neue Secret-Version verwenden.

  9. Löschen Sie die alte Secret-Version aus Secret Manager.

Audit-Logs in Logging aufrufen

In diesem Abschnitt erfahren Sie, wie Sie mit Logging prüfen, ob GKE Ihre Secret-Version auf Ihren Knoten installiert hat.

  1. Rufen Sie in der Google Cloud Console die Seite Log-Explorer auf.

    Zum Log-Explorer

  2. Geben Sie die folgende Abfrage an:

    resource.type="gce_instance"
textPayload:"Installed certificate \\\"projects/PROJECT_NUMBER/secrets/SECRET_NAME/versions/SECRET_VERSION\\\""

    Wenn das Zertifikat installiert wurde, sieht die Ausgabe in etwa so aus:

    "Installed certificate "projects/PROJECT_NUMBER/secrets/SECRET_NAME/versions/SECRET_VERSION""

    Wenn die Installation des Zertifikats fehlgeschlagen ist, sieht die Ausgabe in etwa so aus:

    "Failed to install certificate "projects/PROJECT_NUMBER/secrets/SECRET_NAME/versions/SECRET_VERSION""

Best Practices

Wir empfehlen, die folgenden Best Practices für dieses Feature zu beachten:

  • Verwenden Sie keine Aliasse für Secret Manager-Secret-Versionen. Verwenden Sie für jede Secret-Version die automatisch generierte Versionsnummer. Ein Alias kann im Laufe der Zeit auf eine andere Zertifikatsversion verweisen. Dies kann zu Komplexität bei der Verfolgung der von Ihren Arbeitslasten verwendeten Versionen führen.
  • Verwenden Sie Wartungsfenster und -ausschlüsse, um zu steuern, wann GKE Ihre Knoten neu erstellen kann, um aktualisierte containerd-Konfigurationen anzuwenden.
  • Gewähren Sie Zugriff auf Secrets auf Secret-Ebene, nicht auf Projektebene.

containerd-Konfigurationsoptionen deaktivieren

So entfernen Sie Ihre benutzerdefinierte Konfiguration:

  1. Aktualisieren Sie Ihre Konfigurationsdatei, um enabled: false im Konfigurationselement anzugeben, das Sie deaktivieren möchten, und löschen Sie alle anderen Felder im Element, wie im folgenden Beispiel:

    privateRegistryAccessConfig:
  enabled: false
  2. Wenden Sie aktualisierte Konfiguration auf Ihrem Cluster an. Eine Anleitung finden Sie unter containerd-Konfiguration auf vorhandene Cluster anwenden.

Fehlerbehebung

Informationen zur Fehlerbehebung finden Sie unter Fehlerbehebung bei der Containerlaufzeit.