Tutorial: Crie um Snowflake Native App com o Snowpark Container Services¶

O que você aprenderá¶

Neste tutorial, você aprenderá como:

• Usar Snowflake CLI para inicializar um projeto Snowflake Native App with Snowpark Container Services.

• Criar uma imagem Docker para um aplicativo.

• Criar o pacote de aplicativo e os arquivos de aplicativo necessários para um Snowflake Native App with Snowpark Container Services.

• Testar um Snowflake Native App with Snowpark Container Services chamando a função de serviço dentro do contêiner.

Pré-requisitos¶

Para executar este tutorial, você deve atender aos seguintes pré-requisitos:

• Ter acesso a uma conta Snowflake com suporte ao Snowpark Container Services.

• Você deve ser capaz de usar a função ACCOUNTADMIN para criar a função usada neste tutorial e conceder os privilégios necessários a essa função.

• Você deve ter Snowflake CLI versão 3.0.0 ou superior instalado em sua máquina local.

• Você deve ter o Docker Desktop instalado na sua máquina local.

Configuração da sua conexão de Snowflake CLI¶

Os comandos que você executará neste tutorial pressupõem que você tenha configurado Snowflake CLI para conectar-se por padrão à conta onde você está desenvolvendo o aplicativo. Se esta conta não estiver definida por padrão, você pode usar o argumento -c de linha de comando para especificar uma conexão com nome diferente, por exemplo:

snow sql -q "SELECT 1" -c connection_name

Copy

Criação de um warehouse e um repositório de imagens¶

Para criar os objetos necessários, execute o seguinte por meio de Snowsight ou Snowflake CLI.

1. Para definir o contexto atual em Snowsight para usar a função tutorial_role, execute o seguinte comando:

   USE ROLE tutorial_role;
   

   Copy

   Se você estiver usando Snowflake CLI, você pode usar --role tutorial_role em vez disso.

2. Para criar um warehouse para o Snowflake Native App with Snowpark Container Services, execute o seguinte comando:

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

   Copy

   Um warehouse é exigido pelo Snowflake Native App para executar os comandos SQL e procedimentos armazenados.

3. Para criar o repositório de imagens usado para armazenar o contêiner, execute o seguinte comando:

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

   Copy

Nesta seção, você criou um warehouse que será usado para executar consultas para o aplicativo que você criará, bem como um repositório de imagens para hospedar imagens de contêiner.

Na próxima seção, você criará uma imagem para o contêiner e a enviará para o repositório de imagens criado acima.

Criação de um diretório de projeto¶

O código-fonte do seu aplicativo existe no sistema de arquivos local e pode ser verificado no controle de versão, se desejado. Começaremos usando Snowflake CLI para inicializar um projeto de Native Apps; então, construiremos a imagem para nosso serviço de contêiner em uma subpasta.

1. No seu sistema de arquivos local, execute o seguinte comando para criar uma pasta chamada na-spcs-tutorial:

   snow init --template app_basic na-spcs-tutorial
   

   Copy

   Nota

   Você adicionará outros arquivos e subpastas a essa pasta e editará os arquivos criados por esse comando em subseções posteriores.

   Nota

   Execute o snow init --help para ver outros modelos para configurar um ambiente de desenvolvimento do Snowflake Native App.

2. Crie uma pasta chamada service dentro da pasta na-spcs-tutorial. Esta pasta contém o código-fonte do serviço baseado em contêiner que estamos prestes a criar e publicar no Snowflake.

3. Para obter os arquivos Docker necessários para o tutorial, baixe o arquivo zip para seu sistema de arquivos local.

4. Descompacte o conteúdo para a pasta na-spcs-tutorial/service. Esta pasta deve conter os seguintes arquivos:

   • echo_service.py

   • Dockerfile

   • templates/basic_ui.html

   • echo_spec.yaml

5. Abra uma janela de terminal e mude para esse diretório.

Criação de uma imagem Docker e carregamento no contêiner¶

Para criar uma imagem do Docker e enviá-la ao repositório de imagens, faça o seguinte:

1. Execute o seguinte comando Docker CLI. Observe que você deve especificar o diretório de trabalho atual (.) no comando:

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

   Copy

   Este comando executa o seguinte:

   • Cria uma imagem Docker usando o arquivo Docker incluído no arquivo zip que você baixou

   • Nomeia a imagem my_echo_service_image

   • Aplica a tag tutorial na imagem.

2. Para identificar o URL do repositório de imagens que você criou em uma seção anterior, execute o seguinte comando:

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

   Copy

   O URL do repositório de imagens é capturado na variável $REPO_URL e depois impressa no console. Você usará esse valor na próxima etapa.

3. Para criar uma tag para a imagem que inclui o URL da imagem, execute o seguinte comando Docker CLI:

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

   Copy

   Este comando requer dois parâmetros:

   • <nome_da_imagem> Especifica o nome da imagem e a tag.

   • <url_da_imagem>/<nome_da_imagem> Especifica o URL do repositório de imagens onde a imagem é carregada e o nome e a tag da imagem onde ela deve ser armazenada no repositório remoto.

   Para este tutorial, use $REPO_URL e my_echo_service_image:tutorial:

   docker tag my_echo_service_image:tutorial $REPO_URL/my_echo_service_image:tutorial
   

   Copy

