Snowpark Container Services: サービスの操作¶

長時間実行サービスの作成¶

CREATE SERVICE を使用して長時間実行サービスを作成します。

• インライン仕様を使用してサービスを作成します。以下に示すように、開発中はほとんどのケースでインライン仕様を選ぶことができます。

  CREATE SERVICE echo_service
     IN COMPUTE POOL tutorial_compute_pool
     FROM SPECIFICATION $$
     spec:
       containers:
       - name: echo
         image: /tutorial_db/data_schema/tutorial_repository/my_echo_service_image:tutorial
         readinessProbe:
           port: 8000
           path: /healthcheck
       endpoints:
       - name: echoendpoint
         port: 8000
         public: true
     $$;
  

  Copy

• ステージ情報を使用してサービスを作成します。サービスを実稼働環境に展開する際には、懸念事項の分離という設計原則を適用し、仕様をステージにアップロードし、以下に示すように、ステージ情報の CREATE SERVICE コマンドを提供することをお勧めします。

  CREATE SERVICE echo_service
    IN COMPUTE POOL tutorial_compute_pool
    FROM @tutorial_stage
    SPECIFICATION_FILE='echo_spec.yaml';
  

  Copy

ジョブサービスの実行¶

EXECUTE JOB SERVICE を使用してジョブサービスを作成します。このコマンドは同期的に実行され、ジョブ・サービスのすべてのコンテナーが終了した後に応答を返します。

• インライン仕様を使用してジョブサービスを実行します。

  EXECUTE JOB SERVICE
     IN COMPUTE POOL tutorial_compute_pool
     NAME = example_job_service
     FROM SPECIFICATION $$
     spec:
       container:
       - name: main
         image: /tutorial_db/data_schema/tutorial_repository/my_job_image:latest
         env:
           SNOWFLAKE_WAREHOUSE: tutorial_warehouse
         args:
         - "--query=select current_time() as time,'hello'"
         - "--result_table=results"
     $$;
  

  Copy

• ステージ情報を使用してジョブサービスを実行します。

  EXECUTE JOB SERVICE
    IN COMPUTE POOL tutorial_compute_pool
    NAME = example_job_service
    FROM @tutorial_stage
    SPECIFICATION_FILE='my_job_spec.yaml';
  

  Copy

仕様テンプレートの使用¶

同じ仕様で複数のサービスを作成したいが、構成が異なる場合があります。たとえば、サービス仕様で 環境変数 を定義し、同じ仕様で環境変数の値が異なる複数のサービスを作成したいとします。

仕様テンプレートのサポートにより、仕様内でフィールド値の変数を定義することができます。サービスを作成するときに、これらの変数に値を指定します。

仕様テンプレートの使用は、2段階のプロセスからなります。

1. さまざまな仕様フィールドの値として変数を使用して仕様を作成します。これらの変数を指定するには、 {{ variable_name }} 構文を使用します。例えば、以下の指定では、イメージタグ名に「tag_name」という変数を使い、サービスごとに異なるイメージタグを指定します。

   spec:
     containers:
     - name: echo
       image: myorg-myacct.registry.snowflakecomputing.com/tutorial_db/data_schema/tutorial_repository/my_echo_service_image:{{ tag_name }}
       ...
     endpoints:
     …
   

   Copy

2. CREATE SERVICE コマンドで仕様テンプレートを提供してサービスを作成します。テンプレートの指定には SPECIFICATION_TEMPLATE または SPECIFICATION_TEMPLATE_FILE を使用します。変数の値を指定するには、 USING パラメーターを使用します。例えば、次のステートメントはSnowflakeステージの仕様テンプレートを使用しています。USING パラメーターは、変数 tag_name に値 'latest' を設定します。

   CREATE SERVICE echo_service
      IN COMPUTE POOL tutorial_compute_pool
      FROM @STAGE SPECIFICATION_TEMPLATE_FILE='echo.yaml'
      USING (tag_name=>'latest');
   

   Copy

USING( var_name=>var_value, [var_name=>var_value, ... ] );

例¶

次の例は、仕様テンプレートを使用してサービスを作成する方法を示しています。これらの例の CREATE SERVICE コマンドはインライン仕様を使っています。

