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

一般的なガイドライン¶

サービス/ジョブ仕様には、これら最上位の spec フィールドがあります。

• spec.containers （必須）: 1つ以上のアプリケーションコンテナーのリスト。コンテナー化されたアプリケーションには、少なくとも1つのコンテナーが必要です。

• spec.endpoints （オプション）: サービスが公開するエンドポイントのリスト。エンドポイントにパブリックを選択し、サービスへのネットワークイングレスアクセスを許可することもできます。

• spec.volumes （オプション）: コンテナーで使用するストレージボリュームのリスト。

• spec.logExporters （オプション）: このフィールドは、アカウントのイベントテーブルにエクスポートされるコンテナーログのレベルを管理します。

name フィールド（コンテナー名、エンドポイント名、ボリューム名）には、以下の形式ガイドラインが適用されます。

• 長さは63文字まで

• 小文字の英数字または'-'を含めることができる

• 英文字で始まること

• 英数字で終わること

以下のセクションでは、最上位 spec フィールドのそれぞれについて説明します。

spec.containers フィールド（必須）¶

containers フィールドは、アプリケーション内の OCI コンテナーのリストです。各コンテナーについて、 name と image のみが必須フィールドです。 image フィールドは、SnowflakeアカウントのSnowflakeイメージリポジトリにアップロードしたイメージの名前を指します。例:

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

サービス（またはジョブ）を作成すると、Snowflakeはこれらのコンテナーを指定されたコンピューティングプール内の単一ノード上で実行し、同じネットワークインターフェイスを共有します。複数のサービスインスタンスを実行することができます。その場合、実行されているコンテナーの各セットはサービスインスタンスと呼ばれます。

以下のセクションでは、 containers フィールドの型について説明します。

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

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

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

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

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

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

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

secrets:                            # optional list
  - snowflakeSecret:
    secretKeyRef:
    envVarName:                      # specify this or directoryPath
    directoryPath:                   # specify this or envVarName

spec.endpoints フィールド（オプション）¶

spec.endpoints フィールドを使用して、アプリケーションが公開する TCP ネットワークポートの名前のリストを指定します。Snowpark Container Servicesは、多くのエンドポイントにゼロを公開する可能性があります。以下のフィールドを使用してエンドポイントを説明します。

• name: エンドポイントの一意の名前。サービス関数内でエンドポイントを参照する場合は、この名前を指定します。

• port: アプリケーションがリッスンしているネットワークポート。

• protocol: エンドポイントがサポートするプロトコル。サポートされている値は、 TCP、 HTTP、および HTTPS です。デフォルトでは、プロトコルは HTTP です。このエンドポイントがパブリックまたはサービス関数のターゲットである場合、プロトコルは HTTP または HTTPS にする必要があります（サービスの使用 を参照）。

• public: このエンドポイントをインターネットからアクセスできるようにする場合は、このフィールドを true に設定します。

例

以下は、 チュートリアル1 で使用したアプリケーション仕様です。

spec:
  container:
  - name: echo
    image: <image-name>
    env:
      SERVER_PORT: 8000
      CHARACTER_NAME: Bob
    readinessProbe:
      port: 8000
      path: /healthcheck
  endpoint:
  - name: echoendpoint
    port: 8000
    public: true

このアプリケーションコンテナーは1つのエンドポイントを公開します。また、オプションの public フィールドも含まれており、Snowflake外部（インターネットアクセス）からのエンドポイントへのアクセスを有効にします。デフォルトでは、 public は false です。

spec.volumes フィールド（オプション）¶

このセクションでは、 spec.volumes と spec.containers.volumeMounts の両フィールドについて説明します。 volumes は共有ファイルシステムを定義します。 volumeMount は、コンテナー内のどこにボリュームが出現するかを定義します。複数のコンテナーで同じボリュームを共有できます。したがって、 volumes は spec レベルのフィールドであり、 volumeMount はコンテナー仕様の一部です。

これらのフィールドを使用して、ボリュームとボリュームマウントの両方を説明します。

• コンテナーで利用可能なボリュームを指定するには spec.volumes を使用します。 volumes はリストです。つまり、複数のボリュームが存在する可能性があります。以下のフィールドを使用してボリュームを説明します。

  • name: ボリュームの一意の名前。これは、 spec.containers.volumeMounts.name によって参照されます。

  • source: local、 memory、または "@<ステージ名>" のいずれか。

  • uid: Snowflakeステージボリュームの場合、これはマウントされたファイルのユーザー識別子です。

  • gid: Snowflakeステージボリュームの場合、これはマウントされたファイルのグループ識別子です。

  • size: メモリボリュームの場合、これはボリュームのサイズです。

