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

基本的なサービス操作¶

Snowpark Container Servicesは、サービスの作成と管理に使用できる SQL コマンドのセットを提供します。これらには次が含まれます。 CREATE SERVICE、 ALTER SERVICE、 DROP SERVICE、 SHOW SERVICES、 および DESC[RIBE] SERVICE。

サービスの作成に最低限必要な情報は以下のとおりです。

• サービス仕様: この 仕様 は、サービスの実行に必要な情報をSnowflakeに提供します。仕様は YAML ファイルです。CREATE SERVICE ステートメント内で仕様を直接定義するか、仕様をSnowflakeステージにアップロードし、 CREATE SERVICE ステートメント内でステージ情報を参照します。

  多くの場合、開発中はインライン仕様を選ぶでしょう。しかし、サービスを実稼働環境に展開する際には、懸念事項の分離という設計原則を適用し、仕様をステージにアップロードすることが望ましいといえます。

• コンピューティングプール: Snowflakeは、指定された コンピューティングプール でサービスを実行します。

例

• インライン仕様を使用してサービスを作成します。

  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 echo_service
    IN COMPUTE POOL tutorial_compute_pool
    FROM @tutorial_stage
    SPECIFICATION_FILE='echo_spec.yaml';
  

  Copy

サービスを作成した後、 ALTER SERVICE コマンドを使用してサービスを中断または再開することができます。

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

サービスをリストする¶

さまざまな SHOW SERVICES コマンドを使用して、現在のサービスをリストすることができます。

• SHOW SERVICES: 権限を持っている現在のデータベースとスキーマのサービスをリストします。

• SHOW SERVICES IN ACCOUNT: サービスがどのデータベースやスキーマに属しているかに関係なく、Snowflakeアカウントのサービスをリストします。これは、アカウント内の複数のデータベースとスキーマにSnowflakeサービスが作成されている場合に便利です。他のコマンドと同様に、 SHOW SERVICES IN ACCOUNTS は権限によって制限され、使用しているロールが表示権限を持っているサービスのみを返します。

• SHOW SERVICES IN SCHEMA: 指定されたスキーマのサービスをリストします。

特定のコンピューティングプールのサービスをリストアップするのは、2段階のプロセスです。

1. SHOW SERVICES を実行し、サービスのリストを取得します。

2. 特定のコンピューティングプールにあるサービスのために、前回のクエリ（RESULT_SCAN を使用）のリストをスキャンします。

例

以下のスクリプト例では、 SHOW SERVICES コマンドはまず、現在のデータベースとスキーマの中で、サービス名に特定の文字列を持つサービスをリストします。

次に、 SELECT クエリは、指定されたコンピューティングプール内のサービスのみを返すように結果セットをフィルターします。このクエリでは、前述の SHOW SERVICES コマンドの結果セットを取得するために RESULT_SCAN 関数を使用していることに注意してください。

SHOW SERVICES like '%tutorial%' in account;
SELECT *
    FROM TABLE(RESULT_SCAN(last_query_id()))
    WHERE "compute_pool" = 'TUTORIAL_COMPUTE_POOL';

サービスのモニタリング¶

サービスの詳細な実行時ステータスを取得するには、 SYSTEM$GET_SERVICE_STATUS を使用します。たとえば、この関数を呼び出すと、サービスがまだ実行中なのか、それともサービスの開始に失敗したのかを判断することができます。サービスの開始に失敗した場合、この関数は失敗の詳細を提供します。

この関数を呼び出す場合は、サービスの名前で渡します。

例

CALL SYSTEM$GET_SERVICE_STATUS('echo_service');

以下は出力例です。

• 1つのインスタンスを実行し、1つのコンテナーを持つサービスのサンプル出力:

  [
     {
        "status":"READY",
        "message":"Running",
        "containerName":"echo",
        "instanceId":"0",
        "serviceName":"ECHO_SERVICE",
        "image":"<account>.registry.snowflakecomputing.com/tutorial_db/data_schema/tutorial_repository/my_echo_service_image:tutorial",
        "restartCount":0,
        "startTime":"2023-01-01T00:00:00Z"
     }
  ]
  

  Copy

  instanceId は、コンテナーが属するサービスインスタンス ID です。このサービスのインスタンスを2つ実行した場合、出力にはこのようなオブジェクトが2つ含まれ、各サービスインスタンスのコンテナーステータスが提供されます。この場合、インスタンス IDs は0と1です。

• 1つのインスタンスを実行し、3つのコンテナーを持つサービスのサンプル出力:

  [
     {
        "status":"READY",
        "message":"Running",
        "containerName":"some-proxy",
        "instanceId":"0",
        "serviceName":"example_service",
        "image":"<account>.registry.snowflakecomputing.com/tutorial_db/data_schema/tutorial_repository/my_service_image_proxy:tutorial",
        "restartCount":0,
        "startTime":"2023-01-01T00:00:00Z"
     },
     {
        "status":"READY",
        "message":"Running",
        "containerName":"some-server",
        "instanceId":"0",
        "serviceName":"example_service",
        "image":"<account>.registry.snowflakecomputing.com/tutorial_db/data_schema/tutorial_repository/my_server:tutorial",
        "restartCount":0,
        "startTime":"2023-01-01T00:00:00Z"
     },
     {
        "status":"READY",
        "message":"Running",
        "containerName":"movies",
        "instanceId":"0",
        "serviceName":"example_service",
        "image":"<account>.registry.snowflakecomputing.com/tutorial_db/data_schema/tutorial_repository/my_movies:tutorial",
        "restartCount":0,
        "startTime":"2023-01-01T00:00:00Z"
     }
  ]
  

  Copy

  出力には、各コンテナーのステータス情報が含まれます。これらのコンテナーはすべて、インスタンス ID 0を持つ単一のサービスインスタンスに属しています。