CREATE SERVICE echo_service
   IN COMPUTE POOL tutorial_compute_pool
   MIN_INSTANCES=1
   MAX_INSTANCES=1
   FROM SPECIFICATION_TEMPLATE $$
      spec:
         containers:
         - name: echo
           image: {{ image_url }}
           env:
             SERVER_PORT: {{SERVER_PORT}}
             CHARACTER_NAME: Bob
           readinessProbe:
             port: {{SERVER_PORT}}
             path: /healthcheck
         endpoints:
         - name: echoendpoint
           port: {{SERVER_PORT}}
           public: true
         $$
      USING (image_url=>' "/tutorial_db/data_schema/tutorial_repository/my_echo_service_image:latest" ', SERVER_PORT=>8000 );

spec:
  containers:
  - name: echo
    image: /tutorial_db/data_schema/tutorial_repository/my_echo_service_image:latest
    env:
      SERVER_PORT: 8000
      CHARACTER_NAME: Bob
    readinessProbe:
      port: 8000
      path: /healthcheck
    endpoints:
    - name: echoendpoint
      port: 8000
      public: true

spec:
 containers:
 - name: echo
   image: /tutorial_db/data_schema/tutorial_repository/my_echo_service_image:latest
   env:
     SERVER_PORT: 8000
     CHARACTER_NAME: Bob
   …

CREATE SERVICE echo_service
  IN COMPUTE POOL tutorial_compute_pool
  MIN_INSTANCES=1
  MAX_INSTANCES=1
  FROM SPECIFICATION_TEMPLATE $$
     spec:
       containers:
       - name: echo
         image: /tutorial_db/data_schema/tutorial_repository/my_echo_service_image:latest
         env: {{env_values}}
         readinessProbe:
           port: {{SERVER_PORT}}    #this and next tell SF to connect to port 8000
           path: /healthcheck
       endpoints:
       - name: echoendpoint
         port: {{SERVER_PORT}}
         public: true
        $$
     USING (env_values=>'{"SERVER_PORT": 8000, "CHARACTER_NAME": "Bob"}' );

spec:
  container:
  - name: main
    image: /tutorial_db/data_schema/tutorial_repository/my_job_image:latest
    env:
      SNOWFLAKE_WAREHOUSE: tutorial_warehouse
    args:
    - "--query=select current_time() as time,'hello'"
    - "--result_table=results"

spec:
  container:
  - name: main
    image: /tutorial_db/data_schema/tutorial_repository/my_job_image:latest
    env:
      SNOWFLAKE_WAREHOUSE: tutorial_warehouse
    args: {{ARGS}}
  $$
  USING (ARGS=$$["--query=select current_time() as time,'hello'", "--result_table=results"]$$ );

オートスケールの有効化¶

実行中のサービスインスタンス数を自動スケールするようにSnowflakeを構成するには、以下のステップに従います。

1. サービス仕様ファイルで、サービスインスタンスに必要なメモリと CPU を指定します。詳細については、 container.resources フィールドをご参照ください。

   例

   resources:
     requests:
      cpu: <cpu-units>
   

   Copy

2. CREATE SERVICE コマンドを実行する場合は、 MIN_INSTANCES と MAX_INSTANCES パラメーターを設定します。また、 ALTER SERVICE を使用してこれらの値を変更することもできます。オートスケーリングは、指定された MAX_INSTANCES が MIN_INSTANCES より大きい場合に発生します。

Snowflakeは、指定されたコンピューティングプール上に最小数のサービスインスタンスを作成することから開始します。その後、Snowflakeは80% CPU の使用しきい値に基づいて、サービスインスタンス数をスケールアップまたはスケールダウンします。Snowflakeは、現在実行中のすべてのサービスインスタンスの使用データを集約し、コンピュートプール内の CPU 使用率を継続的に監視します。

Snowflakeは、（すべてのサービスインスタンスを合計した） CPU の使用率が80%を超えると、コンピュートプール内に追加のサービスインスタンスをデプロイします。CPU の使用率が 80% を下回ると、Snowflake は実行中のサービスインスタンスを削除してスケールダウンします。Snowflakeは5分間の安定化ウィンドウを使用して、頻繁なスケーリングを防止します。

以下のスケーリング動作に注意してください。

• サービスインスタンスのスケーリングは、サービス用に構成された MIN_INSTANCES と MAX_INSTANCES パラメーターによって制約されます。

