Tutoriel 3 : Mettre à niveau une application avec des conteneurs¶

Tutoriels prérequis¶

Ce tutoriel suppose que vous savez comment développer une Snowflake Native App de base et que vous pouvez créer un Snowflake Native App with Snowpark Container Services. Ce tutoriel s’appuie sur les connaissances acquises à l’issue des tutoriels suivants :

• Tutoriel 1 : Créer une Native Apps de base avec Snowflake

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

Avant de suivre ce tutoriel pour mettre à niveau une application avec des conteneurs, assurez-vous d’avoir terminé ces deux tutoriels.

Ce que vous apprenez dans ce tutoriel¶

Ce tutoriel développe l’application avec les conteneurs que vous avez créés dans Tutoriel 2 : Créer une application avec des conteneurs. Dans ce tutoriel, vous apprenez à :

• Utiliser la fonction de rappel de l’initialisateur de version pour gérer les mises à niveau et les défaillances du service.

• Créer des définitions de version pour une application.

• Mettre à jour une application.

• Simuler l’échec de la mise à jour d’une application.

• Créer un correctif pour l’application afin de corriger l’erreur.

Déposer l’objet de l’application¶

Si l’application que vous avez créée via Tutoriel 2 : Créer une application avec des conteneurs existe toujours dans votre compte, vous devez supprimer l’objet d’application avant de poursuivre ce tutoriel.

1. Pour déterminer si l’application du tutoriel précédent (na_spcs_tutorial_app) existe dans votre compte, exécutez la commande suivante à partir d’une feuille de calcul :

   SHOW APPLICATIONS LIKE 'na_spcs_tutorial_app';
   

   Copy

2. Si l’application na_spcs_tutorial_app apparaît dans la sortie de cette commande, abandonnez l’application en exécutant les commandes suivantes à partir d’une feuille de calcul :

   USE ROLE tutorial_role;
   DROP APPLICATION IF EXISTS na_spcs_tutorial_app CASCADE;
   

   Copy

Ce que vous avez effectué dans cette section¶

Dans cette section, vous avez vérifié que les fichiers d’application et les objets Snowflake du tutoriel précédent fonctionnent toujours dans votre compte.

Dans la section suivante, vous en apprendrez davantage sur les versions et les mises à niveau dans le Snowflake Native App Framework.

À propos des versions et des correctifs¶

Les versions figurant sur le Snowflake Native App Framework sont des combinaisons de numéros de version et de correctifs. Ceux-ci sont définis dans le paquet d’application.

. rst-class:: bulleted-definition-list

Version

Contient généralement des mises à jour importantes d’une Snowflake Native App. Les versions sont définies dans un paquet d’application.

Correctif

Contient généralement de petites mises à jour d’une Snowflake Native App. Comme les versions, les correctifs sont définis dans le paquet d’application.

À propos des mises à niveau¶

Dans le contexte du Snowflake Native App Framework, les mises à niveau sont des mises à jour d’une version ou d’un correctif d’une Snowflake Native App installée sur le compte consommateur. Le Snowflake Native App Framework prend en charge deux types de mises à niveau :

Mises à niveau automatisées

Les mises à niveau automatisées sont des mises à niveau lancées par le fournisseur. Lorsqu’une nouvelle version ou un nouveau correctif est disponible, le fournisseur modifie la directive de version dans le paquet d’application. Cela déclenche une mise à niveau automatique de toutes les instances installées de l’application spécifiée par la directive de version.

Mises à niveau manuelles

Les mises à niveau manuelles sont des mises à niveau lancées par le consommateur en réponse à une communication du fournisseur. Les mises à jour manuelles sont utiles lorsqu’un fournisseur doit publier rapidement une mise à jour, par exemple une correction de bogue, à l’intention d’un consommateur.

Note

Ce tutoriel décrit comment effectuer une mise à niveau manuelle pour une application avec conteneurs.

Lorsqu’une nouvelle version ou un nouveau correctif est disponible, le fournisseur modifie la directive de version sur le paquet d’application et notifie ensuite au consommateur qu’une nouvelle version est disponible.

Le consommateur effectue la mise à niveau en exécutant la commande ALTER APPLICATION dans son compte pour effectuer la mise à niveau. En général, les mises à niveau manuelles permettent au consommateur de mettre à niveau l’application installée plus rapidement que les mises à niveau automatisées.

À propos de l’initialisateur de version¶

