Cloud Storage-Volume-Bereitstellungen für Jobs konfigurieren

Auf dieser Seite wird gezeigt, wie Sie mithilfe von Cloud Run Volume-Bereitstellungen einen Cloud Storage-Bucket als Speicher-Volume bereitstellen.

Wenn Sie den Bucket als Volume in Cloud Run bereitstellen, wird der Inhalt des Buckets als Dateien im Dateisystem des Containers angezeigt. Nachdem Sie den Bucket als Volume bereitgestellt haben, greifen Sie so auf den Bucket zu, als wäre er ein Verzeichnis in Ihrem lokalen Dateisystem. Dabei verwenden Sie die Dateisystemvorgänge und Bibliotheken Ihrer Programmiersprache anstelle der Google API-Clientbibliotheken.

Sie können Ihr Volume schreibgeschützt bereitstellen und auch Bereitstellungsoptionen für Ihr Volume angeben.

Speicheranforderungen

• Für das gesamte Cloud Storage FUSE-Caching verwendet Cloud Run standardmäßig die Statistik-Cache-Einstellung mit einer Lebensdauer (Time-to-Live, TTL) von 60 Sekunden. Die Standardmaximalgröße des Statistik-Caches beträgt 32 MB, die Standardmaximalgröße des Typ-Caches 4 MB.

• Beim Lesen verbraucht Cloud Storage FUSE auch anderen Arbeitsspeicher als Statistik- und Typ-Caches, z. B. ein 1-MiB-Array für jede gelesene Datei und für Goroutines.

• Beim Schreiben in Cloud Storage wird die gesamte Datei im Cloud Run-Arbeitsspeicher bereitgestellt, bevor die Datei in Cloud Storage geschrieben wird.

Beschränkungen

Da Cloud Run für diese Bereitstellung Cloud Storage FUSE verwendet, müssen Sie beim Bereitstellen eines Cloud Storage-Buckets als Volume einige Dinge beachten:

• Cloud Storage FUSE bietet keine Nebenläufigkeitserkennung für mehrere Schreibvorgänge (Dateisperre) in derselben Datei. Wenn mehrere Schreibvorgänge versuchen, eine Datei zu ersetzen, wird der letzte Schreibvorgang ausgeführt und alle vorherigen gehen verloren.
• Cloud Storage FUSE ist kein vollständig POSIX-konformes Dateisystem. Weitere Informationen finden Sie in der Dokumentation zu Cloud Storage FUSE.

Unzulässige Pfade

Mit Cloud Run können Sie kein Volume unter /dev, /proc oder /sys oder in deren Unterverzeichnissen bereitstellen.

Hinweise

Sie benötigen einen Cloud Storage-Bucket, der als Volume bereitgestellt wird.

Informationen zur optimalen Lese-/Schreibleistung für Cloud Storage finden Sie unter Netzwerkbandbreitenleistung von Cloud Storage FUSE optimieren.

Erforderliche Rollen

Bitten Sie Ihren Administrator, Ihnen die folgenden IAM-Rollen zuzuweisen, um die Berechtigungen zu erhalten, die Sie zum Konfigurieren von Cloud Storage-Volume-Bereitstellungen benötigen:

• Cloud Run-Entwickler (roles/run.developer) im Cloud Run-Job
• Dienstkontonutzer (roles/iam.serviceAccountUser) für die Dienstidentität

Bitten Sie Ihren Administrator, der Dienstidentität die Rolle Storage-Objekt-Betrachter (roles/storage.objectViewer) zuzuweisen, um die Berechtigungen zu erhalten, die Ihre Dienstidentität benötigt, um auf die Datei und den Cloud Storage-Bucket zuzugreifen. Wenn die Dienstidentität auch Schreibvorgänge in einem Bucket ausführen muss, weisen Sie stattdessen die Rolle Storage-Objekt-Nutzer (roles/storage.objectUser) zu.

Weitere Informationen zu Cloud Storage-Rollen und -Berechtigungen finden Sie unter IAM für Cloud Storage.

Eine Liste der IAM-Rollen und -Berechtigungen im Zusammenhang mit Cloud Run finden Sie unter IAM-Rollen für Cloud Run und IAM-Berechtigungen für Cloud Run. Wenn Ihr Cloud Run-Job mitGoogle Cloud APIs wie Cloud-Clientbibliotheken verknüpft ist, lesen Sie die Konfigurationsanleitung für Dienstidentitäten. Weitere Informationen zum Zuweisen von Rollen finden Sie unter Bereitstellungsberechtigungen und Zugriff verwalten.

