서비스에 Snowflake 스테이지 볼륨 사용¶

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.

참고

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 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 두 가지 스테이지 볼륨 구현에 공통된 지침.

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.

참고

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

이 필드에 제공하는 정보는 지원되는 모든 저장소 볼륨 유형에서 일관되며, 스테이지 볼륨의 두 가지 구현 방식에 모두 적용됩니다.

예¶

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

액세스 제어 요구 사항¶

서비스의 소유자 역할은 서비스를 생성하는 데 사용되는 역할입니다. 이는 Snowflake와 상호작용할 때 서비스가 사용하는 역할이기도 합니다. 이 소유자 역할은 마운트된 스테이지에 액세스하기 위해 애플리케이션 컨테이너에 부여되는 권한을 결정합니다. 소유자 역할에는 스테이지에 대한 READ 권한이 있어야 합니다.

소유자 역할에 스테이지 WRITE 권한이 없는 경우, 해당 스테이지의 마운트는 읽기 전용입니다. 즉, 컨테이너에서 스테이지의 파일을 읽을 수만 있습니다. 소유자 역할에 스테이지 WRITE 권한이 있어야 스테이지 마운트 시 읽기와 쓰기를 모두 지원할 수 있습니다.

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.
캐싱 기능이 제거되어 새 구현에서는 임의 읽기 성능이 저하될 수 있습니다. 그러나 로컬 디스크 캐시가 없으면 볼륨 전체의 일관성이 개선됩니다. 파일 변경 사항은 파일을 닫을 때 로컬 디스크 버퍼링 없이 지원 스테이지에 바로 기록됩니다.
읽기는 항상 최신 데이터를 반환하므로, 서비스 간에 데이터를 공유하는 데에는 이 구성이 더 적합합니다.
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
다음 필드는 필수입니다.
- 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
이 필드에 제공하는 정보는 지원되는 모든 저장소 볼륨 유형에서 일관되며, 스테이지 볼륨의 두 가지 구현 방식에 모두 적용됩니다.

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.

스테이지 볼륨 사용 시 지침¶

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

두 가지 스테이지 볼륨 구현에 공통된 지침¶

스테이지 마운트는 순차적 읽기 및 쓰기에 최적화되어 있습니다.
스테이지 마운트 I/O 작업은 컨테이너의 파일 시스템 및 블록 저장소 볼륨의 I/O 작업보다 대기 시간이 길어질 수 있습니다. I/O 작업의 상태 코드를 항상 확인하여 성공했는지 확인해야 합니다.
스테이지 마운트는 파일 업데이트를 비동기적으로 업로드합니다. 스테이지 마운트의 파일 변경 사항은 파일 설명자를 성공적으로 닫거나 플러시해야만 스테이지에 유지됩니다. 스테이지 마운트의 파일 변경 사항이 다른 컨테이너와 Snowflake에 표시되기까지 지연이 발생할 수 있습니다.
마운트된 스테이지의 각 디렉터리에는 100,000개 미만의 파일이 포함되어야 합니다. 디렉터리 내 파일 수에 따라 readdir 지연 시간이 증가할 것으로 예상됩니다.

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

스테이지 마운트 내에서 여러 파일에 동시에 쓰기를 피합니다.
스테이지 마운트는 네트워크 파일 시스템이 아닙니다. 다중 클라이언트를 조정하는 데 스테이지 마운트를 사용하지 마세요.
같은 파일에 여러 핸들을 동시에 열지 마십시오. 열린 파일 핸들은 읽기 또는 쓰기 작업 중 하나에만 사용되지만, 두 가지를 혼합해서 사용하면 안 됩니다. 파일에 쓴 후 읽으려면 먼저 파일을 닫았다가 다시 열어서 읽어야 합니다.

Guidelines when using the generally available stage volume implementation¶