Un initialisateur de version est utilisé pour démarrer ou mettre à niveau des services ou d’autres processus connexes. L’initialisateur de version est une procédure stockée de rappel définie dans le fichier manifeste et mise en œuvre dans le script d’installation. La fonction de rappel de l’initialisateur de version est appelée dans les contextes suivants :

• Lors de l’installation, l’initialisateur de version est appelé dès que le script d’installation de l’application se termine sans erreur.

• Lors de la mise à niveau, il existe deux scénarios possibles dans lesquels l’initialisateur de version est appelé :

  • Si le script d’installation de la nouvelle version réussit, la nouvelle version de l’initialisateur de version est appelée.

  • Si le script d’installation ou l’initialisateur de version de la nouvelle version échoue, l’initialisateur de version de la version précédente est appelé. Cela permet à l’initiateur de la version précédente d’utiliser la commande ALTER SERVICE pour ramener les services à la version précédente.

Ajouter l’initialisateur de version au fichier manifeste¶

L’initialisateur de version est défini dans le fichier manifeste de l’application. Pour définir l’initialisateur de version, ajoutez le code suivant à la fin du fichier manifest.yml :

lifecycle_callbacks:
  version_initializer: app_public.version_init

Ceci spécifie le schéma et le nom de la procédure stockée utilisée comme initialisateur de version. Dans la section suivante, vous mettez en œuvre la procédure stockée version_init.

Ajouter l’initialisateur de version en tant que procédure stockée dans le script d’installation¶

Dans la section précédente, vous avez ajouté le nom de l’initialisateur de version au fichier manifeste. Dans cette section, vous ajoutez le code de la procédure stockée au script d’installation.

1. Ajoutez le code suivant à la fin du fichier setup_script.sql :

CREATE OR REPLACE PROCEDURE app_public.version_init()
RETURNS STRING
LANGUAGE SQL
AS
$$
DECLARE
can_create_compute_pool BOOLEAN;  -- Flag to check if 'CREATE COMPUTE POOL' privilege is held
BEGIN
-- Check if the account holds the 'CREATE COMPUTE POOL' privilege
   SELECT SYSTEM$HOLD_PRIVILEGE_ON_ACCOUNT('CREATE COMPUTE POOL')
      INTO can_create_compute_pool;

   ALTER SERVICE IF EXISTS core.echo_service
      FROM SPECIFICATION_FILE = 'service/echo_spec.yaml';
   IF (can_create_compute_pool) THEN
      -- When installing app, the app has no 'CREATE COMPUTE POOL' privilege at that time,
      -- so it will not execute the code below

      -- Since the ALTER SERVICE is an async process, wait for the service to be ready
      SELECT SYSTEM$WAIT_FOR_SERVICES(120, 'core.echo_service');
   END IF;
   RETURN 'DONE';
END;
$$;

Télécharger les fichiers modifiés et créer une version¶

Après avoir modifié le script d’installation, téléchargez les fichiers modifiés vers la zone de préparation et créez une version en exécutant la procédure suivante :

1. Exécutez la commande suivante pour télécharger les fichiers et créer une version :

   snow app version create v1 -c tut-connection
   

   Copy

La commande snow app version télécharge les fichiers mis à jour sur la zone de préparation. Si le paquet d’application et les fichiers existent déjà, cette commande ne télécharge que les fichiers qui ont été modifiés.

Cette commande crée une nouvelle version de l’application appelée v1 avec le paramètre par défaut défini sur 0.

Définir la directive de version par défaut pour l’application¶

Dans la section précédente, vous avez téléchargé les fichiers modifiés et créé la version v1 de l’application. Dans cette section, vous avez paramétré la directive de version par défaut pour qu’elle utilise la version v1.

Pour mettre à jour la directive de version par défaut, exécutez la commande suivante à partir d’une feuille de calcul :

ALTER APPLICATION PACKAGE na_spcs_tutorial_pkg
  SET DEFAULT RELEASE DIRECTIVE VERSION=v1 PATCH=0;

Lorsque vous définissez la directive de version par défaut pour une application, les consommateurs installent automatiquement cette version lorsqu’ils installent l’application dans leur compte. Dans la section suivante, vous créez l’application dans votre compte local sur la base de la directive de version.

Créer et tester l’appli¶

Maintenant que vous avez ajouté une version et défini la directive de version par défaut, vous pouvez créer l’application et accorder les privilèges requis :

1. Créez l’application à partir de la directive de version en exécutant la commande suivante :

   snow app run --from-release-directive -c tut-connection
   

   Copy

   Cette commande crée l’application en utilisant la directive de version que vous avez définie dans la section précédente.

