サービスでのSnowflakeステージボリュームの使用¶

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

To define a stage volume, add the spec.volumes field in the service specification as shown in the following example:

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

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.

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

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

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>

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

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

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

• 新しいステージ量の実装では、クラウドストレージとの間でファイルコンテンツを直接ストリーミングし、常に最新のコンテンツを取得できるようにします。これにより、より予測可能な動作と、スループットの大幅な向上が実現します。非推奨になったステージ量の実装では、ファイルデータのチャンクがキャッシュされるため、最新のデータを読み込んでいるかどうかがわかりにくくなります。

• キャッシュの削除により、新しい実装ではランダム読み取りのパフォーマンスが低下する可能性があります。ただし、ローカルディスクキャッシュがないと、ボリューム間の一貫性が向上します。ファイルの変更は、ファイルが閉じられると、ローカルディスクのバッファーなしでバックステージに直接書き込まれます。

• 読み取りは常に最新のデータを返すため、この構成はサービス間でデータを共有するのに適しています。

• ランダム書き込み、ファイル追加はサポートされていません。これらの操作を試行すると、エラーが発生します。Snowflakeは、これらのワークロードには ブロックストレージ量 を使用することをお勧めします。

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:

1. 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.

2. 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

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

例（非推奨）¶

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"

The volumeMounts field specifies where inside the container to mount the stage volume. This specification remains the same for both the stage volume implementations.

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

• ステージ・マウントはシーケンシャルな読み書きに最適化されています。

• ステージ・マウントの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 のように、1つのファイルを1つのステージにマウントすることはできません。

• 外部ステージはサポートされていません。Snowflake内部ステージのみがサポートされています。

• ステージマウントは、 POSIX 互換性のあるファイルシステムではありません。例:

  • ファイル名とディレクトリ名の変更はアトミックではありません。

  • ハードリンクはサポートされていません。

• ファイルシステムの変更を監視する Linux カーネルサブシステムの inode notify（inotify） は、ステージマウントでは動作しません。

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

• 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 メモリが必要です。つまり、インスタンスのサイズに応じて使用できるステージボリュームの数に制限があることを意味します。複数のコンテナにボリュームをマウントしても、メモリ消費が増加することはありません。

• A maximum of 20 stage volumes are allowed per service. For more information, see spec.volumes.