Secrets mit Kubernetes-Secrets synchronisieren

In diesem Dokument wird beschrieben, wie Sie in Secret Manager gespeicherte Secrets mit Kubernetes-Secrets in Ihren Google Kubernetes Engine-Clustern (GKE) synchronisieren.

Durch die Synchronisierung können Anwendungen, die in GKE ausgeführt werden, mit Standard-Kubernetes-Methoden wie Umgebungsvariablen oder Volume-Bereitstellungen auf Secrets aus Secret Manager zugreifen. Das ist nützlich für Anwendungen, die bereits so konzipiert sind, dass sie Secrets aus dem Kubernetes-Secret-Objekt lesen, und nicht aktualisiert werden müssen, um direkt auf Secret Manager zuzugreifen.

Empfehlung: Die Funktion zur Secret-Synchronisierung ist eine Alternative zum Secret Manager-Add-on, mit dem Secrets als In-Memory-Dateien direkt in Ihre Pods bereitgestellt werden. Verwenden Sie das Secret Manager-Add-on, wenn Ihre Anwendung es unterstützt, da es eine sicherere Methode ist, um in GKE auf Secrets aus Secret Manager zuzugreifen.

Hinweis

Führen Sie die folgenden Schritte aus, bevor Sie Secrets synchronisieren:

• Aktivieren Sie die Secret Manager API und die Google Kubernetes Engine API.

  Rollen, die zum Aktivieren von APIs erforderlich sind

  Zum Aktivieren von APIs benötigen Sie die IAM-Rolle „Service Usage-Administrator“ (roles/serviceusage.serviceUsageAdmin), die die Berechtigung serviceusage.services.enable enthält. Informationen zum Zuweisen von Rollen.

  APIs aktivieren

• Installieren und dann initialisieren Sie die gcloud CLI. Wenn Sie die gcloud CLI bereits installiert haben, rufen Sie die neueste Version mit dem Befehl gcloud components update ab.

• Prüfen Sie, ob ein GKE-Cluster ausgeführt wird. Für diese Funktion ist GKE-Version 1.33 oder höher erforderlich.

• Prüfen Sie, ob die Workload Identity-Föderation für GKE in Ihrem GKE-Cluster aktiviert ist. Dies ist für die Authentifizierung erforderlich. Die Workload Identity-Föderation für GKE ist in einem Autopilot-Cluster standardmäßig aktiviert.

• Prüfen Sie, ob Sie die erforderlichen Identity and Access Management-Berechtigungen zum Verwalten von GKE-Clustern und Secret Manager haben.

Secret-Synchronisierung in einem GKE-Cluster aktivieren

Aktivieren Sie die Funktion zur Secret-Synchronisierung, wenn Sie einen neuen Cluster erstellen oder einen vorhandenen Cluster aktualisieren. Diese Funktion ist sowohl für Standard- als auch für Autopilot-Cluster verfügbar.

Secret-Synchronisierung in einem neuen Cluster aktivieren

Verwenden Sie einen der folgenden gcloud CLI-Befehle, um einen neuen Cluster mit Secret-Synchronisierung zu erstellen:

Standard-Cluster

Um Secret Manager in der Befehlszeile zu verwenden, installieren Sie zuerst die Google Cloud CLI Version 378.0.0 oder höher oder aktualisieren Sie darauf. In Compute Engine oder GKE müssen Sie sich mit dem Bereich cloud-platform authentifizieren.

Secret-Synchronisierung ohne automatische Rotation aktivieren.

gcloud container clusters create CLUSTER_NAME \
    --location=CONTROL_PLANE_LOCATION \
    --workload-pool=PROJECT_ID.svc.id.goog \
    --enable-secret-sync

Secret-Synchronisierung mit automatischer Rotation aktivieren. Das Standardintervall beträgt 2 Minuten.