2. Après avoir créé l’application, accordez-lui les privilèges requis pour pouvoir l’exécuter en lançant les commandes suivantes à partir d’une feuille de calcul.

   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

3. Appelez la procédure app_public.start_app que vous avez définie dans le fichier setup_script.sql en exécutant la commande suivante à partir d’une feuille de calcul :

   CALL na_spcs_tutorial_app.app_public.start_app();
   

   Copy

4. Confirmez la création de la fonction en exécutant la commande suivante à partir d’une feuille de calcul :

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

   Copy

5. Pour vérifier que le service a été créé et qu’il est en bonne santé, exécutez la commande suivante à partir d’une feuille de calcul :

   CALL na_spcs_tutorial_app.app_public.service_status();
   

   Copy

6. 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 à partir d’une feuille de calcul :

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

   Copy

7. Pour voir les informations sur l’application, exécutez la commande suivante à partir d’une feuille de calcul :

   DESC APPLICATION na_spcs_tutorial_app;
   

   Copy

Passez en revue ce que vous avez appris dans cette section¶

Dans cette section, vous avez effectué les tâches suivantes :

• Vous avez appris ce qu’est l’initialisateur de version et comment vous pouvez l’ajouter au fichier manifeste et au script d’installation.

• Vous avez appris les bases des versions et des correctifs sur le Snowflake Native App Framework.

• Vous avez défini la directive de version par défaut pour qu’elle pointe vers une version spécifique d’une application.

• Vous avez installé le programme d’installation en fonction de la directive de version.

• Vous avez testé l’application en appelant une procédure stockée et utilisé la commande DESCRIBE APPLICATION pour voir le statut de l’application.

Ajouter une nouvelle table à l’application¶

Pour simuler l’ajout d’une nouvelle fonction à votre application, ajoutez une nouvelle table au script d’installation.

1. Ajoutez les commandes suivantes à la fin du fichier setup_script.yml

   CREATE TABLE IF NOT EXISTS core.setup_script_run(run_at TIMESTAMP);
   GRANT SELECT ON TABLE core.setup_script_run to APPLICATION ROLE app_user;
   INSERT INTO core.setup_script_run(run_at) values(current_timestamp());
   

   Copy

Créez une version de l’application¶

Pour télécharger le script de mise en place modifié sur la zone de préparation et créer la version v2 de l’application :

1. Exécutez la commande suivante dans le dossier na-spcs-tutorial :

snow app version create v2 -c tut-connection

Cette commande crée une nouvelle version de l’application appelée v2 avec le paramètre par défaut défini sur 0.

La commande snow app version télécharge les fichiers mis à jour sur la zone de préparation. Si le paquet d’application et les fichiers existent déjà, cette commande ne télécharge que les fichiers qui ont été modifiés.

Définir la directive de version par défaut pour l’application¶

Après avoir créé la version v2 de l’application, définissez la directive de version pour le paquet d’application en exécutant la commande suivante à partir d’une feuille de calcul :

ALTER APPLICATION PACKAGE na_spcs_tutorial_pkg
  SET DEFAULT RELEASE DIRECTIVE VERSION=v2 PATCH=0;

Cette commande définit la directive de version sur la version v2 et le correctif 0.

Mettre à jour l’application de v1 à v2¶

Maintenant que vous avez mis à jour la directive de version pour qu’elle pointe vers la nouvelle version, mettez l’application à niveau en exécutant la commande suivante à partir d’une feuille de calcul :

snow app run --from-release-directive -c tut-connection

Tester l’application mise à jour¶

Après avoir mis à jour l’application, testez-la en exécutant la commande suivante à partir d’une feuille de calcul :

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

Passez en revue ce que vous avez appris dans cette section¶

Félicitations ! Vous avez réussi à mettre à niveau l’application de la version v1 à la version v2.

Dans cette section, vous avez effectué les tâches suivantes :

• Vous avez mis à jour l’application pour inclure une table.

• Vous avez créé une nouvelle version de l’application basée sur cette mise à jour.

• Vous avez mis à jour la directive de version par défaut pour pointer vers la nouvelle version.

• Vous avez mis à niveau manuellement l’application.

Dans la section suivante, vous mettez à niveau le service de l’application et simulez une erreur dans le processus de mise à niveau en ajoutant intentionnellement une erreur dans le script d’installation.

Mettre à jour le fichier de spécification de service¶

Dans cette section, vous mettez à jour les spécifications du service de l’application pour simuler une modification du service.

