教程 3：创建和管理 Snowpark 容器服务

简介

Snowpark Container Services is a fully managed container offering designed to facilitate the deployment, management, and scaling of containerized applications within the Snowflake ecosystem. With this feature, you can run containerized workloads directly within Snowflake.

In this tutorial, you learn how to use Snowflake Python APIs to manage components in Snowpark Container Services.

Important

Snowpark Container Services is generally available to Snowflake accounts in AWS. Preview support is available to accounts in Azure. For more information, see Snowpark Container Services – Available regions.

先决条件

在开始本教程之前，您必须完成以下步骤：

  1. 安装 Docker Desktop。

    This tutorial provides instructions that require Docker Desktop. For installation instructions, see https://docs.docker.com/get-docker/ (https://docs.docker.com/get-docker/).

  2. Follow the common setup instructions, which include the following steps:

    • 设置开发环境。
    • Install the Snowflake Python APIs package.
    • 配置 Snowflake 连接。
    • 导入 Python API 教程所需的所有模块。
    • Create an API Root object.

    Note

    If you have already completed the common setup, you can skip this step and begin the tutorial.

After completing these prerequisites, you are ready to start using the API for managing Snowpark Container Services.

设置开发环境

If you were using a notebook for the previous Snowflake Python APIs tutorials, you switch to a new notebook in this tutorial. The notebook will contain sample code that runs an NGINX web server using Snowpark Container Services, all of which runs in Snowflake.

  1. Open a new notebook using your preferred code editor or by running the command jupyter notebook.

  2. 在笔记本的第一个单元格中运行以下代码：

    from snowflake.core.database import Database
from snowflake.core.schema import Schema

database = root.databases.create(Database(name="spcs_python_api_db"), mode="orreplace")
schema = database.schemas.create(Schema(name="public"), mode="orreplace")

    Using the Snowflake connection and root object that you created previously in the common setup, you create a database named spcs_python_api_db and a schema named public in that database. You also save references that represent these newly created objects. Your Snowpark Container Services components will live in this database and schema.

Overview of Snowpark Container Services

Before you continue with the tutorial, briefly review the main components of Snowpark Container Services. To run containerized applications in Snowpark Container Services, you typically work with the following objects:

  • 镜像仓库：提供一个存储单元，您可以在自己的 Snowflake 账户中将应用程序镜像上传到这个存储单元中。

    Snowpark Container Services provides an OCIv2-compliant image registry service that enables OCI clients (such as Docker CLI and SnowSQL) to access an image registry in your Snowflake account. Using these clients, you can upload your application images to a repository.

    For more information, see Working with an image registry and repository.

  • 计算池：表示一组计算资源（虚拟机节点）。

这些计算资源与 Snowflake 虚拟仓库相似，但并非完全相同。服务（在本例中是您的 NGINX 服务）将在计算池中运行。计算密集型服务需要具有大量核心和大量 GPUs 的高算力计算尺，而密集度较低的服务则可以在具有较少核心的较小计算池中运行。

For more information, see Working with compute pools.

  • 服务：提供了一种运行应用程序容器的途径。

服务至少需要具备一个规范和一个计算池。规范包含运行应用程序容器所需的信息，例如容器镜像的路径，以及服务将会公开的端点。规范使用 YAML 编写。计算池是服务将在其中运行的一组计算资源。

For more information, see Working with services.

继续进入下一步，以创建和设置这些对象。

创建镜像仓库

In this section, first you create an image repository using the Snowflake Python APIs. Then you fetch an NGINX application image from Docker Hub and upload the image to the image repository using the Docker CLI.

创建仓库并获取与其相关的信息

  1. 在笔记本的下一个单元格中，运行以下代码：

    from snowflake.core.image_repository import ImageRepository

my_repo = ImageRepository("MyImageRepository")
schema.image_repositories.create(my_repo)

在此代码示例中，您将在本教程中前面创建的数据库和架构中创建一个镜像仓库。

  1. 要通过提取仓库的详细信息并输出其名称来确认仓库已成功创建，请运行以下代码：

    my_repo_res = schema.image_repositories["MyImageRepository"]
my_repo = my_repo_res.fetch()
print(my_repo.name)

  2. 您需要有关仓库（仓库 URL 和注册表主机名）的信息，才能构建和上传镜像。

要获取存储库 URL，请在下一个单元格中，运行以下代码：

