Snowflake-Stagingbereiche mit Diensten verwenden¶

Snowflake supports various storage volume types for your application containers, including internal stage, local storage, memory storage, and block storage volumes. This section explains how to configure volumes and volume mounts for internal stages. A An internal stage volume is a volume configured to use a Snowflake stage as persistent storage.

With stage volumes your service can access an internal stage’s objects as if they are files on your file system, simplifying your service code compared to using a Snowflake driver and GET and PUT SQL commands to access these objects. Stage volumes can also perform better for scenarios with streaming reads or writes of large data files.

If you file system operations can easily be translated to streaming GET and PUT operations, then Stage volumes will work well for your scenario. If your application needs to rename or move files, modify existing files, or perform file system based locking, then stage volume is not a good fit for your workload.

Bemerkung

There are currently two implementations of stage volumes; a generally available version and a deprecated version. Snowflake recommends that you use the generally available version for new services and that you migrate your existing applications from the deprecated version.

The stage volume implementation streams file contents directly to and from cloud storage, ensuring that you always get the latest contents. Consider the following points when you use a stage volume:

A stage volume is optimized for large, sequential reads and writes, providing strong performance for these access patterns. For best results, read and write data in large, contiguous chunks.
Reads always return the latest data, which lets data sharing occur between services.
Random writes or file appends aren’t supported. Attempting these operations results in an error. Snowflake recommends that you use block storage volumes for these workloads.

Configure a Snowflake stage as a storage volume in a service specification¶

To create a service where service containers use a stage volume, you perform two steps to specify the required settings in the service specification:

Define a stage volume that identifies the Snowflake stage to use as storage volume.
Specify where to mount the stage volume in your application container.

Step 1: Define a stage volume¶

To define a stage volume, add the spec.volumes field in the service specification as shown in the following example. The example shows only the minimum required fields:

spec:
  containers:
    ..
  volumes:
  - name: <name>
    source: stage
    stageConfig:
       name: <stage_name>

Copy

The following list defines the fields from the example:

name: Provides the name of the volume.
source: Identifies the type of the volume (stage).
stageConfig.name: Identifies the Snowflake internal stage or folder on a stage to mount; for example @my_stage, @my_stage/folder, or @my_db.my_schema.my_stage/folder/nestedfolder. Double quotes must surround this value.

You can include the following optional fields in stageConfig:

stageConfig.resources field: The Snowflake component that provides the mounted stage volume requires CPU and memory resources. Use this field to specify these CPU and memory requirements, similar to the resource specifications for your application containers. For more information, see Feld containers.resources fields. If this field isn’t specified, the following default resource settings apply:
- resources.requests.cpu: 0
- resources.requests.memory: 0.5Gi
- resources.limits.cpu: 0.5
- resources.limits.memory: 1Gi
For most applications with typical data traffic to stage volumes, you don’t need to set this field, because the default resource settings should be sufficient. However, if your application performs a high volume of reads and writes, the default settings might lead to performance constraints or read/write failures. For more information, see Gemeinsame Richtlinien für beide Implementierungen von Stagingbereich-Volumes.

To avoid these problems, check the CPU and memory metrics for the container (stage-mount-v2-sidecar-<stage-volume-name>). Snowflake adds this container to your service that provides the implementation of the stage volume you configured. This lets you to see exactly what resources your stage volume is using and determine if it is constrained by CPU or memory. Use these metrics to update the CPU and memory limits as needed.
stageConfig.metadataCache field: If your application frequently retrieves file metadata or lists files on a Snowflake stage in a loop, and you don’t expect the data to change often, you can enable metadata caching for the Snowflake stage storage volume to significantly improve performance. The cache stores this metadata for a specified time period, after which it is cleared. If the application then tries to access the metadata, Snowflake refreshes the cache. Use the hours, minutes, and seconds units to specify the metadataCache. For example 90s, 5m, 1h, 1h30m, 1h30m45s. If not specified, there is no caching.

Bemerkung

