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

複数のサービスインスタンスを作成し、自動スケールを構成する¶

デフォルトでは、Snowflakeは指定したコンピューティングプールでサービスのインスタンスを1つ実行します。重いワークロードを管理するには、 MIN_INSTANCES と MAX_INSTANCES プロパティを設定して、複数のサービスインスタンスを実行できます。このプロパティは、サービスの最小インスタンス数から開始し、必要に応じてSnowflakeがスケールできる最大インスタンス数を指定します。

例

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

複数のサービスインスタンスが実行されている場合、Snowflakeは自動的にロードバランサーを提供し、受信するリクエストを分散します。

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

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

   例

   resources:
     requests:
      memory: <memory-reserved>
      cpu: <cpu-units>
   

   Copy

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

Snowflakeは、指定されたコンピューティングプール上に最小数のサービスインスタンスを作成することから開始します。Snowflakeはしきい値の80%（ CPU とメモリの双方で）を使用して、サービスインスタンス数をスケールアップまたはスケールダウンします。Snowflakeは、現在実行中のすべてのサービスインスタンスから使用状況データを集約して、コンピューティングプール内のリソース使用量（メモリまたは CPU）を継続的にモニターします。

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

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

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

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

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

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

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

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

仕様テンプレートの使用は、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"]$$ );

サービスの終了¶

サービスを一時停止 (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

サービス間通信¶

サービスは、Snowflakeが各サービスに自動的に割り当てる DNS 名を使用して相互に通信できます。例については、 チュートリアル3 をご参照ください。サービス間の通信を可能にするためだけにサービスエンドポイントを作成する場合は、 TCP プロトコルを使用する必要があることに注意してください。

DNS 名形式は以下のとおりです。

<service-name>.<schema-name>.<db-name>.snowflakecomputing.internal

サービスの DNS 名を取得するには、 SHOW SERVICES （または DESCRIBE SERVICE ）を使用します。前述の DNS 名はフルネームです。同じスキーマで作成されたサービスでは、 <サービス名> を使用するだけで通信できます。同じデータベースにありながらスキーマが異なるサービスでは、 <サービス名>.<スキーマ名> のようにスキーマ名を指定する必要があります。

Snowflakeは、同じロールによって作成されたサービス間のネットワーク通信を許可し、異なるロールによって作成されたサービス間のネットワーク通信をブロックします。サービス同士が通信できないようにする場合（セキュリティなどの理由により）は、異なるSnowflakeロールを使用してこれらのサービスを作成します。

DNS 名には以下の制限があります。

• データベース名、スキーマ名、サービス名は、有効な DNS ラベルにする必要があります。（https://www.ietf.org/rfc/rfc1035.html#section-2.3.1 もご参照ください）。それ以外の場合は、サービスの作成に失敗します。

• Snowflakeは、名前（データベース、スキーマ、およびサービス名）のアンダースコア（_）を DNS 名ではダッシュ（-）に置き換えます。

• Snowflakeはサービスの DNS 名を更新しないため、サービスを作成した後はデータベースやスキーマ名を変更しないでください。

• DNS 名は、同じアカウントで実行されているサービス間のSnowflake内部での通信にのみ使用されます。インターネットからはアクセスできません。