将 Snowflake 暂存区卷与服务搭配使用¶

备注

目前，Google Cloud 中的账户不支持在服务中使用 Snowflake 暂存区卷。

Snowflake 支持应用程序容器的各种存储卷类型，包括内部暂存区、本地存储、内存存储和块存储卷。本部分介绍如何为内部暂存区配置卷和卷挂载。

与使用 Snowflake 驱动程序及 GET 和 PUT SQL 命令相比，暂存区卷可让您的服务使用 FileSystem APIs 访问内部暂存区，从而简化您的代码。

对于大数据文件的流式读写场景，暂存区卷也能提供更高的性能。当应用程序使用暂存区卷作为暂存区的便捷替代 API，而不需要一个功能齐全的文件系统时，暂存区卷的效果最佳。

暂存区卷目前有两种实现方式：正式发布版本和当前处于预览阶段的更新版本。

关于新的暂存区卷实现方式¶

正式发布的暂存区卷实现方式使用共享缓存进行读写。尽管这适用于某些场景，但您无法控制是从缓存读取数据还是直接从暂存区读取数据，这可能不适用于所有应用程序。此外，当您使用缓存进行读写时，这可能会带来性能开销。

新的暂存区卷实现方式目前处于预览阶段，仅使用有限的内存缓存。这提高了行为的可预测性和吞吐量速度。该版本最终将取代当前正式发布的实现方式。除非您的工作负载需要随机写入或追加文件（目前尚不支持），否则 Snowflake 建议评估此预览版本。

使用新的暂存区卷实现方式时，请记住以下其他注意事项：

它针对大型顺序读写进行了优化，为这些访问模式提供了强大的性能。为了获得最佳结果，请以较大的连续块读取和写入数据。
由于移除了缓存，新实现方式的随机读取性能可能会降低。但是，如果没有本地磁盘缓存，卷之间的一致性就会得到改善。文件关闭后，文件更改将直接写入备份暂存区，无需本地磁盘缓冲。
读取始终返回最新数据，因此此配置更适合在服务之间共享数据。
不支持随机写入或文件追加。尝试执行这些操作会导致错误。

Specify a Snowflake stage volume in a service specification¶

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

要指定暂存区卷，请使用 spec.volumes 字段。
- 使用暂存区卷实现方式的正式发布版本，如以下示例所示：
  volumes: - name: <name> source: <stage_name>
  Copy
  以下字段为必填字段：
  - name：卷的名称。
  - source: The Snowflake internal stage or folder on the stage to mount, for example @my_stage, @my_stage/folder. Quotes must surround this value.
- 使用暂存区卷实现方式的全新预览版本，如以下示例所示：
  volumes: - name: <name> source: stage stageConfig: name: <stage_name>
  Copy
  以下字段为必填字段：
  - name：卷的名称。
  - source：选择使用时默认使用的角色和仓库。标识卷的类型 (stage)。
  - stageConfig: 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.
Use the spec.containers.volumeMounts field to describe where to mount the stage volume in your application containers, as show in the following example:
```
volumeMounts:
- name: <name>
  mountPath: <absolute_directory_path>
```
Copy
您在该字段中提供的信息在所有支持的存储卷类型中是一致的，并且适用于暂存区卷的两种实现方式。

示例¶

此示例说明了使用现有和新暂存区卷挂载 Snowflake 暂存区之间的区别。在示例服务规范中，app 容器使用现有和新的暂存区卷实现方式来挂载内部暂存区 @model_stage。

@model-legacy 暂存区卷配置指示 Snowflake 使用暂存区卷正式发布的实现方式。
@model-new 暂存区卷配置指定 stageConfig 字段，该字段指示 Snowflake 使用暂存区卷的预览实现方式。

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

Copy

volumeMounts 字段指定在容器内的哪个位置挂载暂存区卷。这两种暂存区卷实现方式的规范保持不变。

访问控制要求¶

服务的所有者角色是用于创建服务的角色。这也是服务在与 Snowflake 交互时使用的角色。所有者角色确定授予应用程序容器访问已挂载暂存区的权限。所有者角色必须对暂存区具有 READ 权限。

If the owner role doesn't 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.

与使用暂存区卷有关的指南¶