Configure metadata caching only when the data in your Snowflake stage doesn’t change for service lifetime; for example, a service that has read-only workloads that need to work on a static set of data in the stage. Don’t configure metadata caching for workloads where data in your Snowflake stage is updated while the service is running.

The following spec.volumes field defines a Snowflake stage volume. The field includes the optional stageConfig fields:

spec:
  containers:
    ..
  volumes:
  - name: <name>
    source: stage
    stageConfig:
        name: <stage_name>
        metadataCache: 1h
        resources:
            requests:
                cpu: 0.35
                memory: 0.4Gi
            limits:
                cpu: 2.0
                memory: 1Gi

Copy

Step 2: Specify where to mount the stage volume in the container¶

After you define a Snowflake stage storage volume by adding the spec.volumes field, use the spec.containers.volumeMounts field to describe where to mount the stage volume in your application containers, as shown in the following example:

spec:
  containers:
  name: ...
  image: ...
  volumeMounts:
  - name: <name>
    mountPath: <absolute_directory_path>

Copy

Die Angaben, die Sie in diesem Feld machen, sind für alle unterstützten Speicher-Volume-Typen konsistent und gelten für beide Implementierungen von Stagingbereich-Volumes.

Beispiel¶

In the example service specification, the app container mounts an internal stage @ai_models_stage:

spec:
  containers:
  - name: app
    image: <image1-name>
    volumeMounts:
    - name: ai-models
      mountPath: /opt/ai-model
  volumes:
  - name: ai-models
    source: stage
    stageConfig:
      name: "@ai_models_stage"

Copy

Anforderungen an die Zugriffssteuerung¶

Die Rolle des Eigentümers des Dienstes ist die Rolle, mit der der Dienst erstellt wird. Es ist auch die Rolle, die die Dienste bei der Interaktion mit Snowflake verwenden. Diese Eigentümerrolle legt die Berechtigungen fest, die Anwendungs-Containern für den Zugriff auf einen gemounteten Stagingbereich gewährt werden. Der Eigentümer muss über die READ-Berechtigung für den Stagingbereich verfügen.

Wenn die Eigentümerrolle nicht die WRITE-Berechtigung für einen Stagingbereich hat, ist die Einbindung für diesen Stagingbereich schreibgeschützt. Das heißt, die Container können die Dateien nur aus dem Stagingbereich lesen. Die Rolle des Eigentümers benötigt die WRITE-Berechtigung auf einem Stagingbereich, damit das Staging-Mount sowohl Lese- als auch Schreibzugriffe unterstützt.

About the deprecated implementation¶

The deprecated stage-volume implementation uses a shared cache for reads and writes. Although this works well for some scenarios, you can’t control whether data is read from the cache or directly from the stage, which might not be suitable for all applications. Additionally, when you use the cache for reads and writes, this can introduce performance overhead.

Migrating code from the deprecated implementation¶

The newer implementation replaces the deprecated implementation, with the following behavioral changes:

The newer stage-volume implementation streams file contents directly to and from cloud storage, ensuring that you always get the latest contents. This provides predictable behavior and significantly faster throughput. The deprecated stage-volume implementation caches chunks of file data, making it difficult to know if you are reading the latest data.
Die Performance bei zufälligen Lesevorgängen kann bei der neuen Implementierung geringer sein, da das Caching entfernt wurde. Ohne einen lokalen Festplattencache wird die Konsistenz zwischen Volumes jedoch verbessert. Dateiänderungen werden beim Schließen der Datei direkt in den unterstützenden Stagingbereich geschrieben, ohne dass eine lokale Festplattenpufferung erfolgt.
Lesevorgänge geben immer die neuesten Daten zurück, sodass sich diese Konfiguration besser für das Data Sharing zwischen Services eignet.
Random writes or file appends aren’t supported. Attempting these operations results in an error. Snowflake recommends that you use block storage volumes for these workloads.

Specify a Snowflake stage volume in a service specification (deprecated)¶