SYSTEM$GET_SERVICE_STATUS は、オプションの timeout_secs 引数を取得します。 timeout_secs が指定されないか、値0で指定された場合、この関数はただちに現在のステータスを返します。 timeout_secs が指定された場合、Snowflakeは指定された時間内にサービスが終了状態（READY または FAILED）になるまで待ってからサービスステータスを返します。指定された時間内にサービスが終了状態に到達しなかった場合、Snowflakeは指定された時間間隔の終了時に現在の状態を返します。

指定するタイムアウトは、サービスの準備が整うと予想されるタイミングに基づく近似値であり、これは、Snowflakeが他のサービスを開始する前に、他のサービスやジョブが停止し、指定したコンピューティングプールのリソースが解放されるのを待っている場合などの状況を特定するのに役立ちます。次の SYSTEM$GET_SERVICE_STATUS 関数は10秒のタイムアウトを指定します。

call SYSTEM$GET_SERVICE_STATUS('echo_service', 10);

ローカルコンテナーログへのアクセス¶

Snowflakeは、アプリケーションコンテナー内のコードが標準出力や標準エラーに出力するものをすべて収集します。コードがサービスのデバッグに有用な情報を出力するようにしてください。

Snowflakeは、これらのコンテナーログにアクセスする2つの方法を提供します。

• SYSTEM$GET_SERVICE_LOGS システム関数の使用: 特定のコンテナーからログにアクセスできます。コンテナーが終了した後も、しばらくはシステム関数を使用してログにアクセスできます。システム関数は、開発中やテスト中、サービスやジョブを最初に作成する場合に最も役に立ちます。詳細については、 SYSTEM$GET_SERVICE_LOGS をご参照ください。

• イベントテーブルの使用: イベントテーブルを使用すると、すべてのサービスにわたる複数のコンテナーからログにアクセスできます。Snowflakeは、後でアクセスできるようにイベントテーブルにログを永続化します。イベントテーブルは、サービスやジョブのレトロスペクティブな分析に最適です。詳細については、 イベントテーブルの使用 をご参照ください。

CALL SYSTEM$GET_SERVICE_LOGS('echo_service', '0', 'echo', 10);

+--------------------------------------------------------------------------+
| SYSTEM$GET_SERVICE_LOGS                                                  |
|--------------------------------------------------------------------------|
| 10.16.6.163 - - [11/Apr/2023 21:44:03] "GET /healthcheck HTTP/1.1" 200 - |
| 10.16.6.163 - - [11/Apr/2023 21:44:08] "GET /healthcheck HTTP/1.1" 200 - |
| 10.16.6.163 - - [11/Apr/2023 21:44:13] "GET /healthcheck HTTP/1.1" 200 - |
| 10.16.6.163 - - [11/Apr/2023 21:44:18] "GET /healthcheck HTTP/1.1" 200 - |
+--------------------------------------------------------------------------+
1 Row(s) produced. Time Elapsed: 0.878s

SELECT TIMESTAMP, RESOURCE_ATTRIBUTES, RECORD_ATTRIBUTES, VALUE
FROM <current-event-table-for-your-account>
WHERE timestamp > dateadd(hour, -1, current_timestamp())
AND RESOURCE_ATTRIBUTES:"snow.executable.type" = 'SnowparkContainers'
ORDER BY timestamp DESC
LIMIT 10;

サービスの使用¶

将来のサービス（まだ作成されていないサービス）の使用をロールに付与することができます。例:

GRANT USAGE ON FUTURE SERVICES IN [DATABASE <name> | SCHEMA <name>]TO ROLE <name>

サービスを作成した後、次の3つのサポートされている方法のいずれかを使用して、そのサービスと通信できます。

• サービス関数: サービスに関連するサービス関数（UDF）を作成します。次に、 SQL クエリからサービスと通信するためにサービス関数を使用します。例については、 チュートリアル1 をご参照ください。

• イングレス: Snowflake外部からサービスにアクセスするには、サービスによって公開されているパブリックエンドポイントを使用します。この場合は、Snowflakeがアクセス制御を管理します。例については、 チュートリアル1 をご参照ください。

• サービス間通信: サービス間通信には、Snowflakeが割り当てたサービス DNS 名を使用します。例については、 チュートリアル3 をご参照ください。

以下のセクションで詳細を説明します。

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

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

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

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');

CREATE SECURITY INTEGRATION SNOWSERVICES_INGRESS_OAUTH
TYPE=oauth
OAUTH_CLIENT=snowservices_ingress
ENABLED=true;

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

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

サービスのコード更新¶

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

• 仕様をインラインで提供します（以下は仕様の一部を表示）。

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

  Copy

• Snowflakeステージのファイルパスを指定します。

  ALTER SERVICE echo_service
  FROM @tutorial_stage
  SPECIFICATION_FILE='echo_spec.yaml';
  

  Copy

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

ALTER SERVICE は、常にリポジトリの最新バージョンのイメージを使用します。たとえば、「echo_service:latest」または「echo_service:sometag」という名前が付いた複数のバージョンのイメージをアップロードした場合、Snowflakeはアップロードされた最新のバージョンのイメージを使用します。

DESCRIBE SERVICE コマンドを使用すると、サービスが実行しているイメージのバージョンを見つけることができます。サービス所有者の場合、 DESCRIBE SERVICE 出力には、イメージダイジェスト（イメージの SHA256）を取得するサービス仕様が含まれます。例:

spec:
containers:
- name: "echo"
   image: "orgname-acctname.registry-dev.snowflakecomputing.com/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

権限¶