Snowpark Container Services : utilisation des tâches¶

Créer un service de longue durée¶

Utilisez CREATE SERVICE pour créer un service de longue durée.

• Créez un service à l’aide d’une spécification en ligne. Dans la plupart des cas, au cours du développement, vous pouvez choisir la spécification en ligne, comme indiqué :

  CREATE SERVICE echo_service
     IN COMPUTE POOL tutorial_compute_pool
     FROM SPECIFICATION $$
     spec:
       containers:
       - name: echo
         image: /tutorial_db/data_schema/tutorial_repository/my_echo_service_image:tutorial
         readinessProbe:
           port: 8000
           path: /healthcheck
       endpoints:
       - name: echoendpoint
         port: 8000
         public: true
     $$;
  

  Copy

• Créez un service en utilisant les informations de la zone de préparation. Lorsque vous déployez le service dans un environnement de production, il est conseillé d’appliquer le principe de séparation des préoccupations et de charger la spécification dans une zone de préparation, de fournir la commande CREATE SERVICE sur les informations de zone de préparation, comme indiqué :

  CREATE SERVICE echo_service
    IN COMPUTE POOL tutorial_compute_pool
    FROM @tutorial_stage
    SPECIFICATION_FILE='echo_spec.yaml';
  

  Copy

Exécuter un service de tâche¶

Utilisez EXECUTE JOB SERVICE pour créer un service de tâche. Cette commande s’exécute de manière synchrone et renvoie la réponse après la sortie de tous les conteneurs du service de tâche.

• Exécutez un service de tâche à l’aide d’une spécification en ligne :

  EXECUTE JOB SERVICE
     IN COMPUTE POOL tutorial_compute_pool
     NAME = example_job_service
     FROM SPECIFICATION $$
     spec:
       container:
       - name: main
         image: /tutorial_db/data_schema/tutorial_repository/my_job_image:latest
         env:
           SNOWFLAKE_WAREHOUSE: tutorial_warehouse
         args:
         - "--query=select current_time() as time,'hello'"
         - "--result_table=results"
     $$;
  

  Copy

• Exécutez un service de tâche en utilisant les informations de la zone de préparation :

  EXECUTE JOB SERVICE
    IN COMPUTE POOL tutorial_compute_pool
    NAME = example_job_service
    FROM @tutorial_stage
    SPECIFICATION_FILE='my_job_spec.yaml';
  

  Copy

Création de plusieurs instances de service et activation de la mise à l’échelle automatique¶

Par défaut, Snowflake exécute une instance du service dans le pool de calcul spécifié. Pour gérer des charges de travail importantes, vous pouvez exécuter plusieurs instances de service en définissant les propriétés MIN_INSTANCES et MAX_INSTANCES, qui spécifient le nombre minimum d’instances du service au début et le nombre maximum d’instances que Snowflake peut ajouter en cas de besoin.

Exemple

CREATE SERVICE echo_service
   IN COMPUTE POOL tutorial_compute_pool
   FROM @tutorial_stage
   SPECIFICATION_FILE='echo_spec.yaml'
   MIN_INSTANCES=2
   MAX_INSTANCES=4;

Lorsque plusieurs instances de service sont en cours d’exécution, Snowflake fournit automatiquement un équilibreur de charge pour répartir les requêtes entrantes.

Pour configurer Snowflake afin qu’il évalue automatiquement le nombre d’instances de service en cours d’exécution, procédez comme suit :

1. Spécifiez les exigences en matière de mémoire et de CPU pour votre instance de service dans le fichier de spécification du service. Pour plus d’informations, voir le champ container.resources.

   Exemple

   resources:
     requests:
      memory: <memory-reserved>
      cpu: <cpu-units>
   

   Copy

2. Lors de l’exécution de la commande CREATE SERVICE, définissez les paramètres MIN_INSTANCES et MAX_INSTANCES. Vous pouvez également utiliser ALTER SERVICE pour modifier ces valeurs. La mise à l’échelle automatique se produit lorsque MAX_INSTANCES est supérieur à MIN_INSTANCES.

Snowflake commence par créer le nombre minimum d’instances de service sur le pool de calcul spécifié. Snowflake utilise un seuil de 80 % (pour le CPU et la mémoire) afin d’augmenter ou de réduire le nombre d’instances de service. Snowflake surveille en permanence l’utilisation des ressources (mémoire ou CPU) dans le pool de calcul, en agrégeant les données d’utilisation de toutes les instances de service en cours d’exécution.

