教程 2：创建带容器的应用程序¶

在本教程中学习的内容¶

在本教程中，您将学习如何执行以下操作：

• 使用 Snowflake CLI 初始化 Snowflake Native App with Snowpark Container Services 项目。

• 为应用程序构建 Docker 镜像。

• 为 Snowflake Native App with Snowpark Container Services 创建应用程序包和所需的应用程序文件。

• 通过调用容器内的服务函数来测试 Snowflake Native App with Snowpark Container Services。

设置您的 Snowflake 环境¶

要执行本教程，您必须满足以下前提条件：

• 访问支持 Snowpark Container Services 的 Snowflake 账户。

• 您必须能够使用 ACCOUNTADMIN 角色来创建本教程中使用的角色，并为该角色授予所需的权限。

• 您必须在本地计算机上安装 Snowflake CLI 版本 3.0.0 或更高版本。

• 您必须在本地计算机上安装 Docker Desktop。

创建仓库和镜像仓库¶

要创建所需的对象，请通过 Snowsight 或 Snowflake CLI 执行以下操作。

1. 要在 Snowsight 中设置当前上下文以使用 tutorial_role 角色，请运行以下命令：

   USE ROLE tutorial_role;
   

   Copy

   如果使用 Snowflake CLI，您可以改用 --role tutorial_role。

2. 要为 Snowflake Native App with Snowpark Container Services 创建仓库，请运行以下命令：

   CREATE OR REPLACE WAREHOUSE tutorial_warehouse WITH
     WAREHOUSE_SIZE = 'X-SMALL'
     AUTO_SUSPEND = 180
     AUTO_RESUME = true
     INITIALLY_SUSPENDED = false;
   

   Copy

   Snowflake Native App 需要仓库来运行 SQL 命令和存储过程。

3. 要创建用于存储容器的镜像仓库，请运行以下命令：

   CREATE DATABASE tutorial_image_database;
   CREATE SCHEMA tutorial_image_schema;
   CREATE IMAGE REPOSITORY tutorial_image_repo;
   

   Copy

在本部分中，您创建了一个仓库，用于为您创建的应用程序执行查询，还创建了一个镜像仓库，用于托管容器镜像。

在下一部分中，您要为容器创建镜像，并将其上传到上面创建的镜像仓库。

使用 Snowflake CLI 创建项目文件¶

1. 要创建项目文件，请运行以下命令：

   snow init --template app_basic na-spcs-tutorial
   

   Copy

2. 输入项目标识符的值。

   您可以在该文件夹中添加其他文件和子文件夹，并在后面的分部中编辑该命令创建的文件。

该命令使用 app_basic 项目模板创建名为 na-spcs-tutorial 的文件夹。

在 na-spcs-tutorial 文件夹中，该命令会创建以下文件和文件夹：

├── README.md
├── app
    └── manifest.yml
    └── README.md
    └── setup_script.sql
├── snowflake.yml

在后面的部分中，您将修改这些文件并为应用程序添加其他资源。

将服务文件添加到应用程序项目中¶

在上一部分中，您创建了一个项目，其中包含应用程序所需的默认应用程序文件。在本部分中，您将添加所需的文件，为应用程序创建容器。

1. 在 na-spcs-tutorial 文件夹内创建名为 service 的文件夹。

   此文件夹包含我们即将构建并发布到 Snowflake 的基于容器的服务的源代码。

2. 要获取教程所需的 Docker 文件，请将 na_spcs_tutorial.zip 文件下载到本地文件系统。

3. 将 zip 文件的内容解压到 na-spcs-tutorial/service 文件夹。该文件夹应包含以下文件：

   • echo_service.py

   • Dockerfile

   • templates/basic_ui.html

   • echo_spec.yaml

验证项目的目录结构¶

为应用程序创建项目并为服务和 Docker 容器添加文件后，该项目在 na-spcs-tutorial 文件夹中应具有如下结构：

├── app
      └── manifest.yml
      └── README.md
      └── setup_script.sql
├── README.md
├── service
      └── echo_service.py
      ├── echo_spec.yaml
      ├── Dockerfile
      └── templates
         └── basic_ui.html
├── snowflake.yml

构建 Docker 镜像并将其上传到镜像仓库¶

要构建 Docker 镜像并将其上传到镜像仓库，请执行以下步骤：

1. 从终端窗口切换到 na-spcs-tutorial/service 文件夹。

2. 运行以下 Docker CLI 命令。请注意，您必须在命令中指定当前工作目录 (.)：

   docker build --rm --platform linux/amd64 -t my_echo_service_image:tutorial .
   

   Copy

   该命令执行以下操作：

   • 使用下载的 zip 文件中包含的 Docker 文件构建 Docker 镜像

   • 为镜像 my_echo_service_image 命名

   • 将 tutorial 标签应用于镜像。