• スケールアップが必要で、コンピューティングプールノードが別のサービスインスタンスを起動するために必要なリソース容量が不足している場合は、コンピューティングプールの自動スケールをトリガーできます。詳細については、 コンピューティングプールノードの自動スケーリング をご参照ください。

• サービスの作成時に MAX_INSTANCES と MIN_INSTANCES パラメーターを指定しても、サービス仕様ファイルでサービスインスタンスのメモリと CPU 要件を指定しない場合は、自動スケーリングは実行されません。Snowflakeは MIN_INSTANCES パラメーターで指定されたインスタンスの数で開始され、数は自動スケーリングされません。

• 長時間稼働しているサービスは、コンピュートプールのリソースを消費し、コストを発生させますが、意味のある作業を行っていない場合には、サービスを一時停止することができます(ALTERSERVICE ... SUSPEND を参照)。どのコンピュートプールノードでもサービスやジョブがアクティブでない場合、Snowflakeの自動一時停止メカニズムがプールを一時停止してコストを削減します。

サービスの終了¶

サービスを一時停止 (ALTERSERVICE... SUSPEND) またはサービスを停止 (DROP SERVICE) すると、Snowflake はすべてのサービスインスタンスを終了します。同様に、サービスコードをアップグレードする場合（ALTER SERVICE...<fromSpecification> ）、Snowflake は、一度に 1 つのサービスインスタンスを終了して再デプロイすることで、 ローリングアップグレード を適用します。

サービスインスタンスを終了する際、Snowflakeはまず各サービスコンテナに SIGTERM シグナルを送信します。コンテナーには、シグナルを処理し、30秒のウィンドウで優雅にシャットダウンするオプションがあります。そうでない場合は、猶予期間の後、Snowflake はコンテナー内のすべてのプロセスを終了します。

サービスコードの更新とサービスの更新¶

サービス作成後、 ALTER SERVICE...<fromSpecification> コマンドを使用してサービスコードを更新し、サービスを再デプロイします。

まず、修正したアプリケーションコードをイメージリポジトリにアップロードし、インラインまたはSnowflakeステージの仕様ファイルへのパスを指定して、サービス仕様を提供する ALTER SERVICE を呼び出します。例:

ALTER SERVICE echo_service
FROM SPECIFICATION $$
spec:
  …
  …
$$;

リクエストを受信すると、Snowflakeは新しいコードを使用してサービスを再展開します。

CREATESERVICE...<from-Specification> コマンドを実行すると、Snowflake は提供されたイメージの特定のバージョンを記録します。Snowflakeは、リポジトリ内のイメージが更新された場合でも、以下のシナリオで同じイメージバージョンをデプロイします。

• 中断されたサービスが再開された場合（ALTERSERVICE... RESUMEを使用）。

• オートスケールがさらにサービス・インスタンスを追加する場合。

• クラスタメンテナンス中にサービスインスタンスが再起動された場合。

しかし、 ALTER SERVICE...<fromSpecification> を呼び出すと、Snowflakeがそのイメージのリポジトリにある最新バージョンを使用するトリガーとなります。

あなたがサービス・オーナーである場合、 DESCRIBE SERVICE コマンドの出力にはサービス仕様が含まれ、下図のようにイメージ・ダイジェスト（仕様の sha256 フィールドの値）が含まれます。

spec:
containers:
- name: "echo"
    image: "/tutorial_db/data_schema/tutorial_repository/my_echo_service_image:latest"
    sha256: "@sha256:8d912284f935ecf6c4753f42016777e09e3893eed61218b2960f782ef2b367af"
    env:
      SERVER_PORT: "8000"
      CHARACTER_NAME: "Bob"
    readinessProbe:
      port: 8000
      path: "/healthcheck"
endpoints:
- name: "echoendpoint"
    port: 8000
    public: true

ALTER SERVICE は、サービスとの通信（ サービスの使用 を参照）に影響を与える可能性があります。

• ALTER SERVICE...<fromSpecification> でエンドポイントが削除されたり、エンドポイントを使用するために必要な関連するパーミッションが削除されたりした場合（仕様リファレンスの serviceRoles を参照）、サービスへのアクセスは失敗します。詳しくは、 Using Service をご参照ください。

• アップグレード中は、新しい接続が新しいバージョンにルーティングされる可能性があります。新しいサービス・バージョンに後方互換性がない場合、有効なサービス利用は中断されます。例えば、サービス・ファンクションを使った継続的なクエリは失敗するかもしれません。

