Auf Cloud Storage-Buckets mit dem Cloud Storage FUSE-CSI-Treiber zugreifen

Filesystem in Userspace (FUSE) ist eine Schnittstelle zum Exportieren eines Dateisystems in den Linux-Kernel. Mit Cloud Storage FUSE können Sie Cloud Storage-Buckets als Dateisystem bereitstellen, sodass Anwendungen über gängige Datei-E/A-Vorgänge auf die Objekte in einem Bucket zugreifen können (z. B. Öffnen, Lesen, Schreiben, Schließen anstatt Cloud-spezifische APIs.

Mit dem Cloud Storage FUSE CSI-Treiber können Sie die Kubernetes API verwenden, um bereits vorhandene Cloud Storage-Buckets als Volumes zu nutzen. Ihre Anwendungen können Objekte mithilfe der Cloud Storage FUSE-Dateisystemsemantik hochladen und herunterladen. Der CSI-Treiber für Cloud Storage FUSE bietet eine vollständig verwaltete Umgebung, die auf dem Open Source Google Cloud Storage FUSE CSI-Treiber basiert.

Der Treiber unterstützt nativ die folgenden Möglichkeiten zur Konfiguration Ihrer Cloud Storage-gestützten Volumes:

Sie können den Cloud Storage FUSE CSI-Treiber mit Datei-Caching verwenden, um die Leseleistung von Anwendungen zu verbessern, die kleine Dateien aus Cloud Storage-Buckets verarbeiten. Das Datei-Cache-Feature von Cloud Storage FUSE ist ein clientbasierter Lese-Cache, mit dem wiederkehrende Dateilesevorgänge schneller aus dem Cache-Speicher Ihrer Wahl bereitgestellt werden können. Je nach Ihren Preis-Leistungs-Anforderungen können Sie aus einer Reihe von Speicheroptionen für den Lese-Cache auswählen, einschließlich lokaler SSDs und Persistent Disk-basierter Speicher. Sie müssen das Datei-Caching mit dem CSI-Treiber für Cloud Storage FUSE aktivieren. Weitere Informationen zu Best Practices für das Caching finden Sie unter Leistung und Best Practices für Cloud Storage FUSE.

Vorteile

  • Der Cloud Storage FUSE CSI-Treiber auf Ihrem Cluster aktiviert die automatische Bereitstellung und Verwaltung des Treibers. Der Treiber funktioniert sowohl mit Standard- als auch mit Autopilot-Clustern.
  • Der Cloud Storage FUSE CSI-Treiber benötigt keinen privilegierten Zugriff, der für FUSE-Clients normalerweise erforderlich ist. Dies ermöglicht eine bessere Sicherheitslage.
  • Die Unterstützung für sitzungsspezifische CSI-Volumes vereinfacht die Konfiguration und Verwaltung des Volumes, da auf PersistentVolumeClaim- und PersistentVolume-Objekte verzichtet wird.
  • Der Cloud Storage FUSE CSI-Treiber unterstützt die Zugriffsmodi ReadWriteMany, ReadOnlyMany und ReadWriteOnce.
  • Sie können Workload Identity Federation for GKE verwenden, um die Authentifizierung zu verwalten und gleichzeitig genau zu steuern, wie Ihre Pods auf Cloud Storage-Objekte zugreifen.
  • Wenn Sie ML-Training und die Bereitstellung von Arbeitslasten mit Frameworks wie Ray, PyTorch, Spark und TensorFlow ausführen, können Sie die vom Cloud Storage FUSE CSI-Treiber bereitgestellte Übertragbarkeit und Einfachheit nutzen, um Ihre Arbeitslasten direkt ohne zusätzliche Codeänderungen auf Ihren GKE-Clustern auszuführen.
  • Sie können Cloud Storage-Objekte mit aktiviertem Datei-Caching lesen, um die Leseleistung zu erhöhen. Weitere Informationen zu den Vorteilen des Datei-Caching finden Sie in der Dokumentation zu Cloud Storage FUSE.
  • Sie können Cloud Storage FUSE-Volumes in init-Containern nutzen.

Hinweise

Führen Sie die folgenden Aufgaben aus, 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.
  • Cloud Storage-Buckets erstellen Zur Verbesserung der Leistung setzen Sie das Feld Location type auf Region und wählen eine Region aus, in der Ihr GKE-Cluster ausgeführt wird.

Beschränkungen

  • Das Cloud Storage FUSE-Dateisystem unterscheidet sich im Vergleich zu einem POSIX-Dateisystem über Leistung, Verfügbarkeit, Zugriffsautorisierung und Semantik.
  • Der Cloud Storage FUSE CSI-Treiber wird in GKE Sandbox nicht unterstützt.
  • Der Cloud Storage FUSE CSI-Treiber unterstützt keine Volume-Snapshots, Volume-Klonen oder Volume-Erweiterungen.
  • Sehen Sie sich die bekannten Probleme im GitHub-Projekt des Cloud Storage FUSE CSI-Treibers an.
  • Sehen Sie sich die offenen Probleme im GitHub-Projekt des Cloud Storage FUSE CSI-Treibers an. Die Probleme werden gesichtet und in zukünftigen Updates behoben.

Voraussetzungen

Damit Sie den CSI-Treiber für Cloud Storage FUSE verwenden können, müssen Ihre Cluster die folgenden Anforderungen erfüllen:

CSI-Treiber für Cloud Storage FUSE aktivieren

Zum Erstellen eines Standardclusters mit aktiviertem Cloud Storage FUSE CSI-Treiber können Sie die gcloud CLI verwenden:

gcloud container clusters create CLUSTER_NAME \
    --addons GcsFuseCsiDriver \
    --cluster-version=VERSION \
    --location=LOCATION \
    --workload-pool=PROJECT_ID.svc.id.goog

Ersetzen Sie Folgendes:

  • CLUSTER_NAME: Der Name Ihres Clusters.
  • VERSION: Die GKE-Versionsnummer. Sie müssen mindestens 1.24 auswählen.
  • LOCATION: der Compute Engine-Standort für den Cluster.
  • PROJECT_ID: Ihre Projekt-ID.

Verwenden Sie den Befehl gcloud container clusters update, um den Treiber auf einem vorhandenen Cluster zu aktivieren:

gcloud container clusters update CLUSTER_NAME \
    --update-addons GcsFuseCsiDriver=ENABLED \
    --location=LOCATION

Ersetzen Sie Folgendes:

Nachdem Sie den CSI-Treiber für Cloud Storage FUSE aktiviert haben, können Sie den Treiber in Kubernetes-Volumes verwenden. Geben Sie dazu den Treiber- und den Bereitstellernamen an: gcsfuse.csi.storage.gke.io.

Zugriff auf Cloud Storage-Buckets mit GKE Workload Identity Federation for GKE konfigurieren

So machen Sie Ihre Cloud Storage-Buckets für Ihren GKE-Cluster mithilfe Workload Identity Federation for GKE zugänglich: Weitere Informationen finden Sie unter Anwendungen für die Verwendung von Workload Identity Federation for GKE konfigurieren.

  1. Rufen Sie Anmeldedaten für Ihren Cluster ab:

    gcloud container clusters get-credentials CLUSTER_NAME \
    --location=LOCATION

    Ersetzen Sie Folgendes:

    • CLUSTER_NAME: Der Name Ihres Clusters, für den Workload Identity Federation for GKE aktiviert ist.
    • LOCATION: der Compute Engine-Standort für den Cluster.

  2. Erstellen Sie einen Namespace, der für das Kubernetes-Dienstkonto verwendet werden soll. Sie können auch den Namespace default oder einen vorhandenen Namespace verwenden.

    kubectl create namespace NAMESPACE

    Ersetzen Sie Folgendes:

    • NAMESPACE: der Name des Kubernetes-Namespace für das Kubernetes-ServiceAccount.

  3. Erstellen Sie ein Kubernetes-ServiceAccount für die Anwendung: Sie können auch ein beliebiges Kubernetes-Dienstkonto in einem beliebigen Namespace verwenden, einschließlich des Kubernetes-Dienstkontos default.

    kubectl create serviceaccount KSA_NAME \
    --namespace NAMESPACE

    Ersetzen Sie Folgendes:

    • KSA_NAME: der Name des neuen Kubernetes-ServiceAccount.
    • NAMESPACE: der Name des Kubernetes-Namespace für das Kubernetes-ServiceAccount.

  4. Weisen Sie dem Kubernetes-Dienstkonto eine der IAM-Rollen für Cloud Storage zu.

    Mit folgendem Befehl können Sie Ihrem Kubernetes-Dienstkonto eine Rolle zuweisen, die nur für den Zugriff auf einen bestimmten Cloud Storage-Bucket berechtigt:

    gcloud storage buckets add-iam-policy-binding gs://BUCKET_NAME \
    --member "principal://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/PROJECT_ID.svc.id.goog/subject/ns/NAMESPACE/sa/KSA_NAME" \
    --role "ROLE_NAME"

    Ersetzen Sie Folgendes:

    • BUCKET_NAME: Name Ihres Cloud Storage-Buckets.
    • PROJECT_NUMBER: Die numerische Projektnummer Ihres GKE-Clusters. Ihre Projektnummer finden Sie unter Projekte identifizieren.
    • PROJECT_ID: Die Projekt-ID Ihres GKE-Clusters.
    • NAMESPACE: der Name des Kubernetes-Namespace für das Kubernetes-ServiceAccount.
    • KSA_NAME: der Name des neuen Kubernetes-ServiceAccount.
    • ROLE_NAME: Die IAM-Rolle, die Ihrem Kubernetes-Dienstkonto zugewiesen werden soll.
      • Verwenden Sie für schreibgeschützte Arbeitslasten die Rolle "Storage-Objekt-Betrachter" (roles/storage.objectViewer).
      • Verwenden Sie für Lese-/Schreibarbeitslasten die Rolle „Storage-Objekt-Nutzer“ (roles/storage.objectUser).

    Optional können Sie die Rolle Ihrem Kubernetes-Dienstkonto zuweisen, um mit folgendem Befehl auf alle Cloud Storage-Buckets im Projekt zuzugreifen:

    gcloud projects add-iam-policy-binding GCS_PROJECT \
    --member "principal://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/PROJECT_ID.svc.id.goog/subject/ns/NAMESPACE/sa/KSA_NAME" \
    --role "ROLE_NAME"

    Ersetzen Sie Folgendes:

    • GCS_PROJECT: Die Projekt-ID Ihrer Cloud Storage-Buckets.
    • PROJECT_NUMBER: Die numerische Projektnummer Ihres GKE-Clusters. Ihre Projektnummer finden Sie unter Projekte identifizieren.
    • PROJECT_ID: Die Projekt-ID Ihres GKE-Clusters.
    • NAMESPACE: der Name des Kubernetes-Namespace für das Kubernetes-ServiceAccount.
    • KSA_NAME: der Name des neuen Kubernetes-ServiceAccount.
    • ROLE_NAME: Die IAM-Rolle, die Ihrem Kubernetes-Dienstkonto zugewiesen werden soll.
      • Verwenden Sie für schreibgeschützte Arbeitslasten die Rolle "Storage-Objekt-Betrachter" (roles/storage.objectViewer).
      • Verwenden Sie für Lese-/Schreibarbeitslasten die Rolle „Storage-Objekt-Nutzer“ (roles/storage.objectUser).

Bereitstellung von Cloud Storage FUSE-Buckets vorbereiten

In diesem Abschnitt wird beschrieben, wie Sie die Bereitstellung von Cloud Storage FUSE-Buckets auf Ihren Clustern vorbereiten.

Pod-Annotationen angeben

Der CSI-Treiber greift auf Pod-Annotationen zurück, um zu ermitteln, ob Ihr Pod Cloud Storage-gestützte Volumes verwendet. Wenn der Treiber die erforderlichen Annotationen erkennt, wird ein Sidecar-Container namens gke-gcsfuse-sidecar in Ihren Arbeitslast-Pod eingefügt. Die Cloud Storage FUSE-Instanzen werden im Sidecar-Container ausgeführt und stellen die Cloud Storage-Buckets für Ihre Arbeitslast bereit.

Damit der CSI-Treiber die Cloud Storage-Buckets bereitstellen kann, müssen Sie die Annotation gke-gcsfuse/volumes: "true" in Ihrer Pod-Spezifikation unter dem Feld metadata angeben. Wenn Sie möchten, dass Ihre Cloud-Storage-gesicherten Volumes von anderen Kubernetes-Arbeitslasttypen (z. B. Job, Deploymentoder StatefulSet) genutzt werden, stellen Sie sicher, dass Sie die Annotationen im Feld spec.template.metadata.annotations konfigurieren.

Ressourcen für den Sidecar-Container konfigurieren

Standardmäßig ist der Sidecar-Container mit den folgenden Ressourcenanfragen konfiguriert, wobei Ressourcenlimits nicht festgelegt sind:

  • 250 mCPU
  • 256 MiB Arbeitsspeicher
  • Sitzungsspezifischer 5 GiB-Speicher

Wenn Sie diese Werte überschreiben möchten, können Sie optional die Annotation gke-gcsfuse/[cpu-limit|memory-limit|ephemeral-storage-limit|cpu-request|memory-request|ephemeral-storage-request] angeben, wie im folgenden Beispiel gezeigt:

apiVersion: v1
kind: Pod
metadata:
  annotations:
    gke-gcsfuse/volumes: "true"
    gke-gcsfuse/cpu-limit: "10"
    gke-gcsfuse/memory-limit: 10Gi
    gke-gcsfuse/ephemeral-storage-limit: 1Ti
    gke-gcsfuse/cpu-request: 500m
    gke-gcsfuse/memory-request: 1Gi
    gke-gcsfuse/ephemeral-storage-request: 50Gi

Berücksichtigen Sie die folgenden Überlegungen, wenn Sie die Menge der zuzuweisenden Ressourcen festlegen:

  • Wenn Sie nur entweder Ressourcenanfrage-Annotation oder Limit-Annotation festlegen, erzwingt GKE dieselben Werte für die Ressourcenanfrage und das Ressourcenlimit.
  • Wenn Ihr Arbeitslast-Pod mehrere Cloud Storage-Volumes verbraucht, werden die Sidecar-Container-Ressourcen von mehreren Cloud Storage-FUSE-Instanzen gemeinsam genutzt. Wenn dies auf Sie zutrifft, sollten Sie die Ressourcenzuweisung für mehrere Cloud Storage-Volumes erhöhen.
  • Weisen Sie dem Sidecar-Container mehr CPU zu, wenn Ihre Arbeitslasten einen höheren Durchsatz benötigen. Eine unzureichende CPU führt zu einer Drosselung durch Cloud Storage FUSE.
  • Wenn Ihre Arbeitslasten eine große Anzahl von Dateien verarbeiten müssen und das Metadaten-Caching von Cloud Storage FUSE aktiviert ist, erhöhen Sie die Arbeitsspeicherzuweisung des Sidecar-Containers. Der Arbeits-Speicherverbrauch von Cloud Storage FUSE für das Metadaten-Caching ist proportional zur Anzahl der Dateien, aber nicht zur Dateigröße. Unzureichender Arbeits-Speicher führt zu einem Fehler aufgrund fehlenden Speichers in Cloud Storage FUSE und zum Absturz der Arbeitslastanwendung.
  • Zum Caching von Dateien speichert Cloud Storage FUSE die Dateien standardmäßig in einem lokalen temporären Verzeichnis. Schätzen Sie, wie viel freier Speicherplatz Ihre Arbeitslast für das Datei-Caching benötigt, und erhöhen Sie das flüchtige Speicherlimit entsprechend. Weitere Informationen finden Sie unter Volume-Attribute.
  • Bei Schreibvorgängen stellt Cloud Storage FUSE die Dateien in einem lokalen temporären Verzeichnis bereit, bevor die Dateien in den Cloud Storage-Bucket hochgeladen werden. Schätzen Sie, wie viel freier Speicherplatz Ihre Arbeitslast für das Staging beim Schreiben großer Dateien benötigt, und erhöhen Sie das flüchtige Speicherlimit entsprechend. Weitere Informationen finden Sie unter Lese-/Schreib-Semantik in der GitHub-Dokumentation zu Cloud Storage FUSE.
  • Mit dem Wert "0" können Sie Ressourcenlimits oder Anfragen in Standardclustern aufheben. Die Annotation gke-gcsfuse/memory-limit: "0" lässt beispielsweise das Arbeits-Speicherlimit des Sidecar-Containers bei der Standardarbeitsspeicheranforderung leer. Dies ist nützlich, wenn Sie nicht entscheiden können, wie viele Ressourcen Cloud Storage FUSE für Ihre Arbeitslasten benötigt, und Cloud Storage FUSE alle verfügbaren Ressourcen auf einem Knoten nutzen darf. Nachdem Sie die Ressourcenanforderungen für Cloud Storage FUSE anhand Ihrer Arbeitslastmesswerte berechnet haben, können Sie geeignete Limits festlegen.

Privates Image für den Sidecar-Container konfigurieren

In diesem Abschnitt wird beschrieben, wie Sie das Sidecar-Container-Image verwenden, wenn Sie es in einer privaten Container Registry hosten. Dieses Szenario kann zutreffen, wenn Sie private Cluster für Sicherheitszwecke verwenden müssen oder wenn Ihr Cluster eingeschränkten Zugriff auf das öffentliche Internet hat. So konfigurieren und verwenden Sie das private Sidecar-Container-Image:

  1. Auf dieser Seite finden Sie ein kompatibles öffentliches Sidecar-Container-Image.

  2. Rufen Sie es in Ihrer lokalen Umgebung ab und übertragen Sie es in Ihre private Container Registry.

  3. Geben Sie im Manifest einen Container mit dem Namen gke-gcsfuse-sidecar an, der nur das Feld image enthält. GKE verwendet das angegebene Sidecar-Container-Image, um sich auf die Sidecar-Container-Injektion vorzubereiten. Hier ein Beispiel:

apiVersion: v1
kind: Pod
metadata:
  annotations:
    gke-gcsfuse/volumes: "true"
spec:
  containers:
  - name: gke-gcsfuse-sidecar
    image: PRIVATE_REGISTRY/gcs-fuse-csi-driver-sidecar-mounter:PRIVATE_IMAGE_TAG
  - name: main # your main workload container.

Ersetzen Sie Folgendes:

  • PRIVATE_REGISTRY: Ihre private Container Registry.
  • PRIVATE_IMAGE_TAG: durch Ihr privates Sidecar-Container-Image-Tag.

Benutzerdefiniertes Schreib-Zwischenspeicher-Volume für den Sidecar-Container konfigurieren

In diesem Abschnitt wird beschrieben, wie Sie ein benutzerdefiniertes Zwischenspeicher-Volume für die Schreibvorgangzwischenspeicherung in Cloud Storage FUSE konfigurieren. Dieses Szenario kann zutreffen, wenn Sie das Standard-Volume emptyDir für Cloud Storage FUSE ersetzen müssen, um die Dateien in Schreibvorgängen bereitzustellen. Sie können jeden von GKE unterstützten Speichertyp angeben, z. B. PersistentVolumeClaim. GKE verwendet das angegebene Volume für die Zwischenspeicherung von Dateischreibvorgängen. Dies ist nützlich, wenn Sie Dateien mit mehr als 10 GiB in Autopilot-Cluster schreiben müssen. Wenn Sie das benutzerdefinierte Zwischenspeicher-Volume verwenden möchten, müssen Sie fsGroup ungleich null angeben. Das folgende Beispiel zeigt, wie Sie einen vordefinierten PVC als Zwischenspeicher-Volume verwenden können:

apiVersion: v1
kind: Pod
metadata:
  annotations:
    gke-gcsfuse/volumes: "true"
spec:
  securityContext:
    fsGroup: FS_GROUP
  containers:
  ...
  volumes:
  - name: gke-gcsfuse-buffer
    persistentVolumeClaim:
      claimName: BUFFER_VOLUME_PVC

Ersetzen Sie Folgendes:

  • FS_GROUP: die fsGroup-ID.
  • BUFFER_VOLUME_PVC ist der Name des vordefinierten PVC.

Benutzerdefiniertes Lese-Cache-Volume für den Sidecar-Container konfigurieren

In diesem Abschnitt wird beschrieben, wie Sie ein benutzerdefiniertes Cache-Volume für das Lese-Caching von Cloud Storage FUSE konfigurieren. Dieses Szenario kann zutreffen, wenn Sie das Standard-Volume emptyDir für Cloud Storage FUSE ersetzen müssen, um die Dateien in Lesevorgängen im Cache zu speichern. Sie können jeden von GKE unterstützten Speichertyp angeben, z. B. PersistentVolumeClaim. GKE verwendet das angegebene Volume für das Datei-Caching. Dies ist nützlich, wenn Sie Dateien mit mehr als 10 GiB in Autopilot-Clustern im Cache speichern müssen. Wenn Sie das benutzerdefinierte Cache-Volume verwenden möchten, müssen Sie fsGroup ungleich null angeben. Das folgende Beispiel zeigt, wie Sie einen vordefinierten PVC als Cache-Volume verwenden können:

apiVersion: v1
kind: Pod
metadata:
  annotations:
    gke-gcsfuse/volumes: "true"
spec:
  securityContext:
    fsGroup: FS_GROUP
  containers:
  ...
  volumes:
  - name: gke-gcsfuse-cache
    persistentVolumeClaim:
      claimName: CACHE_VOLUME_PVC

Ersetzen Sie Folgendes:

  • FS_GROUP: die fsGroup-ID.
  • CACHE_VOLUME_PVC ist der Name des vordefinierten PVC.

Volume als sitzungsspezifisches CSI-Volume bereitstellen

Sitzungsspezifische CSI-Volumes sind an den Pod-Lebenszyklus gebunden. Bei diesem Bereitstellungsansatz müssen Sie die PersistentVolume- und PersistentVolumeClaim-Objekte, die den Cloud Storage-Buckets zugeordnet sind, nach der Pod-Beendigung nicht beibehalten.

Sitzungsspezifisches CSI-Speicher-Volume in einem Pod verwenden

  1. Speichern Sie das folgende YAML-Manifest:

    apiVersion: v1
kind: Pod
metadata:
  name: gcs-fuse-csi-example-ephemeral
  namespace: NAMESPACE
  annotations:
    gke-gcsfuse/volumes: "true"
spec:
  terminationGracePeriodSeconds: 60
  containers:
  - image: busybox
    name: busybox
    command: ["sleep"]
    args: ["infinity"]
    volumeMounts:
    - name: gcs-fuse-csi-ephemeral
      mountPath: /data
      readOnly: true
  serviceAccountName: KSA_NAME
  volumes:
  - name: gcs-fuse-csi-ephemeral
    csi:
      driver: gcsfuse.csi.storage.gke.io
      readOnly: true
      volumeAttributes:
        bucketName: BUCKET_NAME
        mountOptions: "implicit-dirs"
        gcsfuseLoggingSeverity: warning

    Das vorherige Beispiel zeigt, wie Sie den Cloud Storage-Bucket inline im Pod-Manifest angeben können. Das Beispiel enthält die folgenden Felder:

    • metadata.annotations: Die Annotation gke-gcsfuse/volumes: "true" ist erforderlich. Optionale Annotationen finden Sie unter Ressourcen für den Sidecar-Container konfigurieren.
    • spec.terminationGracePeriodSeconds: Optional. Standardmäßig ist dies auf 30 eingestellt. Wenn Sie große Dateien in den Cloud Storage-Bucket schreiben müssen, erhöhen Sie diesen Wert, damit Cloud Storage FUSE genügend Zeit hat, um die Daten nach dem Beenden Ihrer Anwendung zu leeren. Weitere Informationen finden Sie im Blog Kubernetes best practices: Termining withrace.
    • spec.serviceAccountName: Verwenden Sie dasselbe Kubernetes-Dienstkonto wie im Schritt Zugriff auf Cloud Storage-Buckets mit der GKE Workload Identity Federation for GKE konfigurieren.
    • spec.volumes[n].csi.driver: Verwenden Sie gcsfuse.csi.storage.gke.io als CSI-Treibernamen.
    • spec.volumes[n].csi.volumeAttributes.bucketName: Geben Sie den Namen des Cloud Storage FUSE-Buckets an. Sie können einen Unterstrich (_) angeben, um alle Buckets bereitzustellen, auf die das Kubernetes-Dienstkonto zugreifen kann. Weitere Informationen finden Sie unter Dynamische Bereitstellung in der Dokumentation zu Cloud Storage FUSE.
    • spec.volumes[n].csi.volumeAttributes.mountOptions: Optional. Übergeben Sie Optionen zur Bereitstellung an Cloud Storage FUSE. Geben Sie die Flags in einem String durch Kommas getrennt ohne Leerzeichen an.
    • spec.volumes[n].csi.volumeAttributes: Optional. Übergeben Sie andere Volume-Attribute an Cloud Storage FUSE.
    • spec.volumes[n].csi.readOnly: Optional. Geben Sie true an, wenn alle Volume-Bereitstellungen schreibgeschützt sind.
    • spec.containers[n].volumeMounts[m].readOnly: Optional. Geben Sie true an, wenn nur eine bestimmte Volume-Bereitstellung schreibgeschützt ist.

  2. Wenden Sie das Manifest auf den Cluster an:

    kubectl apply -f FILE_PATH

    Ersetzen Sie FILE_PATH durch den Pfad zur YAML-Datei.

Sitzungsspezifisches CSI-Speicher-Volume in einer Jobarbeitslast verwenden

  1. Speichern Sie das folgende YAML-Manifest:

    apiVersion: batch/v1
kind: Job
metadata:
  name: gcs-fuse-csi-job-example
  namespace: NAMESPACE
spec:
  template:
    metadata:
      annotations:
        gke-gcsfuse/volumes: "true"
    spec:
      serviceAccountName: KSA_NAME
      containers:
      - name: writer
        image: busybox
        command:
          - "/bin/sh"
          - "-c"
          - touch /data/test && echo $(date) >> /data/test && sleep 10
        volumeMounts:
        - name: gcs-fuse-csi-ephemeral
          mountPath: /data
      - name: reader
        image: busybox
        command:
          - "/bin/sh"
          - "-c"
          - sleep 10 && cat /data/test
        volumeMounts:
        - name: gcs-fuse-csi-ephemeral
          mountPath: /data
          readOnly: true
      volumes:
      - name: gcs-fuse-csi-ephemeral
        csi:
          driver: gcsfuse.csi.storage.gke.io
          volumeAttributes:
            bucketName: BUCKET_NAME
      restartPolicy: Never
  backoffLimit: 1

    Ersetzen Sie Folgendes:

    Das Manifest stellt einen Job bereit, der einen Cloud Storage FUSE-Bucket über ein sitzungsspezifisches CSI-Volume nutzt.

  2. Wenden Sie das Manifest auf den Cluster an:

    kubectl apply -f FILE_PATH

    Ersetzen Sie FILE_PATH durch den Pfad zur YAML-Datei.

Wenn Sie den CSI-Treiber in einer Job-Arbeitslast verwenden oder wenn der Pod RestartPolicy den Wert Never hat, wird der Sidecar-Container automatisch beendet, nachdem alle anderen Arbeitslastcontainer beendet wurden.

Weitere Beispiele finden Sie in der GitHub-Projektdokumentation unter Beispielanwendungen.

Volume mit statischer Bereitstellung bereitstellen

Bei der statischen Bereitstellung erstellen Sie ein oder mehrere PersistentVolume-Objekte (PV-Objekte), die die Details des zugrunde liegenden Speichersystems enthalten. Pods in Ihren Clustern können dann den Speicher über PersistentVolumeClaims (PVCs) nutzen.

PersistentVolume erstellen

  1. Speichern Sie das folgende YAML-Manifest:

    apiVersion: v1
kind: PersistentVolume
metadata:
  name: gcs-fuse-csi-pv
spec:
  accessModes:
  - ReadWriteMany
  capacity:
    storage: 5Gi
  storageClassName: example-storage-class
  claimRef:
    namespace: NAMESPACE
    name: gcs-fuse-csi-static-pvc
  mountOptions:
    - implicit-dirs
  csi:
    driver: gcsfuse.csi.storage.gke.io
    volumeHandle: BUCKET_NAME
    volumeAttributes:
      gcsfuseLoggingSeverity: warning

    Das Beispielmanifest zeigt, wie Sie ein PersistentVolume für Cloud Storage-Buckets definieren können. Das Beispiel enthält die folgenden Felder:

    • spec.claimRef.namespace: Geben Sie den PersistentVolumeClaim-Namespace an.
    • spec.claimRef.name: Geben Sie den Namen des PersistentVolumeClaim an.
    • spec.csi.driver: Verwenden Sie gcsfuse.csi.storage.gke.io als Namen für den CSI-Treiber.
    • spec.csi.volumeHandle: Geben Sie den Namen Ihres Cloud Storage-Buckets an. Sie können einen Unterstrich (_) übergeben, um alle Buckets bereitzustellen, auf die das Kubernetes-Dienstkonto gemäß der Konfiguration Zugriff hat. Weitere Informationen finden Sie unter Dynamische Bereitstellung in der Dokumentation zu Cloud Storage FUSE.
    • spec.mountOptions: Optional. Übergeben Sie Optionen zur Bereitstellung an Cloud Storage FUSE.
    • spec.csi.volumeAttributes: Optional. Übergeben Sie Volume-Attribute an Cloud Storage FUSE.

  2. Wenden Sie das Manifest auf den Cluster an:

    kubectl apply -f FILE_PATH

    Ersetzen Sie FILE_PATH durch den Pfad zur YAML-Datei.

PersistentVolumeClaim erstellen

  1. Speichern Sie das folgende YAML-Manifest:

    apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: gcs-fuse-csi-static-pvc
  namespace: NAMESPACE
spec:
  accessModes:
  - ReadWriteMany
  resources:
    requests:
      storage: 5Gi
  volumeName: gcs-fuse-csi-pv
  storageClassName: example-storage-class

    Das Beispielmanifest zeigt, wie Sie einen PersistentVolumeClaim zum Binden des PersistentVolume definieren können. Das Beispiel enthält die folgenden Felder:

    • metadata.namespace: Geben Sie den PersistentVolumeClaim-Namespace an, der mit dem Namespace Ihrer Arbeitslast übereinstimmen muss.
    • spec.volumeName: Geben Sie den PersistentVolume-Namen an.

    Befolgen Sie die folgenden Richtlinien, um ein PersistentVolume an einen PersistentVolumeClaim zu binden:

    • Die spec.storageClassName-Felder in PV- und PVC-Manifesten sollten übereinstimmen. Der storageClassName muss sich nicht auf ein vorhandenes StorageClass-Objekt beziehen. Zum Binden der Anforderung an ein Volume können Sie einen beliebigen Namen verwenden, der aber nicht leer sein kann.
    • Die spec.accessModes-Felder in PV- und PVC-Manifesten sollten übereinstimmen.
    • spec.capacity.storage für das PersistentVolume-Manifest sollte mit spec.resources.requests.storage für das PersistentVolumeClaim-Manifest übereinstimmen. Da es bei Cloud Storage-Buckets keine Größenbeschränkung gibt, können Sie eine beliebige Anzahl von Kapazitäten eingeben. Diese dürfen aber nicht leer sein.

  2. Wenden Sie das Manifest auf den Cluster an:

    kubectl apply -f FILE_PATH

    Ersetzen Sie FILE_PATH durch den Pfad zur YAML-Datei.

Volume von einem PersistentVolumeClaim nutzen

  1. Speichern Sie das folgende YAML-Manifest:

    apiVersion: v1
kind: Pod
metadata:
  name: gcs-fuse-csi-example-static-pvc
  namespace: NAMESPACE
  annotations:
    gke-gcsfuse/volumes: "true"
spec:
  containers:
  - image: busybox
    name: busybox
    command: ["sleep"]
    args: ["infinity"]
    volumeMounts:
    - name: gcs-fuse-csi-static
      mountPath: /data
      readOnly: true
  serviceAccountName: KSA_NAME
  volumes:
  - name: gcs-fuse-csi-static
    persistentVolumeClaim:
      claimName: gcs-fuse-csi-static-pvc
      readOnly: true

    Das Beispiel zeigt, wie Sie einen Pod definieren, der einen Cloud Storage FUSE-Bucket über einen PersistentVolumeClaim nutzt. Das Beispiel enthält die folgenden Felder:

  2. Wenden Sie das Manifest auf den Cluster an:

    kubectl apply -f FILE_PATH

    Ersetzen Sie FILE_PATH durch den Pfad zur YAML-Datei.

Weitere Beispiele finden Sie in der GitHub-Projektdokumentation unter Beispielanwendungen.

Volumes mit aktiviertem Datei-Caching nutzen

Das Datei-Caching-Feature ist in GKE standardmäßig deaktiviert. Verwenden Sie das Volume-Attribut fileCacheCapacity, um das Datei-Caching zu aktivieren und zu steuern.

GKE verwendet ein emptyDir-Volume für das Caching von Cloud Storage FUSE-Dateien, das vom Bootlaufwerk der Knoten-VM unterstützt wird. Wenn Sie Lokale SSD auf dem Knoten aktivieren, verwendet GKE die lokale SSD zur Sicherung des Volumes emptyDir.

Sie können ein benutzerdefiniertes Lese-Cache-Volume für den Sidecar-Container konfigurieren, um das Standard-Volume emptyDir für das Datei-Caching in Lesevorgängen zu ersetzen. Für CPU- und GPU-VM-Familien mit Unterstützung für lokale SSDs empfehlen wir die Verwendung von lokalem SSD-Speicher. Für TPU-Familien oder Autopilot empfehlen wir die Verwendung von abgestimmtem nichtflüchtigen Speicher oder nichtflüchtigen SSD-Speicher.

Sitzungsspezifisches CSI-Speicher-Volume mit aktiviertem Datei-Caching verwenden

So stellen Sie einen Pod bereit, der einen Cloud Storage FUSE-Bucket über ein sitzungsspezifisches CSI-Volume mit Datei-Caching nutzt:

  1. Erstellen Sie einen Cluster oder Knotenpool mit sitzungsspezifischem lokalen SSD-Speicher.

    Folgen Sie der GKE-Dokumentation, um einen Cluster oder Knotenpool mit sitzungsspezifischem lokalem SSD-Speicher zu erstellen.

  2. Speichern Sie das folgende YAML-Manifest:

    apiVersion: v1
kind: Pod
metadata:
  name: gcs-fuse-csi-file-cache-example
  namespace: NAMESPACE
  annotations:
    gke-gcsfuse/volumes: "true"
    gke-gcsfuse/ephemeral-storage-limit: "50Gi"
spec:
  nodeSelector:
    cloud.google.com/gke-ephemeral-storage-local-ssd: "true"
  restartPolicy: Never
  initContainers:
  - name: data-loader
    image: gcr.io/google.com/cloudsdktool/google-cloud-cli:slim
    resources:
      limits:
        cpu: 500m
        memory: 1Gi
      requests:
        cpu: 500m
        memory: 1Gi
    command:
      - "/bin/sh"
      - "-c"
      - |
        mkdir -p /test_files
        for i in $(seq 1 1000); do dd if=/dev/zero of=/test_files/file_$i.txt bs=1024 count=64; done
        gsutil -m cp -r /test_files gs://BUCKET_NAME
  containers:
  - name: data-validator
    image: busybox
    resources:
      limits:
        cpu: 500m
        memory: 512Mi
      requests:
        cpu: 500m
        memory: 512Mi
    command:
      - "/bin/sh"
      - "-c"
      - |
        echo "first read with cache miss"
        time cat /data/test_files/file_* > /dev/null

        echo "second read from local cache"
        time cat /data/test_files/file_* > /dev/null
    volumeMounts:
    - name: gcs-fuse-csi-ephemeral
      mountPath: /data
  serviceAccountName: KSA_NAME
  volumes:
  - name: gcs-fuse-csi-ephemeral
    csi:
      driver: gcsfuse.csi.storage.gke.io
      volumeAttributes:
        bucketName: BUCKET_NAME
        mountOptions: "implicit-dirs"
        fileCacheCapacity: "10Gi"

    Ersetzen Sie Folgendes:

    Der init-Container data-loader generiert 1.000 Dateien mit einer Größe von 64 KiB und lädt die Dateien in einen Cloud Storage-Bucket hoch. Der Hauptcontainer data-validator liest alle Dateien aus dem Bucket zweimal und protokolliert die Dauer.

  3. Wenden Sie das Manifest auf den Cluster an:

    kubectl apply -f FILE_PATH

    Ersetzen Sie FILE_PATH durch den Pfad zur YAML-Datei.

  4. Führen Sie folgenden Befehl aus, um sich die Logausgabe anzeigen zu lassen:

    kubectl logs -n NAMESPACE gcs-fuse-csi-file-cache-example -c data-validator

    Ersetzen Sie NAMESPACE durch den Namespace Ihrer Arbeitslast.

    Die Ausgabe sieht in etwa so aus:

    first read with cache miss
real    0m 54.68s
...
second read from local cache
real    0m 0.38s
...

    Die Ausgabe zeigt, dass der zweite Lesevorgang mit dem lokalen Cache viel schneller ist als der erste Lesevorgang mit Cache-Fehler.

Bereitstellung von Cloud Storage FUSE-Buckets konfigurieren

In diesem Abschnitt wird beschrieben, wie Sie die Cloud Storage FUSE-Volumes konfigurieren können.

Bereitstellungsoptionen

Der Cloud Storage FUSE CSI-Treiber unterstützt Bereitstellungs-Flags, um zu konfigurieren, wie Cloud Storage-Buckets in Ihrem lokalen Dateisystem bereitgestellt werden. Eine vollständige Liste der unterstützten Bereitstellungs-Flags finden Sie in der Dokumentation zur gcsfuse-Befehlszeile.

Sie können die Bereitstellungs-Flags so angeben:

  • Im Feld spec.mountOptions für ein PersistentVolume-Manifest, wenn Sie die statische Bereitstellung verwenden.
  • Im Feld spec.volumes[n].csi.volumeAttributes.mountOptions, wenn Sie sitzungsspezifische CSI-Volumes verwenden.

Volume-Attribute

Mit dem Cloud Storage FUSE CSI-Treiber können Sie die Cloud Storage FUSE-Konfigurationsdatei nicht direkt angeben. Sie können einige Felder in der Konfigurationsdatei mit den folgenden Volume-Attributen konfigurieren. Die Werte werden in die Felder der Konfigurationsdatei übersetzt.

  • gcsfuseLoggingSeverity

    • Beschreibung: der Schweregrad der Logs, die Cloud Storage FUSE generieren soll, ausgedrückt als Enum. Wenn Sie bereits die Bereitstellungsoptionen debug_fuse, debug_fs oder debug_gcs verwenden, wird diese neue Konfiguration automatisch auf trace gesetzt. Dieses Volume-Attribut wird in das Feld logging:severity der Konfigurationsdatei übersetzt.

    • Gültige Werte (sortiert vom niedrigsten zum höchsten Schweregrad):

      • trace
      • debug
      • info
      • warning
      • error

    • Standardwert: info.

  • fileCacheCapacity

    • Beschreibung: Die maximale Größe, die der Dateicache verwenden darf. Wenn ein Wert ungleich null vorhanden ist, aktiviert dieses Volume-Attribut das Datei-Caching in Cloud Storage FUSE. Dieses Volume-Attribut wird in das Feld file-cache:max-size-mb der Konfigurationsdatei übersetzt.

    • Zulässige Werte:

      • Mengenwerte, z. B. 500Mi, 10Gi.
      • "-1": verwendet die gesamte verfügbare Kapazität des Cache-Volumes.
      • "0": Der Datei-Cache ist deaktiviert.

    • Standardwert: "0"

  • fileCacheForRangeRead

    • Beschreibung: Gibt an, ob das vollständige Objekt asynchron heruntergeladen und im Cache-Verzeichnis von Cloud Storage FUSE gespeichert werden soll, wenn der erste Lesevorgang aus einem Offset ungleich null erfolgt. Dies sollte auf "wahr" gesetzt sein, wenn Sie mehrere zufällige oder partielle Lesevorgänge ausführen möchten. Dieses Volume-Attribut wird in das Feld file-cache:cache-file-for-range-read der Konfigurationsdatei übersetzt.

    • Zulässige Werte:

      • Boolesche Werte im Stringformat: "true", "false".

    • Standardwert: "false".

  • metadataStatCacheCapacity

    • Beschreibung: Die maximale Größe, die der Statistik-Cache verwenden darf. Der Statistik-Cache befindet sich immer vollständig im Arbeitsspeicher. Wenn Sie die Bereitstellungsoption stat-cache-capacity bereits verwenden, wird der Wert weiterhin berücksichtigt und entsprechend in diese neue Konfiguration übersetzt. Dieses Volume-Attribut wird in das Feld metadata-cache:stat-cache-max-size-mb der Konfigurationsdatei übersetzt.

    • Zulässige Werte:

      • Mengenwerte, z. B. 500Mi, 1Gi.
      • „-1“: Damit der Statistik-Cache so viel Arbeitsspeicher wie nötig verwendet.
      • „0“: Der Statistik-Cache ist deaktiviert.
      • Verwenden Sie den Standardwert 32Mi,wenn Ihre Arbeitslast bis zu 20.000 Dateien umfasst. Wenn Ihre Arbeitslast mehr als 20.000 Dateien enthält, erhöhen Sie die Größe um Werte von 10 MiB pro weitere 6.000 Dateien, also durchschnittlich etwa 1.500 Byte pro Datei.

    • Standardwert: 32Mi.

  • metadataTypeCacheCapacity

    • Beschreibung: Die maximale Größe pro Verzeichnis, die der Typ-Cache verwenden kann. Der Typcache wird immer vollständig im Arbeitsspeicher abgelegt. Dieses Volume-Attribut wird in das Feld metadata-cache:type-cache-max-size-mb der Konfigurationsdatei übersetzt.

    • Zulässige Werte:

      • Mengenwerte, z. B. 500Mi, 1Gi.
      • "-1": damit der Typ-Cache so viel Speicher wie nötig verwenden kann.
      • "0": Der Typ-Cache ist deaktiviert.
      • Verwenden Sie den Standardwert 4Mi,wenn die maximale Anzahl von Dateien in einem einzelnen Verzeichnis aus dem bereitgestellten Bucket maximal 20.000 Dateien umfasst. Wenn die maximale Anzahl von Dateien in einem einzelnen Verzeichnis,das Sie bereitstellen, mehr als 20.000 Dateien enthält,erhöhen Sie die Größe um 1 MiB pro 5.000 Dateien, durchschnittlich ca. 200 Byte pro Datei.

    • Standardwert: 4Mi.

  • metadataCacheTtlSeconds

    • Beschreibung: Die Gültigkeitsdauer (TTL) der im Cache gespeicherten Metadateneinträge in Sekunden. Wenn Sie bereits die Bereitstellungsoptionen stat-cache-ttl oder type-cache-ttl verwenden, werden die Werte weiterhin berücksichtigt und entsprechend in diese neue Konfiguration übersetzt. Dieses Volume-Attribut wird in das Feld metadata-cache:ttl-secs der Konfigurationsdatei übersetzt.

    • Zulässige Werte:

      • Ganzzahlwerte im Stringformat, z. B. „600“.
      • "-1": Ein TTL-Ablauf wird umgangen und die Datei wird aus dem Cache bereitgestellt, wann immer sie verfügbar ist.
      • "0": Die aktuelle Datei wird gelesen. Bei Verwendung des Werts 0 wird ein Get-Metadatenaufruf ausgegeben, um sicherzustellen, dass die Objektgenerierung für die Datei im Cache mit dem übereinstimmt, was in Cloud Storage gespeichert ist.

    • Standardwert: "60"

Sie können die Volume-Attribute so angeben:

  • Im Feld spec.csi.volumeAttributes für ein PersistentVolume-Manifest, wenn Sie die statische Bereitstellung verwenden.
  • Im Feld spec.volumes[n].csi.volumeAttributes, wenn Sie sitzungsspezifische CSI-Volumes verwenden.

Hinweise

Beachten Sie beim Konfigurieren von Bereitstellungen die folgenden Hinweise:

  • Die folgenden Flags sind nicht zulässig: app-name, temp-dir, foreground, log-file, log-format, key-file, token-url und reuse-token-from-url.
  • Cloud Storage FUSE macht die impliziten Verzeichnisse nicht standardmäßig sichtbar. Wenn Sie diese Verzeichnisse sichtbar machen möchten, können Sie das Bereitstellungs-Flag implicit-dirs aktivieren. Weitere Informationen finden Sie in der GitHub-Dokumentation zu Cloud Storage FUSE unter Dateien und Verzeichnisse.
  • Wenn Sie einen Sicherheitskontext für Ihren Pod oder Container verwenden oder wenn Ihr Container-Image einen Nicht-Root-Nutzer oder eine Gruppe verwendet, müssen Sie die Bereitstellungs-Flags uid und gid festlegen. Außerdem müssen Sie die Bereitstellungs-Flags file-mode und dir-mode verwenden, um die Dateisystemberechtigungen festzulegen. Beachten Sie, dass Sie die Befehle chmod, chown oder chgrp nicht für ein Cloud Storage FUSE-Dateisystem ausführen können. Daher sind die Bereitstellungs-Flags uid, gid, file-mode und dir-mode erforderlich, um Zugriff für einen Nutzer oder eine Gruppe von Root-Nutzern zu gewähren.
  • Wenn Sie nur ein Verzeichnis im Bucket und nicht den gesamten Bucket bereitstellen möchten, übergeben Sie das Verzeichnis mit dem relativen Pfad mit dem Flag only-dir=relative/path/to/the/bucket/root.
  • Konfigurieren Sie Volume-Attribute, um das Caching-Verhalten von Cloud Storage FUSE zu optimieren. Weitere Informationen finden Sie in der Dokumentation zu Cloud Storage FUSE-Caching.
  • Wenn die Anzahl der Kerne oder Threads größer als 100 ist, ändern Sie max-conns-per-host in diesen Wert.
  • Wenn Sie die Linux-Kernel-Bereitstellungsoptionen konfigurieren müssen, können Sie die Optionen über das Flag o übergeben. Wenn Sie beispielsweise keine direkte Ausführung von Binärdateien im bereitgestellten Dateisystem zulassen möchten, legen Sie das Flag o=noexec fest. Für jede Option ist ein separates Flag erforderlich, z. B. o=noexec,o=noatime. Nur die folgenden Optionen sind zulässig: exec, noexec, atime, noatime, sync, async und dirsync.
  • Wenn Sie Probleme mit Cloud Storage FUSE beheben müssen, legen Sie die Flags debug_fuse, debug_fs und debug_gcs fest. Wenn eine der drei Optionen angegeben ist, wird das Volume-Attribut gcsfuseLoggingSeverity automatisch auf trace gesetzt.
  • Mit dem Cloud Storage FUSE CSI-Treiber können Sie das Feld cache-dir in der Cloud Storage FUSE-Konfigurationsdatei nicht ändern. Verwenden Sie das Volume-Attribut fileCacheCapacity, um das Datei-Caching zu aktivieren oder zu deaktivieren. Um das Standard-Volume emptyDir für das Datei-Caching zu ersetzen, können Sie ein benutzerdefiniertes Cache-Volume für den Sidecar-Container konfigurieren.

CSI-Treiber für Cloud Storage FUSE deaktivieren

Sie können den Cloud Storage FUSE CSI-Treiber nicht für Autopilot-Cluster deaktivieren.

Sie können den CSI-Treiber für Cloud Storage FUSE mit dem Google Cloud CLI auf einem vorhandenen Standardcluster deaktivieren.

gcloud container clusters update CLUSTER_NAME \
    --update-addons GcsFuseCsiDriver=DISABLED

Ersetzen Sie CLUSTER_NAME durch den Namen Ihres Clusters.

Fehlerbehebung

Informationen zur Behebung von Problemen bei der Verwendung des CSI-Treibers für Cloud Storage FUSE finden Sie in der Anleitung zur Fehlerbehebung in der Dokumentation zum GitHub-Projekt.

Nächste Schritte