• コンテナーのファイルシステムで、指定したボリュームがマウントされている場所を示すには spec.containers.volumeMounts を使用します。 containers.volumeMounts もリストです。つまり、各コンテナーは複数のボリュームマウントを持つことができる。以下のフィールドを使用してボリュームマウントを説明します。

  • name: マウントするボリュームの名前。単一のコンテナーは同じボリュームを複数回参照できます。

  • mountPath: コンテナーをマウントするためのボリュームへのファイルパス。

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

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

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

• メモリ: RAM に格納されたファイルシステムをコンテナー用に使用できます。

• Snowflakeステージ: Snowflakeステージを作成し、ステージングされたファイルへの便利なアクセスをコンテナーに付与できます。Snowflakeステージをマウントする場合は、以下の条件が適用されます。

  • 外部ステージはサポートされていません。SSE 暗号化を使用したSnowflake内部ステージのみがサポートされます。このようなステージを作るには、 CREATE STAGE を使用します。

    CREATE STAGE my_stage ENCRYPTION = (type = 'SNOWFLAKE_SSE');
    

    Copy

  • ステージまたはサブディレクトリ、たとえば @my_stage や @my_stage/folder をステージでマウントすることができます。ステージで、 @my_stage/folder/file のようなファイルをマウントすることはできません。

  • サービスロールは、マウントされたステージへのアクセス向けとしてコンテナーに付与される権限を決定します。サービスロールは、サービス/ジョブを作成するために使用されるロールです。また、サービス/ジョブがSnowflakeとのすべてのやり取りで使用するロールでもあります。

    たとえば、ステージでサービスロールが WRITE 権限を持っていない場合、そのステージのマウントは読み取り専用になります。つまり、コンテナーができるのはステージからファイルを読み取ることのみです。サービスロールがステージで WRITE 権限を持っている場合、そのステージのマウントは読み取りと書き込みの両方をサポートします。Snowflakeは、ファイルの更新を非同期でアップロードします。

  • Snowflakeステージをマウントするコンテナーは通常、ルートユーザーとして実行されます。しかし、コンテナーが非ルートユーザーとして実行されることもあります。例:

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

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

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

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

      Copy

      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)
         

例

機械学習アプリケーションには、以下の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 フィールドも指定する必要があることに注意してください。指定できるメモリサイズの単位については、 単位について をご参照ください。

spec.logExporters フィールド（オプション）¶

spec.logExporters を使用して、Snowflakeがアプリケーションログを収集する方法を構成します。Snowflakeは、出力をアプリケーションコンテナー内のコードから標準出力または標準エラーに収集します。

Snowflakeはこれらのログをアカウント内の イベントテーブル にエクスポートします。詳細については、 ローカルコンテナーログへのアクセス をご参照ください。 spec.logExporters.eventTableConfig を使用して、どのログをイベントテーブルに保存するかを示します。

logExporters:
  eventTableConfig:
    logLevel: < INFO | ERROR | NONE >

サポートされている logLevel 値は次のとおりです。

• INFO: すべてのユーザーログをエクスポートします。

• ERROR: エラーログのみをエクスポートします。Snowflakeは標準エラーストリームからログのみをエクスポートします。

• NONE （デフォルト）: イベントテーブルにログをエクスポートしません。

単位について¶

サービス仕様は、複数の場所で数値を取得します。Snowpark Container Servicesは、これらの値を表現するためのさまざまな単位をサポートしています。大きな値と小さな値には、表示のように2進数と10進数の単位を使うことができます。以下のリストでは、「#」は整数値を表します。

• 2進数単位:

  • numberKi は number*1024 を意味します。たとえば、 memory: 4Ki は memory: 4096 と等価です。

  • numberMi は number*1024^2 を意味します。

  • numberGi は number*1024^3 を意味します。

• 10進数単位:

  • numberk は number*10^3 を意味します。たとえば、 memory: 4k は memory: 4000 と等価です。

  • numberM は number*10^6 を意味します。

  • numberG は number*10^9 を意味します。

• 分数単位:

  • numberm は number*0.001 を意味します。たとえば、 cpu: 500m は cpu: 0.5 と等価です。