サービスでの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. An internal stage volume is a volume configured to use a Snowflake stage as persistent storage.

ステージ量を使用すると、サービスはファイルシステム上のファイルであるかのように内部ステージのオブジェクトにアクセスでき、Snowflakeドライバーや GET および :doc:`/sql-reference/sql/put`SQL コマンドを使用してこれらのオブジェクトにアクセスする場合と比較して、サービスコードを簡素化できます。ステージ量は、大きなデータファイルのストリーミング読み取りや書き込みを行うシナリオの場合に、よりパフォーマンスを向上させることもできます。

If your 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.

注釈

現在、ステージ量には一般公開されているバージョンと非推奨バージョンの2つの実装があります。Snowflakeでは、新しいサービスには一般公開されているバージョンを使用し、既存のアプリケーションは非推奨バージョンから移行することを推奨しています。

ステージ量の実装では、クラウドストレージとの間でファイルコンテンツを直接ストリーミングし、常に最新のコンテンツを取得できるようにします。ステージ量を使用する場合は、以下の点を考慮してください。

ステージ量は大規模な連続読み取りおよび書き込み用に最適化されており、これらのアクセスパターンに強力なパフォーマンスを提供します。最良の結果を得るには、大きな連続したチャンクでデータを読み書きします。
読み取りは常に最新のデータを返すため、サービス間でデータ共有が発生します。
ランダム書き込み、ファイル追加はサポートされていません。これらの操作を試行すると、エラーが発生します。Snowflakeは、これらのワークロードにはブロックストレージ量を使用することをお勧めします。

サービス仕様のストレージ量としてSnowflakeステージを設定する¶

サービスコンテナがステージ量を使用するサービスを作成するには、2つのステップを実行して、サービス仕様に必要な設定を指定します。

ストレージ量として使用するSnowflakeステージを識別するステージ量を定義します。
アプリケーションコンテナ内のステージ量をマウントする場所を指定します。

ステップ1：ステージ量を定義する¶

ステージ量を定義するには、次の例に示すように、サービス仕様に spec.volumes フィールドを追加します。

spec:
  containers:
    ..
  volumes:
  - name: <name>
    source: stage
    stageConfig:
       name: <stage_name>
       metadataCache: <time_period>
       resources:
         requests:
           memory: <amount-of-memory>
           cpu: <cpu-units>
         limits:
           memory: <amount-of-memory>
           cpu: <cpu-units>

Copy

次のリストは、例からフィールドを定義します。

name: 量の名前を提供します。
source: 量（ステージ）のタイプを識別します。
stageConfig.name:Snowflake内部ステージまたはマウントするステージ上のフォルダーを識別します。例えば @my_stage 、 @my_stage/folder または @my_db.my_schema.my_stage/folder/nestedfolder 。この値は二重引用符で囲む必要があります。

stageConfig に次のオプションフィールドを含めることができます。

stageConfig.resources フィールド:マウントされたステージ量を提供するSnowflakeコンポーネントには、 CPU とメモリリソースが必要です。このフィールドを使用して、アプリケーションコンテナのリソース仕様と同様に、これらの CPU およびメモリ要件を指定します。詳細については、 containers.resources フィールドフィールドをご参照ください。このフィールドが指定されていない場合は、以下のデフォルトのリソース設定が適用されます。
- resources.requests.cpu: 0
- resources.requests.memory: 0.5Gi
- resources.limits.cpu: 0.5
- resources.limits.memory: 1Gi
ステージ量への一般的なデータトラフィックを持つほとんどのアプリケーションでは、デフォルトのリソース設定で十分なため、このフィールドを設定する必要はありません。ただし、アプリケーションが大量の読み取りと書き込みを実行する場合、デフォルト設定ではパフォーマンスの制限や読み取り/書き込みの失敗が発生する可能性があります。詳細については、ステージ・ボリュームの両方の実装の共通ガイドラインをご参照ください。

