Snowpark Container Services : considérations supplémentaires pour les services et les tâches¶

Connexion à Snowflake¶

Snowflake fournit les variables d’environnement suivantes pour vous permettre de configurer un client Snowflake dans le code de votre service/tâche :

• SNOWFLAKE_ACCOUNT : fournit le nom du compte Snowflake sous lequel le service est actuellement exécuté.

• SNOWFLAKE_HOST : fournit le nom d’hôte utilisé pour se connecter à Snowflake.

Snowflake fournit également un jeton OAuth dans le conteneur dans un fichier nommé /snowflake/session/token. Lors de la création d’une connexion, vous fournissez ce jeton au connecteur.

Lorsque vous créez une connexion à Snowflake à partir d’un conteneur, vous devez utiliser les jetons SNOWFLAKE_HOST, SNOWFLAKE_ACCOUNT et OAuth. Vous ne pouvez pas utiliser le jeton OAuth sans utiliser également SNOWFLAKE_HOST, et vous ne pouvez pas utiliser le jeton OAuth en dehors de Snowpark Container Services. Pour plus d’informations, voir Utilisation d’un jeton OAuth pour exécuter SQL.

Exemples

• Dans le tutoriel 2 (voir main.py), le code lit les variables d’environnement comme suit :

  SNOWFLAKE_ACCOUNT = os.getenv('SNOWFLAKE_ACCOUNT')
  SNOWFLAKE_HOST = os.getenv('SNOWFLAKE_HOST')
  

  Copy

  Le code transmet ces variables à un code de création de connexion pour le client Snowflake choisi. Le conteneur utilise ces identifiants de connexion pour créer une nouvelle session, avec le rôle de service comme rôle principal, afin d’exécuter des requêtes. L’exemple de code suivant est le minimum requis pour créer une connexion Snowflake en Python :

  def get_login_token():
    with open('/snowflake/session/token', 'r') as f:
      return f.read()
  
  conn = snowflake.connector.connect(
    host = os.getenv('SNOWFLAKE_HOST'),
    account = os.getenv('SNOWFLAKE_ACCOUNT'),
    token = get_login_token(),
    authenticator = 'oauth'
  )
  

  Copy

• Lorsque vous utilisez l’hôte par défaut (c’est-à-dire que vous n’incluez pas l’argument host lors de la création d’une connexion), la connexion à Snowflake en utilisant d’autres formes d’authentification (telles que le nom d’utilisateur et le mot de passe) est prise en charge. Par exemple, la connexion suivante spécifie le nom d’utilisateur et le mot de passe pour l’authentification :

  conn = snowflake.connector.connect(
    account = os.getenv('SNOWFLAKE_ACCOUNT'),
    user = '<user-name>',
    password = <password>
  )
  

  Copy

  L’utilisation d’un hôte par défaut nécessite l’intégration d’accès externe avec une règle de réseau permettant l’accès de votre service au nom d’hôte Snowflake pour votre compte. Par exemple, si le nom de votre compte est MyAccount, le nom d’hôte sera moncompte.snowflakecomputing.com. Pour plus d’informations, voir Sortie réseau.

  • Créez une règle de réseau qui correspond au nom d’hôte d’API Snowflake de votre compte :

    CREATE OR REPLACE NETWORK RULE snowflake_egress_access
      MODE = EGRESS
      TYPE = HOST_PORT
      VALUE_LIST = ('myaccount.snowflakecomputing.com');
    

    Copy

  • Créez une intégration à l’aide de la règle de réseau précédente :

    CREATE EXTERNAL ACCESS INTEGRATION snowflake_egress_access_integration
      ALLOWED_NETWORK_RULES = (snowflake_egress_access)
      ENABLED = true;
    

    Copy

Configuration de la base de données et du contexte du schéma pour l’exécution de SQL¶

Cette section présente deux concepts :

• La logique utilisée par Snowflake pour déterminer la base de données et le schéma dans lesquels créer votre service/tâche.

• La méthode par laquelle Snowflake transmet cette information à vos conteneurs, permettant ainsi au code du conteneur d’exécuter SQL dans le même contexte de base de données et de schéma.

Snowflake utilise la logique suivante pour déterminer la base de données et le schéma dans lesquels créer un service/une tâche :

