Tutorial 2: Crie um aplicativo com contêineres¶

O que você aprenderá neste tutorial¶

Neste tutorial, você aprenderá o seguinte:

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

Configure seu ambiente Snowflake¶

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.

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 é usado para executar consultas para o aplicativo que criou, bem como um repositório de imagens para hospedar imagens de contêineres.

Na próxima seção, crie uma imagem para o contêiner e carregue-a no repositório de imagens que você criou acima.

Criação de um arquivo de projeto usando o Snowflake CLI¶

1. Para criar um arquivo de projeto, execute o seguinte comando:

   snow init --template app_basic na-spcs-tutorial
   

   Copy

2. Digite um valor para o identificador do projeto.

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

Esse comando cria uma pasta chamada na-spcs-tutorial usando o modelo de projeto app_basic.

Na pasta na-spcs-tutorial, esse comando cria os seguintes arquivos e pastas:

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

Nas seções posteriores, você modifica esses arquivos e acrescenta recursos adicionais ao seu aplicativo.

Adição dos arquivos de serviço ao projeto do aplicativo¶

Na seção anterior, você criou um projeto que inclui os arquivos de aplicativo padrão exigidos pelo seu aplicativo. Nesta seção, adicione os arquivos necessários para criar o contêiner do seu aplicativo.

1. 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.

2. Para obter os arquivos do Docker necessários para o tutorial, faça o download do arquivo na_spcs_tutorial.zip para o sistema de arquivos local.

3. Descompacte o conteúdo do arquivo zip na pasta na-spcs-tutorial/service. Esta pasta deve conter os seguintes arquivos:

   • echo_service.py

   • Dockerfile

   • templates/basic_ui.html

   • echo_spec.yaml

Verificação da estrutura de diretórios de seu projeto¶

Depois de criar o projeto para o seu aplicativo e adicionar os arquivos para o serviço e o contêiner do Docker, o projeto deverá ter a seguinte estrutura na pasta 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

Criação de uma imagem do Docker e carregamento no repositório de imagens¶

Para criar uma imagem do Docker e carregá-la no repositório de imagens, siga estas etapas:

1. Em uma janela de terminal, vá para a pasta na-spcs-tutorial/service.

2. 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.

3. 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 -c tut-connection)
   echo $REPO_URL
   

   Copy

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

4. 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

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

   snow spcs image-registry login -c tut-connection
   

   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.

6. 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

7. 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 -c tut-connection
   

   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ê cria um pacote de aplicativo que usa essa imagem.

Modificação do arquivo de manifesto padrão¶

Para modificar o arquivo de manifesto do aplicativo, siga estas etapas:

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 fique 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.

Modificação do script de configuração padrão¶

Para modificar o script de configuração padrão do pacote de aplicativo, siga estas etapas:

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

Modificação do README padrão¶

Para modificar o arquivo README do aplicativo, siga estas etapas:

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

   Welcome to your first app with containers!
   

   Copy

Esse arquivo README fica visível para os consumidores depois que eles instalam seu aplicativo.

Modificação do arquivo de definição de projeto padrão¶

Nesta seção, você modifica o arquivo de definição de projeto usado 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ê realizará essa implementação usando o Snowflake CLI.

Carregamento de arquivos para o estágio e criação do objeto do aplicativo¶

Para criar um aplicativo no modo de desenvolvimento, siga estas etapas:

1. Em um terminal, vá para a pasta na-spcs-tutorial.

2. Crie o pacote do aplicativo e o objeto em sua conta executando o seguinte comando:

   snow app run -c tut-connection
   

   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 da definição do projeto snowflake.yml que você modificou 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.

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

Nesta seção, você concede 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 de uma planilha do Snowflake:

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

   Essa instrução chama o procedimento app_public.service_status que você definiu no script de configuração. O procedimento retorna informações sobre os contêineres desse serviço.

   Se o valor na coluna status não for READY, execute a instrução novamente, até que o status do contêiner de serviço seja READY.

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ê vê a seguinte mensagem do serviço que configurou em uma seção anterior:

   ``Bob said hello``
   

   Copy