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 会在指定的计算池中运行一个服务实例。要管理繁重的工作负载，您可以通过设置 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 更改这些值。

Snowflake 会首先在指定的计算池上创建最少数量的服务实例，然后根据需要自动调整实例数量。Snowflake 使用 80% 的阈值（对于 CPU 和内存）来增加或减少服务实例的数量。

任何时候，指定的计算池上都可以运行一个或多个服务实例。Snowflake 可持续监控计算池内的资源利用率（内存或 CPU），汇总当前运行的所有服务实例的使用量数据。

当汇总资源使用量（所有服务实例）超过 80% 时，Snowflake 会在计算池中部署额外的服务实例。如果汇总资源使用量低于 80%，Snowflake 会通过移除一个正在运行的服务实例来缩小规模。Snowflake 使用五分钟的稳定窗口来防止频繁扩缩。

请注意以下扩缩行为：

• 服务实例的扩缩受限于为服务配置的 MIN_INSTANCES 和 MAX_INSTANCES 参数。

• 如果需要扩大规模，而计算池节点缺乏启动另一个服务实例所需的资源能力，则可以触发计算池自动扩缩。有关更多信息，请参阅 计算池节点的自动扩缩。

• 如果您在创建服务时指定了 MAX_INSTANCES 和MIN_INSTANCES 参数，但没有在服务规范文件中指定服务实例的内存和 CPU 要求，则不会发生自动扩缩；Snowflake 会以 MIN_INSTANCES 属性指定的实例数启动，不会自动扩缩。

更新服务代码，重新部署服务¶

您可以修改应用程序代码和配置，并在 ALTER SERVICE 命令中提供新的服务规范，指示 Snowflake 使用新规范重新部署正在运行的服务。

您首先要将修改后的应用程序代码上传到镜像仓库，然后调用 ALTER SERVICE，以提供内联服务规范或在 Snowflake 暂存区的文件中指定规范文件路径。例如：

• 提供内联规范（显示部分规范）。

  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.cn/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

使用 SYSTEM$GET_SERVICE_LOGS¶

您需要提供服务名称、实例 ID、容器名称，还可选择提供要检索的最新日志行数。如果只有一个服务实例正在运行，则服务实例 ID 为 0。例如，以下 GET_SERVICE_LOGS 命令会从名为``echo`` 的容器的日志中检索末尾的 10 行，该容器属于名为 echo_service 的服务的实例 0：

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

如果不知道服务信息（如实例 ID 或容器名称），可以先运行 GET_SERVICE_STATUS 获取每个实例中运行的服务实例和容器的信息。

输出示例：

+--------------------------------------------------------------------------+
| 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

SYSTEM$GET_SERVICE_LOGS 输出有以下限制：

• 它只是简单地合并了标准输出和标准错误流，从而无法区分常规输出和错误消息。

• 它在单个服务实例中报告特定容器的捕获数据。

• 它只报告运行中容器的日志。该函数无法从先前重新启动的容器或者已停止或已删除的服务容器中获取日志。

• 该函数最多可返回 100 KB 数据。

使用事件表¶

Snowflake 可以从您的容器中捕获标准输出和标准错误，并将其记录到为您的账户配置的事件表中。有关更多信息，请参阅 日志记录和跟踪概述。

例如，以下 SELECT 查询可检索过去一小时内记录的 Snowflake 服务和作业事件：

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;

Snowflake 建议您在事件表查询的 WHERE 子句中包含时间戳，如本例所示。这一点尤为重要，因为各种 Snowflake 组件可能会生成大量数据。通过应用筛选器，可以检索到较小的数据子集，从而提高查询性能。

您可以通过使用服务规范文件中的 spec.logExporters 字段 来控制希望在事件表中持久化的日志级别（全部、仅错误或无）。

事件表包括以下列，这些列提供了有关 Snowflake 从您的容器收集的日志的有用信息：

• TIMESTAMP： 显示 Snowflake 收集日志的时间。

• RESOURCE_ATTRIBUTES： 此列中的每个对象都标识了生成日志的 Snowflake 服务和服务中的容器。例如，它提供了服务运行时指定的服务名称、容器名称和计算池名称等详细信息。

  {
  "snow.containers.compute_pool.id": 549816068,
  "snow.containers.compute_pool.name": "TUTORIAL_COMPUTE_POOL",
  "snow.containers.container.name": "echo",
  "snow.containers.instance.name": "0",
  "snow.containers.restart.id": "cd0cf2",
  "snow.database.id": 549816076,
  "snow.database.name": "TUTORIAL_DB",
  "snow.executable.id": 980991015,
  "snow.executable.name": "ECHO_SERVICE",
  "snow.executable.type": "SnowparkContainers",
  "snow.schema.id": 549816076,
  "snow.schema.name": "DATA_SCHEMA"
  }
  

  Copy

• RECORD_ATTRIBUTES： 对于 Snowflake 服务，它标识错误源（标准输出或标准错误）。

  { "log.iostream": "stdout" }
  

  Copy

• VALUE： 标准输出和标准错误被分成若干行，每一行都会在事件表中生成一条记录。

  "echo-service [2023-10-23 17:52:27,429] [DEBUG] Sending response: {'data': [[0, 'Joe said hello!']]}"
  