repositories = schema.image_repositories
  for repo_obj in repositories.iter():
 print(repo_obj.repository_url)

  • The repository_url attribute in the output provides the URL. For example:

    <orgname>-<acctname>.registry.snowflakecomputing.cn/spcs_python_api_db/public/myimagerepository

  • 仓库 URL 中的主机名为注册表主机名。例如：

    <orgname>-<acctname>.registry.snowflakecomputing.cn

提取 NGINX 镜像并将其上传到仓库

  1. 要让 Docker 代表您将镜像上传到仓库，您必须首先使用 Snowflake 对 Docker 进行身份验证。

    To authenticate Docker with the Snowflake registry, open a command-line terminal and run the following docker login command using the Docker CLI:

    docker login <registry_hostname> -u <username>
    • registry_hostname: Specify the hostname in repository_url from the result of the previous step.
    • username: Specify your Snowflake username. Docker will prompt you for your password.

示例

docker login myorg-myacct.registry.snowflakecomputing.cn -u admin

  1. Fetch the AMD64 build of the NGINX image from Docker Hub (https://hub.docker.com/r/amd64/nginx/):

    docker pull --platform linux/amd64 amd64/nginx

  2. Tag the amd64/nginx image with the Snowflake image repository URL:

    docker tag docker.io/amd64/nginx:latest <repository_url>/<image_name>

示例

docker tag docker.io/amd64/nginx:latest myorg-myacct.registry.snowflakecomputing.cn/spcs_python_api_db/public/myimagerepository/amd64/nginx:latest

标记是一种自定义的、人类可读的标识符，您可以选择使用它来识别镜像的特定版本或变体。

  1. 将镜像上传到 Snowflake 账户中的仓库：

    docker push <repository_url>/<image_name>

示例

docker push myorg-myacct.registry.snowflakecomputing.cn/spcs_python_api_db/public/myimagerepository/amd64/nginx:latest

创建计算池

要定义和创建计算池，在笔记本的下一个单元格中，运行以下代码：

new_compute_pool_def = ComputePool(
    name="MyComputePool",
    instance_family="CPU_X64_XS",
    min_nodes=1,
    max_nodes=2,
)

new_compute_pool = root.compute_pools.create(new_compute_pool_def)

In this cell, you define a compute pool using the ComputePool constructor by providing values for the following attributes:

  • instance_family: The instance family identifies the type of machine you want to provision for the nodes in the compute pool.

    Each machine type provides a different amount of compute resources to their compute pools. In this cell, you use the smallest available machine type, CPU_X64_XS. For more information, see CREATE COMPUTE POOL.

  • min_nodes: The minimum number of nodes to launch the compute pool with.

  • max_nodes: The maximum number of nodes the compute pool can scale to.

    When you create a compute pool, Snowflake launches it with the minimum number of nodes specified. Snowflake then manages the scaling automatically and creates new nodes—up to the maximum number specified—when the running nodes can’t take any additional workload.

Then you create the compute pool by passing the compute pool definition to compute_pools.create().

创建服务

使用您设置的镜像仓库和计算池，您现在可以定义和创建服务。服务是指在计算池中运行的容器集合，这些容器均在 Snowflake 中编排。

  1. 要检索包含容器镜像的仓库，在笔记本的下一个单元格中，运行以下代码：

    image_repository = schema.image_repositories["MyImageRepository"]

此仓库位于您的 Snowflake 账户中，列为 PUBLIC 架构内的一个暂存区。您需要此引用，以便在下一步中提取容器镜像信息。

  1. 要定义和创建服务，请在下一个单元格中，运行以下代码：

    from textwrap import dedent
from io import BytesIO
from snowflake.core.service import Service, ServiceSpecInlineText

specification = dedent(f"""\
 spec:
   containers:
   - name: web-server
     image: {image_repository.fetch().repository_url}/amd64/nginx:latest
   endpoints:
   - name: ui
     port: 80
     public: true
 """)

service_def = Service(
 name="MyService",
 compute_pool="MyComputePool",
 spec=ServiceSpecInlineText(spec_text=specification),
 min_instances=1,
 max_instances=1,
)

nginx_service = schema.services.create(service_def)

此单元格定义服务规范和服务，然后为您的 NGINX Web 服务器创建服务。规范和服务的定义具有以下属性：

  • specification – You define the specification using a Python formatted string literal (f-string). The string is formatted as YAML.

    The specification contains the name of the container, a path to the container image, and the endpoints that the service will expose for public access. In this example, you define the specification inline, but you can also define a specification as a reference to a .yml file in a stage.

  • service_def – You define a service with the Service constructor, passing in a name for the service, the compute pool it will run in, a path to the specification, and the total number of instances for the service.

    In this cell, you use ServiceSpecInlineText to set the value of spec because you define the specification inline as an f-string. You can specify the service to run multiple instances, but in this example you specify only one instance of the service to run by setting min_instances and max_instances to 1.

  1. 要检查服务的状态，请在下一个单元格中，运行以下代码：

    from pprint import pprint

pprint(nginx_service.get_service_status(timeout=5))

输出应类似于以下内容：

{'auto_resume': True,
'auto_suspend_secs': 3600,
'instance_family': 'CPU_X64_XS',
'max_nodes': 1,
'min_nodes': 1,
'name': 'MyService'}

使用服务

After you create the service, Snowpark Container Services will take a few minutes to provision the endpoints that are needed to access the service.

  1. 要检查端点的状态，在笔记本的下一个单元格中，运行以下代码：

    import json, time

while True:
 public_endpoints = nginx_service.fetch().public_endpoints
 try:
     endpoints = json.loads(public_endpoints)
 except json.JSONDecodeError:
     print(public_endpoints)
     time.sleep(15)
 else:
     break

    The code example isn’t specific to Snowpark Container Services or the Snowflake Python APIs – it simply provides a handy way to check whether the endpoints are ready. Note that you fetch the endpoints by calling .fetch().public_endpoints on your service object.

输出应类似于以下内容：

Endpoints provisioning in progress... check back in a few minutes
Endpoints provisioning in progress... check back in a few minutes
Endpoints provisioning in progress... check back in a few minutes
  1. 配置端点后，即可在浏览器中打开公共端点。

请在下一个单元格中运行以下代码：

import webbrowser

print(f"Visiting {endpoints['ui']} in your browser. You might need to log in there.")
webbrowser.open(f"https://{endpoints['ui']}")

输出应类似于以下内容：

Visiting myorg-myacct.snowflakecomputing.app in your browser. You might need to log in there.

如果成功，在访问端点时，您会在浏览中看到以下 NGINX 成功页面：

Screenshot of the NGINX web server success page in a browser
  1. 您可以使用 Python API 管理新服务。

例如，若要暂停服务然后检查其状态，请运行以下代码：

from time import sleep

nginx_service.suspend()
sleep(3)
print(nginx_service.get_service_status(timeout=5))
  1. 若要恢复服务，请运行以下代码： 
    nginx_service.resume()
sleep(3)
print(nginx_service.get_service_status(timeout=5))

With just a few lines of Python, you were able to run an NGINX web server in Snowflake using Snowpark Container Services.

清理

Snowflake 会针对您账户中的活跃计算池节点收费。为了避免不必要的费用，请先暂停服务和计算池，然后删除这两个对象。

  1. 若要暂停计算池和服务，在笔记本的下一个单元格中，运行以下代码：

    new_compute_pool_def.suspend()
nginx_service.suspend()

  2. 若要删除计算池和服务，运行以下代码：

    new_compute_pool_def.drop()
nginx_service.drop()

下一步是什么？

Congratulations! In this tutorial, you learned the fundamentals for managing components in Snowpark Container Services using the Snowflake Python APIs.

摘要

在此过程中，您完成了以下步骤：

  • 创建镜像仓库，并将应用程序镜像上传到其中。
  • 创建运行服务的计算池。
  • 创建服务来运行应用程序容器。
  • 使用和管理服务。
  • Clean up your Snowpark Container Services resource objects by suspending and dropping them.

其他资源

要获取更多使用 API 管理 Snowflake 中其他类型对象的示例，请参阅以下开发者指南：

GuideDescription
Managing Snowflake databases, schemas, tables, and views with PythonUse the API to create and manage databases, schemas, and tables.
Managing Snowflake users, roles, and grants with PythonUse the API to create and manage users, roles, and grants.
Managing data loading and unloading resources with PythonUse the API to create and manage data loading and unloading resources, including external volumes, pipes, and stages.
Managing Snowflake tasks and task graphs with PythonUse the API to create, execute, and manage tasks and task graphs.
下一步
设置开发环境