このような問題を回避するには、コンテナ用（stage-mount-v2-sidecar-<stage-volume-name>）:ref:CPU およびメモリメトリック<label-monitoring_services_platform_metrics> を確認してください。Snowflakeは、このコンテナをサービスに追加し、構成したステージ量の実装を提供します。これにより、ステージ量がどのようなリソースを使用しているかを正確に確認し、 CPU またはメモリによって制約されているかどうかを判断することができます。必要に応じてこれらのメトリックを使用して、 CPU およびメモリ制限を更新します。
stageConfig.metadataCache フィールド:アプリケーションが頻繁にファイルメタデータを取得したり、Snowflakeステージ上のファイルをループで一覧表示したりし、データが頻繁に変更されることを予期しない場合は、Snowflakeステージストレージ量のメタデータキャッシュを有効にして、パフォーマンスを大幅に向上させることができます。キャッシュは指定された期間このメタデータを保存し、その後クリアされます。その後、アプリケーションがメタデータにアクセスしようとすると、Snowflakeはキャッシュを更新します。時間、分、秒の単位を使用して、 metadataCache を指定します。例:90s、 5m、 1h、 1h30m、 ``1h30m45s``指定しない場合、キャッシュはありません。

注釈

Snowflakeステージのデータがサービスの有効期間中に変更されない場合にのみ、メタデータキャッシュを構成します。たとえば、ステージにある静的なデータセットを操作する必要がある読み取り専用のワークロードがあるサービスなどです。サービスの実行中にSnowflakeステージのデータが更新されるワークロードのメタデータキャッシュを構成しないでください。

次の spec.volumes フィールドは、Snowflakeステージ量を定義します。フィールドには、オプションの stageConfig フィールドが含まれます。

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

ステップ2：コンテナ内のステージ量をマウントする場所を指定する¶

spec.volumes フィールドを追加してSnowflakeステージストレージ量を定義した後、 spec.containers.volumeMounts フィールドを使用して次の例に示すように、アプリケーションコンテナのステージ量をマウントする場所を記述します。

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

Copy

このフィールドに入力する情報は、サポートされるすべてのストレージボリュームタイプで一貫しており、ステージボリュームの両方の実装に適用されます。

例¶

メインコンテナの /path/to/stage でマウントされたステージ mydb.myschema.ai_models_stage を持つサービスを作成します。

CREATE SERVICE my_service
IN COMPUTE POOL tutorial_compute_pool
FROM SPECIFICATION $$
spec:
  containers:
  - name: echo
    image: /tutorial_db/data_schema/tutorial_repository/my_echo_service_image:latest
    volumeMounts:
    - name: stage-vol
      mountPath: /path/to/stage
  volumes:
  - name: stage-vol
    source: stage
    stageConfig:
      name: "@mydb.myschema.ai_models_stage"
$$;

Copy

メインコンテナの /path/to/stage でマウントされたステージサブパス mydb.myschema.ai_models_stage/subpath を持つサービスを作成します。

CREATE SERVICE my_service
IN COMPUTE POOL tutorial_compute_pool
FROM SPECIFICATION $$
spec:
  containers:
  - name: echo
    image: /tutorial_db/data_schema/tutorial_repository/my_echo_service_image:latest
    volumeMounts:
    - name: stage-vol
      mountPath: /path/to/stage
  volumes:
  - name: stage-vol
    source: stage
    stageConfig:
      name: "@mydb.myschema.ai_models_stage/subpath"
      metadataCache: 1h
      resources:
        requests:
          cpu: 0.35
          memory: 0.4Gi
        limits:
          cpu: 2.0
          memory: 1Gi
$$;

Copy

アクセス制御の要件¶

サービス所有者ロールは、サービスを作成するために使用されるロールです。また、サービスがSnowflakeとやりとりする際に使用するロールでもあります。所有者ロールは、マウントされたステージへのアクセス向けとしてコンテナーに付与される権限を決定します。サービスの所有者ロールには、ステージ上で READ 権限が必要です。

たとえば、ステージでサービスロールが WRITE 権限を持っていない場合、そのステージのマウントは読み取り専用になります。つまり、コンテナーができるのはステージからファイルを読み取ることのみです。所有者ロールが読み取りと書き込みの両方をサポートするステージ・マウントには、ステージ上で WRITE 権限が必要です。