Lorsque l’utilisation agrégée des ressources (pour toutes les instances de service) dépasse 80 %, Snowflake déploie une instance de service supplémentaire dans le pool de calcul. Si l’utilisation des ressources agrégées tombe en dessous de 80 %, Snowflake procède à une diminution en supprimant une instance de service en cours d’exécution. Snowflake utilise une fenêtre de stabilisation de cinq minutes pour éviter les mises à l’échelle fréquentes.

Notez les comportements de mise à l’échelle suivants :

• La mise à l’échelle des instances de service est limitée par les paramètres MIN_INSTANCES et MAX_INSTANCES configurés pour le service.

• Si une mise à l’échelle est nécessaire et que les nœuds du pool de calcul n’ont pas la capacité de ressources nécessaire pour démarrer une autre instance de service, la mise à l’échelle automatique du pool de calcul peut être déclenchée. Pour plus d’informations, voir Mise à l’échelle automatique des nœuds d’un pool de calcul.

• Si vous spécifiez les paramètres MAX_INSTANCES et MIN_INSTANCES lors de la création d’un service, mais que vous ne spécifiez pas les exigences en matière de mémoire et de CPU pour votre instance de service dans le fichier de spécification du service, aucune mise à l’échelle automatique ne se produit ; Snowflake démarre avec le nombre d’instances spécifié par le paramètre MIN_INSTANCES et ne fera pas de mise à l’échelle automatique.

Utilisation de modèles de spécifications¶

Il peut arriver que vous souhaitiez créer plusieurs services en utilisant la même spécification, mais avec des configurations différentes. Par exemple, vous supposez que vous définissez une variable d’environnement dans une spécification de service et vous souhaitez créer plusieurs services en utilisant la même spécification mais des valeurs différentes pour la variable d’environnement.

La spécification de modèles vous permet de définir des variables pour des valeurs de champ dans la spécification. Lorsque vous créez un service, vous fournissez des valeurs pour ces variables.

L’utilisation des modèles de spécification se fait en deux étapes :

1. Créez une spécification en utilisant des variables comme valeurs pour les différents champs de la spécification. Utilisez la syntaxe {{ variable_name }} pour spécifier ces variables. Par exemple, la spécification suivante utilise une variable nommée « tag_name » pour le nom de la balise d’image, afin que vous spécifiiez une balise d’image différente pour chaque service.

   spec:
     containers:
     - name: echo
       image: myorg-myacct.registry.snowflakecomputing.com/tutorial_db/data_schema/tutorial_repository/my_echo_service_image:{{ tag_name }}
       ...
     endpoints:
     …
   

   Copy

2. Créez un service en fournissant le modèle de spécification dans une commande CREATE SERVICE. Vous utilisez SPECIFICATION_TEMPLATE ou SPECIFICATION_TEMPLATE_FILE pour spécifier le modèle. Utilisez le paramètre USING pour spécifier la valeur de la variable. Par exemple, l’instruction suivante utilise un modèle de spécification d’une zone de préparation Snowflake. Le paramètre USING définit la variable tag_name sur la valeur 'latest'.

   CREATE SERVICE echo_service
      IN COMPUTE POOL tutorial_compute_pool
      FROM @STAGE SPECIFICATION_TEMPLATE_FILE='echo.yaml'
      USING (tag_name=>'latest');
   

   Copy

USING( var_name=>var_value, [var_name=>var_value, ... ] );

Exemples¶

Ces exemples illustrent la création de services à l’aide de modèles de spécification. Les commandes CREATE SERVICE présentées dans ces exemples utilisent la spécification en ligne.

CREATE SERVICE echo_service
   IN COMPUTE POOL tutorial_compute_pool
   MIN_INSTANCES=1
   MAX_INSTANCES=1
   FROM SPECIFICATION_TEMPLATE $$
      spec:
         containers:
         - name: echo
           image: {{ image_url }}
           env:
             SERVER_PORT: {{SERVER_PORT}}
             CHARACTER_NAME: Bob
           readinessProbe:
             port: {{SERVER_PORT}}
             path: /healthcheck
         endpoints:
         - name: echoendpoint
           port: {{SERVER_PORT}}
           public: true
         $$
      USING (image_url=>' "/tutorial_db/data_schema/tutorial_repository/my_echo_service_image:latest" ', SERVER_PORT=>8000 );