• Pour un service, Snowflake utilise le nom du service fourni dans la commande CREATE SERVICE afin de déterminer la base de données et le contexte du schéma pour le service :

  • Exemple 1 : la commande CREATE SERVICE suivante spécifie test_service comme nom de service :

    CREATE SERVICE test_service IN COMPUTE POOL ...
    

    Copy

    Snowflake place ce service dans la base de données et le schéma actuels.

  • Exemple 2 : la commande CREATE SERVICE suivante spécifie un nom de service entièrement qualifié :

    CREATE SERVICE test_db.test_schema.test_service IN COMPUTE POOL ...
    

    Copy

    Snowflake place le service dans la base de données (test_db) et le schéma (test_schema) spécifiés, quel que soit le schéma actuel.

• Pour une tâche, vous n’indiquez pas de nom de travail lorsque vous créez une tâche à l’aide de la commande EXECUTE SERVICE :

  EXECUTE SERVICE IN COMPUTE POOL ..
  

  Copy

  Dans ce cas, vous n’avez pas la possibilité de placer la tâche n’importe où. Par conséquent, Snowflake place la tâche dans la base de données et le schéma actuels. Si vous souhaitez qu’une tâche exécute des instructions SQL dans différents schémas, vous pouvez la lancer en utilisant différents contextes de schéma. Par exemple :

  USE ROLE test_role;
  USE DATABASE tutorial_db;
  
  USE SCHEMA schema1;
  -- Execute using tutorial_db and schema1
  EXECUTE SERVICE IN COMPUTE POOL ...
  
  USE SCHEMA schema2;
  -- execute service again, using schema2
  EXECUTE SERVICE IN COMPUTE POOL ...
  

  Copy

Lorsque Snowflake démarre un service/une tâche, Snowflake fournit les informations relatives à la base de données et au schéma aux conteneurs en cours d’exécution en utilisant les variables d’environnement suivantes :

• SNOWFLAKE_DATABASE

• SNOWFLAKE_SCHEMA

Le code de votre conteneur peut utiliser des variables d’environnement dans le code de connexion pour déterminer la base de données et le schéma à utiliser, comme le montre cet exemple :

conn = snowflake.connector.connect(
  host = os.getenv('SNOWFLAKE_HOST'),
  account = os.getenv('SNOWFLAKE_ACCOUNT'),
  token = get_login_token(),
  authenticator = 'oauth',
  database = os.getenv('SNOWFLAKE_DATABASE'),
  schema = os.getenv('SNOWFLAKE_SCHEMA')
)

Exemple

Dans le tutoriel 2, vous créez une tâche Snowflake qui se connecte à Snowflake et exécute des instructions SQL. Les étapes suivantes résument la manière dont le code du tutoriel utilise les variables d’environnement :

1. Dans la configuration commune (voir la section Configuration commune), vous créez des ressources, notamment une base de données et un schéma. Vous définissez également la base de données et le schéma actuels pour la session :

   USE DATABASE tutorial_db;
   ...
   USE SCHEMA data_schema;
   

   Copy

2. Après avoir créé une tâche (exécution de EXECUTE SERVICE), Snowflake démarre le conteneur et définit les variables d’environnement suivantes dans le conteneur en fonction de la base de données et du schéma actuels de la session :

   • SNOWFLAKE_DATABASE est défini sur « TUTORIAL_DB »

   • SNOWFLAKE_SCHEMA est défini sur « DATA_SCHEMA »

3. Le code de la tâche (voir main.py dans le tutoriel 2) lit ces variables d’environnement :

   SNOWFLAKE_DATABASE = os.getenv('SNOWFLAKE_DATABASE')
   SNOWFLAKE_SCHEMA = os.getenv('SNOWFLAKE_SCHEMA')
   

   Copy

4. Le code de la tâche définit la base de données et le schéma comme le contexte dans lequel exécuter les instructions SQL (fonction run_job() dans main.py) :

   {
      "account": SNOWFLAKE_ACCOUNT,
      "host": SNOWFLAKE_HOST,
      "authenticator": "oauth",
      "token": get_login_token(),
      "warehouse": SNOWFLAKE_WAREHOUSE,
      "database": SNOWFLAKE_DATABASE,
      "schema": SNOWFLAKE_SCHEMA
   }
   ...
   

   Copy

Utilisation d’un jeton OAuth pour exécuter SQL¶

