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

• 通过引用 Snowflake 暂存区上存储的服务规范来创建服务。在生产环境中部署服务时，您可以应用关注点分离设计原则，并将规范上传到一个暂存区，在 CREATE SERVICE 命令中提供暂存区信息，如下所示：

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

  Copy

执行作业服务¶

使用 EXECUTE JOB SERVICE 创建作业服务。默认情况下，此命令同步运行，并在任务服务的所有容器退出后返回响应。您可以选择指定 ASYNC 参数以异步运行作业服务。

• 使用内联规范执行作业服务：

  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

  您可以选择使用该 ASYNC 属性异步执行此作业。

  EXECUTE JOB SERVICE
     IN COMPUTE POOL tutorial_compute_pool
     NAME = example_job_service
     ASYNC = TRUE
     FROM SPECIFICATION $$
     ...
     $$;
  

  Copy

• 使用暂存区信息执行作业服务：

  EXECUTE JOB SERVICE
    IN COMPUTE POOL tutorial_compute_pool
    NAME = example_job_service
    FROM @tutorial_stage
    SPECIFICATION_FILE='my_job_spec.yaml';
  

  Copy

使用规范模板¶

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

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

在规范模板中，您可以将变量指定为各种规范字段的值。使用 {{ variable_name }} 语法来指定这些变量。然后，在 CREATE SERVICE 命令中，指定 USING 参数来设置这些变量的值。

例如，以下 CREATE SERVICE 命令中的内联规范模板为镜像标签名称使用名为 tag_name 的变量。您可以使用此变量为每项服务指定不同的镜像标签。在此示例中，USING 参数将 tag_name 变量设置为值 latest。

CREATE SERVICE echo_service
  IN COMPUTE POOL tutorial_compute_pool
  FROM SPECIFICATION $$
  spec:
    containers:
    - name: echo
      image: myorg-myacct.registry.snowflakecomputing.cn/tutorial_db/data_schema/tutorial_repository/my_echo_service_image:{{ tag_name }}
        ...
    endpoints:
    - name: ...
      ...
  $$
  USING (tag_name=>'latest');

如果您选择将规范模板保存到账户中的 Snowflake 暂存区，您可以在 CREATE SERVICE 命令中指向模板的位置：

CREATE SERVICE echo_service
    IN COMPUTE POOL tutorial_compute_pool
    FROM @STAGE SPECIFICATION_TEMPLATE_FILE='echo.yaml'
    USING (tag_name=>'latest');

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 属性指定的实例数启动，不会自动扩缩。

暂停服务¶

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

要暂停服务，您可以明确调用 :doc:` ALTER SERVICE ...SUSPEND </sql-reference/sql/alter-service>` 以暂停服务或使用 CREATE SERVICE 或 ALTER SERVICE 设置 AUTO_SUSPEND_SECS 属性来定义空闲时长，在此之后 Snowflake 将自动暂停服务。

设置 AUTO_SUSPEND_SECS 属性后，如果服务尚未暂停且空闲时间超过 AUTO_SUSPEND_SECS 秒钟，Snowflake 会自动暂停该服务。当满足以下两个条件时，服务处于空闲状态：

• 当前没有正在运行的查询包含对该服务的 服务函数 调用。

• 服务状态为 RUNNING。

当 Snowflake 暂停服务时，它会关闭计算池上的所有服务实例。如果计算池上没有运行其他服务，且为该计算池配置了自动暂停功能，则 Snowflake 也会暂停该计算池节点。因此，您无需为非活动计算池付费。

同时请注意以下事项：

• 作业服务不支持自动暂停。

• 对于具有公共端点的服务，系统不支持自动暂停功能，因为 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 会使用新代码重新部署服务。

如果您是服务所有者，则 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），因此对服务的访问将失败。有关更多信息，请参见 使用服务。

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

运行服务所需的权限（服务所有者角色）¶

创建服务的角色是服务的所有者角色。服务在此角色的上下文中执行所有 SQL。有关更多信息，请参阅 使用 OAuth 令牌执行 SQL。

如果服务需要权限（例如，访问数据库对象或对数据库对象执行操作），则必须向所有者角色授予该权限。

在服务间通信中，所有者角色决定目标服务上的哪些端点可访问（请参阅 服务角色）。

对服务执行操作所需的权限¶

如果角色需要对服务执行操作（例如，暂停服务），则必须向该角色授予执行该操作的权限。

每个 SQL 命令参考都提供命令的访问控制要求。有关更多信息，请参阅 SHOW SERVICES、ALTER SERVICE 和 DROP SERVICE。

访问服务端点所需的权限（服务角色）¶

服务可以公开一个或多个客户端可以通过发送请求来访问的端点。服务的所有者角色对服务及其端点拥有完全访问权限。要允许其他角色访问端点，您必须向他们授予相应的权限。Snowflake 支持在服务规范中定义“服务角色”，以管理对公开端点的访问权限。