Cloud Storage-Volume bereitstellen

Sie können mehrere Buckets an verschiedenen Bereitstellungspfaden bereitstellen. Sie können ein Volume auch für mehrere Container bereitstellen, wobei Sie denselben oder unterschiedliche Bereitstellungspfade für die verschiedenen Containern nutzen können.

Wenn Sie mehrere Container verwenden, geben Sie zuerst die Volumes und dann die Volume-Bereitstellungen pro Container an.

  resource "google_cloud_run_v2_job" "default" {
    name     = "JOB_NAME"
    location = "REGION"

    template {
      template {
        containers {
          image = "IMAGE_URL"
          volume_mounts {
            name = "VOLUME_NAME"
            mount_path = "MOUNT_PATH"
          }
        }

      volumes {
        name = "VOLUME_NAME"
        gcs {
          bucket = google_storage_bucket.default.name
          read_only = IS_READ_ONLY
        }
      }
    }
  }
}

  resource "google_storage_bucket" "default" {
    name     = "BUCKET_NAME"
    location = "REGION"
  }

Lesen und Schreiben auf ein Volume

Wenn Sie das Cloud Run-Feature zur Volume-Bereitstellung verwenden, greifen Sie mit denselben Bibliotheken in Ihrer Programmiersprache auf ein bereitgestelltes Volume zu, mit denen Sie Dateien auf Ihrem lokalen Dateisystem lesen und schreiben.

Dies ist besonders nützlich, wenn Sie einen vorhandenen Container verwenden, der erwartet, dass Daten im lokalen Dateisystem gespeichert werden und ein reguläres Dateisystem für den Zugriff darauf verwendet.

In den folgenden Snippets wird davon ausgegangen, dass ein Volume bereitgestellt wird, bei dem mountPath auf /mnt/my-volume festgelegt ist.

var fs = require('fs');
fs.appendFileSync('/mnt/my-volume/sample-logfile.txt', 'Hello logs!', { flag: 'a+' });

f = open("/mnt/my-volume/sample-logfile.txt", "a")

f, err := os.Create("/mnt/my-volume/sample-logfile.txt")

import java.io.File;
File f = new File("/mnt/my-volume/sample-logfile.txt");

Volume-Konfiguration mit Bereitstellungsoptionen

Optional können Sie mit Mount-Optionen verschiedene Eigenschaften der Volume-Bereitstellung konfigurieren. Mit den verfügbaren Bereitstellungsoptionen können Sie Cacheeinstellungen konfigurieren, ein bestimmtes Verzeichnis bereitstellen, Debug-Logging aktivieren und andere Verhaltensweisen festlegen.

Bereitstellungsoptionen angeben

Sie können Einbindungsoptionen mit der Google Cloud CLI, YAML oder Terraform angeben. Die Mount-Optionen werden in der Google Cloud CLI durch Semikolons (;) und in YAML durch Kommas getrennt, wie auf den folgenden Tabs dargestellt:

gcloud beta run jobs update JOB \
    --add-volume name=VOLUME_NAME,type=cloud-storage,bucket=BUCKET_NAME, mount-options="OPTION_1=VALUE_1;OPTION_N=VALUE_N" \
    --add-volume-mount volume=VOLUME_NAME,mount-path=MOUNT_PATH

resource "google_cloud_run_v2_job" "default" {
  provider = google-beta
  name     = "JOB_NAME"
  location = "REGION"

  template {
    template {
      containers {
        image = "IMAGE_URL"
        volume_mounts {
          name = "VOLUME_NAME"
          mount_path = "MOUNT_PATH"
        }
      }

      volumes {
        name = "VOLUME_NAME"
        gcs {
          bucket = google_storage_bucket.default.name
          read_only = IS_READ_ONLY
          mount_options = ["OPTION_1=VALUE_1", "OPTION_N=VALUE_N", "OPTION_O"]
        }
      }
    }
  }
}

Häufig verwendete Mount-Optionen

Mit Mount-Optionen können Sie unter anderem:

• Cache-Einstellungen konfigurieren
• Nur ein bestimmtes Verzeichnis aus dem Cloud Storage-Bucket bereitstellen
• Eigentümerschaft des Volumes konfigurieren (uid, gid)
• Implizite Verzeichnisse deaktivieren
• Geben Sie die Debug-Logging-Ebenen an.

