자습서: Snowpark Container Service로 Snowflake Native App 만들기¶

알아볼 내용¶

이 자습서에서는 다음에 대해 설명합니다.

• Snowflake CLI 를 사용하여 Snowflake Native App with Snowpark Container Services 프로젝트를 초기화합니다.

• 앱에 대한 Docker 이미지를 빌드합니다.

• 애플리케이션 패키지와 Snowflake Native App with Snowpark Container Services 에 필요한 애플리케이션 파일을 생성합니다.

• 컨테이너 내에서 서비스 함수를 호출하여 Snowflake Native App with Snowpark Container Services 를 테스트합니다.

전제 조건¶

이 자습서를 수행하려면 다음 전제 조건을 충족해야 합니다.

• Snowpark Container Services를 지원하는 Snowflake 계정에 액세스합니다.

• 이 자습서에 사용된 역할을 생성하고 해당 역할에 필요한 권한을 부여하려면 ACCOUNTADMIN 역할을 사용할 수 있어야 합니다.

• 로컬 머신에 Snowflake CLI 버전 3.0.0 이상이 설치되어 있어야 합니다.

• 로컬 머신에 Docker Desktop이 설치되어 있어야 합니다.

Snowflake CLI 연결 설정¶

이 자습서에서 실행할 명령은 앱을 개발 중인 계정에 기본적으로 연결하도록 Snowflake CLI 를 구성한 것으로 가정합니다. 이 계정이 기본적으로 설정되어 있지 않은 경우 -c 명령줄 인자를 사용하여 다른 이름의 연결을 지정할 수 있습니다. 예:

snow sql -q "SELECT 1" -c connection_name

Copy

웨어하우스와 이미지 리포지토리 만들기¶

필요한 오브젝트를 생성하려면 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 를 사용하여 Native Apps 프로젝트를 부트스트랩한 다음 하위 폴더에 컨테이너 서비스용 이미지를 빌드해 보겠습니다.

1. 로컬 파일 시스템에서 다음 명령을 실행하여 이름이 na-spcs-tutorial 인 폴더를 만듭니다.

   snow init --template app_basic na-spcs-tutorial
   

   Copy

   참고

   이 폴더에 파일과 하위 폴더를 추가하고 이후 하위 섹션에서 이 명령으로 생성된 파일을 편집합니다.

   참고

   snow init --help 를 실행하여 Snowflake Native App 개발 환경 설정을 위한 다른 템플릿을 확인합니다.

2. na-spcs-tutorial 폴더에 이름이 service 인 폴더를 만듭니다. 이 폴더에는 Snowflake에 빌드하여 게시할 컨테이너 기반 서비스의 소스 코드가 들어 있습니다.

3. 자습서에 필요한 Docker 파일을 얻으려면 zip 파일 을 로컬 파일 시스템에 다운로드합니다.

4. na-spcs-tutorial/service 폴더에 압축을 풉니다. 이 폴더에는 다음 파일이 포함되어야 합니다.

   • echo_service.py

   • Dockerfile

   • templates/basic_ui.html

   • echo_spec.yaml

5. 터미널 창을 열고 이 디렉터리로 변경합니다.

Docker 이미지를 빌드하고 컨테이너에 업로드¶

Docker 이미지를 빌드하고 이미지 리포지토리에 업로드하려면 다음을 수행합니다.

1. 다음 Docker CLI 명령을 실행합니다. 명령에 현재 작업 디렉터리(.)를 지정해야 합니다.

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

   Copy

   이 명령은 다음을 수행합니다.

   • 다운로드한 zip 파일에 포함된 Docker 파일을 사용하여 Docker 이미지를 빌드합니다.

   • 이미지 my_echo_service_image 의 이름 지정

   • 이미지에 tutorial 태그를 적용합니다.

2. 이전 섹션에서 생성한 이미지 리포지토리의 URL을 식별하려면 다음 명령을 실행합니다.

   REPO_URL=$(snow spcs image-repository url tutorial_image_database.tutorial_image_schema.tutorial_image_repo --role tutorial_role)
   echo $REPO_URL
   

   Copy

   이미지 리포지토리의 URL은 $REPO_URL 변수에 캡처된 다음 콘솔에 인쇄됩니다. 이 값은 다음 단계에서 사용합니다.

3. 이미지 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

4. Snowflake 레지스트리로 인증하려면 다음 Snowflake CLI 명령을 실행합니다.

   snow spcs image-registry login [-c connection_name]
   

   Copy

   이 명령은 Docker CLI가 Snowflake 계정의 이미지 리포지토리를 사용하는 데 필요한 자격 증명을 로드합니다. 기본값을 사용하지 않는 경우 연결 이름을 지정해야 합니다.

   모든 작업이 성공하면 Login Succeeded 메시지가 표시됩니다.

5. Docker 이미지를 이미지 리포지토리에 업로드하려면 다음 docker push 명령을 실행합니다.

   docker push $REPO_URL/<image_name>
   

   Copy

   이 명령은 이전 단계의 <image_name> 과 동일한 값을 사용합니다.

   docker push $REPO_URL/my_echo_service_image:tutorial
   

   Copy

6. 다음 명령을 실행하여 이미지가 성공적으로 업로드되었는지 확인합니다.

   snow spcs image-repository list-images tutorial_image_database.tutorial_image_schema.tutorial_image_repo --role tutorial_role
   

   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 만들기¶

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 계정에 배포할 수 있는 로컬 파일 구조를 Snowflake Native App with Snowpark Container Services 로 정의했습니다. 다음 섹션에서는 Snowflake CLI 를 사용하여 이 배포를 수행합니다.

애플리케이션 배포¶

스테이지 개발 모드에서 애플리케이션을 배포하려면 다음을 수행합니다.

1. na-spcs-tutorial 폴더에서 다음 명령을 실행하여 계정에 애플리케이션 패키지와 오브젝트를 생성합니다.

   snow app run [-c connection_name]
   

   Copy

   이 명령은 계정에서 이름이 na_spcs_tutorial_pkg 인 애플리케이션 패키지와 이름이 na_spcs_tutorial_app 인 애플리케이션 오브젝트가 생성되었다는 확인을 표시합니다. 이 이름은 이전 섹션에서 생성한 snowflake.yml 프로젝트 정의의 이름과 일치합니다.

콘솔에 URL 출력을 사용하여 애플리케이션을 볼 수 있습니다. 하지만 먼저 컨테이너 기반 서비스를 만드는 데 필요한 모든 권한이 있는지 확인해야 합니다.

이 작업은 다음 섹션에서 수행합니다.

권한 부여 및 앱 테스트¶

이 섹션에서는 앱에 필요한 권한을 부여하고 컨테이너에서 서비스를 호출하여 앱을 테스트합니다.

Snowsight 또는 Snowflake CLI 를 사용하여 SQL 명령을 실행할 수 있습니다.

권한을 부여하고 앱을 테스트하려면 다음 단계를 수행합니다.

참고

다음 구문으로 Snowflake CLI 에서 실행합니다.

snow sql -q "<sql>" --role tutorial_role --warehouse tutorial_warehouse

Copy

이전 단계와 마찬가지로 -c connection_name 을 추가하여 기본 연결이 아닌 연결을 선택할 수 있습니다.

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 메시지가 표시됩니다.