チュートリアル2: コンテナーでアプリを作成する¶

このチュートリアルで学べること¶

このチュートリアルでは、次の方法を学びます。

• Snowflake Native App with Snowpark Container Services プロジェクトを初期化するには、 Snowflake CLI を使用します。

• アプリのDockerイメージを構築します。

• Snowflake Native App with Snowpark Container Services のアプリケーションパッケージと必要なアプリケーションファイルを作成します。

• コンテナ内でサービス関数を呼び出して、 Snowflake Native App with Snowpark Container Services をテストします。

Snowflake環境のセットアップ¶

このチュートリアルを実行するには、次の前提条件を満たしている必要があります。

• Snowpark Container Serviceをサポートする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

   このコマンドには2つのパラメーターが必要です。

   • <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

   このコマンドは、Snowflakeアカウント内のイメージリポジトリを使用するためにDocker CLI に必要な認証情報をロードします。デフォルトを使用しない場合は、接続名を指定する必要があります。

   すべてが成功した場合、 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 TABLE ()
   LANGUAGE SQL
   EXECUTE AS OWNER
   AS $$
      BEGIN
            LET stmt VARCHAR := 'SHOW SERVICE CONTAINERS IN SERVICE core.echo_service;
            LET res RESULTSET := (EXECUTE IMMEDIATE :stmt);
            RETURN TABLE(res);
      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 プロシージャを呼び出します。プロシージャは、このサービスのコンテナーに関する情報を返します。

   status 列の値が READY でない場合、サービスコンテナーのステータスが READY になるまで、ステートメントを再度実行します。

5. サービス関数を呼び出してサービスにリクエストを送信し、応答を確認するには、次のコマンドを実行します。

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

   Copy

   先のセクションで構成したサービスから次のようなメッセージが表示されます：

   ``Bob said hello``
   

   Copy