3. 要识别上一部分中创建的镜像仓库的 URL，请运行以下命令：

   REPO_URL=$(snow spcs image-repository url tutorial_image_database.tutorial_image_schema.tutorial_image_repo -c tut-connection)
   echo $REPO_URL
   

   Copy

   镜像仓库的 URL 在 $REPO_URL 变量中捕获，然后打印到控制台。下一步将使用该值。

4. 要为包含镜像 URL 的镜像创建标签，请运行以下 Docker CLI 命令：

   docker tag <image_name> <image_url>/<image_name>
   

   Copy

   该命令需要两个参数：

   • <image_name> 指定镜像名称和标签。

   • <image_url>/<image_name> 指定上传镜像的镜像仓库的 URL，以及远程存储库中存储的镜像名称和标签。

   本教程使用 $REPO_URL 和 my_echo_service_image:tutorial：

   docker tag my_echo_service_image:tutorial $REPO_URL/my_echo_service_image:tutorial
   

   Copy

5. 要使用 Snowflake 注册表进行身份验证，请运行以下 Snowflake CLI 命令：

   snow spcs image-registry login -c tut-connection
   

   Copy

   该命令加载必要凭据，以便 Docker CLI 使用 Snowflake 账户中的镜像仓库。如果不使用默认名称，您必须指定连接名称。

   如果一切顺利，则显示消息 Login Succeeded。

6. 要将 Docker 镜像上传到镜像仓库，请运行以下 docker push 命令：

   docker push $REPO_URL/<image_name>
   

   Copy

   使用与前几步中 <image_name> 相同的值，该命令是：

   docker push $REPO_URL/my_echo_service_image:tutorial
   

   Copy

7. 运行以下命令，确认镜像上传成功：

   snow spcs image-repository list-images tutorial_image_database.tutorial_image_schema.tutorial_image_repo -c tut-connection
   

   Copy

在本部分中，您创建了包含 echo 服务的 Docker 镜像，并将其推送到在教程前面创建的 tutorial_repository 镜像仓库。

在下一部分中，您将创建可使用该镜像的应用程序包。

修改默认清单文件¶

要修改应用程序的清单文件，请执行以下步骤：

1. 修改 na-spcs-tutorial/app/manifest.yml，使其如下所示：

   manifest_version: 1
   
   artifacts:
      setup_script: setup_script.sql
      readme: README.md
      container_services:
         images:
         - /tutorial_image_database/tutorial_image_schema/tutorial_image_repo/my_echo_service_image:tutorial
   
   privileges:
   - BIND SERVICE ENDPOINT:
        description: "A service that can respond to requests from public endpoints."
   - CREATE COMPUTE POOL:
        description: "Permission to create compute pools for running services"
   

   Copy

   该示例包括以下内容：

   • artifacts 属性指定了带容器的应用程序所需的资源位置，包括上一步创建的 Docker 镜像的位置，以及在 Snowsight 中可见的项目 README。

   • privileges 属性允许服务响应公共请求并创建自己的计算池。这些属性是教程下一步中实例化服务所必需的。

修改默认设置脚本¶

要修改应用程序包的默认设置脚本，请执行以下步骤：

1. 修改 na-spcs-tutorial/app/setup_script.sql 文件，添加以下内容：

   CREATE APPLICATION ROLE IF NOT EXISTS app_user;
   
   CREATE SCHEMA IF NOT EXISTS core;
   GRANT USAGE ON SCHEMA core TO APPLICATION ROLE app_user;
   
   CREATE OR ALTER VERSIONED SCHEMA app_public;
   GRANT USAGE ON SCHEMA app_public TO APPLICATION ROLE app_user;
   
   CREATE OR REPLACE PROCEDURE app_public.start_app()
      RETURNS string
      LANGUAGE sql
      AS
   $$
   BEGIN
      -- account-level compute pool object prefixed with app name to prevent clashes
      LET pool_name := (SELECT CURRENT_DATABASE()) || '_compute_pool';
   
      CREATE COMPUTE POOL IF NOT EXISTS IDENTIFIER(:pool_name)
         MIN_NODES = 1
         MAX_NODES = 1
         INSTANCE_FAMILY = CPU_X64_XS
         AUTO_RESUME = true;
   
      CREATE SERVICE IF NOT EXISTS core.echo_service
         IN COMPUTE POOL identifier(:pool_name)
         FROM spec='service/echo_spec.yaml';
   
      CREATE OR REPLACE FUNCTION core.my_echo_udf (TEXT VARCHAR)
         RETURNS varchar
         SERVICE=core.echo_service
         ENDPOINT=echoendpoint
         AS '/echo';
   
      GRANT USAGE ON FUNCTION core.my_echo_udf (varchar) TO APPLICATION ROLE app_user;
   
      RETURN 'Service successfully created';
   END;
   $$;
   
   GRANT USAGE ON PROCEDURE app_public.start_app() TO APPLICATION ROLE app_user;
   
   CREATE OR REPLACE PROCEDURE app_public.service_status()
   RETURNS VARCHAR
   LANGUAGE SQL
   EXECUTE AS OWNER
   AS $$
      DECLARE
            service_status VARCHAR;
      BEGIN
            CALL SYSTEM$GET_SERVICE_STATUS('core.echo_service') INTO :service_status;
            RETURN PARSE_JSON(:service_status)[0]['status']::VARCHAR;
      END;
   $$;
   
   GRANT USAGE ON PROCEDURE app_public.service_status() TO APPLICATION ROLE app_user;
   

   Copy

