Référence Spécification de service¶

Lignes directrices générales¶

Une spécification de service/tâche comporte ces champs spec de premier niveau :

• spec.containers (obligatoire) : une liste d’un ou plusieurs conteneurs d’application. Votre application conteneurisée doit avoir au moins un conteneur.

• spec.endpoints (facultatif) : une liste de points de terminaison que le service expose. Vous pouvez choisir un point de terminaison public, permettant l’accès au service par le réseau.

• spec.volumes (facultatif) : une liste de volumes de stockage à utiliser par les conteneurs.

• spec.logExporters (facultatif) : ce champ permet de gérer le niveau des journaux de conteneurs exportés vers la table d’événements de votre compte.

Les règles de format suivantes s’appliquent aux champs name (noms de conteneurs, de points de terminaison et de volumes) :

• Peut contenir jusqu’à 63 caractères

• Peut contenir une séquence de caractères alphanumériques minuscules ou « - ».

• Doit commencer par un caractère alphabétique

• Doit se terminer par un caractère alphanumérique

Les sections suivantes expliquent chacun des champs spec de premier niveau.

Champ spec.containers (obligatoire)¶

Le champ containers est une liste de conteneurs OCI dans votre application. Pour chaque conteneur, seuls name et image sont des champs obligatoires. Le champ image fait référence au nom de l’image que vous avez chargée dans un référentiel d’images Snowflake dans votre compte Snowflake. Par exemple :

spec:
  containers:
    - name: echo
      image: /tutorial_db/data_schema/tutorial_repository/echo_service:dev

Lorsque vous créez un service (ou une tâche), Snowflake exécute ces conteneurs sur un seul nœud dans le pool de calcul spécifié, en partageant la même interface réseau. Vous pouvez exécuter plusieurs instances de service ; dans ce cas, chaque ensemble de ces conteneurs en cours d’exécution est appelé Instance de service.

Les sections suivantes expliquent les types de champs containers.

ENTRYPOINT ["python3", "main.py"]
CMD ["Bob"]

spec:
  containers:
  - name: <name>
    image: <image_name>
    env:
      ENV_VARIABLE_1: <value1>
      ENV_VARIABLE_2: <value2>
      …
      …

CHARACTER_NAME = os.getenv('CHARACTER_NAME', 'I')
SERVER_PORT = os.getenv('SERVER_PORT', 8080)

spec:
  containers:
  - name: echo
    image: <image_name>
    env:
      CHARACTER_NAME: Bob
      SERVER_PORT: 8085
  endpoints:
  - name: echo-endpoint
    port: 8085

@app.get("/healthcheck")
def readiness_probe():

spec:
  containers:
  - name: echo
    image: <image_name>
    env:
      SERVER_PORT: 8088
      CHARACTER_NAME: Bob
    readinessProbe:
      port: 8088
      path: /healthcheck
  endpoints:
  - name: echo-endpoint
    port: 8088

spec:
  containers:
  - name: resource-test-gpu
    image: ...
    resources:
      requests:
        memory: 2G
        cpu: 0.5
        nvidia.com/gpu: 1
      limits:
        memory: 4G
        nvidia.com/gpu: 1

secrets:                            # optional list
  - snowflakeSecret:
    secretKeyRef:
    envVarName:                      # specify this or directoryPath
    directoryPath:                   # specify this or envVarName

Champ spec.endpoints (facultatif)¶

Utilisez le champ spec.endpoints pour spécifier une liste de noms pour les ports réseau TCP que votre application expose. Snowpark Container Services peut exposer zéro à de nombreux points de terminaison. Utilisez les champs suivants pour décrire un point de terminaison :

• name : nom unique du point de terminaison. Lorsque vous faites référence au point de terminaison dans une fonction de service, vous spécifiez ce nom.

• port : le port réseau sur lequel votre application écoute.

• protocol : protocole pris en charge par le point de terminaison. Les valeurs prises en charge sont TCP, HTTP et HTTPS. Par défaut, le protocole est HTTP. Le protocole doit être HTTP ou HTTPS lorsque ce point de terminaison est public ou la cible d’une fonction de service (voir Utilisation d’un service).

• public : si vous souhaitez que ce point de terminaison soit accessible depuis Internet, définissez ce champ sur true.

Exemple

Voici la spécification de l’application utilisée dans le tutoriel 1 :

spec:
  container:
  - name: echo
    image: <image-name>
    env:
      SERVER_PORT: 8000
      CHARACTER_NAME: Bob
    readinessProbe:
      port: 8000
      path: /healthcheck
  endpoint:
  - name: echoendpoint
    port: 8000
    public: true

Ce conteneur d’application expose un point de terminaison. Il comprend également le champ facultatif public pour permettre l’accès au point de terminaison depuis l’extérieur de Snowflake (accès Internet). Par défaut, public est false.

Champ spec.volumes (facultatif)¶