gcloud container clusters create CLUSTER_NAME \
    --location=CONTROL_PLANE_LOCATION \
    --workload-pool=PROJECT_ID.svc.id.goog \
    --enable-secret-sync \
    --enable-secret-sync-rotation

Secret-Synchronisierung mit einem benutzerdefinierten Rotationsintervall aktivieren. Das Mindestintervall beträgt 1 Minute.

gcloud container clusters create CLUSTER_NAME \
    --location=CONTROL_PLANE_LOCATION \
    --workload-pool=PROJECT_ID.svc.id.goog \
    --enable-secret-sync \
    --enable-secret-sync-rotation \
    --secret-sync-rotation-interval=60s

Ersetzen Sie Folgendes:

• CLUSTER_NAME: der Name Ihres GKE-Cluster
• CONTROL_PLANE_LOCATION: die Region oder Zone Ihrer Cluster-Steuerungsebene, z. B. us-central1 oder us-east1-a
• PROJECT_ID: Ihre Google Cloud Projekt-ID

Autopilot-Cluster

Um Secret Manager in der Befehlszeile zu verwenden, installieren Sie zuerst die Google Cloud CLI Version 378.0.0 oder höher oder aktualisieren Sie darauf. In Compute Engine oder GKE müssen Sie sich mit dem Bereich cloud-platform authentifizieren.

Secret-Synchronisierung ohne automatische Rotation aktivieren.

gcloud container clusters create-auto CLUSTER_NAME \
    --location=CONTROL_PLANE_LOCATION \
    --enable-secret-sync

Secret-Synchronisierung mit automatischer Rotation aktivieren. Das Standardintervall beträgt 2 Minuten.

gcloud container clusters create-auto CLUSTER_NAME \
    --location=CONTROL_PLANE_LOCATION \
    --enable-secret-sync \
    --enable-secret-sync-rotation

Secret-Synchronisierung mit einem benutzerdefinierten Rotationsintervall aktivieren. Das Mindestintervall beträgt 1 Minute.

gcloud container clusters create-auto CLUSTER_NAME \
    --location=CONTROL_PLANE_LOCATION \
    --enable-secret-sync \
    --enable-secret-sync-rotation \
    --secret-sync-rotation-interval=60s

Ersetzen Sie Folgendes:

• CLUSTER_NAME: der Name Ihres GKE-Cluster
• CONTROL_PLANE_LOCATION: die Region oder Zone Ihrer Cluster-Steuerungsebene, z. B. us-central1 oder us-east1-a

Secret-Synchronisierung in einem vorhandenen Cluster aktivieren

Verwenden Sie einen der folgenden gcloud CLI-Befehle, um vorhandene Cluster mit Secret-Synchronisierung zu aktualisieren:

gcloud

Um Secret Manager in der Befehlszeile zu verwenden, installieren Sie zuerst die Google Cloud CLI Version 378.0.0 oder höher oder aktualisieren Sie darauf. In Compute Engine oder GKE müssen Sie sich mit dem Bereich cloud-platform authentifizieren.

Secret-Synchronisierung in einem vorhandenen Cluster aktivieren

gcloud container clusters update CLUSTER_NAME \
    --location=CONTROL_PLANE_LOCATION \
    --enable-secret-sync

Rotation mit einem benutzerdefinierten Intervall aktivieren

gcloud container clusters update CLUSTER_NAME \
    --location=CONTROL_PLANE_LOCATION \
    --enable-secret-sync-rotation \
    --secret-sync-rotation-interval=300s

Rotation deaktivieren

gcloud container clusters update CLUSTER_NAME \
    --location=CONTROL_PLANE_LOCATION \
    --no-enable-secret-sync-rotation

Ersetzen Sie Folgendes:

• CLUSTER_NAME: der Name Ihres GKE-Cluster
• CONTROL_PLANE_LOCATION: die Region oder Zone Ihrer Cluster-Steuerungsebene, z. B. us-central1 oder us-east1-a

