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