Tous les clients fournis par Snowflake prennent en charge OAuth comme moyen d’authentification. Les conteneurs de services/tâches utilisent également le mécanisme OAuth pour s’authentifier auprès de Snowflake. Par exemple, lorsqu’un conteneur veut exécuter SQL, il crée une connexion à Snowflake, comme n’importe quel autre client Snowflake :

def get_login_token():
  with open('/snowflake/session/token', 'r') as f:
    return f.read()

conn = snowflake.connector.connect(
  host = os.getenv('SNOWFLAKE_HOST'),
  account = os.getenv('SNOWFLAKE_ACCOUNT'),
  token = get_login_token(),
  authenticator = 'oauth'
)

Lorsque vous créez un service/une tâche, Snowflake exécute les conteneurs et fournit un jeton Oauth pour les conteneurs à utiliser à l’emplacement suivant dans le conteneur : /snowflake/session/token.

Notez les détails suivants concernant ce jeton OAuth :

• Vous devez lire le contenu du fichier /snowflake/session/token immédiatement avant de l’utiliser, car le contenu expire au bout de 10 minutes, et Snowflake actualise ce fichier toutes les quelques minutes. Une fois qu’un conteneur s’est connecté avec succès à Snowflake, le délai d’expiration ne s’applique pas à la connexion (comme pour les sessions créées directement par les utilisateurs).

• Ce jeton OAuth n’est valable que pour la tâche ou le service Snowflake concerné. Vous ne pouvez pas copier le jeton OAuth et l’utiliser en dehors du service/de la tâche.

• En utilisant le jeton OAuth, les conteneurs se connectent à Snowflake en tant qu’utilisateur et rôle du service/de la tâche comme suit :

  • L’utilisateur est la personne qui a créé le service/la tâche.

  • Le rôle est le rôle de service pour le service/la tâche, et c’est le seul rôle pris en charge. Vous ne pouvez pas modifier le rôle.

• L’utilisation du jeton OAuth pour se connecter créera une nouvelle session. Le jeton OAuth n’est associé à aucune session SQL existante.

  Note

  Une différence importante entre l’exécution de procédures stockées et l’exécution d’un service/d’une tâche est que les procédures stockées s’exécutent dans la même session que le SQL qui les exécute. Mais chaque fois qu’un conteneur établit une nouvelle connexion, vous créez une nouvelle session.

Entrée réseau¶

Pour permettre à quiconque d’interagir avec votre service depuis Internet, vous déclarez les ports réseau sur lesquels votre service écoute en tant que points de terminaison dans le fichier de spécification du service. Ces points de terminaison contrôlent l’entrée.

Par défaut, les points de terminaison de service sont privés. Seules les fonctions de service et les communications de service à service peuvent adresser des requêtes aux points de terminaison privés. Vous pouvez déclarer un point de terminaison comme étant public afin d’autoriser les requêtes vers un point de terminaison depuis Internet. Le rôle qui crée le service (avec un point de terminaison public) doit avoir le privilège BIND SERVICE ENDPOINT sur le compte.

endpoints:
- name: <endpoint name>
  port: <port number>
  protocol : < TCP / HTTP / HTTPS >
  public: true

Pour un exemple, voir le tutoriel 1.

Sortie réseau¶

Le code de votre application (tâche ou service) peut nécessiter un accès à Internet. Par défaut, les conteneurs d’application n’ont pas la permission d’accéder à Internet. Vous devez activer l’accès à Internet en utilisant les intégrations d’accès externe (EAIs).

En règle générale, vous souhaitez qu’un administrateur de compte crée des EAIs pour gérer l’accès externe autorisé à partir des tâches et des services. Les administrateurs de comptes peuvent alors accorder l’utilisation d’EAI à des rôles spécifiques que les développeurs utilisent pour exécuter des tâches ou des services.

L’exemple suivant décrit les étapes de la création d’une EAI qui autorise le trafic de sortie vers des destinations spécifiques spécifiées à l’aide de règles de réseau. Vous vous référez ensuite au EAI lorsque vous créez une tâche ou un service pour autoriser des requêtes vers des destinations Internet spécifiques.

Exemple

Supposons que vous souhaitiez que le code de votre application (tâche ou service) envoie des requêtes aux destinations suivantes :

• Requêtes HTTPS vers translation.googleapis.com

• Requêtes HTTP et HTTPS vers google.com

Suivez ces étapes pour permettre à votre tâche ou service d’accéder à ces domaines sur Internet :