Secret-Synchronisierung konfigurieren

Führen Sie die folgenden Schritte aus, um Secrets zu synchronisieren:

1. Erstellen Sie mit dem folgenden Befehl ein Kubernetes-ServiceAccount:

   kubectl create serviceaccount KSA_NAME --namespace NAMESPACE
   

   Ersetzen Sie Folgendes:

   • KSA_NAME: der Name Ihres Kubernetes-ServiceAccount
   • NAMESPACE: der Kubernetes-Namespace, in dem Sie das ServiceAccount erstellen möchten

2. Erstellen Sie eine IAM-Zulassungsrichtlinie, die auf das neue Kubernetes-ServiceAccount verweist, und gewähren Sie dem ServiceAccount die Berechtigung für den Zugriff auf das Secret:

   gcloud

   Um Secret Manager in der Befehlszeile zu verwenden, installieren Sie zuerst die Google Cloud CLI Version 378.0.0 oder höher oder aktualisieren Sie darauf. In Compute Engine oder GKE müssen Sie sich mit dem Bereich cloud-platform authentifizieren.

   gcloud secrets add-iam-policy-binding SECRET_NAME \
      --role=roles/secretmanager.secretAccessor \
      --member=principal://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/PROJECT_ID.svc.id.goog/subject/ns/NAMESPACE/sa/KSA_NAME
   

   Ersetzen Sie Folgendes:

   • SECRET_NAME: der Name des Secrets in Secret Manager
   • PROJECT_NUMBER: Ihre Google Cloud Projektnummer
   • PROJECT_ID: Ihre Google Cloud Projekt-ID
   • NAMESPACE: der Kubernetes-Namespace
   • KSA_NAME: der Name Ihres Kubernetes-ServiceAccount

3. Erstellen Sie mit einem YAML-Manifest eine benutzerdefinierte SecretProviderClass-Ressource. Die SecretProviderClass-Ressource definiert die spezifischen Secrets, die aus Secret Manager abgerufen werden sollen, einschließlich ihrer Ressourcennamen und -pfade. Das Secret Manager-Add-on verwendet die SecretProviderClass-Ressource auch, um die bereitzustellenden Secrets und den Dateinamen aufzulisten, unter dem sie bereitgestellt werden sollen.

   Erstellen Sie eine Datei spc.yaml mit folgendem Inhalt:

   apiVersion: secrets-store.csi.x-k8s.io/v1
   kind: SecretProviderClass
   metadata:
     name: SECRET_PROVIDER_CLASS_NAME
     namespace: NAMESPACE
   spec:
     provider: gke
     parameters:
       secrets: |
         -   resourceName: "projects/SECRET_PROJECT_ID/secrets/SECRET_NAME_1/versions/SECRET_VERSION_1"
             path: "FILENAME.txt"
         -   resourceName: "projects/SECRET_PROJECT_ID/secrets/SECRET_NAME_2/versions/SECRET_VERSION_2"
             path: "FILENAME1.txt"
   

   Ersetzen Sie Folgendes:

   • SECRET_PROVIDER_CLASS_NAME: der Name für Ihr SecretProviderClass-Objekt.
   • NAMESPACE: der Kubernetes-Namespace, in dem Sie diese Ressource erstellen.
   • resourceName: die vollständige Ressourcen-ID für das Secret in Secret Manager. Sie muss die Projekt-ID, den Secret-Namen und die Version im folgenden Format enthalten: projects/SECRET_PROJECT_ID/secrets/SECRET_NAME/versions/SECRET_VERSION.
     • SECRET_PROJECT_ID: die ID des Google Cloud Projekts , in dem das Secret gespeichert ist. Dies kann mit der PROJECT_ID identisch sein, wenn das Secret im selben Projekt wie der GKE-Cluster gespeichert ist.
     • SECRET_NAME: der Secret-Name.
     • SECRET_VERSION: die Secret-Version. Die Secret-Version muss sich in derselben Region wie der Cluster befinden.
   • path: der lokale Dateiname oder Alias, unter dem der Secret-Wert in der Kubernetes-Umgebung verfügbar gemacht wird. Es ist die eindeutige ID, die eine bestimmte Secret Manager-Version mit der lokalen Darstellung verknüpft, die vom Cluster verwendet wird. Wenn das Secret mit der SecretSync-Ressource mit einem Kubernetes-Secret synchronisiert wird, wird in diesem Pfad über das Feld sourcePath auf den Secret-Wert für die Synchronisierung verwiesen. Sie können mehrere Secrets (definiert durch resourceName) verschiedenen Pfadnamen innerhalb derselben SecretProviderClass zuordnen.

