サービス仕様リファレンス¶

containers.name および containers.image フィールド¶

各コンテナーについて、名前とイメージのみが必須フィールドです。

• name はイメージ名です。この名前は、観測可能性の目的のために、特定のコンテナーを識別するために使用することができます（例えば、 logs、 metrics）。

• image フィールドは、SnowflakeアカウントのSnowflakeイメージリポジトリにアップロードしたイメージの名前を指します。

例:

spec:
  containers:
    - name: echo
      image: /tutorial_db/data_schema/tutorial_repository/echo_service:dev

containers.command および containers.args フィールド¶

これらのオプション・フィールドを使用して、コンテナー内で起動される実行ファイルと、その実行ファイルに渡される引数を制御します。イメージの作成時に、通常はDockerfileでこれらのデフォルトを設定することができます。これらのサービス仕様フィールドを使用することで、コンテナー・イメージを再構築することなく、これらのデフォルトを変更できます（つまり、コンテナーの動作を変更できます）。

• containers.command は Dockerfile ENTRYPOINT を上書きします。これにより、コンテナー内で別の実行ファイルを実行することができます。

• containers.args は Dockerfile CMD を上書きします。これにより、コマンド（実行ファイル）に異なる引数を付与することができます。

例

Dockerfile には、以下のコードが含まれています。

ENTRYPOINT ["python3", "main.py"]
CMD ["Bob"]

これらの Dockerfile エントリは python3 コマンドを実行し、 main.py と Bob の2つの引数を渡します。これらの値は、以下のように仕様ファイルで上書きすることができます。

• ENTRYPOINT を上書きするには、仕様ファイルに containers.command フィールドを追加します。

  spec:
    containers:
    - name: echo
      image: <image_name>
      command:
      - python3.9
      - main.py
  

  Copy

• 引数「Bob」を上書きするには、仕様ファイルに containers.args フィールドを追加します。

  spec:
    containers:
    - name: echo
      image: <image_name>
      args:
        - Alice
  

  Copy

containers.env フィールド¶

containers.env フィールドを使ってコンテナー環境変数を定義します。コンテナー内のすべてのプロセスは、これらの環境変数にアクセスできます。

spec:
  containers:
  - name: <name>
    image: <image_name>
    env:
      ENV_VARIABLE_1: <value1>
      ENV_VARIABLE_2: <value2>
      …
      …

例

チュートリアル1 では、アプリケーション・コード（echo_service.py）は、図のように環境変数を読み込みます。

CHARACTER_NAME = os.getenv('CHARACTER_NAME', 'I')
SERVER_PORT = os.getenv('SERVER_PORT', 8080)

この例では、 getenv 関数に変数のデフォルト値を渡していることに注意してください。環境変数が定義されていない場合は、これらのデフォルトが使用されます。

• CHARACTER_NAME: Echoサービスは、文字列（例: 「Hello」）を含む HTTP POST リクエストを受信すると、「I said Hello」を返します。このデフォルト値は、仕様ファイルで上書きすることができます。たとえば、値を「Bob」に設定すると、Echoサービスは「Bob said Hello」という応答を返します。

• SERVER_PORT: このデフォルト構成では、Echoサービスはポート8080でリッスンします。デフォルト値を上書きして、別のポートを指定することができます。

以下のサービス仕様は、これらの環境変数の値を上書きします。

spec:
  containers:
  - name: echo
    image: <image_name>
    env:
      CHARACTER_NAME: Bob
      SERVER_PORT: 8085
  endpoints:
  - name: echo-endpoint
    port: 8085

サービスがリッスンするポート番号を変更したため、仕様ではエンドポイント（endpoints.port field フィールド値）も更新されていることに注意してください。

containers.readinessProbe フィールド¶

containers.readinessProbe フィールドを使用して、アプリケーションの準備完了プローブを特定します。Snowflakeはこのプローブを呼び出して、アプリケーションがいつリクエストを処理できるようになったかを判断します。

Snowflakeは、指定されたポートおよびパスで、指定されたreadinessプローブに対して HTTP GET リクエストを実行し、健全なコンテナーのみがトラフィックを提供できるように、 HTTP 200 OK ステータスを返すサービスを探します。

以下のフィールドを使用して、必要な情報を入力します。

• port: サービスがreadinessプローブリクエストをリッスンしているネットワークポート。このポートをエンドポイントとして宣言する必要はありません。

• path: Snowflakeは、このパスを持つサービスに HTTP GET リクエストを実行します。

例

チュートリアル1では、アプリケーションコード（echo_python.py）は以下のreadinessプローブを実装します。

