Tutoriel 2 : Créer une application avec des conteneurs¶

Ce que vous apprenez dans ce tutoriel¶

Dans ce tutoriel, vous apprenez à :

• Utilisez Snowflake CLI pour initialiser un projet Snowflake Native App with Snowpark Container Services.

• Créez une image Docker pour une appli.

• Créez le paquet d’application et les fichiers d’application requis pour un Snowflake Native App with Snowpark Container Services.

• Testez un Snowflake Native App with Snowpark Container Services en appelant la fonction de service dans le conteneur.

Configurer votre environnement Snowflake¶

Pour réaliser ce tutoriel, vous devez remplir les conditions préalables suivantes :

• Accès à un compte Snowflake qui prend en charge Snowpark Container Services.

• Vous devez pouvoir utiliser le rôle ACCOUNTADMIN pour créer le rôle utilisé dans ce tutoriel et lui accorder les privilèges requis.

• Vous devez avoir Snowflake CLI version 3.0.0 ou supérieure installée sur votre machine locale.

• Docker Desktop doit être installé sur votre machine locale.

Créer un entrepôt et un référentiel d’images¶

Pour créer les objets requis, effectuez les opérations suivantes via Snowsight ou Snowflake CLI.

1. Pour définir le contexte actuel dans Snowsight afin qu’il utilise le rôle tutorial_role, exécutez la commande suivante :

   USE ROLE tutorial_role;
   

   Copy

   Si vous utilisez Snowflake CLI, vous pouvez utiliser --role tutorial_role à la place.

2. Pour créer un entrepôt pour Snowflake Native App with Snowpark Container Services, exécutez la commande suivante :

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

   Copy

   Un entrepôt est requis par la Snowflake Native App pour exécuter les commandes SQL et les procédures stockées.

3. Pour créer le référentiel d’images utilisé pour stocker le conteneur, exécutez la commande suivante :

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

   Copy

Dans cette section, vous avez créé un entrepôt qui est utilisé pour exécuter des requêtes pour l’application que vous allez créer, ainsi qu’un référentiel d’images pour héberger des images de conteneurs.

Dans la section suivante, vous créez une image pour le conteneur et la télécharger dans le référentiel d’images que vous avez créé ci-dessus.

Créer un fichier de projet à l’aide de la CLI Snowflake¶

1. Pour créer un fichier de projet, exécutez la commande suivante :

   snow init --template app_basic na-spcs-tutorial
   

   Copy

2. Saisissez une valeur pour l’identificateur du projet.

   Vous ajoutez d’autres fichiers et sous-dossiers à ce dossier et vous modifiez les fichiers créés par cette commande dans les sous-sections suivantes.

Cette commande crée un dossier nommé na-spcs-tutorial en utilisant le modèle de projet app_basic.

Dans le dossier na-spcs-tutorial, cette commande crée les fichiers et dossiers suivants :

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

Dans les sections suivantes, vous modifiez ces fichiers et ajoutez des ressources supplémentaires à votre application.

Ajouter les fichiers de service au projet d’application¶

Dans la section précédente, vous avez créé un projet qui comprend les fichiers d’application par défaut nécessaires à votre application. Dans cette section, vous ajoutez les fichiers nécessaires à la création du conteneur pour votre application.

1. Créez un dossier appelé service à l’intérieur du dossier na-spcs-tutorial.

   Ce dossier contient le code source du service basé sur un conteneur que nous sommes sur le point de construire et de publier sur Snowflake.

2. Pour obtenir les fichiers Docker requis pour le tutoriel, téléchargez le fichier na_spcs_tutorial.zip sur votre système local.

3. Décompressez le contenu du fichier zip dans le dossier na-spcs-tutorial/service. Ce dossier doit contenir les fichiers suivants :

   • echo_service.py

   • Dockerfile

   • templates/basic_ui.html

   • echo_spec.yaml

Vérifier la structure du répertoire de votre projet¶