여러 스테이지 마운트(다른 컨테이너에 마운트된 동일한 스테이지 볼륨)에서 동일한 파일에 동시에 쓰기는 권장되지 않습니다.
로컬 디스크 캐시가 없으면 마운트 전반의 일관성이 개선됩니다. 파일 변경 사항은 파일을 닫을 때 로컬 디스크 버퍼링 없이 지원 스테이지에 바로 플러시됩니다. 읽기는 항상 최신 데이터를 반환하므로, 서비스 간에 데이터를 공유하는 데에는 새로운 스테이지 마운트가 더 적합합니다.
최적의 성능을 얻으려면 대규모의 연속 청크에서 데이터를 읽고 쓰세요. 일반 공급 버전의 스테이지 볼륨 구현과 비교해 볼 때 소규모 읽기/쓰기 작업의 성능 저하가 발생하지만, 이로 인해 새로운 구현의 성능 향상을 상쇄할 수 있습니다.

스테이지 볼륨 사용 시 제한 사항¶

이 섹션에서는 컨테이너가 스테이지 볼륨을 사용하는 애플리케이션 코드를 구현할 때 알고 있어야 하는 제한 사항을 설명합니다. 이러한 제한과 관련된 문제가 발생하면 계정 담당자에게 문의하세요.

두 가지 스테이지 볼륨 구현에 공통된 제한 사항¶

스테이지에서는 스테이지 또는 하위 디렉터리만 마운트할 수 있습니다(예: @my_stage, @my_stage/folder). 스테이지에서는 단일 파일을 마운트할 수 없습니다(예: @my_stage/folder/file).
외부 스테이지는 지원되지 않습니다. Snowflake 내부 스테이지만 지원됩니다.
서비스당 최대 5개의 스테이지 볼륨이 허용됩니다. 자세한 내용은 spec.volumes 섹션을 참조하세요.
컴퓨팅 풀 노드당 최대 8개의 스테이지 볼륨이 지원됩니다. Snowflake는 메모리, CPU, GPU를 관리하는 방식과 유사하게 노드당 스테이지 마운트 제한을 관리합니다. 새로운 서비스 인스턴스를 시작하면 기존 노드에 요청된 스테이지 마운트를 지원할 용량이 없을 때 Snowflake가 새로운 노드를 시작할 수 있습니다.
스테이지 마운트는 POSIX와 완전 호환되지 않는 파일 시스템입니다. 예:
- 파일 및 디렉터리 이름 변경은 원자적이지 않습니다.
- 하드 링크는 지원되지 않습니다.
파일 시스템의 변경 사항을 모니터링하는 Linux 커널 하위 시스템 inode notify(inotify)는 스테이지 마운트에서 작동하지 않습니다.

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

스테이지 볼륨 기능은 Snowflake 계정의 클라우드 플랫폼에 따라 다릅니다.
- AWS의 계정은 SNOWFLAKE_FULL 및 SNOWFLAKE_SSE 스테이지 암호화를 모두 사용하는 내부 스테이지를 지원합니다. 자세한 내용은 내부 스테이지 매개 변수 섹션을 참조하세요.
- Azure의 계정은 현재 SNOWFLAKE_SSE 암호화를 사용하는 내부 스테이지를 지원합니다. CREATE STAGE 실행 시 ENCRYPTION 매개 변수를 사용하여 CREATE STAGE my_stage ENCRYPTION = (TYPE = 'SNOWFLAKE_SSE'); 암호화 유형을 지정합니다.
- Google Cloud의 계정은 지원되지 않습니다.
여러 스테이지 마운트(즉, 다른 컨테이너에 마운트된 동일한 스테이지 볼륨)에서 동일한 파일에 동시에 쓰기는 지원되지 않습니다.

일반 공급 버전의 스테이지 볼륨 구현 사용 시 제한 사항¶

임의 쓰기 및 파일 추가 기능은 지원되지 않습니다.
마운트된 각 스테이지에는 스테이지당 512MB의 메모리가 필요합니다. 즉, 인스턴스 크기에 따라 사용할 수 있는 스테이지 볼륨 수에는 제한이 있습니다. 여러 컨테이너에 볼륨을 마운트해도 메모리 사용량이 증가하지는 않습니다.