本节为您提供了在实现容器使用暂存区卷的应用程序代码时应遵循的指南。

暂存区卷两种实现方式的通用指南¶

暂存区挂载针对顺序读写进行了优化。
暂存区挂载 I/O 操作的延迟可能高于容器文件系统和块存储卷上的 I/O 操作。您应始终检查 I/O 操作的状态码，以确保它们成功。
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 a delay before the changes to files on a stage mount become visible to other containers and Snowflake.
已挂载暂存区中的每个目录应包含少于 100,000 个文件。预计 readdir 延迟会随着目录中文件数量的增加而增加。

使用暂存区卷实现方式的正式发布版本时的指南¶

避免在暂存区挂载中同时写入多个文件。
Stage mount isn't a network file system. Don't use stage mounts for multi-client coordination.
不要同时打开同一个文件的多个句柄。使用打开的文件句柄进行读取或写入操作，但不能将两者混用。要在写入文件后读取文件，请关闭该文件，然后在读取之前重新打开该文件。

使用暂存区卷实现方式新预览版本时的指南¶

Concurrent writes to the same file from multiple stage mounts --- same stage volume mounted on different containers --- aren't recommended.
如果没有本地磁盘缓存，可以提升不同挂载点之间的一致性。关闭文件后，文件更改将直接刷新到备份暂存区，无需本地磁盘缓冲。读取始终返回最新数据，这使得新的暂存区挂载更适合在服务之间共享数据。
以较大的连续块读取和写入数据，以实现最佳性能。与正式发布的暂存区卷实现方式相比，小规模读取和写入的性能损失可能会减轻新实现方式带来的性能提升。

使用暂存区卷时的限制¶

This section describes limitations you should be aware of when you implement application code in which containers use stage volumes. If you encounter any issues with these limits, contact your account representative.

两种暂存区卷实现方式的共同限制¶

You can only mount a stage or a subdirectory in a stage; for example, @my_stage, @my_stage/folder. You can't mount a single file in a stage; for example, @my_stage/folder/file.
External stages aren't supported. Only Snowflake internal stages are supported.
A maximum of 5 stage volumes is allowed per service. For more information, see spec.volumes.
每个计算池节点最多支持 8 个暂存区卷。Snowflake 管理每个节点的暂存区挂载限制，与管理内存、CPU 和 GPU 的方式类似。当现有节点无法支持所请求的暂存区挂载时，启动新的服务实例可能会导致 Snowflake 启动新节点。
暂存区挂载不是完全 POSIX 兼容的文件系统。例如：
- 文件和目录重命名不是原子的。
- 不支持硬链接。
The Linux kernel subsystem inode notify (inotify) that monitors changes to file systems doesn't work on stage mounts.

使用暂存区卷实现方式的正式发布版本时的限制¶

暂存区卷能力因您 Snowflake 账户的云平台而异：
- Accounts on AWS support internal stages with both SNOWFLAKE_FULL and SNOWFLAKE_SSE stage encryption. For more information, see Internal stage parameters.
- Accounts on Azure currently support internal stages with SNOWFLAKE_SSE encryption. When you run CREATE STAGE, use the ENCRYPTION parameter to specify the encryption type: CREATE STAGE my_stage ENCRYPTION = (TYPE = 'SNOWFLAKE_SSE');
- 不支持 Google Cloud 上的账户。
Concurrent writes to the same file from multiple stage mounts --- that is, the same stage volume mounted on different containers --- aren't supported.

使用暂存区卷实现方式新预览版本时的限制¶

暂存区卷能力因您 Snowflake 账户的云平台而异：
- Accounts on AWS support internal stages with both SNOWFLAKE_FULL and SNOWFLAKE_SSE stage encryption (see Internal stage parameters).
- Accounts on Azure and Google Cloud currently support internal stages with SNOWFLAKE_SSE encryption. When you run CREATE STAGE, use the ENCRYPTION parameter to specify the encryption type: CREATE STAGE my_stage ENCRYPTION = (TYPE = 'SNOWFLAKE_SSE');
Random writes, and file appends aren't supported.
挂载的每个暂存区的每个暂存区需要 512 MB 内存。这意味着，根据实例大小，可以使用的暂存区卷数量存在限制。在多个容器上挂载卷不会增加内存消耗。