Cette section explique les champs spec.volumes et spec.containers.volumeMounts. volumes définit un système de fichiers partagé. Un volumeMount définit l’endroit où un volume apparaît dans un conteneur. Plusieurs conteneurs peuvent partager le même volume. Par conséquent, volumes est un champ de niveau spec, et volumeMount fait partie d’une spécification de conteneur.

Utilisez ces champs pour décrire les volumes et les montages de volumes.

• Utilisez spec.volumes pour spécifier les volumes disponibles pour vos conteneurs. volumes est une liste. En d’autres termes, il peut y avoir plusieurs volumes. Utilisez les champs suivants pour décrire un volume :

  • name : nom unique du volume. Il est désigné par spec.containers.volumeMounts.name.

  • source : il peut s’agir de local, memory ou "@<stagename>".

  • uid : pour un volume de zone de préparation Snowflake, il s’agit de l’uid du fichier monté.

  • gid : pour un volume de zone de préparation Snowflake, il s’agit du gid du fichier monté.

  • size : pour un volume de mémoire, il s’agit de la taille du volume.

• Utilisez spec.containers.volumeMounts pour indiquer où les volumes spécifiés sont montés dans le système de fichiers du conteneur. containers.volumeMounts est également une liste. En d’autres termes, chaque conteneur peut avoir plusieurs montages de volumes. Utilisez les champs suivants pour décrire un montage de volume :

  • name : nom du volume à monter. Un même conteneur peut faire plusieurs fois référence au même volume.

  • mountPath : le chemin d’accès au fichier où le volume du conteneur doit être monté.

Snowflake prend en charge les types de volumes suivants pour les conteneurs d’application : volumes locaux, mémoire et zone de préparation Snowflake.

• Volume local : les conteneurs d’une instance de service peuvent utiliser un disque local pour partager des fichiers. Par exemple, si votre application comporte deux conteneurs, un conteneur d’application et un analyseur de journaux, l’application peut écrire des journaux sur le volume local et l’analyseur de journaux peut lire les journaux.

  Notez que, si vous exécutez plusieurs instances d’un service, seuls les conteneurs appartenant à une instance de service peuvent partager des volumes. Les conteneurs qui appartiennent à des instances de service différentes ne partagent pas de volumes.

• Mémoire : vous pouvez utiliser un système de fichiers RAM pour les conteneurs.

• Zone de préparation Snowflake : vous pouvez créer une zone de préparation Snowflake et donner aux conteneurs un accès pratique aux fichiers en zone de préparation. Les conditions suivantes s’appliquent lorsque vous montez une zone de préparation Snowflake :

  • Les zones de préparation externes ne sont pas prises en charge. Seuls les zones de préparation internes Snowflake avec chiffrement SSE sont prises en charge. Utilisez CREATE STAGE pour créer une telle zone de préparation :

    CREATE STAGE my_stage ENCRYPTION = (type = 'SNOWFLAKE_SSE');
    

    Copy

  • Vous pouvez monter une zone de préparation ou un sous-répertoire, par exemple @my_stage, @my_stage/folder, dans une zone de préparation. Vous ne pouvez pas monter un fichier, par exemple @my_stage/folder/file, dans une zone de préparation.

  • Le rôle de service détermine les permissions accordées aux conteneurs pour accéder à une zone de préparation montée. Le rôle de service est le rôle utilisé pour créer le service/la tâche. C’est également le rôle que le service/la tâche utilise pour toutes les interactions avec Snowflake.

    Par exemple, si le rôle de service n’a pas le privilège WRITE sur une zone de préparation, le montage de cette zone de préparation sera en lecture seule. En d’autres termes, les conteneurs ne peuvent lire que les fichiers de la zone de préparation. Si le rôle de service dispose du privilège WRITE sur une zone de préparation, le montage de cette zone de préparation prendra en charge la lecture et l’écriture. Snowflake télécharge les mises à jour de fichiers de manière asynchrone.

  • Un conteneur qui monte une zone de préparation Snowflake s’exécute généralement en tant qu’utilisateur root. Cependant, il peut arriver que votre conteneur s’exécute en tant qu’utilisateur non root. Par exemple :

    • Si votre application utilise une bibliothèque tierce, celle-ci utilise un utilisateur non root pour exécuter le code de l’application à l’intérieur du conteneur.

    • Pour d’autres raisons, telles que la sécurité, vous pouvez exécuter votre application en tant qu’utilisateur non root à l’intérieur du conteneur.

      Afin d’éviter les erreurs potentielles liées aux autorisations des utilisateurs de fichiers, il est important de définir les UID (Utilisateur ID) et GID (Groupe ID) du conteneur dans le cadre de la spécification. Ceci est particulièrement important pour les conteneurs qui utilisent un utilisateur et un groupe spécifiques pour lancer ou exécuter l’application dans le conteneur. En définissant les paramètres UID et GID appropriés, vous pouvez utiliser un conteneur fonctionnant en tant qu’utilisateur non root. Par exemple :

      spec:
        ...
      
        volumes:
        - name: stagemount
          source: "@test"
          uid: <UID-value>
          gid: <GID-value>
      

      Copy

      Snowflake utilise ces informations pour monter la zone de préparation avec les permissions appropriées.

      Obtenir les UID et GID du conteneur :

      1. Exécutez le conteneur localement en utilisant docker run.

      2. Recherchez l’ID du conteneur à l’aide de la commande docker container list. Exemple de sortie partielle :

         CONTAINER ID   IMAGE                       COMMAND
         —----------------------------------------------------------
         a6a1f1fe204d  tutorial-image         "/usr/local/bin/entr…"
         

      3. Exécutez la commande docker id à l’intérieur du conteneur pour obtenir les UID et GID :

         docker exec -it <container-id> id
         

         Copy

         Exemple de sortie :

         uid=0(root) gid=0(root) groups=0(root)
         

