Using Snowflake stage volumes with services¶

Specifying Snowflake stage in service specification¶

To create a service where service containers use a Snowflake stage mount, you provide the necessary configuration in the service specification as follows:

1. Specify the spec.volumes field to define the stage volume to use.

   volumes:
   - name: <name>
     source: <stage name>
   

   Copy

   The following fields are required:

   • name: Name of the volume.

   • source: The Snowflake internal stage to mount, for example @my_stage, @my_stage/folder. Double quotes must surround this value.

2. Specify the spec.containers.volumeMounts field to describe where to mount a volume in your application containers. The information you provide in this field is the same for all supported storage volumes. For example,

   volumeMounts:
   - name: <name>
     mountPath: <absolute-directory-path>
   

   Copy

In the following example specification, the app container mounts the @model_stage internal stage:

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

Access control requirements¶

The service’s owner role is the role that is used to create the service. It is also the role the services use when interacting with Snowflake. This owner role determines the permissions granted to application containers for accessing a mounted stage. The owner role must have the READ privilege on the stage.

If the owner role does not have the WRITE privilege on a stage, the mount for that stage is read-only. That is, the containers can only read the files from the stage. The owner role needs the WRITE privilege on a stage for the stage mount to support both read and write.

Guidelines and limitations¶

The following guidelines and limitations apply when application containers use stage mounts:

Limitations

• The following are general limitations. If you encounter any issues with these limits, contact your account representative.

  • Each service can support up to five stage volumes per service. This references the spec.volumes field in the service specification.

  • Only eight stage mounts per node are supported. Snowflake manages the stage mount per node limit similar to how it manages memory, CPU, and GPU. Launching a new service instance can cause Snowflake to launch new nodes when no existing nodes has the capacity to support the requested stage mounts.

• You can only mount a stage or a subdirectory in a stage. For example, @my_stage, @my_stage/folder. You cannot mount a single file in a stage, for example, @my_stage/folder/file.

• External stages are not supported. Only Snowflake internal stages with SSE encryption (see Internal stage parameters) are supported. Use CREATE STAGE to create such a stage: CREATE STAGE my_stage ENCRYPTION = (type = 'SNOWFLAKE_SSE');.

• Concurrent writes to the same file from multiple stage mounts (same stage volume mounted on different containers) are not supported.

• Stage mounts are not fully POSIX compatible file systems. For example:

  • File and directory renames are not atomic.

  • Hard links are not supported.

• The Linux kernel subsystem inode notify (inotify) that monitors changes to filesystems does not work on stage mounts.

Guidelines

• Stage mount is optimized for sequential reads and writes.

• Avoid concurrently writing to multiple files within a stage mount.

• Stage mount I/O operations might have higher latencies than I/O operations on the container’s file system and block storage volumes. You should always check the status code of I/O operations to ensure they succeeded.

• To maintain performance, avoid creating or modifying files larger than 25 GB.

• Stage mounts upload file updates asynchronously. Changes to files on a stage mount are only guaranteed to be persisted to the stage after the file descriptor is successfully closed or flushed. There might be some delay before the changes to files on a stage mount become visible to other containers and Snowflake.

• Each directory in a mounted stage should contain fewer than 100,000 files. Expect readdir latency to increase with the number of files in the directory.

• Stage mount is not a network file system. Don’t use stage mounts for multi-client coordination.

• Don’t open multiple handles to the same file concurrently. Use opened file handles for either read or write operations, but not a mixture of both. To read from a file after writing to it, close the file and then re-open the file before reading.