Usando volumes de estágio Snowflake com serviços¶

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.

Nota

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 Campo 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 Diretrizes comuns para ambas as implementações de volumes de estágio.

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.

Nota

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

As informações fornecidas neste campo são consistentes em todos os tipos de volume de armazenamento com suporte e se aplicam a ambas as implementações dos volumes de estágio.

Exemplo¶

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

Requisitos de controle de acesso¶

A função de proprietário do serviço é a função usada para criar o serviço. É também a função que os serviços usam ao interagir com o Snowflake. Esta função de proprietário determina as permissões concedidas aos contêineres de aplicativo para acessar um estágio montado. O função de proprietário deve ter privilégio READ no estágio.

Se a função de proprietário não tiver o privilégio WRITE em um estágio, a montagem para esse estágio será somente leitura. Ou seja, os containers só podem ler os arquivos do estágio. A função de proprietário precisa do privilégio WRITE em um estágio para que a montagem do estágio ofereça suporte à leitura e gravação.

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.
O desempenho de leitura aleatória pode ser menor com a nova implementação devido à remoção do cache. Entretanto, sem um cache de disco local, a consistência entre os volumes é melhorada. As alterações de arquivo são gravadas diretamente no estágio de suporte quando o arquivo é fechado, sem buffer de disco local.
As leituras sempre retornam os dados mais recentes, tornando essa configuração melhor para o compartilhamento de dados entre serviços.
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
Os seguintes campos são obrigatórios:
- 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
As informações fornecidas neste campo são consistentes em todos os tipos de volume de armazenamento com suporte e se aplicam a ambas as implementações dos volumes de estágio.

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.

Diretrizes ao usar volumes de estágio¶

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

Diretrizes comuns para ambas as implementações de volumes de estágio¶

A montagem em estágio é otimizada para leituras e gravações sequenciais.
As operações de E/S de montagem em estágio podem ter latências maiores do que as operações de E/S no sistema de arquivo do contêiner e nos volumes de armazenamento em bloco. Você deve sempre verificar o código de status das operações de E/S para garantir que elas foram bem-sucedidas.
As montagens de estágio carregam atualizações de arquivo de forma assíncrona. As alterações em arquivos em uma montagem de estágio só são garantidas como persistentes no estágio após o descritor de arquivo ser fechado ou esvaziado com sucesso. Pode haver algum atraso antes que as alterações nos arquivos em uma montagem de estágio se tornem visíveis para outros contêineres e para o Snowflake.
Cada diretório em um estágio montado deve conter menos de 100 mil arquivos. Espere que a latência readdir aumente com o número de arquivos no diretório.

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

Evite gravar simultaneamente em vários arquivos dentro de uma montagem de estágio.
A montagem de estágio não é um sistema de arquivos de rede. Não utilize montagens de estágio para coordenação de vários clientes.
Não abra vários identificadores para o mesmo arquivo simultaneamente. Use identificadores de arquivo abertos para operações de leitura ou gravação, mas não uma mistura de ambas. Para ler um arquivo após gravar nele, feche o arquivo e abra-o novamente antes de ler.

Guidelines when using the generally available stage volume implementation¶

Gravações simultâneas no mesmo arquivo de várias montagens de estágio (mesmo volume de estágio montado em contêineres diferentes) não são recomendadas.
A ausência de um cache de disco local melhora a consistência entre as montagens. As alterações no arquivo são liberadas diretamente para o estágio de suporte ao fechar o arquivo, sem buffer de disco local. As leituras sempre retornam os dados mais recentes, tornando a nova montagem de estágio melhor para compartilhar dados entre serviços.
Leia e grave dados em partes grandes e contíguas visando um desempenho ideal. A cobrança de desempenho para leituras e gravações pequenas quando comparado à implementação de volume de estágio geralmente disponível pode mitigar os ganhos de desempenho da nova implementação.

Limitações ao usar volumes de estágio¶

Esta seção descreve as limitações que você deve conhecer ao implementar código de aplicativo em que os contêineres usam volumes de estágio. Se você tiver algum problema com esses limites, entre em contato com seu representante de conta.

Limitações comuns para ambas as implementações de volumes de estágio¶

É permitido montar apenas um estágio ou um subdiretório em um estágio; por exemplo, @my_stage, @my_stage/folder. Não é possível montar um único arquivo em um estágio, por exemplo, @my_stage/folder/file.
Áreas de preparação externa não são suportadas. Somente os estágios internos do Snowflake são compatíveis.
Um máximo de 5 volumes de estágio é permitido por serviço. Para obter mais informações, consulte spec.volumes.
Há suporte para um máximo de 8 volumes em estágio por nó do pool de computação. O Snowflake gerencia o limite de montagem de estágio por nó de forma semelhante à forma como gerencia a memória, CPU e GPU. Iniciar uma nova instância de serviço pode fazer com que o Snowflake inicie novos nós quando nenhum nó existente tiver capacidade para oferecer suporte às montagens de estágio solicitadas.
As montagens de estágio não são sistemas de arquivo totalmente compatíveis com POSIX. Por exemplo:
- As renomeações de arquivo e diretório não são atômicas.
- Links físicos não são permitidos.
O subsistema inode notify (inotify) do kernel Linux que monitora alterações nos sistemas de arquivos não funciona em montagens de estágio.

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

As capacidades de volume do estágio variam de acordo com a plataforma de nuvem de sua conta Snowflake:
- Contas na AWS oferecem suporte a áreas de preparação interna com criptografia de estágio SNOWFLAKE_FULL e SNOWFLAKE_SSE. Para obter mais informações, consulte Parâmetros de área de preparação interna.
- Atualmente, as contas no Azure oferecem suporte a áreas de preparação interna com criptografia SNOWFLAKE_SSE. Ao executar CREATE STAGE, use o parâmetro ENCRYPTION para especificar o tipo de criptografia: CREATE STAGE my_stage ENCRYPTION = (TYPE = 'SNOWFLAKE_SSE');
- Contas no Google Cloud não têm suporte.
Gravações simultâneas no mesmo arquivo de várias montagens de estágio (mesmo volume de estágio montado em contêineres diferentes) não são compatíveis.

Limitações ao usar a versão geralmente disponível da implementação do volume do estágio¶

Gravações aleatórias e anexos de arquivo não são compatíveis.
Cada estágio montado requer 512 MB de memória por estágio. Isso significa que há uma limitação no número de volumes de estágio que podem ser usados com base no tamanho da instância. Montar o volume em vários contêineres não aumenta o consumo de memória.