4. Führen Sie den folgenden Befehl aus, um das Manifest anzuwenden:

   kubectl apply -f spc.yaml
   

5. Erstellen Sie mit einem YAML-Manifest eine benutzerdefinierte SecretSync-Ressource. Diese Ressource weist den Synchronisierungscontroller an, ein Kubernetes-Secret basierend auf den in der SecretProviderClass definierten Inhalten zu erstellen oder zu aktualisieren.

   Erstellen Sie eine Datei secret-sync.yaml mit folgendem Inhalt:

   apiVersion: secret-sync.gke.io/v1
   kind: SecretSync
   metadata:
     name: KUBERNETES_SECRET_NAME
     namespace: NAMESPACE
   spec:
     serviceAccountName: KSA_NAME
     secretProviderClassName: SECRET_PROVIDER_CLASS_NAME
     secretObject:
       type: KUBERNETES_SECRET_TYPE
       data:
         -   sourcePath: "FILENAME.txt"
             targetKey: "TARGET_KEY1"
         -   sourcePath: "FILENAME1.txt"
             targetKey: "TARGET_KEY2"
   

   Ersetzen Sie Folgendes:

   • KUBERNETES_SECRET_NAME: der Name, den Sie dem neuen Kubernetes-Secret geben möchten, das von der SecretSync-Ressource erstellt wird.
   • NAMESPACE: der Kubernetes-Namespace, in dem die neue Ressource erstellt wird. Er muss mit dem Namespace der SecretProviderClass identisch sein.
   • KSA_NAME: der Name des Kubernetes-ServiceAccount, das vom SecretSync-Controller zum Erstellen und Aktualisieren des Ziel-Kubernetes-Secret verwendet wird. Dieses ServiceAccount muss die erforderlichen Berechtigungen für den Zugriff auf externe Secrets aus Secret Manager haben.
   • SECRET_PROVIDER_CLASS_NAME: der Name des SecretProviderClass-Objekts, das Sie im vorherigen Schritt erstellt haben. Die SecretSync-Ressource verwendet dies, um die richtige Konfiguration für die Secrets zu finden.
   • KUBERNETES_SECRET_TYPE: der Typ des zu erstellenden Kubernetes-Secret, z. B. Opaque, tls oder docker-registry. Dadurch wird festgelegt, wie Kubernetes die Secret-Daten verarbeitet.
   • sourcePath: der lokale Dateiname oder Alias (der Wert des Felds path in der SecretProviderClass), der die abzurufenden Secret-Daten identifiziert. Der SecretSync-Controller verwendet diesen sourcePath, um den spezifischen Secret-Inhalt anzufordern und in ein neues Kubernetes-Secret zu konvertieren.
   • targetKey: der Schlüssel, der im Abschnitt data des neu erstellten Kubernetes-Secret verwendet wird. Dadurch wird definiert, wie der mit sourcePath abgerufene Secret-Inhalt benannt und im endgültigen Kubernetes-Secret-Objekt gespeichert wird. Mit mehreren Einträgen im Datenarray können Sie mehrere Schlüssel/Wert-Paare innerhalb desselben Ziel-Secret definieren.

