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

使用规范模板¶

有时，您可能希望使用相同的规范创建多项服务，但采用不同的配置。例如，假设您以一种服务规范定义了一个 环境变量，并且您希望使用相同的规范创建多项服务，但环境变量的值不同。

借助规范模板，您可以为规范中的字段值定义变量。在创建服务时，您需要为这些变量提供值。

使用规范模板的流程分为两个步骤：

1. 使用变量作为各种规范字段的值来创建规范。使用 {{ variable_name }} 语法来指定这些变量。例如，以下规范为镜像标签名称使用名为“tag_name”的变量，以便您可以为每项服务指定不同的镜像标签。

   spec:
     containers:
     - name: echo
       image: myorg-myacct.registry.snowflakecomputing.cn/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 利用率，汇总当前运行的所有服务实例的使用量数据。

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

请注意以下扩缩行为：

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

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

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

• 长期运行的服务会消耗计算池资源并产生成本，但您可以在服务不执行有意义的工作时将其暂停（请参见 ALTER SERVICE ...SUSPEND）。当任何计算池节点上没有服务或作业处于活动状态时，Snowflake 的自动暂停机制会暂停计算池，以降低成本。

服务终止¶

当您暂停服务 (ALTER SERVICE ...SUSPEND) 或放弃服务 (DROP SERVICE) 时，Snowflake 会终止所有服务实例。同样，当您升级服务代码 (ALTER SERVICE...<fromSpecification>) 时，Snowflake 会通过每次终止和重新部署一个服务实例来应用 滚动升级。

在终止服务实例时，Snowflake 会首先将 SIGTERM 信号发送到每个服务容器。容器可以选择处理信号并在 30 秒的窗口内正常关闭。否则，宽限期过后，Snowflake 会终止容器中的所有进程。

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

创建服务后，使用 ALTER SERVICE … <fromSpecification> 命令更新服务代码并重新部署服务。

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

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

收到请求后，Snowflake 会使用新代码重新部署服务。

当您运行 CREATE SERVICE ...<from-Specification> 命令，Snowflake 会记录所提供镜像的特定版本。在以下情况下，即使存储库中的镜像已更新，Snowflake 也会部署相同的镜像版本：

• 当恢复暂停的服务时（使用 ALTER SERVICE ... 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），因此对服务的访问将失败。有关更多信息，请参见 使用服务。

• 在升级过程中，新连接可能会路由到新版本。如果新服务版本不向后兼容，它将中断任何正在进行的服务使用。例如，使用服务函数的持续查询可能会失败。

使用默认服务角色授予对所有端点的 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 (Snowpark Container Services) 创建的用户定义函数 (UDF)。不过，您不用直接编写 UDF 代码，而可将 UDF 与您的服务关联起来。请注意，您只能将服务函数与支持 HTTP 或 HTTPS 协议的服务端点关联。

例如，在 教程 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 会将请求定向到相关联的服务端点和路径。

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

一项服务可以 公开 一个或多个端点，允许用户从公共网络使用该服务。 在这种情况下，Snowflake 会管理访问控制。请注意，仅允许通过 HTTP 或 HTTPS 端点使用入口。

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

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

服务到服务通信¶

服务实例可通过 TCP（包括 HTTP/HTTPS）直接相互通信。这既适用于属于同一服务的实例，也适用于属于不同服务的实例。

实例只能接收 已声明端点 上的通信（请求）。客户端（发送请求的服务）必须具备连接该端点所需的角色和权限。

• 默认情况下，服务实例可以在已声明端点上连接到同一服务的其他实例。从广义上讲，服务的 所有者角色 拥有连接到具有相同所有者角色的服务端点的权限。

• 为了让客户端服务连接到拥有不同所有者角色的服务端点，必须将与端点相关的 :ref:` 服务角色 <label-snowpark_containers_service_endpoint_access>` 授予客户端服务的 所有者角色。例如：

  GRANT SERVICE ROLE my_service!all_endpoints_usage TO ROLE custom_role;
  

  Copy

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

可以使用服务 IP 地址或服务实例 IP 地址访问服务实例。

• 使用 IP 服务地址的请求会被路由到负载平衡器，而负载平衡器又会将请求路由到随机选择的服务实例。

• 使用服务实例 IP 地址的请求会直接路由到特定的服务实例。连接到使用 portRange ` 字段定义的端点时，必须使用服务实例 IP（请参见 :ref:`label-spcs_spec_ref_spec_endpoints）。

这两个 IP 地址都可使用 Snowflake 自动分配给每项服务的 DNS 名称进行查找。请注意，无法使用 DNS 连接到特定实例。例如，使用服务实例 DNS 名称构建 URL 没有意义，因为无法使用服务实例 DNS 名称来引用特定的服务实例。

启用 2025_01 行为变更捆绑包 时，服务实例 IP 的地址会显示在 SHOW SERVICE INSTANCES IN SERVICE 命令的输出中。

有关服务到服务通信的示例，请参见 教程 3。

请注意，如果创建服务端点仅为了允许服务到服务通信，则应该使用 TCP 协议（请参见 spec.endpoints 字段（可选））。

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

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