修改默认 README¶

要修改应用程序的 README 文件，请执行以下步骤：

1. 修改 na-spcs-tutorial/app/README.md，使其如下所示：

   Welcome to your first app with containers!
   

   Copy

使用者安装应用程序后，即可看到 README 文件。

修改默认项目定义文件¶

在本部分中，您将修改 Snowflake CLI 所使用的项目定义文件。

1. 修改 na-spcs-tutorial/snowflake.yml，使其如下所示：

   definition_version: 2
   entities:
      na_spcs_tutorial_pkg:
         type: application package
         manifest: app/manifest.yml
         artifacts:
            - src: app/*
              dest: ./
            - service/echo_spec.yaml
         meta:
            role: tutorial_role
            warehouse: tutorial_warehouse
      na_spcs_tutorial_app:
         type: application
         from:
            target: na_spcs_tutorial_pkg
         debug: false
         meta:
            role: tutorial_role
            warehouse: tutorial_warehouse
   

   Copy

在本部分中，您定义了一个本地文件结构，可作为 Snowflake Native App with Snowpark Container Services 部署到 Snowflake 账户。在下一部分中，您将使用 Snowflake CLI 执行此部署。

将文件上传到暂存区并创建应用程序对象¶

要在开发模式下创建应用程序，请执行以下步骤：

1. 在终端切换到 na-spcs-tutorial 文件夹。

2. 运行以下命令，在账户中创建应用程序包和对象：

   snow app run -c tut-connection
   

   Copy

   该命令将显示确认信息，说明已在您的账户中创建了名为 na_spcs_tutorial_pkg 的应用程序包和名为 na_spcs_tutorial_app 的应用程序对象。这些名称与前一部分中修改的 snowflake.yml 项目定义中的名称相对应。

您可以使用控制台的 URL 输出来查看应用程序。不过，您必须首先确保它拥有所有必要权限，以创建基于容器的服务。

授予权限并测试应用程序¶

在本部分中，您将向应用程序授予所需的权限，并通过调用容器中的服务来测试应用程序。

您可以使用 Snowsight 或 Snowflake CLI 运行 SQL 命令。

要授予权限并测试应用程序，请在 Snowflake 工作表中执行以下步骤：

1. 运行以下过程，向应用程序授予 CREATE COMPUTE POOL 权限：

   GRANT CREATE COMPUTE POOL ON ACCOUNT TO APPLICATION na_spcs_tutorial_app;
   GRANT BIND SERVICE ENDPOINT ON ACCOUNT TO APPLICATION na_spcs_tutorial_app;
   

   Copy

2. 运行我们在 setup_script.sql 文件中定义的 app_public.start_app 过程。

   CALL na_spcs_tutorial_app.app_public.start_app();
   

   Copy

   该过程会创建计算池、实例化服务并创建服务函数。

3. 运行以下过程，确认函数已创建：

   SHOW FUNCTIONS LIKE '%my_echo_udf%' IN APPLICATION na_spcs_tutorial_app;
   

   Copy

   备注

   使用者看不到正在运行的服务，因为它作为 Snowflake Native App 的一部分运行。例如，运行 SHOW SERVICES IN APPLICATION na_spcs_tutorial_app; 不会返回任何信息。

4. 要验证服务是否已创建并正常运行，请运行以下命令：

   CALL na_spcs_tutorial_app.app_public.service_status();
   

   Copy

   该命令调用您在设置脚本中定义的 app_public.service_status 过程：

   当此过程返回 READY 时，继续下一步。

5. 要调用服务函数，向服务发送请求并验证响应，请运行以下命令：

   SELECT na_spcs_tutorial_app.core.my_echo_udf('hello');
   

   Copy

   您将从前面部分配置的服务中看到以下信息：

   ``Bob said hello``
   

   Copy