@app.get("/healthcheck")
def readiness_probe():

したがって、仕様ファイルには containers.readinessProbe フィールドが含まれます。

spec:
  containers:
  - name: echo
    image: <image_name>
    env:
      SERVER_PORT: 8088
      CHARACTER_NAME: Bob
    readinessProbe:
      port: 8088
      path: /healthcheck
  endpoints:
  - name: echo-endpoint
    port: 8088

readinessプローブが指定するポートは、構成されたエンドポイントである必要はありません。使用するサービスは、readinessプローブ専用に別のポートをリッスンすることができます。

containers.volumeMounts フィールド¶

spec.volumes フィールドと spec.containers.volumeMounts フィールドは連動しているため、1つのセクションでまとめて説明します。詳細については、 spec.volumes フィールド（オプション） をご参照ください。

containers.resources フィールド¶

コンピューティングプールは、利用可能なリソース（CPU 、メモリ、ストレージ）のセットを定義し、Snowflakeはコンピューティングプールのどこでサービスを実行するかを決定します。

指定コンテナーのリソース要件を明示的に示し、仕様に適切な制限を設定することを推奨します。指定するリソースは、コンピューティングプール内のノードのインスタンスファミリーに制約されることに注意してください。詳細については、 CREATE COMPUTE POOL をご参照ください。

containers.resources フィールドを使用して、特定のアプリケーションコンテナーに対する明示的なリソース要件を指定します。

• containers.resources.requests: 指定するリクエストは、サービスによって予想される平均的なリソース使用量でなければなりません。Snowflakeはこの情報を使って、コンピューティングプールにおけるサービスインスタンスの配置を決定します。Snowflakeは、指定されたノードに配置されたリソース要件の合計が、そのノードで利用可能なリソース内に収まることを保証します。

• containers.resources.limits: 指定した制限値は、指定した制限値以上のリソースを割り当てないようにSnowflakeに指示します。こうして、コスト超過を防ぐことができます。

以下のリソースのリクエストと制限を指定できます。

• memory: アプリケーションコンテナーに必要なメモリ。値を表す単位は 10進数でも2進数 でも構いません。例えば、2Gは2,000,000,000バイトのリクエストを表し、2Giは2×1024×1024×1024バイトのリクエストを表します。

  メモリを指定する場合は、単位が必要です。例: 100M または 5Gi。サポートされている単位は、M、Mi、G、Giです。

• cpu: 仮想コア（vCPU）単位を指します。たとえば、1 CPU 単位は1 vCPU と等価です。0.5のような小数リクエストも可能で、500mと表すこともできます。

• nvidia.com/gpu: GPUs が必要な場合は、それらをリクエストしなければならず、同じ数量に対して limit も指定する必要があります。コンテナーが GPU の容量に対するリクエストと制限を指定しない場合は、 GPUs にアクセスできません。リクエストできる GPUs の数は、 コンピューティングプール を作成するときに選択した INSTANCE_TYPE がサポートする最大 GPUs によって制限されます。

resource.requests および resource.limits は、関連する コンピューティングプール のインスタンスファミリのノード容量（vCPU およびメモリ）に対する相対値です。

• リソースリクエスト（CPU、メモリ、またはその両方）が提供されない場合、Snowflakeはリソースを導出します。

  • cpu の場合は、0.5か、指定した cpu の制限値のいずれか小さい方が導出値になります。

  • memory の場合は、0.5 GiB か、指定した memory の制限値のいずれか小さい方が導出値になります。

• リソース制限（CPU、メモリ、またはその両方）が提供されていない場合、Snowflakeは関連する コンピューティングプール のインスタンスファミリーのノード容量をデフォルトの制限とします。

• resource.limits を提供し、それらがノード容量を超える場合、Snowflakeはノード容量に制限を設定します。

• Snowflakeは cpu と memory について、これらのリソース要件を個別に評価します。

Snowflakeが指定されたコンピューティングプールでサービスをスケジュールすることが理論的に不可能な場合は、 CREATE SERVICE が失敗します。理論的に不可能なのは、コンピューティングプールが許可された最大ノード数を持ち、コンピューティングプール上で他のサービスが実行されていない場合です。つまり、Snowflakeがコンピューティングプールの制限内でリクエストされたリソースを割り当てることはできないということです。理論的には可能でも、必要なリソースが使用中であれば、 CREATE SERVICE は成功します。一部のサービスインスタンスは、リソースが利用可能になるまで、リソース不足のためにサービスをスケジュールできないことを示すステータスを報告します。

例1

以下の仕様では、 containers.resources フィールドにコンテナーのリソース要件を説明します。

