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) 或删除服务 (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

服务到服务通信¶

服务可使用 Snowflake 自动分配给每个服务的 DNS 名称相互通信。有关示例，请参阅 教程 3。请注意，如果创建服务端点仅为了允许服务到服务的通信，则应该使用 TCP 协议。

DNS 名称格式为：

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

使用 /sql-reference/sql/show-services`（或 :doc:/sql-reference/sql/desc-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 内部通信。从互联网访问此名称。