spec:
  containers:
  - name: echo
    image: /tutorial_db/data_schema/tutorial_repository/my_echo_service_image:latest
    env:
      SERVER_PORT: 8000
      CHARACTER_NAME: Bob
    readinessProbe:
      port: 8000
      path: /healthcheck
    endpoints:
    - name: echoendpoint
      port: 8000
      public: true

spec:
 containers:
 - name: echo
   image: /tutorial_db/data_schema/tutorial_repository/my_echo_service_image:latest
   env:
     SERVER_PORT: 8000
     CHARACTER_NAME: Bob
   …

CREATE SERVICE echo_service
  IN COMPUTE POOL tutorial_compute_pool
  MIN_INSTANCES=1
  MAX_INSTANCES=1
  FROM SPECIFICATION_TEMPLATE $$
     spec:
       containers:
       - name: echo
         image: /tutorial_db/data_schema/tutorial_repository/my_echo_service_image:latest
         env: {{env_values}}
         readinessProbe:
           port: {{SERVER_PORT}}    #this and next tell SF to connect to port 8000
           path: /healthcheck
       endpoints:
       - name: echoendpoint
         port: {{SERVER_PORT}}
         public: true
        $$
     USING (env_values=>'{"SERVER_PORT": 8000, "CHARACTER_NAME": "Bob"}' );

spec:
  container:
  - name: main
    image: /tutorial_db/data_schema/tutorial_repository/my_job_image:latest
    env:
      SNOWFLAKE_WAREHOUSE: tutorial_warehouse
    args:
    - "--query=select current_time() as time,'hello'"
    - "--result_table=results"

spec:
  container:
  - name: main
    image: /tutorial_db/data_schema/tutorial_repository/my_job_image:latest
    env:
      SNOWFLAKE_WAREHOUSE: tutorial_warehouse
    args: {{ARGS}}
  $$
  USING (ARGS=$$["--query=select current_time() as time,'hello'", "--result_table=results"]$$ );

Résiliation du service¶

Lorsque vous suspendez un service (ALTER SERVICE … SUSPEND) ou supprimez un service (DROP SERVICE), Snowflake met fin à toutes les instances de service. De même, lorsque vous mettez à niveau le code de service (ALTER SERVICE … <fromSpecification>), Snowflake applique des mises à niveau progressives en mettant fin et en redéployant une instance de service à la fois.

Lors de la fin d’une instance de service, Snowflake envoie d’abord un signal SIGTERM à chaque conteneur de service. Le conteneur a la possibilité de traiter le signal et de s’arrêter correctement avec une fenêtre de 30 secondes. Sinon, après la période de grâce, Snowflake termine tous les processus du conteneur.

Mise à jour du code de service de redéploiement du service¶

Une fois qu’un service est créé, utilisez la commande ALTER SERVICE … <fromSpecification> pour mettre à jour le code du service et redéployer le service.

Vous chargez d’abord le code d’application modifié dans votre référentiel d’images, puis vous appelez ALTER SERVICE en fournissant la spécification du service, soit en ligne, soit en spécifiant le chemin d’accès à un fichier de spécification dans la zone de préparation Snowflake. Par exemple :

ALTER SERVICE echo_service
FROM SPECIFICATION $$
spec:
  …
  …
$$;

Dès réception de la requête, Snowflake redéploie le service en utilisant le nouveau code.

Lorsque vous exécutez la commande CREATE SERVICE … <from-Specification>, Snowflake enregistre la version spécifique de l’image fournie. Snowflake déploie cette même version d’image dans les scénarios suivants, même si l’image dans le référentiel a été mise à jour :

• Lorsqu’un service suspendu est repris (en utilisant ALTER SERVICE … RESUME).

• Lorsque la mise à l’échelle automatique ajoute davantage d’instances de service.

• Lorsque les instances de service sont redémarrées pendant la maintenance du cluster.

Mais si vous appelez ALTER SERVICE … <fromSpecification>, cela incite Snowflake à utiliser la dernière version du référentiel pour cette image.

Si vous êtes le propriétaire du service, la sortie de la commande DESCRIBE SERVICE inclut la spécification du service, qui inclut le condensé d’image (la valeur du champ sha256 dans la spécification), comme indiqué ci-dessous :

spec:
containers:
- name: "echo"
    image: "/tutorial_db/data_schema/tutorial_repository/my_echo_service_image:latest"
    sha256: "@sha256:8d912284f935ecf6c4753f42016777e09e3893eed61218b2960f782ef2b367af"
    env:
      SERVER_PORT: "8000"
      CHARACTER_NAME: "Bob"
    readinessProbe:
      port: 8000
      path: "/healthcheck"