Caching-Einstellungen konfigurieren

Sie können die Caching-Einstellungen für Ihr Volume ändern, indem Sie die Cache-bezogenen Mount-Optionen festlegen. In der folgenden Tabelle sind die Einstellungen zusammen mit den Standardwerten für Cloud Run aufgeführt :

Mit dem folgenden Google Cloud CLI-Befehl wird metadata-cache-ttl-secs auf 120 Sekunden festgelegt und die Kapazität des Statistik- und Typ-Cache auf 52 bzw. 7 MiB erhöht:

gcloud beta run jobs update JOB \
    --add-volume name=VOLUME_NAME,type=cloud-storage,bucket=BUCKET_NAME,mount-options="metadata-cache-ttl-secs=120;stat-cache-max-size-mb=52;type-cache-max-size-mb=7" \
    --add-volume-mount volume=VOLUME_NAME,mount-path=MOUNT_PATH

Ersetzen Sie Folgendes:

• JOB: der Name des Jobs.
• VOLUME_NAME: Ein beliebiger Name für Ihr Volume. Der Wert VOLUME_NAME wird verwendet, um das Volume der Volume-Bereitstellung zuzuordnen.
• BUCKET_NAME: Der Name Ihres Cloud Storage-Buckets.
• MOUNT_PATH: der relative Pfad, unter dem Sie das Volume bereitstellen, z. B. /cache.

Debug-Logging aktivieren

Standardmäßig protokolliert Cloud Storage FUSE Ereignisse mit Info oder höher. Sie können die Protokollierungseinstellungen mit einer der folgenden Protokollschweregrade ändern, die von niedrig bis hoch aufgeführt sind:

• trace
• debug
• info
• warning
• error
• Wenn Sie das gesamte Logging deaktivieren möchten, geben Sie den Wert off an.

Wenn Sie einen Schweregrad angeben, generiert Cloud Storage FUSE Logs für Ereignisse mit einem Schweregrad, der dem angegebenen Schweregrad entspricht oder höher ist. Wenn Sie beispielsweise den Schweregrad warning angeben, generiert Cloud Storage FUSE Logs für Warnungen und Fehler.

Wenn Sie die Log-Schweregrad auf Werte über info festlegen, kann sich das auf die Leistung auswirken und eine große Menge an Logdaten generieren. Wir empfehlen daher, dies nur bei Bedarf zu tun.

Mit der folgenden Befehlszeile wird das Debug-Logging aktiviert:

gcloud beta run jobs update JOB \
    --add-volume name=VOLUME_NAME,type=cloud-storage,bucket=BUCKET_NAME,mount-options="log-severity=debug" \
    --add-volume-mount volume=VOLUME_NAME,mount-path=MOUNT_PATH

Ersetzen Sie Folgendes:

• JOB durch den Namen des Jobs.
• VOLUME_NAME durch einen beliebigen Namen für Ihr Volume. Der Wert VOLUME_NAME wird verwendet, um das Volume der Volume-Bereitstellung zuzuordnen.
• BUCKET_NAME durch den Namen Ihres Cloud Storage-Buckets.
• MOUNT_PATH durch den relativen Pfad, unter dem Sie das Volume bereitstellen, z. B. /cache.

Implizite Verzeichnisse deaktivieren

Damit Cloud Storage eher wie ein Standarddateisystem aussieht, aktiviert Cloud Run implizite Verzeichnisse standardmäßig, wenn ein Cloud Storage-Bucket bereitgestellt wird. Sie können implizite Verzeichnisse mit der Mount-Option implicit-dirs deaktivieren. Das Deaktivieren impliziter Verzeichnisse kann die Leistung verbessern und Kosten senken, geht aber mit Kompatibilitätseinbußen einher.

Mit der Funktion für implizite Verzeichnisse kann Cloud Run vorhandene Cloud Storage-Dateien erkennen, deren Dateinamen eine Verzeichnisstruktur nachahmen, z. B. /mydir/myfile.txt. Wenn Sie implizite Verzeichnisse deaktivieren, kann Cloud Run solche Dateien nicht auflisten oder lesen.

Wenn Sie implizite Verzeichnisse deaktivieren, wird die Anzahl der Anfragen an Cloud Storage reduziert, was die Leistung und Kosten Ihrer Anwendung verbessern kann. Weitere Informationen finden Sie in der Dokumentation zu Cloud Storage FUSE unter Dateien und Verzeichnisse.