spec:
  containers:
  - name: resource-test-gpu
    image: ...
    resources:
      requests:
        memory: 2G
        cpu: 0.5
        nvidia.com/gpu: 1
      limits:
        memory: 4G
        nvidia.com/gpu: 1

この例では、Snowflakeはコンテナーに対して、少なくとも2 GB のメモリ、1個の GPU および半個の CPU コアを割り当てるようにリクエストされます。同時に、コンテナーは4 GB を超えるメモリと1個を超える GPU を使用することが禁止されます。

例2

仮に

• 2つのノードのコンピューティングプールを作成します。各ノードに27 GB のメモリと1個の GPU があります。

  CREATE COMPUTE POOL tutorial_compute_pool
    MIN_NODES = 2
    MAX_NODES = 2
    INSTANCE_FAMILY = gpu_nv_s
  

  Copy

• Snowflakeにサービスのインスタンスを2つ実行するように依頼するサービスを作成します。

  CREATE SERVICE echo_service
    MIN_INSTANCES=2
    MAX_INSTANCES=2
    IN COMPUTE POOL tutorial_compute_pool
    FROM @<stage_path>
    SPEC=<spec-file-stage-path>;
  

  Copy

  MIN_INSTANCES と MAX_INSTANCES の両方を2に設定します。したがって、Snowflakeはサービスのインスタンスを2つ実行します。

では、これらのシナリオを考えてみましょう。

• アプリケーションの仕様にリソース要件を明示的に含めない場合、Snowflakeはこれらのインスタンスを同じノードで実行するか、コンピューティングプール内の異なるノードで実行するかを決定します。

• サービス仕様にリソース要件を含めて、 10 GB のコンテナー用のメモリをリクエストします。

  - name: resource-test
    image: ...
    resources:
      requests:
        memory: 15G
  

  Copy

  コンピューティングプールノードには27 GB のメモリがあり、Snowflakeは同じノード上で2つのコンテナーを実行できません。Snowflakeは2つのサービスインスタンスをコンピューティングプールの別々のノードで実行します。

• サービス仕様にリソース要件を含めて、コンテナー用に1 GB のメモリと1個の GPU をリクエストします。

  spec:
    containers:
    - name: resource-test-gpu
      image: ...
      resources:
        requests:
          memory: 2G
          nvidia.com/gpu: 1
        limits:
          nvidia.com/gpu: 1
  

  Copy

  コンテナーごとに1個の GPU をリクエストしており、各ノードには1個の GPU しかありません。この場合、メモリには問題がありませんが、Snowflakeは1つのノードに両方のサービスをスケジュールすることができません。この要件により、Snowflakeは2つのコンピューティングプールノードで2つのサービスインスタンスを実行することになります。

containers.secrets フィールド¶

secrets:                                # optional list
  - snowflakeSecret:
      objectName: <object-name>         # specify this or objectReference
      objectReference: <reference-name> # specify this or objectName
    directoryPath: <path>               # specify this or envVarName
    envVarName: <name>                  # specify this or directoryPath
    secretKeyRef: username | password | secret_string # specify only with envVarName
  - snowflakeSecret: <object-name>      # equivalent to snowflakeSecret.objectName
    ...

サービス仕様の containers.secrets フィールドを使用して、Snowflake が管理する認証情報をアプリケーションコンテナーに提供します。まず、 Snowflake secret オブジェクトに認証情報を格納します。次に、サービス仕様の中で、シークレットオブジェクトを参照し、コンテナー内のどこに認証情報を配置するかを指定します。

以下は、 containers.secrets フィールドの使い方の要約です。

• Snowflake secret の指定: snowflakeSecret フィールドを使用して、Snowflake secret オブジェクト名またはオブジェクト参照のいずれかを指定します。オブジェクト参照は、Snowpark コンテナーサービスを使用してNative App（コンテナー付きアプリ）を作成する場合に適用できます。

  • secretKeyRef を使用して、Snowflake シークレットのキー名を指定します。

• アプリケーション・コンテナ内のシークレットの配置を指定する: envVarName フィールドを使用して、シークレットを環境変数として渡すか、 directoryPath を使用して、シークレットをローカル・コンテナー・ファイルに書き込みます。

詳細については、 Snowflakeシークレットを使用してコンテナーに認証情報を引き渡す をご参照ください。

サービスを作成するロール（所有者ロール）には、参照されるシークレットの READ 権限が必要であることに注意してください。

サポートされているボリュームタイプについて¶

Snowflakeは、アプリケーションコンテナが使用するボリュームタイプとして、ローカル、メモリ、ブロック、およびSnowflakeステージをサポートしています。