endpoints:
- name: "echoendpoint"
    port: 8000
    public: true

ALTER SERVICE peut avoir un impact sur les communications (voir Utilisation d’un service) avec le service.

• Si ALTER SERVICE … <fromSpecification> supprime un point de terminaison ou supprime les autorisations pertinentes requises pour utiliser un point de terminaison (voir serviceRoles dans la référence de spécification), l’accès au service échouera. Pour plus d’informations, voir Utilisation d’un service.

• Pendant que la mise à niveau est en cours, de nouvelles connexions peuvent être acheminées vers la nouvelle version. Si la nouvelle version du service n’est pas rétrocompatible, elle perturbera toute utilisation active du service. Par exemple, les requêtes en cours utilisant une fonction de service peuvent échouer.

Accorder le privilège USAGE sur tous les points de terminaison utilisant le rôle de service par défaut¶

Lorsque vous créez un service (y compris un service de tâche), Snowflake crée également un rôle par défaut, nommé ALL_ENDPOINTS_USAGE. Ce rôle dispose du privilège USAGE sur tous les points de terminaison auxquels le service est exposé. Vous pouvez attribuer à d’autres rôles ce rôle par défaut à l’aide de la commande GRANT SERVICE ROLE :

GRANT SERVICE ROLE my_echo_service_image!ALL_ENDPOINTS_USAGE TO ROLE some_other_role;

Les utilisateurs qui utilisent some_other_role ont le privilège USAGE sur tous les points de terminaison de service.

Lorsque vous supprimez un service, Snowflake supprime tous les rôles de service (rôle par défaut et rôles de service définis dans la spécification de service) associés au service et annule toutes les autorisations de rôle de service.

Accorder le privilège USAGE sur des points de terminaison spécifiques à l’aide des rôles de service définis dans la spécification¶

Utilisez les rôles de service pour gérer l’accès affiné aux points de terminaison de service. Vous définissez les rôles de service, ainsi que la liste des points de terminaison auxquels ils accordent le privilège USAGE, dans la spécification de service.

L’octroi de privilèges sur des points de terminaison spécifiques d’un service se fait en deux étapes :

1. Définir un rôle de service : utilisez une spécification de service pour définir un rôle de service en fournissant un nom de rôle et une liste d’un ou plusieurs points de terminaison pour lesquels vous souhaitez accorder le privilège USAGE. Par exemple, dans le fragment de spécification suivant, le champ de premier niveau serviceRoles définit deux rôles de service, chacun ayant le privilège USAGE sur des points de terminaison spécifiques.

   spec:
   ...
   serviceRoles:                 # Optional list of service roles
   - name: <svc_role_name1>
     endpoints:                  # endpoints that role can access
     - <endpoint_name1>
     - <endpoint_name2>
   - name: <svc_role_name2>
     endpoints:
     - <endpoint_name3>
     - <endpoint_name4>
   

   Copy

2. Accordez le rôle de service à d’autres rôles. La commande GRANT SERVICE ROLE vous permet d’attribuer le rôle de service à d’autres rôles (rôles de compte, d’application ou de base de données). Par exemple :

   GRANT SERVICE ROLE <service-name>!<svc_role_name1> TO ROLE <another-role>
   

   Copy

Fonctions de service : utilisation d’un service à partir d’une requête SQL¶

Une fonction de service est une fonction définie par l’utilisateur (UDF) que vous créez à l’aide de CREATE FUNCTION (Snowpark Container Services). Cependant, au lieu d’écrire directement le code de l’UDF, vous associez l’UDF à votre point de terminaison de service. Notez que vous ne pouvez associer une fonction de service qu’à un point de terminaison de service prenant en charge le protocole HTTP ou HTTPS.

Par exemple, dans le tutoriel 1, vous créez un service nommé echo_service qui expose un point de terminaison (echoendoint) tel que défini dans la spécification du service :

spec:
…
  endpoints:
  - name: echoendpoint
    port: 8080

echoendpoint est un nom de point de terminaison convivial qui représente le port correspondant (8080). Pour communiquer avec ce point de terminaison de service, vous créez une fonction de service en fournissant les paramètres SERVICE et ENDPOINT comme indiqué :