非推奨の実装について¶

非推奨になったステージ量の実装では、読み取りと書き込みに共有キャッシュを使用します。これは一部のシナリオではうまく機能しますが、キャッシュから、またはステージから直接、データを読み込むことは制御できません。これはすべてのアプリケーションに適しているとは限りません。さらに、キャッシュを読み取りと書き込みに使用すると、パフォーマンスのオーバーヘッドが発生する可能性があります。

非推奨実装からのコードの移行¶

新しい実装は非推奨になった実装を置き換え、次の動作を変更します。

新しいステージ量の実装では、クラウドストレージとの間でファイルコンテンツを直接ストリーミングし、常に最新のコンテンツを取得できるようにします。これにより、より予測可能な動作と、スループットの大幅な向上が実現します。非推奨になったステージ量の実装では、ファイルデータのチャンクがキャッシュされるため、最新のデータを読み込んでいるかどうかがわかりにくくなります。
キャッシュの削除により、新しい実装ではランダム読み取りのパフォーマンスが低下する可能性があります。ただし、ローカルディスクキャッシュがないと、ボリューム間の一貫性が向上します。ファイルの変更は、ファイルが閉じられると、ローカルディスクのバッファーなしでバックステージに直接書き込まれます。
読み取りは常に最新のデータを返すため、この構成はサービス間でデータを共有するのに適しています。
ランダム書き込み、ファイル追加はサポートされていません。これらの操作を試行すると、エラーが発生します。Snowflakeは、これらのワークロードにはブロックストレージ量を使用することをお勧めします。

サービス仕様でSnowflakeステージ量を指定する（非推奨）¶

サービスコンテナがSnowflakeステージ量を使用するサービスを作成するには、以下のステップに示すように、サービス仕様で必要な設定を指定します。

ステージ量を指定するには、次の例に示すように、 spec.volumes フィールドを使用します。
```
volumes:
- name: <name>
  source: <stage_name>
```
Copy
以下のフィールドは必須です。
- name: 量の名前。
- source:Snowflake内部ステージまたはマウントするステージ上のフォルダー。例えば @my_stage/folder 、 @my_stage 。この値は引用符で囲む必要があります。
spec.containers.volumeMounts フィールドを使用して、アプリケーションコンテナのステージ量をマウントする場所を次の例に示すように記述します。
```
volumeMounts:
- name: <name>
  mountPath: <absolute_directory_path>
```
Copy
このフィールドに入力する情報は、サポートされるすべてのストレージボリュームタイプで一貫しており、ステージボリュームの両方の実装に適用されます。

例（非推奨）¶

サンプルのサービス仕様の例では、アプリコンテナは非推奨のステージ量実装を使用して内部ステージ @model_stage をマウントします。

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

Copy

volumeMounts フィールドは、ステージ・ボリュームをマウントするコンテナ内の場所を指定します。この仕様は、両方のステージ量の実装で同じままです。

ステージボリュームを使用する際のガイドライン¶

このセクションでは、コンテナがSnowflakeステージをストレージ量として使用するアプリケーションコードを実装するときに従うべきガイドラインを提供します。

ステージ・ボリュームの両方の実装の共通ガイドライン¶

ステージ・マウントはシーケンシャルな読み書きに最適化されています。
ステージ・マウントのI/O操作は、コンテナーのファイル・システムやブロック・ストレージ・ボリュームのI/O操作よりも待機時間が高くなる可能性があります。I/O操作が成功したかどうかを確認するために、常にステータスコードをチェックすべきです。
ステージは、アップロードファイルの更新を非同期にマウントします。ステージ・マウント上のファイルへの変更は、ファイル・ディスクリプターが正常にクローズまたはフラッシュされた後にのみ、ステージに永続化されることが保証されます。ステージマウント上のファイルへの変更が他のコンテナーやSnowflakeから見えるようになるまで、多少の遅延が発生する場合があります。
マウントされたステージの各ディレクトリに含まれるファイルは、100,000個以下である必要があります。ディレクトリ内のファイル数に応じて readdir 待機時間が長くなることが予想されます。