To create a service where service containers use Snowflake stage volume, specify the required settings in the service specification as shown in the following steps:

To specify the stage volume, use the spec.volumes field as shown in the following example:
```
volumes:
- name: <name>
  source: <stage_name>
```
Copy
Die folgenden Felder sind erforderlich:
- name: The name of the volume.
- source: The Snowflake internal stage or folder on the stage to mount; for example @my_stage, @my_stage/folder. Quotes must surround this value.
To describe where to mount the stage volume in your application containers, use the spec.containers.volumeMounts field, as shown in the following example:
```
volumeMounts:
- name: <name>
  mountPath: <absolute_directory_path>
```
Copy
Die Angaben, die Sie in diesem Feld machen, sind für alle unterstützten Speicher-Volume-Typen konsistent und gelten für beide Implementierungen von Stagingbereich-Volumes.

Example (deprecated)¶

In the example service specification, the app container mounts an internal stage @model_stage by using the deprecated stage volume implementations:

spec:
  containers:
  - name: app
    image: <image1-name>
    volumeMounts:
    - name: models-legacy
      mountPath: /opt/model-legacy
  volumes:
  - name: models-legacy
    source: "@model_stage"

Copy

The volumeMounts field specifies where inside the container to mount the stage volume. This specification remains the same for both the stage volume implementations.

Richtlinien bei der Verwendung von Stagingbereich-Volumes¶

This section provides you with guidelines to follow when you implement application code in which a container uses a Snowflake stage as storage volume.

Gemeinsame Richtlinien für beide Implementierungen von Stagingbereich-Volumes¶

Der Stagingbereich ist für sequentielles Lesen und Schreiben optimiert.
E/A-Operationen im Stagingbereich können höhere Latenzen aufweisen als E/A-Operationen auf dem Dateisystem und den Blockspeicher-Volumes des Containers. Sie sollten immer den Statuscode von E/A-Operationen überprüfen, um sicherzustellen, dass sie erfolgreich waren.
Im Stagingbereich werden Uploaddateien asynchron aktualisiert. Änderungen an Dateien auf einem Stagingbereich werden erst dann garantiert, wenn der Datei-Deskriptor erfolgreich geschlossen oder geleert wurde. Es kann eine gewisse Verzögerung geben, bevor die Änderungen an Dateien in einem Stagingbereich für andere Container und Snowflake sichtbar werden.
Jedes Verzeichnis in einem gemounteten Stagingbereich sollte weniger als 100.000 Dateien enthalten. Rechnen Sie damit, dass die Latenz von readdir mit der Anzahl der Dateien im Verzeichnis zunimmt.

Guidelines when using the deprecated version of the stage volume implementation¶

Vermeiden Sie das gleichzeitige Schreiben in mehrere Dateien innerhalb eines Stagingbereichs.
Der Stagingbereich ist kein Netzwerkdateisystem. Verwenden Sie keine Stagingbereiche für die Koordination mehrerer Clients.
Öffnen Sie nicht mehrere Handles für dieselbe Datei gleichzeitig. Verwenden Sie geöffnete Datei-Handles entweder für Lese- oder für Schreiboperationen, aber nicht für eine Mischung aus beidem. Um aus einer Datei zu lesen, nachdem Sie in sie geschrieben haben, schließen Sie die Datei und öffnen Sie sie dann erneut, bevor Sie lesen.

Guidelines when using the generally available stage volume implementation¶

Gleichzeitige Schreibvorgänge auf dieselbe Datei aus mehreren Stagingbereichen (dasselbe Stagingbereich-Volume in verschiedenen Containern) werden nicht empfohlen.
Das Fehlen eines lokalen Festplattencaches verbessert die Konsistenz zwischen Einbindungen. Dateiänderungen werden beim Schließen der Datei direkt in den unterstützenden Stagingbereich geleert, ohne dass eine lokale Festplattenpufferung erfolgt. Lesevorgänge geben immer die neuesten Daten zurück, sodass sich die neue Einbindung von Stagingbereichen besser für das Data Sharing zwischen Services eignet.
Die optimalen Ergebnisse erzielen Sie, wenn Sie Daten in großen, zusammenhängenden Blöcken lesen und schreiben. Die Leistungseinbußen bei kleinen Lese- und Schreibvorgängen im Vergleich zur allgemein verfügbaren Stagingbereich-Volume-Implementierung können die Performancegewinne der neuen Implementierung abschwächen.