1. Créez une intégration d’accès externe (EAI). Pour ce faire, il faut disposer des autorisations nécessaires. Par exemple, vous pouvez utiliser le rôle ACCOUNTADMIN pour créer une EAI. Il s’agit d’un processus en deux étapes :

   1. Utilisez la commande CREATE NETWORK RULE pour créer une ou plusieurs règles de réseau de sortie répertoriant les destinations externes auxquelles vous souhaitez autoriser l’accès. Vous pouvez réaliser cet exemple avec une seule règle de réseau, mais pour l’illustration, nous créons deux règles de réseau :

      1. Créez une règle de réseau nommée translate_network_rule :

         CREATE OR REPLACE NETWORK RULE translate_network_rule
           MODE = EGRESS
           TYPE = HOST_PORT
           VALUE_LIST = ('translation.googleapis.com');
         

         Copy

         Cette règle autorise les connexions TCP vers la destination translation.googleapis.com. Le domaine dans la propriété VALUE_LIST ne spécifie pas le numéro de port optionnel, de sorte que le port par défaut 443 (HTTPS) est supposé. Cela permet à votre application de se connecter à n’importe quelle URL qui commence par https://translation.googleapis.com/.

      2. Créez une règle de réseau nommée google_network_rule :

         CREATE OR REPLACE NETWORK RULE google_network_rule
           MODE = EGRESS
           TYPE = HOST_PORT
           VALUE_LIST = ('google.com:80', 'google.com:443');
         

         Copy

         Cela permet à votre application de se connecter à n’importe quelle URL qui commence par http://google.com/ ou https://google.com/.

      Snowpark Container Services ne prend en charge que les règles de réseau qui autorisent les ports 22, 80, 443 et 1024+. Si une règle de réseau référencée autorise l’accès à d’autres ports, la création du service échouera. Contactez votre représentant de compte si vous avez besoin d’utiliser des ports supplémentaires.

      Note

      Pour permettre à votre tâche ou service d’envoyer des requêtes HTTP ou HTTPS à n’importe quelle destination sur Internet, vous spécifiez « 0.0.0.0 » comme domaine dans la propriété VALUE_LIST. La règle de réseau suivante permet d’envoyer des requêtes « HTTP » et « HTTPS » n’importe où sur Internet. Seuls les ports 80 ou 443 sont pris en charge avec « 0.0.0.0 ».

      CREATE NETWORK RULE allow_all_rule
        TYPE = 'HOST_PORT'
        MODE= 'EGRESS'
        VALUE_LIST = ('0.0.0.0:443','0.0.0.0:80');
      

      Copy

   2. Créez une intégration d’accès externe (EAI) qui spécifie que les deux règles de réseau de sortie précédentes sont autorisées :

      CREATE EXTERNAL ACCESS INTEGRATION google_apis_access_integration
        ALLOWED_NETWORK_RULES = (translate_network_rule, google_network_rule)
        ENABLED = true;
      

      Copy

      L’administrateur du compte peut désormais accorder l’utilisation de l’intégration aux développeurs pour leur permettre d’exécuter une tâche/un service qui peut accéder à des destinations spécifiques sur Internet.

      GRANT USAGE ON INTEGRATION google_apis_access_integration TO ROLE test_role;
      

      Copy

2. Créez le service ou la tâche en fournissant l’EAI comme indiqué dans les exemples suivants. Le rôle qui crée le service ou la tâche a besoin du privilège d’utilisation sur l’EAI et du privilège de lecture sur les secrets référencés. Notez que vous ne pouvez pas utiliser le rôle ACCOUNTADMIN pour créer un service ou une tâche.

   • Créez un service :

     USE ROLE test_role;
     
     CREATE SERVICE eai_service
       IN COMPUTE POOL MYPOOL
       FROM SPECIFICATION
       $$
       spec:
         containers:
           - name: main
             image: /db/data_schema/tutorial_repository/my_echo_service_image:tutorial
             env:
               TEST_FILE_STAGE: source_stage/test_file
             args:
               - read_secret.py
         endpoints:
           - name: read
             port: 8080
       $$
       EXTERNAL_ACCESS_INTEGRATIONS = (google_apis_access_integration);
     

     Copy

     Cet exemple de requête CREATE SERVICE utilise une spécification de service en ligne et spécifie la propriété facultative EXTERNAL_ACCESS_INTEGRATIONS pour inclure l’EAI. L’EAI spécifie les règles de réseau qui autorisent le trafic de sortie du service vers les destinations spécifiques.

   • Créez une tâche :

     EXECUTE SERVICE
       IN COMPUTE POOL tt_cp
       FROM SPECIFICATION $$
       spec:
         container:
         - name: curl
           image: /tutorial_db/data_schema/tutorial_repo/alpine-curl:latest
           command:
           - "curl"
           - "http://google.com/"
       $$
       EXTERNAL_ACCESS_INTEGRATIONS = (google_apis_access_integration);
     

     Copy

     Cet exemple de commande EXECUTE SERVICE spécifie la spécification en ligne et la propriété facultative EXTERNAL_ACCESS_INTEGRATIONS pour inclure l’EAI. Cela autorise le trafic de sortie de la tâche vers les destinations spécifiées dans les règles de réseau que l’EAI autorise.