使用此功能的前提条件¶

要使用服务角色管理端点访问，必须在账户中启用 2024_04 行为变更捆绑包。

要 在账户中启用此捆绑包，请执行以下语句：

SELECT SYSTEM$ENABLE_BEHAVIOR_CHANGE_BUNDLE('2024_04');

为帮助您采用这些变更，Snowflake 已为每个现有服务创建了默认服务角色 (ALL_ENDPOINTS_USAGE)。Snowflake 还将默认服务角色授予了您之前向其授予对该服务的 USAGE 权限的其他角色，因此现有服务应该可以无缝运行。

不过，某些问题可能会阻止 Snowflake 创建默认服务角色。您可以运行以下 SHOW ROLES IN SERVICE 命令来验证是否为您的服务创建了默认服务角色。

SHOW ROLES IN SERVICE <service_name>;

输出示例：

+-------------------------------+-------------------------+------------+
| created_on                  |   name                       |  comment   |
+-------------------------------+-------------------------+------------+
| 2024-04-29 14:58:50.063 -0700 |   ALL_ENDPOINTS_USAGE   |            |
+-------------------------------+-------------------------+------------+

检查输出；如果输出包含默认服务角色 (ALL_ENDPOINTS_USAGE)，则无需进一步操作。否则，请执行以下操作以创建默认服务角色并将其授予其他角色：

1. 运行 ALTER SERVICE 命令来升级服务 ...

   ALTER SERVICE <name>
   {
      FROM @<stage>
      SPECIFICATION_FILE = '<yaml_file_stage_path>'
      |
      FROM SPECIFICATION <specification_text>
   }
   

   Copy

2. 使用 GRANT SERVICE ROLE 命令将默认服务角色 (ALL_ENDPOINTS_USAGE) 授予您先前向其授予对服务的 USAGE 权限的角色。

   GRANT SERVICE ROLE <service-name>!ALL_ENDPOINTS_USAGE TO ROLE <another_role>;
   

   Copy

向所有端点授予 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 权限的端点列表。

向服务的特定端点授予权限分为两个步骤：

1. 定义服务角色： 使用服务规范来定义服务角色，方法是提供角色名称，以及包含一个或多个您像向其授予 USAGE 权限的端点的列表。例如，在下面的规范片段中，顶级 serviceRoles 字段定义了两个服务角色，每个角色都对特定端点拥有 USAGE 权限。

   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 创建的用户定义函数 (UDF)。不过，您不用直接编写 UDF 代码，而是将 UDF 与您的服务关联起来。例如，在 教程 1 中，您创建了一个名为 echo_service 的服务，它公开了服务规范中定义的一个端点 (echoendoint)：

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）。

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

调用服务函数时，Snowflake 会将请求定向到相关联的服务端点和路径。

当您运行服务的多个实例时，可以通过指定可选的 MAX_BATCH_ROWS 参数来创建服务函数，以限制 批量大小，即 Snowflake 批量发送到服务的最大行数。例如，假设 MAX_BATCH_ROWS 为 10，您调用 my_echo_udf 服务函数时输入 100 行。Snowflake 会将输入的行分成多个批次，每个批次最多有 10 行，然后向服务发送一系列请求，请求正文中包含批次中的行。当处理耗时过长时，配置批次大小会有所帮助，将行分布在所有可用服务器上也会有所帮助。

您可以使用 ALTER FUNCTION 更改服务函数。以下 ALTER FUNCTION 命令更改了与之关联的服务端点和批次大小：

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 外部的服务¶

一项服务可以公开一个或多个端点，允许用户从公共网络使用该服务。

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

在服务规范文件中将端点标记为公共端点：

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

有关服务规范的更多信息，请参阅 规范参考。

服务到服务通信¶

服务可使用 Snowflake 自动分配给每个服务的 DNS 名称相互通信。有关示例，请参阅 教程 3。

DNS 名称格式为：

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

使用 SHOW SERVICES（或 DESCRIBE SERVICE）获取服务的 DNS 名称。前面的 DNS 名称是全名。在同一架构下创建的服务可以只使用 <service-name> 进行通信。处于同一数据库但不同架构的服务必须提供架构名称，例如 <service-name>.<schema-name>。

Snowflake 允许由同一角色创建的服务之间的网络通信，并阻止由不同角色创建的服务之间的网络通信。如果您想防止服务之间相互通信（出于安全等原因），请使用不同的 Snowflake 角色来创建这些服务。

DNS 名称有以下限制：

• 您的数据库、架构或服务名称必须是有效的 DNS 标签。（另请参阅 ` <https://www.ietf.org/rfc/rfc1035.html#section-2.3.1 (https://www.ietf.org/rfc/rfc1035.html#section-2.3.1)> `_ ）。否则，创建服务将失败。

• Snowflake 将名称（数据库、架构和服务名称）中的下划线 (_) 替换为 DNS 名称中的短划线 (-)。

• 创建服务后，请勿更改数据库或架构名称，因为 Snowflake 不会更新服务的 DNS 名称。

• DNS 名称仅用于在同一账户中运行的服务之间的 Snowflake 内部通信。从互联网访问此名称。