Exemple

Votre application de machine learning comprend les deux conteneurs suivants :

• Un conteneur app pour l’application principale

• Un conteneur logger-agent qui collecte les journaux et les charge sur Amazon S3

Ces conteneurs utilisent les deux volumes suivants :

• Volume local : cette application écrit les journaux que l’agent de journalisation lit.

• Zone de préparation Snowflake, @model_stage : l’application principale lit les fichiers de cette zone de préparation.

Dans l’exemple de spécification suivant, le conteneur app monte les volumes logs et models, et le conteneur logging-agent ne monte que le volume logs :

spec:
  containers:
  - name: app
    image: <image1-name>
    volumeMounts:
    - name: logs
      mountPath: /opt/app/logs
    - name: models
      mountPath: /opt/models
  - name: logging-agent
    image: <image2-name>
    volumeMounts:
    - name: logs
      mountPath: /opt/logs
  volumes:
  - name: logs
    source: local
  - name: models
    source: "@model_stage"

Copy

Si plusieurs instances du service sont en cours d’exécution, les conteneurs logging-agent et app d’une instance de service partagent le volume logs. Le volume logs n’est pas partagé entre les instances de service.

Si, en plus de ces volumes, votre conteneur app utilise également un volume de mémoire à 2 GB, vérifiez la spécification pour inclure le volume dans la liste volumes et ajoutez également un autre montage de volume dans la liste volumeMounts des conteneurs app :

spec:
  containers:
  - name: app
    image: <image1-name>
    volumeMounts:
    - name: logs
      mountPath: /opt/app/logs
    - name: models
      mountPath: /opt/models
    - name: my-mem-volume
      mountPath: /dev/shm
  - name: logging-agent
    image: <image2-name>
    volumeMounts:
    - name: logs
      mountPath: /opt/logs
  volumes:
  - name: logs
    source: local
  - name: models
    source: "@model_stage"
  - name: "my-mem-volume"
    source: memory
    size: 2G

Copy

Notez que lorsque vous spécifiez memory comme étant la source du volume, vous devez également spécifier le champ volumes.size pour indiquer la taille de la mémoire. Pour plus d’informations sur les unités de taille de mémoire que vous pouvez spécifier, voir À propos des unités.

Champ spec.logExporters (facultatif)¶

Utilisez spec.logExporters pour configurer la façon dont Snowflake collecte vos journaux d’application. Snowflake collecte la sortie de votre code dans votre conteneur d’application vers la sortie standard ou l’erreur standard.

Snowflake exporte ces journaux vers une table d’événements dans votre compte. Pour plus d’informations, voir Accès aux journaux des conteneurs locaux. Utilisez les spec.logExporters.eventTableConfig pour indiquer les journaux que vous souhaitez enregistrer dans la table d’événements :

logExporters:
  eventTableConfig:
    logLevel: < INFO | ERROR | NONE >

Les valeurs logLevel prises en charge sont les suivantes :

• INFO : exporter tous les journaux des utilisateurs.

• ERROR : exporter uniquement les journaux d’erreurs. Snowflake n’exporte que les journaux du flux stderr.

• NONE (par défaut) : ne pas exporter les journaux dans la table d’événements.

À propos des unités¶

Une spécification de service prend des valeurs numériques à plusieurs endroits. Snowpark Container Services prend en charge une variété d’unités pour exprimer ces valeurs. Pour les grandes et les petites valeurs, vous pouvez utiliser les unités binaires et décimales comme indiqué. Dans la liste suivante, « # » représente une valeur entière.

• Unités binaires :

  • numberKi signifie number*1024. Par exemple, memory: 4Ki est équivalent à memory: 4096.

  • numberMi signifie number*1024^2.

  • numberGi signifie number*1024^3.

• Unités décimales :

  • numberk signifie number*10^3. Par exemple, memory: 4k est équivalent à memory: 4000.

  • numberM signifie number*10^6.

  • numberG signifie number*10^9

• Unités fractionnaires :

  • numberm signifie number*0.001. Par exemple, cpu: 500m est équivalent à cpu: 0.5.