Mit der folgenden Befehlszeile werden implizite Verzeichnisse deaktiviert:

gcloud beta run jobs update JOB \
    --add-volume name=VOLUME_NAME,type=cloud-storage,bucket=BUCKET_NAME,mount-options="implicit-dirs=false" \
    --add-volume-mount volume=VOLUME_NAME,mount-path=MOUNT_PATH

Ersetzen Sie Folgendes:

• JOB: der Name des Jobs.
• VOLUME_NAME: Ein beliebiger Name für Ihr Volume. Der Wert VOLUME_NAME wird verwendet, um das Volume der Volume-Bereitstellung zuzuordnen.
• BUCKET_NAME: Der Name Ihres Cloud Storage-Buckets.
• MOUNT_PATH: der relative Pfad, unter dem Sie das Volume bereitstellen, z. B. /cache.

Bestimmtes Verzeichnis in Ihrem Cloud Storage-Bucket bereitstellen

Standardmäßig stellt Cloud Run den gesamten Cloud Storage-Bucket bereit, sodass Cloud Run-Jobs Zugriff auf alle Inhalte haben. In einigen Fällen möchten Sie möglicherweise nur ein bestimmtes Verzeichnis bereitstellen. Wenn der Bucket beispielsweise eine große Anzahl von Dateien enthält, kann das Einbinden eines bestimmten Verzeichnisses die Leistung verbessern.

Sie können dies auch zur Isolation implementieren, wenn verschiedene Jobs Zugriff auf verschiedene Verzeichnisse im Speicher-Bucket benötigen.

In der folgenden Befehlszeile wird das einzubindende Verzeichnis angegeben:

gcloud beta run jobs update JOB \
    --add-volume name=VOLUME_NAME,type=cloud-storage,bucket=BUCKET_NAME,mount-options="only-dir=images" \
    --add-volume-mount volume=VOLUME_NAME,mount-path=MOUNT_PATH

Ersetzen Sie Folgendes:

• JOB: der Name des Jobs.
• VOLUME_NAME: Ein beliebiger Name für Ihr Volume. Der Wert VOLUME_NAME wird verwendet, um das Volume der Volume-Bereitstellung zuzuordnen.
• BUCKET_NAME: Der Name Ihres Cloud Storage-Buckets.
• MOUNT_PATH: der relative Pfad, unter dem Sie das Volume bereitstellen, z. B. /cache.

Stelle die Lautstärke auf UID und GID ein.

Mit den Mount-Optionen uid und gid können Sie die User-ID und die Group-ID für das Volume ändern. Das ist nützlich, wenn Sie den Inhaber der Datei auf einen bestimmten Nutzer oder eine bestimmte Gruppe festlegen möchten, die der Identität eines oder mehrerer ausgeführter Container entspricht. Standardmäßig gehören Volumes dem Root.

Mit der folgenden Befehlszeile werden uid und gid festgelegt:

gcloud beta run jobs update JOB \
    --add-volume name=VOLUME_NAME,type=cloud-storage,bucket=BUCKET_NAME,mount-options="uid=UID;gid=GID"  \
    --add-volume-mount volume=VOLUME_NAME,mount-path=MOUNT_PATH

Ersetzen Sie Folgendes:

• JOB: der Name des Jobs.
• VOLUME_NAME: Ein beliebiger Name für Ihr Volume. Der Wert VOLUME_NAME wird verwendet, um das Volume der Volume-Bereitstellung zuzuordnen.
• BUCKET_NAME: Der Name Ihres Cloud Storage-Buckets.
• MOUNT_PATH: der relative Pfad, unter dem Sie das Volume bereitstellen, z. B. /cache.

Einstellungen für Volume-Bereitstellungen ansehen

Sie können die aktuellen Einstellungen für die Volume-Einbindung in der Google Cloud Console oder über die Google Cloud CLI aufrufen.

Netzwerkbandbreitenleistung von Cloud Storage FUSE optimieren

Für eine bessere Lese- und Schreibleistung empfehlen wir, Ihren Cloud Run-Job über Direct VPC mit einem VPC-Netzwerk zu verbinden und den gesamten ausgehenden Traffic über Ihr VPC-Netzwerk zu leiten. Sie haben dazu folgende Möglichkeiten:

• Aktivieren Sie den privaten Google-Zugriff und achten Sie darauf, den Parameter vpc-egress auf all-traffic festzulegen.
• Verwenden Sie eine der Optionen, die auf der Seite mit Best Practices für Netzwerke im Abschnitt Interner Traffic zu einer Google API beschrieben sind.