Communications réseau entre les conteneurs¶

Il y a deux considérations à prendre en compte :

• Communications entre les conteneurs d’une instance de service : si une instance de service utilise plusieurs conteneurs, ces conteneurs peuvent communiquer entre eux via localhost (il n’est pas nécessaire de définir des points de terminaison dans la spécification du service).

• Les conteneurs appartenant à différents services/différentes tâches ou de plusieurs instances de services : les conteneurs appartenant à différents services (ou à différentes instances d’un même service) peuvent communiquer en utilisant des points de terminaison définis dans des fichiers de spécification. Pour plus d’informations, voir Communications de service à service.

Transmission de secrets en tant que variables d’environnement¶

Pour transmettre des secrets de conteneurs Snowflake en tant que variables d’environnement, incluez un champ containers.secrets :

containers:
- name: main
  image: <url>
  secrets:
  - snowflakeSecret: <snowflake-secret-name>
    secretKeyRef: <secret-key-reference>
    envVarName: <env-variable-name>

secretKeyRef : cette valeur dépend du type de secret Snowflake. Valeurs possibles :

• username ou password si le secret Snowflake est de type password.

• secret_string si le secret Snowflake est de type generic_string.

• access_token si le secret Snowflake est de type oauth2.

CREATE SECRET testdb.testschema.my_secret_object
  TYPE = password
  USERNAME = 'snowman'
  PASSWORD = '1234abc';

containers:
- name: main
  image: <url>
  secrets:
  - snowflakeSecret: testdb.testschema.my_secret_object
    secretKeyRef: username
    envVarName: LOGIN_USER
  - snowflakeSecret: testdb.testschema.my_secret_object
    secretKeyRef: password
    envVarName: LOGIN_PASSWORD

CREATE SECRET testdb.testschema.my_secret
  TYPE=generic_string
  SECRET_STRING='
       some_magic: config
  ';

containers:
- name: main
  image: <url>
  secrets:
  - snowflakeSecret: testdb.testschema.my_secret
    secretKeyRef: secret_string
    envVarName: GENERIC_SECRET

Transmission de secrets dans des fichiers de conteneurs locaux¶

Pour que les secrets de Snowflake soient accessibles à votre conteneur d’application dans les fichiers locaux du conteneur, incluez un champ containers.secrets :

containers:
- name: <name>
  image: <url>
  ...
  secrets:
  - snowflakeSecret: <snowflake-secret-name>
    directoryPath: '<local directory path in the container>'

directoryPath : Snowflake remplit un fichier pour chaque clé secrète dans le répertoire spécifié ; il n’est pas nécessaire de spécifier secretKeyRef.

CREATE SECRET testdb.testschema.my_secret_object
  TYPE = password
  USERNAME = 'snowman'
  PASSWORD = '1234abc';

containers:
- name: main
  image: <url>
  secrets:
  - snowflakeSecret: testdb.testschema.my_secret_object
    directoryPath: '/usr/local/creds'

CREATE SECRET testdb.testschema.oauth_secret
  TYPE = OAUTH2
  OAUTH_REFRESH_TOKEN = '34n;vods4nQsdg09wee4qnfvadH'
  OAUTH_REFRESH_TOKEN_EXPIRY_TIME = '2023-12-31 20:00:00'
  API_AUTHENTICATION = my_integration;

containers:
- name: main
  image: <url>
  secrets:
  - snowflakeSecret: testdb.testschema.oauth_secret
    directoryPath: '/usr/local/creds'