Tutoriel : Créer une Snowflake Native App avec les Snowpark Container Services¶

Ce que vous apprendrez¶

Dans ce tutoriel, vous apprendrez à :

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

Conditions préalables¶

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.

Configurer votre connexion Snowflake CLI¶

Les commandes que vous exécuterez dans ce tutoriel supposent que vous avez configuré Snowflake CLI pour qu’il se connecte par défaut au compte sur lequel vous développez l’appli. Si ce compte n’est pas défini par défaut, vous pouvez utiliser l’argument de ligne de commande -c pour spécifier une autre connexion nommée, par exemple :

snow sql -q "SELECT 1" -c connection_name

Copy

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 servira à exécuter des requêtes pour l’appli 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 allez créer 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 répertoire de projet¶

Le code source de votre application se trouve dans le système de fichiers local et peut, si vous le souhaitez, faire l’objet d’un contrôle de version. Nous commencerons par utiliser Snowflake CLI pour démarrer un projet Native Apps ; ensuite, nous construirons l’image de notre service de conteneur dans un sous-dossier.

1. Sur votre système de fichiers local, exécutez la commande suivante pour créer un dossier nommé na-spcs-tutorial :

   snow init --template app_basic na-spcs-tutorial
   

   Copy

   Note

   Vous ajouterez d’autres fichiers et sous-dossiers à ce dossier et modifierez les fichiers que cette commande a créés dans les sous-sections suivantes.

   Note

   Exécutez snow init --help pour voir d’autres modèles de configuration d’un environnement de développement Snowflake Native App.

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

3. Pour obtenir les fichiers Docker nécessaires au tutoriel, téléchargez le fichier zip sur votre système de fichiers local.

4. Dézippez le contenu 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

5. Ouvrez une fenêtre de terminal et accédez à ce répertoire.

Construire une image Docker et la télécharger dans le conteneur¶

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

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

2. 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 --role tutorial_role)
   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.

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

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

   snow spcs image-registry login [-c connection_name]
   

   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.

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

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

   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 allez créer un paquet d’application qui utilise cette image.

Création du fichier manifeste d’un paquet d’application¶

Pour créer le fichier manifeste requis pour le paquet d’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 sera 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.

Créer le script d’installation pour le paquet d’application¶

Pour créer le script d’installation requis pour le 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 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

Créer un fichier lisez-moi pour le paquet d’application¶

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 lisez-moi est visible par les consommateurs qui ont installé votre appli.

Créer le fichier de définition du projet¶

Dans cette section, vous allez créer le fichier de définition de projet requis par 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 effectuerez ce déploiement à l’aide de Snowflake CLI.

Déployer l’application¶

Pour déployer l’application en zone de développement de zone de préparation, procédez comme suit :

1. Créez le paquet d’application et l’objet dans votre compte en exécutant la commande suivante dans le dossier na-spcs-tutorial :

   snow app run [-c connection_name]
   

   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 créée 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.

Vous le ferez dans la section suivante.

Accorder les privilèges et tester l’application¶

Dans cette section, vous allez accorder les privilèges requis à l’appli et la tester en appelant les services dans le conteneur.

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

Pour accorder les privilèges et tester l’appli, procédez comme suit.

Note

Pour exécuter dans Snowflake CLI, essayez la syntaxe suivante :

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

Copy

Comme dans les étapes précédentes, vous pouvez ajouter -c connection_name pour choisir une connexion autre que celle par défaut.

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 commande appelle la procédure app_public.service_status que vous avez définie dans le script d’installation :

   Lorsque cette procédure renvoie READY, vous passez à l’étape suivante.

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

   Vous verrez un message du service que nous avons téléchargé dans une section précédente : Bob said hello.