6. Führen Sie den folgenden Befehl aus, um das Manifest anzuwenden:

   kubectl apply -f secret-sync.yaml
   

   Der Synchronisierungscontroller erstellt ein Kubernetes-Secret im angegebenen Namespace. Dieses Secret enthält die aus Secret Manager zugeordneten Daten.

7. Prüfen Sie, ob das Kubernetes-Secret erstellt wurde:

   kubectl get secret KUBERNETES_SECRET_NAME -n NAMESPACE -o yaml
   

   Ersetzen Sie Folgendes:

   • KUBERNETES_SECRET_NAME: der Name des neuen Kubernetes-Secret
   • NAMESPACE: der Kubernetes-Namespace, in dem das neue Secret erstellt wird

8. Verwenden Sie den folgenden Befehl, um ein Synchronisierungsproblem zu beheben:

   kubectl describe secretSync KUBERNETES_SECRET_NAME -n NAMESPACE
   

   Ersetzen Sie Folgendes:

   • KUBERNETES_SECRET_NAME: der Name des neuen Kubernetes-Secret
   • NAMESPACE: der Kubernetes-Namespace, in dem das neue Secret vorhanden sein sollte

Hinweis: Wenn Sie VPC Service Controls verwenden, um die Secret Manager API einzuschränken und beim Verwenden dieser Funktion Ingress-Verstöße auftreten, verhindert Ihr Dienstperimeter möglicherweise den Zugriff auf die Secret Manager API aus einem Projekt das nicht Teil des Perimeters ist. Wenden Sie sich an den Google Cloud Support, wenn die Probleme weiter auftreten.

Secret-Rotation verwalten

Wenn Sie das Flag --enable-secret-sync-rotation aktivieren in Ihrem Cluster, prüft der Synchronisierungscontroller regelmäßig in Secret Manager nach neuen Versionen der in der SecretProviderClass-Ressource angegebenen Secrets. Das Flag --secret-sync-rotation-interval bestimmt, wie oft der Controller nach Updates sucht.

Wenn der Controller eine neue Secret-Version in Secret Manager erkennt, aktualisiert er das entsprechende Kubernetes-Secret. Der Controller vergleicht Hashes des Secret-Inhalts, um Secrets nur bei Änderungen zu aktualisieren.

Anwendungen, die diese Secrets verwenden, müssen die aktualisierten Secret-Werte aus dem Kubernetes-Secret erkennen und neu laden. Wie dies gehandhabt wird, hängt vom Design der Anwendung ab.

Secret-Synchronisierung deaktivieren

Führen Sie den folgenden gcloud CLI-Befehl aus, um die Secret-Synchronisierung zu deaktivieren:

gcloud

Um Secret Manager in der Befehlszeile zu verwenden, installieren Sie zuerst die Google Cloud CLI Version 378.0.0 oder höher oder aktualisieren Sie darauf. In Compute Engine oder GKE müssen Sie sich mit dem Bereich cloud-platform authentifizieren.

gcloud container clusters update CLUSTER_NAME \
    --location=CONTROL_PLANE_LOCATION \
    --no-enable-secret-sync

Ersetzen Sie Folgendes:

• CLUSTER_NAME: der Name Ihres GKE-Cluster
• CONTROL_PLANE_LOCATION: die Region oder Zone Ihrer Cluster-Steuerungsebene, z. B. us-central1 oder us-east1-a

Mit diesem Befehl wird der Synchronisierungscontroller beendet. Bereits erstellte Kubernetes-Secrets werden nicht gelöscht. Sie müssen alle synchronisierten Kubernetes-Secrets manuell löschen, wenn Sie sie nicht mehr benötigen.

Synchronisierte Secrets löschen

Wenn Sie ein synchronisiertes Kubernetes-Secret löschen möchten, löschen Sie die SecretSync-Ressource mit dem folgenden Befehl:

    kubectl delete secretsync KUBERNETES_SECRET_NAME --namespace NAMESPACE