Containerstartzeit und Cloud Storage FUSE-Bereitstellungen

Wenn Sie Cloud Storage FUSE verwenden, kann sich der Startzeitpunkt Ihres Cloud Run-Containers leicht verlängern, da Cloud Run die Volume-Bereitstellung vor dem Start der Container startet. Der Container wird nur gestartet, wenn Cloud Storage FUSE erfolgreich bereitgestellt wurde.

Cloud Storage FUSE stellt ein Volume erst dann bereit, wenn eine Verbindung zu Cloud Storage hergestellt wurde. Netzwerkverzögerungen können sich auf die Containerstartzeit auswirken. Wenn der Verbindungsversuch fehlschlägt, kann Cloud Storage FUSE nicht bereitgestellt und der Cloud Run-Job nicht gestartet werden. Wenn die Bereitstellung mit Cloud Storage FUSE länger als 30 Sekunden dauert, wird der Cloud Run-Job nicht gestartet, da für Cloud Run insgesamt 30 Sekunden Zeit für die Durchführung aller Bereitstellungen zur Verfügung stehen.

Leistungsmerkmale von Cloud Storage FUSE

Wenn Sie zwei Volumes definieren, die jeweils auf einen anderen Bucket verweisen, werden zwei Cloud Storage FUSE-Prozesse gestartet. Die Bereitstellungen und Prozesse erfolgen parallel.

Vorgänge mit Cloud Storage FUSE sind von der Netzwerkbandbreite betroffen, da Cloud Storage FUSE über die Cloud Storage API mit Cloud Storage kommuniziert. Einige Vorgänge wie das Auflisten der Inhalte eines Buckets können langsam sein, wenn die Netzwerkbandbreite niedrig ist. Ähnlich kann das Lesen einer großen Datei einige Zeit in Anspruch nehmen, da dies auch von der Netzwerkbandbreite abhängt.

Wenn Sie in einen Bucket schreiben, stellt Cloud Storage FUSE das Objekt vollständig im Arbeitsspeicher bereit. Das Schreiben großer Dateien ist also durch die Menge an Arbeitsspeicher begrenzt, die der Containerinstanz zur Verfügung steht. Das maximale Containerarbeitsspeicherlimit beträgt 32 GiB.

Die Schreibvorgänge werden nur dann in den Bucket übertragen, wenn Sie einen close oder fsync ausführen. Das vollständige Objekt wird dann in den Bucket hochgeladen. Die einzige Ausnahme, bei der ein Objekt vollständig noch einmal in den Bucket hochgeladen wird, ist der Fall einer Datei mit angehängtem Inhalt, die mindestens 2 MiB groß ist.

Weitere Informationen finden Sie in den folgenden Ressourcen:

• Cloud Storage FUSE-Dokumentation
• Leistung von Cloud Storage FUSE
• Cloud Storage FUSE-Semantik

Laufwerke und Bereitstellungspunkte löschen und entfernen

Sie können alle Volumes und Bereitstellungen löschen oder einzelne Volumes und Volume-Bereitstellungen entfernen.

Alle Volumes und Volume-Bereitstellungen löschen

Führen Sie den folgenden Befehl aus, um alle Volumes und Volume-Bereitstellungen aus Ihrem Job mit einem einzelnen Container zu entfernen:

gcloud run jobs update JOB \
    --clear-volumes
    --clear-volume-mounts

Wenn Sie mehrere Container haben, folgen Sie den Sidecars-CLI-Konventionen, um Volumes und Volume-Bereitstellungen zu löschen:

gcloud run jobs update JOB \
    --clear-volumes \
    --clear-volume-mounts \
    --container=container1 \
    --clear-volumes \
    -–clear-volume-mounts \
    --container=container2 \
    --clear-volumes \
    -–clear-volume-mounts

Einzelne Volumes und Volume-Bereitstellungen entfernen

Wenn Sie ein Volume entfernen möchten, müssen Sie auch alle Volume-Mounts entfernen, die dieses Volume verwenden.

Verwenden Sie die Flags remove-volume und remove-volume-mount, um einzelne Volumes oder Volume-Bereitstellungen zu entfernen:

gcloud run jobs update JOB \
    --remove-volume VOLUME_NAME
    --container=container1 \
    --remove-volume-mount MOUNT_PATH \
    --container=container2 \
    --remove-volume-mount MOUNT_PATH