1. Dans le fichier service/echo_spec.yaml, changez la valeur de CHARACTER_NAME de Bob à Tom.

   Cette modification entraîne le renvoi par le service du message suivant :

   `Tom said hello.`
   

   Copy

L’objectif de cette modification est de vous permettre de savoir quelle version du service est en cours d’exécution après avoir tenté une mise à niveau dans les sections suivantes.

Mettre à jour le script d’installation pour inclure une erreur intentionnelle¶

Pour simuler une erreur au cours du processus de mise à niveau, introduisez une erreur intentionnelle dans le script d’installation en ajoutant une instruction SELECT pour une table qui n’existe pas.

Ajoutez l’instruction suivante à la fin de la procédure app_public.version_init() dans le fichier setup_script.sql.

SELECT * FROM table_does_not_exist;

Cette instruction est syntaxiquement correcte, mais fait référence à une table qui n’existe pas. Cela provoque une erreur lors de l’exécution du script d’installation pendant la mise à niveau.

Après cette modification, la fonction app_public.version_init() devrait ressembler à l’exemple suivant :

GRANT USAGE ON PROCEDURE app_public.service_status() TO APPLICATION ROLE app_user;

CREATE OR REPLACE PROCEDURE app_public.version_init()
RETURNS STRING
LANGUAGE SQL
AS
$$
DECLARE
  -- Flag to check if 'CREATE COMPUTE POOL' privilege is held
  can_create_compute_pool BOOLEAN;
BEGIN
   -- Check if the account holds the 'CREATE COMPUTE POOL' privilege
   SELECT SYSTEM$HOLD_PRIVILEGE_ON_ACCOUNT('CREATE COMPUTE POOL')
     INTO can_create_compute_pool;

   ALTER SERVICE IF EXISTS core.echo_service
     FROM SPECIFICATION_FILE = 'service/echo_spec.yaml';
   IF (can_create_compute_pool) THEN
     -- When installing app, the app has no 'CREATE COMPUTE POOL' privilege at that time,
     -- so it will not execute the code below

     -- Since the ALTER SERVICE is an async process, wait for the service to be ready
     SELECT SYSTEM$WAIT_FOR_SERVICES(120, 'core.echo_service');
   END IF;

   -- trigger an error. The upgrade fails
   SELECT * FROM non_exist_table;

   RETURN 'DONE';
END;
$$;

Télécharger les fichiers révisés et créer un nouveau patch¶

Dans les sections précédentes, vous avez mis à jour la spécification de service et le script de configuration de l’application.

Pour télécharger les fichiers et créer un nouveau correctif pour l’application, effectuez les tâches suivantes :

1. Exécuter la commande suivante pour ajouter un correctif au paquet d’application.

snow app version create v2 --patch 1 -c tut-connection

1. Lorsque vous y êtes invité, entrez y pour ajouter un nouveau paquet d’application.

Définir la directive de version par défaut pour l’application¶

Dans la section précédente, vous avez téléchargé les fichiers et créé un correctif pour les mises à jour. Pour définir la directive de version par défaut du correctif, exécutez la commande suivante à partir d’une feuille de calcul :

ALTER APPLICATION PACKAGE na_spcs_tutorial_pkg
  SET DEFAULT RELEASE DIRECTIVE VERSION=v2 PATCH=1;

Cette commande définit ce correctif pour l’application sur le correctif 1.

Mettre à jour l’application¶

Dans les sections précédentes, vous avez effectué des mises à jour de l’application et créé un nouveau correctif. Dans cette section, vous mettez à niveau l’application en vous attendant à ce qu’elle échoue en raison de l’erreur que vous avez introduite dans les sections précédentes.

Pour mettre à jour l’application, exécutez la commande suivante :

snow app run --from-release-directive -c tut-connection

Pour voir l’état de mise à niveau de l’application, exécutez la commande suivante à partir d’une feuille de calcul :

DESC APPLICATION na_spcs_tutorial_app;

Cette commande affiche des informations sur l’application, notamment l’état de la mise à niveau, le nombre de tentatives de mise à niveau et la raison de l’échec de la mise à niveau.

Après l’échec de la mise à niveau, Snowflake CLI renvoie le message suivant :

Object 'TABLE_DOES_NOT_EXIST' does not exist or not authorized.'

En outre, après l’échec de la mise à niveau, la commande DESC APPLICATION affiche les propriétés suivantes relatives aux mises à niveau :