Ersetzen Sie Folgendes:

• KUBERNETES_SECRET_NAME: der Name des Kubernetes-Secret
• NAMESPACE: der Kubernetes-Namespace, in dem das Secret vorhanden ist

Von vorhandenem CSI-Treiber für Secrets-Speicher migrieren

Wenn Sie von Ihrer vorhandenen Installation des CSI-Treibers für Secrets-Speicher migrieren, gehen Sie so vor:

1. Aktualisieren Sie das Feld provider in Ihrer SecretProviderClass von gcp zu gke. Im folgenden Beispiel wird gezeigt, wie Sie das Feld provider aktualisieren:

   apiVersion: secrets-store.csi.x-k8s.io/v1
   kind: SecretProviderClass
   metadata:
     name: app-secrets-gke
   spec:
     provider: gke
     parameters:
       secrets: |
         -   resourceName: "projects/87654321/secrets/api-key-secret/versions/2"
             path: "good1.txt"
   

2. Erstellen Sie eine SecretSync-Ressource. Verwenden Sie die folgende Beispielkonfiguration:

   apiVersion: secret-sync.gke.io/v1
   kind: SecretSync
   metadata:
     name: my-kube-secret
     namespace: NAMESPACE
   spec:
     serviceAccountName: KSA_NAME
     secretProviderClassName: my-app-secrets
     secretObject:
       type: Opaque # Or other Kubernetes Secret types
       data:
         -   sourcePath: "my-secret.txt"
             targetKey: "USERNAME"
         -   sourcePath: "another-secret.txt"
             targetKey: "PASSWORD"
   

Sicherheitsaspekte

Secret Manager bietet Sicherheitsfunktionen wie die Zugriffssteuerung mit IAM, kundenverwaltete Verschlüsselungsschlüssel (Customer-Managed Encryption Keys, CMEK) und Audit-Logging. Secrets werden in Secret Manager im Ruhezustand und bei der Übertragung verschlüsselt. Wenn Sie Secrets mit Kubernetes-Secrets synchronisieren, hängt ihre Sicherheit im Cluster von der Konfiguration Ihres GKE-Cluster ab. Berücksichtige Folgendes:

• Speicher: Kubernetes-Secrets werden in etcd gespeichert, dem primären Datenspeicher von GKE. Standardmäßig verschlüsselt GKE alle inaktiven Daten. Für mehr Sicherheit, können Sie Kubernetes-Secrets auf Anwendungsebene verschlüsseln mit einem Schlüssel, den Sie in Cloud Key Management Service(Cloud KMS) verwalten. Durch das Verschlüsseln von Secrets wird eine zusätzliche Sicherheitsebene für vertrauliche Arbeitslasten geschaffen.

• Zugriffssteuerung: GKE unterstützt mehrere Optionen zum Verwalten des Zugriffs auf Ressourcen in Projekten und deren Clustern mithilfe der rollenbasierten Zugriffssteuerung (Role-Based Access Control, RBAC). Zu weit gefasste RBAC-Berechtigungen können Secrets für unbeabsichtigte Arbeitslasten oder Nutzer zugänglich machen. Gewähren Sie Zugriff nach dem Prinzip der geringsten Berechtigung und prüfen Sie regelmäßig den Zugriff auf Secret Manager und die Kubernetes-Secrets.

• Umgebungsvariablen: Um die Sicherheit zu verbessern, sollten Sie Kubernetes-Secrets als Volumes bereitstellen, anstatt sie als Umgebungsvariablen zu verwenden. Dadurch wird das Risiko einer versehentlichen Protokollierung oder Offenlegung gegenüber anderen Prozessen verringert.

Nächste Schritte

• Weitere Informationen zu Kubernetes-Secrets
• Weitere Informationen zur Workload Identity