Après avoir créé le projet pour votre application et ajouté les fichiers pour le service et le conteneur Docker, le projet doit avoir la structure suivante dans le dossier 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

Créer une image Docker et la télécharger dans le référentiel d’images.¶

Pour créer une image Docker et la télécharger dans le référentiel d’images, procédez comme suit :

1. Dans une fenêtre de terminal, accédez au dossier na-spcs-tutorial/service.

2. Exécutez la commande Docker CLI suivante. Notez que vous devez spécifier le répertoire de travail actuel (.) dans la commande :

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

   Copy

   Cette commande permet d’effectuer les opérations suivantes :

   • Construit une image Docker en utilisant le fichier Docker inclus dans le fichier zip que vous avez téléchargé

   • Nomme l’image my_echo_service_image

   • Applique la balise tutorial à l’image.

3. Pour identifier l’URL du référentiel d’images que vous avez créé dans une section précédente, exécutez la commande suivante :

   REPO_URL=$(snow spcs image-repository url tutorial_image_database.tutorial_image_schema.tutorial_image_repo -c tut-connection)
   echo $REPO_URL
   

   Copy

   L’URL du référentiel d’images est capturée dans la variable $REPO_URL, puis imprimée dans la console. Vous utiliserez cette valeur à l’étape suivante.

4. Pour créer une balise pour l’image qui inclut l’URL de l’image, exécutez la commande Docker CLI suivante :

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

   Copy

   Cette commande nécessite deux paramètres :

   • <image_name> Spécifie le nom de l’image et de la balise.

   • <image_url>/<image_name> Spécifie l’URL du référentiel d’images où l’image est téléchargée ainsi que le nom et la balise de l’image où elle doit être stockée dans le référentiel distant.

   Pour ce tutoriel, utilisez $REPO_URL et my_echo_service_image:tutorial :

   docker tag my_echo_service_image:tutorial $REPO_URL/my_echo_service_image:tutorial
   

   Copy

5. Pour vous authentifier auprès du registre Snowflake, exécutez la commande suivante de Snowflake CLI :

   snow spcs image-registry login -c tut-connection
   

   Copy

   Cette commande charge les identifiants de connexion nécessaires pour que Docker CLI utilise les référentiels d’images de votre compte Snowflake. Vous devez spécifier le nom de la connexion si vous n’utilisez pas le nom par défaut.

   Le message Login Succeeded s’affiche si tout s’est déroulé correctement.

6. Pour télécharger l’image Docker dans le référentiel d’images, exécutez la commande docker push suivante :

   docker push $REPO_URL/<image_name>
   

   Copy

   En utilisant la même valeur que <image_name> des étapes précédentes, cette commande est :

   docker push $REPO_URL/my_echo_service_image:tutorial
   

   Copy

7. Confirmez que l’image a été téléchargée avec succès en exécutant la commande suivante :

   snow spcs image-repository list-images tutorial_image_database.tutorial_image_schema.tutorial_image_repo -c tut-connection
   

   Copy

Dans cette section, vous avez créé une image Docker contenant le service echo et l’avez poussée vers le référentiel d’images tutorial_repository que vous avez créé plus tôt dans le tutoriel.

Dans la section suivante, vous créez un paquet d’application qui utilise cette image.

Modifier le fichier manifeste par défaut¶

Pour modifier le fichier manifeste de l’application, procédez comme suit :

1. Modifiez na-spcs-tutorial/app/manifest.yml pour qu’il ressemble à ce qui suit :

   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

   Cet exemple comprend ce qui suit :

   • La propriété artifacts spécifie les emplacements des ressources requises par une appli avec des conteneurs, y compris l’emplacement de l’image Docker que vous avez créée dans une étape précédente, ainsi que le projet README qui est visible dans Snowsight.

   • La propriété privileges permet à un service de répondre aux demandes publiques et de créer son propre pool de calcul. Ces propriétés sont nécessaires à l’instanciation de notre service dans l’étape suivante du tutoriel.