Einschränkungen bei der Verwendung von Stagingbereich-Volumes¶

In diesem Abschnitt werden die Einschränkungen beschrieben, die Sie bei der Implementierung von Anwendungscode beachten sollten, in dem Container Stagingbereich-Volumes verwenden. Wenn Sie Probleme mit diesen Beschränkungen haben, wenden Sie sich an Ihren Kundenbetreuer.

Gemeinsame Einschränkungen für beide Implementierungen von Stagingbereich-Volumes¶

Sie können nur einen Stagingbereich oder ein Unterverzeichnis in einen Stagingbereich einbinden, z. B. @my_stage, @my_stage/folder. Sie können keine einzelne Datei in einen Stagingbereich einbinden, z. B. @my_stage/folder.
Externe Stagingbereiche werden nicht unterstützt. Es werden nur Snowflake-interne Stagingbereiche unterstützt.
Pro Service sind maximal 5 Stagingbereich-Volumes erlaubt. Weitere Informationen dazu finden Sie unter spec.volumes.
Es werden maximal 8 Staging-Volumess pro Computepool-Knoten unterstützt. Snowflake verwaltet die Beschränkung des Stagingbereichs pro Knoten ähnlich wie Speicher, CPU und GPU. Das Starten einer neuen Dienstinstanz kann Snowflake dazu veranlassen, neue Knoten zu starten, wenn keine vorhandenen Knoten die Kapazität haben, den angeforderten Stagingbereich zu unterstützen.
Stagingbereiche sind nicht vollständig POSIX-kompatible Dateisysteme. Beispiel:
- Dateien und Verzeichnisse werden nicht atomar umbenannt.
- Harte Links werden nicht unterstützt.
Das Linux-Kernel-Subsystem inode notify (inotify), das Änderungen an Dateisystemen überwacht, funktioniert nicht im Stagingbereich.

Limitations when using the deprecated version of the stage volume implementation¶

Die Funktionen für Stagingbereich-Volumes variieren je nach Cloudplattform für Ihr Snowflake-Konto:
- Konten auf AWS unterstützen interne Stagingbereiche sowohl mit SNOWFLAKE_FULL- als auch mit SNOWFLAKE_SSE-Stagingbereich-Verschlüsselung. Weitere Informationen dazu finden Sie unter Parameter für interne Stagingbereiche.
- Konten auf Azure unterstützen derzeit interne Stagingbereiche mit SNOWFLAKE_SSE-Verschlüsselung Verwenden Sie bei der Ausführung von CREATE STAGE den Parameter ENCRYPTION zur Angabe des Verschlüsselungstyps: CREATE STAGE my_stage ENCRYPTION = (TYPE = 'SNOWFLAKE_SSE');
- Konten auf Google Cloud werden nicht unterstützt.
Gleichzeitige Schreibvorgänge auf dieselbe Datei aus mehreren Stagingbereichen (dasselbe Stagingbereich -Volume in verschiedenen Containern) werden nicht unterstützt.

Einschränkungen bei der Verwendung der allgemein verfügbaren Version der Stagingbereich-Volume-Implementierung¶

Zufällige Schreibvorgänge oder Anhänge von Dateien werden nicht unterstützt.
Jeder eingebundene Stagingbereich erfordert 512 MB Arbeitsspeicher pro Stagingbereich. Das bedeutet, dass die Anzahl der Stagingbereiche, die verwendet werden können, je nach Größe der Instanz begrenzt ist. Das Einbinden des Volumes in mehrere Container erhöht nicht den Speicherverbrauch.