ステージ量実装の非推奨バージョンを使用する際のガイドライン¶

ステージ・マウント内で複数のファイルへの同時書き込みを避けます。
ステージ・マウントはネットワーク・ファイルシステムではありません。マルチクライアントの調整にステージマウントを使わないでください。
同じファイルへの複数のハンドルを同時に開かないでください。オープンされたファイル・ハンドルは、読み取り操作か書き込み操作のどちらかに使用します。ファイルに書き込んだ後、そのファイルから読み込むには、読み込む前に一旦ファイルを閉じ、再度ファイルを開きます。

一般公開されているステージ量実装を使用する際のガイドライン¶

複数のステージマウント（異なるコンテナーにマウントされた同じステージボリューム）から同じファイルへの同時書き込みはサポートされていません。
ローカルディスクキャッシュがないため、マウント間の一貫性が向上します。ファイルの変更は、ファイルを閉じると、ローカルディスクのバッファーなしでバックステージに直接フラッシュされます。読み取りは常に最新のデータを返すため、新しいステージ・マウントはサービス間でデータを共有するのに適しています。
最適なパフォーマンスのため、大きな連続したチャンクでデータを読み書きします。一般に利用可能なステージボリュームの実装と比較して、小規模な読み取りおよび書き込みのパフォーマンスコストは、新しい実装によるパフォーマンス向上を軽減することができます。

ステージボリュームを使用する際の制限事項¶

このセクションでは、コンテナーがステージボリュームを使用するアプリケーションコードを実装するときに注意すべき制限について説明します。これらの限度額に関する問題が発生した場合は、アカウント担当者にお問い合わせください。

ステージボリュームの両方の実装における共通の制限¶

ステージまたはサブディレクトリをステージでマウントすることができます。例: @my_stage @my_stage/folder.例えば、 @my_stage/folder のように、1つのファイルを1つのステージにマウントすることはできません。
外部ステージはサポートされていません。Snowflake内部ステージのみがサポートされています。
ステージマウントは、 POSIX 互換性のあるファイルシステムではありません。例:
- ファイル名とディレクトリ名の変更はアトミックではありません。
- ハードリンクはサポートされていません。
ファイルシステムの変更を監視する Linux カーネルサブシステムの inode notify（inotify）は、ステージマウントでは動作しません。

ステージボリューム実装の非推奨バージョンを使用する場合の制限¶

1つのサービスにつき最大5つのステージ・ボリュームを使用できます。詳細については、spec.volumes をご参照ください。
コンピューティングプールノードあたり最大8ステージボリュームがサポートされています。Snowflake は、メモリ、 CPU、 GPU を管理する方法と同様に、ノードごとのステージマウントの制限を管理します。新しいサービスインスタンスを起動すると、既存のノードにリクエストされたステージマウントをサポートする容量がない場合に、Snowflakeが新しいノードを起動することがあります。
ステージボリュームの機能は、Snowflakeアカウントのクラウドプラットフォームによって異なります：
- アカウントは、SNOWFLAKE_FULL および SNOWFLAKE_SSE ステージ暗号化の両方に対応する内部ステージを AWS でサポートします。詳細については、内部ステージパラメーターをご参照ください。
- Azure 上のアカウントは現在、SNOWFLAKE_SSE 暗号化の内部ステージをサポートしています。SNOWFLAKE_SSE を実行する場合は、 :doc:` パラメーターを使用して暗号化タイプを指定します。CREATE
- Google Cloud上のアカウントはサポートされていません。
複数のステージマウント（異なるコンテナーにマウントされた同じステージボリューム）から同じファイルへの同時書き込みはサポートされていません。

ステージ・ボリューム実装の一般公開バージョンを使用する場合の制限事項¶

ランダム書き込み、ファイル追加はサポートされていません。
マウントされる各ステージには、ステージごとに512 MB メモリが必要です。つまり、インスタンスのサイズに応じて使用できるステージボリュームの数に制限があることを意味します。複数のコンテナにボリュームをマウントしても、メモリ消費が増加することはありません。
1つのサービスにつき最大20個のステージ量を使用できます。詳細については、 spec.volumes をご参照ください。