CREATE FUNCTION my_echo_udf (text varchar)
   RETURNS varchar
   SERVICE=echo_service
   ENDPOINT=echoendpoint
   AS '/echo';

Le paramètre AS fournit le chemin HTTP vers le code de service. Vous obtenez cette valeur de chemin à partir du code du service. Par exemple, les lignes de code suivantes proviennent de service.py dans Tutoriel 1.

@app.post("/echo")
def echo():
...

Lorsque vous invoquez la fonction de service, Snowflake dirige la requête vers le point de terminaison et le chemin du service associé.

ALTER FUNCTION my_echo_udf(VARCHAR)
   SET SERVICE=other_service
   ENDPOINT=otherendpoint
   MAX_BATCH_ROWS=100

"Alex", "2014-01-01 16:00:00"
"Steve", "2015-01-01 16:00:00"
…

SELECT service_func(col1, col2) FROM input_table;

{
   "data":[
      [
         0,
         "Alex",
         "2014-01-01 16:00:00"
      ],
      [
         1,
         "Steve",
         "2015-01-01 16:00:00"
      ],
      …
      [
         <row_index>,
         "<column1>",
         "<column2>"
      ],
   ]
}

{
   "data":[
      [0, "a"],
      [1, "b"],
      …
      [ row_index,  output_column1]
   ]
}

USE ROLE service_owner;
GRANT USAGE ON service service_db.my_schema.my_service TO ROLE func_owner;

USE ROLE func_owner;
CREATE OR REPLACE test_udf(v VARCHAR)
  RETURNS VARCHAR
  SERVICE=service_db.my_schema.my_service
  ENDPOINT=endpointname1
  AS '/run';

SELECT test_udf(col1) FROM some_table;

ALTER FUNCTION test_udf(VARCHAR) SET
  SERVICE = service_db.other_schema.other_service
  ENDPOINT=anotherendpoint;

GRANT USAGE ON FUNCTION test_udf(varchar) TO ROLE func_user;
USE ROLE func_user;
SELECT my_test_udf('abcd');

Entrée : utilisation d’un service en dehors de Snowflake¶

Un service peut exposer un ou plusieurs points de terminaison comme étant publics pour permettre aux utilisateurs d’utiliser le service à partir du Web public. Dans ce cas, Snowflake gère le contrôle d’accès. Remarque : l’entrée n’est autorisée qu’avec les points de terminaison HTTP ou HTTPS.

Marquez le point de terminaison comme public dans votre fichier de spécification de service :

spec
  ...
  endpoints
  - name: <endpoint name>
    port: <port number>
    public: true

Communications de service à service¶

Les services peuvent communiquer entre eux en utilisant le nom DNS que Snowflake attribue automatiquement à chaque service. Pour un exemple, voir le tutoriel 3. Notez que si un point de terminaison de service est créé uniquement pour autoriser les communications de service à service, le protocole TCP doit être utilisé.

Le format du nom DNS est le suivant :

<service-name>.<schema-name>.<db-name>.snowflakecomputing.internal

Utilisez SHOW SERVICES (ou DESCRIBE SERVICE) pour obtenir le nom DNS d’un service. Le nom DNS qui précède est un nom complet. Les services créés dans le même schéma peuvent communiquer en utilisant uniquement <service-name>. Les services qui se trouvent dans la même base de données, mais dans des schémas différents doivent fournir le nom du schéma, par exemple <service-name>.<schema-name>.

Snowflake autorise les communications réseau entre les services créés par le même rôle et bloque les communications réseau entre les services créés par des rôles différents. Si vous souhaitez empêcher vos services de communiquer entre eux (pour des raisons de sécurité, par exemple), utilisez différents rôles Snowflake pour créer ces services.

Les noms DNS présentent les limitations suivantes :

• Les noms de votre base de données, de votre schéma ou de votre service doivent être des étiquettes DNS valides. (Voir aussi https://www.ietf.org/rfc/rfc1035.html#section-2.3.1). Sinon, la création d’un service échouera.

• Snowflake remplace le trait de soulignement (_) dans les noms (base de données, schéma et nom de service) par un tiret (-) dans le nom DNS.

• Après avoir créé un service, ne modifiez pas le nom de la base de données ou du schéma, car Snowflake ne mettra pas à jour le nom DNS du service.

• Un nom DNS est uniquement destiné aux communications internes au sein de Snowflake entre les services fonctionnant dans le même compte. Il n’est pas accessible depuis Internet.