Propriété	Valeur
upgrade_state	FAILED
upgrade_failure_reason	upgrade_failure_reason[ErrorCode 2003] Uncaught exception of type “STATEMENT_ERROR” on line 89 at position 0 : Uncaught exception of type “STATEMENT_ERROR” on line 19 at position 3 : SQL compilation error: Object “TABLE_DOES_NOT_EXIST” does not exist or not authorized.

Exécuter le service de l’application pour voir quelle version du service est en cours d’exécution¶

Dans la section précédente, vous avez simulé une défaillance lors de la mise à niveau de la version v2, correctif 0 vers la version v2, correctif 1.

Pour déterminer quelle version du service est actuellement en cours d’exécution, exécutez la commande suivante à partir d’une feuille de calcul.

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

Cette commande renvoie la chaîne suivante :

Bob said hello

Ici, vous voyez que depuis l’échec de la mise à niveau, l’application continue d’exécuter le service de v2, correctif 0.

Toutefois, si vous n’avez pas inclus d’initialisateur de version dans l’application, le processus de mise à niveau aurait mis le service à niveau vers v2, correctif 1 bien que la mise à niveau de l’application ait échoué. Si une mise à niveau de l’application échoue, l’initialisateur de version garantit que la version du service n’est pas mise à niveau et continue d’être synchronisée avec l’application.

Passez en revue ce que vous avez appris dans cette section¶

Dans cette section, vous avez effectué les tâches suivantes :

• Vous avez introduit une erreur dans le script d’installation pour simuler une erreur dans le processus de mise à niveau.

• Vous avez vérifié la version de l’application et du service après l’échec.

• Vous avez appris comment l’initialisateur de version garantit que la version d’un service est synchronisée avec la version de l’application lorsqu’une mise à niveau échoue.

Modifier le script d’installation¶

Pour corriger l’erreur intentionnelle que vous avez introduite dans une section précédente, supprimez l’instruction suivante du fichier setup_script.yaml :

SELECT * FROM table_does_not_exist;

Télécharger les fichiers mis à jour et créer un nouveau patch¶

Pour télécharger le script de configuration modifié vers une zone de préparation et créer une nouvelle préparation, effectuez les tâches suivantes :

1. Exécutez la commande suivante pour créer un nouveau correctif pour l’application :

2. Lorsque vous y êtes invité, entrez y pour ajouter un nouveau paquet d’application.

Mettre à jour la directive sur la version par défaut¶

Dans la section précédente, vous avez créé le correctif 2 pour l’application. Pour définir la directive de version par défaut du correctif, exécutez la commande suivante à partir d’une feuille de calcul :

ALTER APPLICATION PACKAGE na_spcs_tutorial_pkg
  SET DEFAULT RELEASE DIRECTIVE VERSION=v2 PATCH=2;

Mettre à jour l’application et vérifier la version du service¶

Après avoir créé une nouvelle version et défini la directive de version par défaut, mettez à niveau l’application et testez le service en effectuant les tâches suivantes :

1. Pour mettre à jour l’application de la version v2 correctif 0 à la version v2 correctif 2, exécutez la commande suivante :

   snow app run --from-release-directive -c tut-connection
   

   Copy

2. Pour vérifier la version du service en cours d’exécution, exécutez la commande suivante à partir d’une feuille de calcul :

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

   Copy

3. Pour voir le statut de l’application, y compris la version actuellement installée, exécutez la commande suivante :

   DESC APPLICATION na_spcs_tutorial_app;
   

   Copy

   Dans la sortie, la propriété version est v2 et la propriété correctif est 2.

Passez en revue ce que vous avez appris dans cette section¶

Félicitations ! Vous avez réussi à mettre à jour l’application après l’échec de la mise à jour.

Dans cette section, vous avez effectué les tâches suivantes :

• Vous avez corrigé l’erreur dans le script d’installation.

• Vous avez créé un correctif, p2, pour mettre à jour l’application.

• Vous avez mis à jour l’application vers le nouveau correctif.

Résumé¶

Dans ce tutoriel, vous avez effectué les tâches suivantes :

• Ajout d’une procédure stockée d’initialisation de la version pour gérer les services lors des mises à niveau et des pannes.

• Création d’une nouvelle définition de la version de l’application dans le paquet d’application. Les définitions de version précisent le numéro de version et le correctif de l’application.

• Définition de la directive de version par défaut pour une application. Les directives de version déterminent quelle version et quel correctif sont installés lorsqu’un consommateur installe ou met à niveau une application.

• Mise à jour d’une application et vérification de ce qui se passe lors de l’échec de la mise à jour.