Modifier le script d’installation par défaut¶

Pour modifier le script d’installation par défaut du paquet d’application, procédez comme suit :

1. Modifiez le fichier na-spcs-tutorial/app/setup_script.sql pour y inclure les éléments suivants :

   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

Modifier le fichier README par défaut¶

Pour modifier le fichier README de l’application, procédez comme suit :

1. Modifiez na-spcs-tutorial/app/README.md pour qu’il ressemble à ce qui suit :

   Welcome to your first app with containers!
   

   Copy

Ce fichier README est visible par les consommateurs après l’installation de votre application.

Modifier le fichier de définition du projet par défaut¶

Dans cette section, vous modifiez le fichier de définition du projet utilisé par la Snowflake CLI.

1. Modifiez na-spcs-tutorial/snowflake.yml pour qu’il ressemble à ce qui suit :

   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

Dans cette section, vous avez défini une structure de fichiers locale qui peut être déployée dans un compte Snowflake en tant que Snowflake Native App with Snowpark Container Services. Dans la section suivante, vous effectuez ce déploiement à l’aide de Snowflake CLI.

Télécharger les fichiers dans la zone de préparation et créer l’objet de l’application¶

Pour créer une application en mode développement, procédez comme suit :

1. Dans un terminal, accédez au dossier na-spcs-tutorial.

2. Créez le paquet d’application et l’objet dans votre compte en exécutant la commande suivante :

   snow app run -c tut-connection
   

   Copy

   Cette commande affiche une confirmation qu’un paquet d’application appelé na_spcs_tutorial_pkg et un objet d’application appelé na_spcs_tutorial_app ont été créés dans votre compte. Ces noms correspondent aux noms de la définition du projet snowflake.yml que vous avez modifié dans une section précédente.

Vous pouvez utiliser la sortie d’URL vers la console pour voir l’application. Cependant, vous devez d’abord vous assurer qu’il dispose de tous les privilèges nécessaires pour créer son service basé sur un conteneur.

Accorder les privilèges et tester l’application¶

Dans cette section, vous accordez les privilèges requis à l’application et vous la testez en appelant les services du conteneur.

Vous pouvez exécuter les commandes SQL en utilisant soit Snowsight soit Snowflake CLI.

Pour accorder les privilèges et tester l’application, effectuez les étapes suivantes à partir d’une feuille calcul Snowflake :

1. Accordez le privilège CREATE COMPUTE POOL à l’appli en exécutant ce qui suit :

   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. Exécutez la procédure app_public.start_app que nous avons définie dans le fichier setup_script.sql.

   CALL na_spcs_tutorial_app.app_public.start_app();
   

   Copy

   Cette procédure crée le pool de calcul, instancie le service et crée la fonction de service.

3. Confirmez la création de la fonction en exécutant la procédure suivante :

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

   Copy

   Note

   Les consommateurs ne peuvent pas voir le service en cours d’exécution, car il s’exécute dans le cadre du Snowflake Native App. Par exemple, l’exécution de SHOW SERVICES IN APPLICATION na_spcs_tutorial_app; ne renvoie rien.

4. Pour vérifier que le service a été créé et qu’il est intègre, exécutez la commande suivante :

   CALL na_spcs_tutorial_app.app_public.service_status();
   

   Copy

   Cette instruction appelle la procédure app_public.service_status que vous avez définie dans le script d’installation. La procédure renvoie des informations sur les conteneurs de ce service.

   Si la valeur de la colonne status n’est pas READY, exécutez à nouveau l’instruction jusqu’à ce que le statut du conteneur de service soit READY.

5. Pour appeler la fonction de service afin d’envoyer une requête au service et de vérifier la réponse, exécutez la commande suivante :

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

   Copy

   Le message suivant s’affiche, provenant du service que vous avez configuré dans une section précédente :

   ``Bob said hello``
   

   Copy