• ローカルボリューム: サービスインスタンス内のコンテナーは、ローカルディスクを使用してファイルを共有できます。たとえば、アプリケーションにアプリケーションコンテナーとログアナライザーの2つのコンテナーがある場合、アプリケーションはローカルボリュームにログを書き込むことができ、ログアナライザーはログを読み取ることができます。

  サービスの複数のインスタンスを実行している場合、ボリュームを共有できるのはサービスインスタンスに属するコンテナーだけであることに注意してください。異なるサービスインスタンスに属するコンテナーは、ボリュームを共有しません。

• **メモリ

• ブロック: コンテナはブロックストレージボリュームを使用することもできます。詳細については、 サービスでのブロックストレージボリュームの使用 をご参照ください。

• Snowflake ステージ: 自分のアカウントにあるSnowflake・ステージ上のファイルへの便利なアクセスをコンテナーに与えることもできます。詳細については、 サービスでのSnowflakeステージボリュームの使用 をご参照ください。

例

機械学習アプリケーションには、以下の2つのコンテナーが含まれています。

• メインアプリケーション用 app コンテナー

• ログを収集し、Amazon S3にアップロードする logger-agent コンテナー。

これらのコンテナーは、以下の2つのボリュームを使用します。

• local ボリューム: このアプリケーションは、ログエージェントが読み取るログを書き込みます。

• Snowflakeステージ、 @model_stage: メインアプリケーションはこのステージからファイルを読み取ります。

以下の仕様例では、 app コンテナーは、 logs と models の両方のボリュームをマウントし、 logging-agent コンテナーは logs ボリュームのみをマウントします。

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

Copy

サービスの複数のインスタンスが実行されている場合、サービスインスタンス内の logging-agent と app コンテナーは logs ボリュームを共有します。 logs ボリュームはサービスインスタンス間では共有されません。

これらのボリュームに加えて、 app コンテナーが2 GB メモリボリュームも使用する場合は、仕様を修正して volumes リストにボリュームを含め、 app コンテナー volumeMounts リストに別のボリュームマウントも追加します。

spec:
  containers:
  - name: app
    image: <image1-name>
    volumeMounts:
    - name: logs
      mountPath: /opt/app/logs
    - name: models
      mountPath: /opt/models
    - name: my-mem-volume
      mountPath: /dev/shm
  - name: logging-agent
    image: <image2-name>
    volumeMounts:
    - name: logs
      mountPath: /opt/logs
  volumes:
  - name: logs
    source: local
  - name: models
    source: "@model_stage"
  - name: "my-mem-volume"
    source: memory
    size: 2G

Copy

ボリューム source として memory を指定する場合は、メモリサイズを示す volumes.size フィールドも指定する必要があることに注意してください。指定できるメモリサイズの単位については、 単位について をご参照ください。

マウントされたボリュームのファイル・権限について¶

Snowflakeステージまたはブロックストレージボリュームをマウントするコンテナーは通常、ルートユーザーとして実行されます。しかし、コンテナーが非ルートユーザーとして実行されることもあります。例:

• アプリケーションがサードパーティライブラリを使用する場合、ライブラリはコンテナー内でアプリケーションコードを実行するために非ルートユーザーを使用します。

• セキュリティなどの他の理由から、コンテナー内で非ルートユーザーとしてアプリケーションを実行することもあります。

ファイルユーザー権限に関連する潜在的なエラーを避けるために、コンテナーの UID （ユーザー ID）と GID （グループ ID）を仕様の一部として設定することが重要です。これは特に、コンテナー内でアプリケーションの起動や実行に特定のユーザーとグループを使用するコンテナーに関係があります。適切な UID と GID を設定すると、非ルートユーザーとして実行するコンテナーを使用できます。例:

spec:
  ...

  volumes:
  - name: stagemount
    source: "@test"
    uid: <UID-value>
    gid: <GID-value>

Snowflakeはこの情報を使用して、適切な権限でステージをマウントします。

コンテナーの UID と GID を取得するには、以下を行います。

1. docker run を使用してコンテナーをローカルで実行します。

2. docker container list コマンドを使用してコンテナー ID を検索します。サンプル出力の一部は次のとおりです。

   CONTAINER ID   IMAGE                       COMMAND
   —----------------------------------------------------------
   a6a1f1fe204d  tutorial-image         "/usr/local/bin/entr…"
   

3. コンテナー内で docker id コマンドを実行し、 UID と GID を取得します。

   docker exec -it <container-id> id
   

   Copy

   サンプル出力:

   uid=0(root) gid=0(root) groups=0(root)