4. Para autenticar com o registro Snowflake, execute o seguinte comando Snowflake CLI:

   snow spcs image-registry login [-c connection_name]
   

   Copy

   Este comando carrega as credenciais necessárias para o Docker CLI para usar os repositórios de imagens na sua conta Snowflake. Você deve especificar o nome da conexão, caso não esteja usando o padrão.

   A mensagem Login Succeeded exibe se tudo foi bem-sucedido.

5. Para carregar a imagem do Docker no repositório de imagens, execute o seguinte comando docker push:

   docker push $REPO_URL/<image_name>
   

   Copy

   Usando o mesmo valor que <nome_da_imagem> dos passos anteriores, este comando é:

   docker push $REPO_URL/my_echo_service_image:tutorial
   

   Copy

6. Confirme se a imagem foi carregada com sucesso executando o seguinte comando:

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

   Copy

Nesta seção, você criou uma imagem Docker contendo o serviço echo e a enviou para o repositório de imagens tutorial_repository que você criou anteriormente no tutorial.

Na próxima seção, você criará um pacote de aplicativo que usa essa imagem.

Criação do arquivo de manifesto para o pacote de aplicativo¶

Para criar o arquivo de manifesto necessário para o pacote do aplicativo, faça o seguinte:

1. Modifique na-spcs-tutorial/app/manifest.yml para ficar parecido com o seguinte:

   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

   Este exemplo inclui o seguinte:

   • A propriedade artifacts especifica os locais dos recursos necessários para um aplicativo com contêineres, incluindo o local da imagem do Docker que você criou em uma etapa anterior, bem como o projeto README que ficará visível em Snowsight.

   • A propriedade privileges permite que um serviço responda a solicitações públicas e também crie seu próprio pool de computação. Essas propriedades são necessárias para instanciar nosso serviço na próxima etapa do tutorial.

Criação do script de configuração para o pacote do aplicativo¶

Para criar o script de configuração necessário para o pacote do aplicativo, faça o seguinte:

1. Modifique o arquivo na-spcs-tutorial/app/setup_script.sql para incluir o seguinte:

   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

Criação de um leia-me para o pacote do aplicativo¶

1. Modifique na-spcs-tutorial/app/README.md para ficar parecido com o seguinte:

   Welcome to your first app with containers!
   

   Copy

Este arquivo leia-me fica visível para os consumidores que instalaram seu aplicativo.

Criação do arquivo de definição do projeto¶

Nesta seção, você criará o arquivo de definição do projeto exigido pelo Snowflake CLI.

1. Modifique na-spcs-tutorial/snowflake.yml para ficar parecido com o seguinte:

   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

Nesta seção, você definiu uma estrutura de arquivo local que pode ser implantada em uma conta Snowflake como um Snowflake Native App with Snowpark Container Services. Na próxima seção, você executará essa implantação usando Snowflake CLI.

Implantação do aplicativo¶

Para implantar o aplicativo no modo de desenvolvimento em estágios, faça o seguinte:

1. Crie o pacote do aplicativo e o objeto em sua conta executando o seguinte comando dentro da pasta na-spcs-tutorial:

   snow app run [-c connection_name]
   

   Copy

   Este comando exibe uma confirmação de que um pacote de aplicativo chamado na_spcs_tutorial_pkg e um objeto de aplicativo chamado na_spcs_tutorial_app foram criados em sua conta. Esses nomes correspondem aos nomes na definição de projeto snowflake.yml que você criou em uma seção anterior.

Você pode usar a saída do URL para o console para visualizar o aplicativo. No entanto, primeiro você deve garantir que ele tenha todos os privilégios necessários para criar seu serviço baseado em contêiner.

Você fará isso na próxima seção.

Concessão dos privilégios e teste do aplicativo¶

Nesta seção, você concederá os privilégios necessários ao aplicativo e testará o aplicativo chamando os serviços no contêiner.

Você pode executar os comandos SQL usando o Snowsight ou o Snowflake CLI.

Para conceder os privilégios e testar o aplicativo, execute as seguintes etapas.

Nota

Para executar em Snowflake CLI, tente a seguinte sintaxe:

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

Copy

Como nas etapas anteriores, você pode adicionar -c connection_name para escolher uma conexão não padrão.

1. Conceda o privilégio CREATE COMPUTE POOL ao aplicativo executando o seguinte:

   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. Execute o procedimento app_public.start_app que definimos no arquivo setup_script.sql.

   CALL na_spcs_tutorial_app.app_public.start_app();
   

   Copy

   Este procedimento cria o pool de computação, instancia o serviço e cria a função de serviço.

3. Confirme se a função foi criada executando o seguinte:

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

   Copy

   Nota

   Os consumidores não conseguem ver o serviço em execução porque ele é executado como parte do Snowflake Native App. Por exemplo, a execução de SHOW SERVICES IN APPLICATION na_spcs_tutorial_app; não retorna nada.

4. Para verificar se o serviço foi criado e está íntegro, execute o seguinte comando:

   CALL na_spcs_tutorial_app.app_public.service_status();
   

   Copy

   Este comando chama o procedimento app_public.service_status que você definiu no script de configuração:

   Quando este procedimento retorna READY, você prossegue para a próxima etapa.

5. Para chamar a função de serviço para enviar uma solicitação ao serviço e verificar a resposta, execute o seguinte comando:

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

   Copy

   Você verá uma mensagem do serviço que carregamos em uma seção anterior: Bob said hello.