デフォルトのサービス・ロールを使用するすべてのエンドポイントで USAGE 権限を付与します。¶

サービス（ジョブサービスを含む）を作成すると、Snowflakeは ALL_ENDPOINTS_USAGE という名前のデフォルトサービスロールも作成します。このロールはサービスが公開するすべてのエンドポイントに対して USAGE の権限を持ちます。 GRANT SERVICE ROLE コマンドを使用して、このデフォルトサービスロールを他のロールに付与できます。

GRANT SERVICE ROLE my_echo_service_image!ALL_ENDPOINTS_USAGE TO ROLE some_other_role;

some_other_role を使用しているユーザーは、すべてのサービスエンドポイントで USAGE 権限を持ちます。

サービスをドロップすると、Snowflakeはサービスに関連付けられたすべてのサービスロール（デフォルトサービスロールおよびサービス仕様で定義されたサービスロール）をドロップし、すべてのサービスロールの付与を無効にします。

仕様で定義されたサービス・ロールを使用して、特定のエンドポイントに USAGE 権限を付与します。¶

サービスロールを使用して、サービスエンドポイントへのきめ細かなアクセスを管理します。サービスロールは、サービス仕様で USAGE 権限を付与されたエンドポイントのリストとともに定義します。

サービスの特定のエンドポイントに権限を付与するには、2段階のプロセスがあります。

1. サービスロールを定義する: ロール名と、 USAGE 権限を付与したい1つ以上のエンドポイントのリストを提供することによって、サービスロールを定義するためにサービス仕様を使用します。たとえば、以下の仕様の断片では、最上位 serviceRoles フィールドは、特定のエンドポイントで USAGE 権限を持つ2つのサービスロールを定義しています。

   spec:
   ...
   serviceRoles:                 # Optional list of service roles
   - name: <svc_role_name1>
     endpoints:                  # endpoints that role can access
     - <endpoint_name1>
     - <endpoint_name2>
   - name: <svc_role_name2>
     endpoints:
     - <endpoint_name3>
     - <endpoint_name4>
   

   Copy

2. 他のロールにサービスロールを付与する: GRANT SERVICE ROLE コマンドを使用して、サービスロールを他のロール（アカウントロール、アプリケーションロール、データベースロール）に付与します。例:

   GRANT SERVICE ROLE <service-name>!<svc_role_name1> TO ROLE <another-role>
   

   Copy

サービス関数: SQL クエリからのサービスの使用¶

サービス関数とは、 CREATE FUNCTION （Snowpark Container Services） を使用して作成するユーザー定義関数（UDF）のことです。しかし、 UDF のコードを直接記述する代わりに、 UDF をサービスエンドポイントに関連付けます。サービス機能は、 HTTP または HTTPS プロトコルをサポートするサービスエンドポイントにのみ関連付けることができます。

たとえば、 チュートリアル1 では、サービス仕様で定義された1つのエンドポイント（echoendoint）を公開する echo_service という名前のサービスを作成します。

spec:
…
  endpoints:
  - name: echoendpoint
    port: 8080

echoendpoint は、対応するポート（8080）を表す分かりやすいエンドポイント名です。このサービスエンドポイントと通信するには、次に示すように SERVICE と ENDPOINT パラメーターを指定してサービス関数を作成します。

CREATE FUNCTION my_echo_udf (text varchar)
   RETURNS varchar
   SERVICE=echo_service
   ENDPOINT=echoendpoint
   AS '/echo';

AS パラメーターは、サービスコードへの HTTP パスを提供します。このパス値はサービスコードから取得します（例: チュートリアル 1 のservice.pyを参照）。例えば、以下のコード行は チュートリアル 1 の service.py にあります。

@app.post("/echo")
def echo():
...

サービス関数を呼び出すと、Snowflakeは関連するサービスエンドポイントとパスにリクエストを誘導します。

ALTER FUNCTION my_echo_udf(VARCHAR)
   SET SERVICE=other_service
   ENDPOINT=otherendpoint
   MAX_BATCH_ROWS=100

"Alex", "2014-01-01 16:00:00"
"Steve", "2015-01-01 16:00:00"
…

SELECT service_func(col1, col2) FROM input_table;