角色需要服务角色的示例包括：

• 服务函数 的所有者角色需要服务角色，授予对服务函数引用的端点的访问权限。否则，您无法创建服务函数。如果服务函数的所有者角色在创建服务函数后失去对服务角色的权限，则使用该服务函数的查询将因权限错误而失败。

• 在 服务间通信 中，服务的所有者角色需要服务角色，授予对其他服务端点的访问权限以调用该端点。

• 从 Snowflake 外部向服务暴露的公共端点发起 入口请求 的用户必须被授予获得服务角色的角色，才能访问该端点。

要使角色（例如 some_role）能够访问服务端点，请执行以下操作：

1. 授予对创建服务的数据库和架构的 USAGE 权限。这些权限允许解析架构中对象的名称。在这种情况下，对象就是服务。

   例如，以下命令向角色 (some_role) 授予这些 USAGE 权限。

   GRANT USAGE ON DATABASE my_db TO ROLE some_role;
   GRANT USAGE ON SCHEMA my_schema TO ROLE some_role;
   

   Copy

2. 授予有权访问端点的服务角色（请参阅 GRANT SERVICE ROLE）。

   您有以下选项：

   • 使用 all_endpoints_usage 服务角色（Snowflake 为每项服务创建的预定义服务角色）授予对服务公开的所有端点的访问权限。服务角色名称使用以下语法：service-name!service-role。

     GRANT SERVICE ROLE my_service!all_endpoints_usage TO ROLE some_role;
     

     Copy

   • 授予对服务公开的特定端点的访问权限。这要求您在规范中定义一个或多个具有特定端点权限的服务角色。然后，授权这些服务角色来管理精细的端点访问权限。

     在以下 CREATE SERVICE 命令中，内联规范定义了两个端点（ep1 和 ep2）和一个仅有权访问 ep1 端点的服务角色（ep1_role）。

     USE DATABASE my_db;
     USE SCHEMA my_schema;
     
     
     CREATE SERVICE my_service
     IN COMPUTE POOL tutorial_pool
     FROM SPECIFICATION $$
     spec:
       containers:
       - name: echo
         image: /tutorial_db/data_schema/tutorial_repository/my_echo_service_image:latest
       endpoints:
       - name: ep1
         port: 8000
         public: true
       - name: ep2
         port: 8082
         public: true
     serviceRoles:
     - name: ep1_role
       endpoints:
       - ep1
     $$
     

     Copy

     现在，要授予对 ep1 端点的 some_role 访问权限，请授予 ep1_role 服务角色，如下所示：

     GRANT SERVICE ROLE my_service!ep1_role TO ROLE some_role;
     

     Copy

服务函数：使用 SQL 查询中的服务¶

服务函数是使用 CREATE FUNCTION (Snowpark Container Services) 创建的用户定义函数 (UDF)。不过，您不用直接编写 UDF 代码，而可将 UDF 与您的服务关联起来。请注意，您只能将服务函数与支持 HTTP 协议的服务端点关联（请参阅 spec.endpoints 字段（可选））。

例如，在 教程 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():
...

您可以在 SELECT 语句中调用服务函数，如下所示：

SELECT service_function_name(<parameter-list>);

Snowflake 将请求定向到相关的服务端点和路径。

"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]
   ]
}

ALTER FUNCTION my_echo_udf(VARCHAR) SET
   MAX_BATCH_ROWS = 15
   MAX_BATCH_RETRIES = 5;

USE ROLE service_owner;
GRANT USAGE ON DATABASE service_db TO ROLE func_owner;
GRANT USAGE ON SCHEMA my_schema TO ROLE func_owner;
GRANT SERVICE ROLE ON service service_db.my_schema.my_service!all_endpoints_usage 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 DATABASE service_db TO ROLE func_user;
GRANT USAGE ON SCHEMA my_schema TO ROLE func_user;
GRANT USAGE ON FUNCTION test_udf(varchar) TO ROLE func_user;
USE ROLE func_user;
SELECT my_test_udf('abcd');

入口：使用来自 Snowflake 外部的服务¶

您可以在服务规范中将一个或多个端点声明为公共端点，以允许用户从公共场所使用该服务。请注意，用户必须是创建该服务的同一 Snowflake 账户中的 Snowflake 用户。

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

请注意，仅允许通过 HTTP 端点使用入口（请参阅 spec.endpoints 字段（可选））。

服务到服务通信¶

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

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

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

• 为了使客户端服务连接到具有不同所有者角色的服务的端点，该客户端服务的所有者角色需要使用 服务角色 授予对其他服务的端点的访问权限，以调用该端点。有关更多信息，请参阅 访问服务端点所需的权限（服务角色）。

• 如果您想防止服务之间相互通信（出于安全等原因），请使用不同的 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