{
   "data":[
      [
         0,
         "Alex",
         "2014-01-01 16:00:00"
      ],
      [
         1,
         "Steve",
         "2015-01-01 16:00:00"
      ],
      …
      [
         <row_index>,
         "<column1>",
         "<column2>"
      ],
   ]
}

{
   "data":[
      [0, "a"],
      [1, "b"],
      …
      [ row_index,  output_column1]
   ]
}

USE ROLE service_owner;
GRANT USAGE ON service service_db.my_schema.my_service TO ROLE func_owner;

USE ROLE func_owner;
CREATE OR REPLACE test_udf(v VARCHAR)
  RETURNS VARCHAR
  SERVICE=service_db.my_schema.my_service
  ENDPOINT=endpointname1
  AS '/run';

SELECT test_udf(col1) FROM some_table;

ALTER FUNCTION test_udf(VARCHAR) SET
  SERVICE = service_db.other_schema.other_service
  ENDPOINT=anotherendpoint;

GRANT USAGE ON FUNCTION test_udf(varchar) TO ROLE func_user;
USE ROLE func_user;
SELECT my_test_udf('abcd');

イングレス: Snowflake外部からのサービスの使用¶

サービスは、1つまたは複数のエンドポイントを パブリック として公開して、ユーザーがパブリックウェブからサービスを使用できるようにします。この場合は、Snowflakeがアクセス制御を管理します。イングレスは HTTP または HTTPS のエンドポイントでのみ許可されます。

サービス仕様ファイルでエンドポイントをパブリックとしてマークします。

spec
  ...
  endpoints
  - name: <endpoint name>
    port: <port number>
    public: true

サービス間通信¶

サービス・インスタンスは、 TCP (HTTP/HTTPSを含む)を介して相互に直接通信することができます。これは、同じサービスに属するインスタンスにも、異なるサービスに属するインスタンスにも当てはまります。

インスタンスは で宣言されたエンドポイント でのみ通信（リクエスト）を受け取ることができます。クライアント（リクエストを送信するサービス）は、そのエンドポイントに接続するために必要なロールとグラントを持っていなければなりません。

• デフォルトでは、サービスインスタンスは宣言されたエンドポイントで同じサービスの他のインスタンスに接続できます。広い意味では、サービスの 所有者ロール は、同じオーナーロールを持つサービスのエンドポイントに接続する権限を持っています。

• クライアントサービスが異なる所有者ロールを持つサービスのエンドポイントに接続するには、エンドポイントに関連付けられた サービスロール が、クライアントサービスの 所有者ロール に付与されている必要があります。例:

  GRANT SERVICE ROLE my_service!all_endpoints_usage TO ROLE custom_role;
  

  Copy

• サービス同士が通信できないようにする場合（セキュリティなどの理由により）は、異なるSnowflakeロールを使用してこれらのサービスを作成します。

サービス・インスタンスには、サービス・アドレス（IP）またはサービス・インスタンス・アドレス（IP）のいずれかを使用してアクセスできます。

• サービス IP アドレスを使ったリクエストはロードバランサーにルーティングされ、ロードバランサーはランダムに選ばれたサービスインスタンスにリクエストをルーティングします。

• サービスインスタンス IP アドレスを使用したリクエストは、特定のサービスインスタンスに直接ルーティングされます。portRange フィールドを使用して定義されたエンドポイントに接続する場合は、サービスインスタンス IP を使用する必要があります（ spec.endpoints フィールド（オプション） を参照）。

どちらの IP アドレスも、Snowflake が各サービスに自動的に割り当てる DNS 名を使用して検出可能です。なお、 DNS を使って特定のインスタンスに接続することはできません。例えば、サービスインスタンス DNS 名を使用して URL を構築することは意味がありません。なぜなら、サービスインスタンス DNS 名を使用して特定のサービスインスタンスをリファレンスする方法がないからです。

2025_01 動作変更バンドル が有効な場合、 SHOW SERVICE INSTANCES IN SERVICE コマンドの出力にサービスインスタンス IP アドレスが表示されます。

サービス間通信の例については、 チュートリアル3 をご参照ください。

サービス間の通信を可能にするためだけにサービスエンドポイントを作成する場合は、 TCP プロトコルを使用する必要があることに注意してください（spec.endpoints フィールド（オプション） を参照）。

<service-name>.<hash>.svc.spcs.internal

instances.<service-name>.<hash>.svc.spcs.internal