Tutorial: Eine Snowflake Native App mit Snowpark Container Services erstellen¶

Lerninhalte¶

In diesem Tutorial erfahren Sie Folgendes:

• Verwenden der Snowflake CLI, um ein Snowflake Native App with Snowpark Container Services-Projekt zu initialisieren.

• Erstellen eines Docker-Image für eine App.

• Erstellen des Anwendungspakets und der erforderlichen Anwendungsdateien für eine Snowflake Native App with Snowpark Container Services.

• Testen einer Snowflake Native App with Snowpark Container Services, indem die Dienstfunktion innerhalb des Containers aufgerufen wird.

Voraussetzungen¶

Um dieses Tutorial auszuführen, müssen Sie die folgenden Voraussetzungen erfüllen:

• Zugriff auf ein Snowflake-Konto, das Snowpark Container Services unterstützt.

• Sie müssen in der Lage sein, mit der Rolle ACCOUNTADMIN die in diesem Tutorial verwendete Rolle zu erstellen und dieser Rolle die erforderlichen Berechtigungen zuzuweisen.

• Sie müssen Snowflake CLI Version 3.0.0 oder höher auf Ihrem lokalen Computer installiert haben.

• Sie müssen Docker Desktop auf Ihrem lokalen Computer installiert haben.

Snowflake CLI-Verbindung einrichten¶

Bei den Befehlen, die Sie in diesem Tutorial ausführen, wird davon ausgegangen, dass Sie Snowflake CLI so konfiguriert haben, dass es sich standardmäßig mit dem Konto verbindet, in dem Sie die App entwickeln. Wenn dieses Konto nicht standardmäßig eingestellt ist, können Sie mit dem Befehlszeilenargument -c eine andere benannte Verbindung angeben, z. B.:

snow sql -q "SELECT 1" -c connection_name

Copy

Warehouse und Image-Repository erstellen¶

Um die benötigten Objekte zu erstellen, führen Sie entweder über Snowsight oder Snowflake CLI folgende Schritte aus.

1. Um den aktuellen Kontext in Snowsight so einzustellen, dass die Rolle tutorial_role verwendet wird, führen Sie den folgenden Befehl aus:

   USE ROLE tutorial_role;
   

   Copy

   Wenn Sie Snowflake CLI verwenden, können Sie stattdessen --role tutorial_role verwenden.

2. Um ein Warehouse für die Snowflake Native App with Snowpark Container Services zu erstellen, führen Sie den folgenden Befehl aus:

   CREATE OR REPLACE WAREHOUSE tutorial_warehouse WITH
     WAREHOUSE_SIZE = 'X-SMALL'
     AUTO_SUSPEND = 180
     AUTO_RESUME = true
     INITIALLY_SUSPENDED = false;
   

   Copy

   Ein Warehouse wird von der Snowflake Native App benötigt, um SQL-Befehle und gespeicherte Prozeduren auszuführen.

3. Um das Image-Repository zu erstellen, das zum Speichern des Containers verwendet wird, führen Sie den folgenden Befehl aus:

   CREATE DATABASE tutorial_image_database;
   CREATE SCHEMA tutorial_image_schema;
   CREATE IMAGE REPOSITORY tutorial_image_repo;
   

   Copy

In diesem Abschnitt haben Sie ein Warehouse erstellt, das zum Ausführen von Abfragen für die von Ihnen erstellte App verwendet wird, sowie ein Image-Repository, das Container-Images hostet.

Im nächsten Abschnitt erstellen Sie ein Image für den Container und laden es in das zuvor erstellte Image-Repository hoch.

Projektverzeichnis erstellen¶

Der Quellcode für Ihre App befindet sich im lokalen Dateisystem und kann auf Wunsch in die Versionskontrolle eingecheckt werden. Zuerst verwenden wir Snowflake CLI, um ein Native Apps-Projekt zu booten. Anschließend erstellen wir das Image für unseren Containerdienst in einem Unterordner.

1. Führen Sie auf Ihrem lokalen Dateisystem den folgenden Befehl aus, um einen Ordner mit dem Namen na-spcs-tutorial zu erstellen:

   snow init --template app_basic na-spcs-tutorial
   

   Copy

   Bemerkung

   Sie werden in späteren Unterabschnitten weitere Dateien und Unterordner zu diesem Ordner hinzufügen und die von diesem Befehl erstellten Dateien bearbeiten.

   Bemerkung

   Führen Sie snow init --help aus, um weitere Vorlagen für das Einrichten einer Snowflake Native App-Entwicklungsumgebung anzuzeigen.

2. Erstellen Sie innerhalb des Ordners na-spcs-tutorial einen Ordner mit dem Namen service. Dieser Ordner enthält den Quellcode für den Container-basierten Dienst, den wir erstellen und in Snowflake veröffentlichen werden.

3. Um die für das Tutorial benötigten Docker-Dateien zu erhalten, laden Sie die ZIP-Datei in Ihr lokales Dateisystem herunter.

4. Entpacken Sie den Inhalt in den Ordner na-spcs-tutorial/service. Dieser Ordner sollte die folgenden Dateien enthalten:

   • echo_service.py

   • Dockerfile

   • templates/basic_ui.html

   • echo_spec.yaml

5. Öffnen Sie ein Terminalfenster, und wechseln Sie in dieses Verzeichnis.

Docker-Image erstellen und in den Container hochladen¶

Um ein Docker-Image zu erstellen und es in das Image-Repository hochzuladen, gehen Sie wie folgt vor:

1. Führen Sie den folgenden Docker CLI-Befehl aus. Beachten Sie, dass Sie in dem Befehl das aktuelle Verzeichnis (.) angeben müssen:

   docker build --rm --platform linux/amd64 -t my_echo_service_image:tutorial .
   

   Copy

   Dieser Befehl führt Folgendes aus:

   • Erstellt ein Docker-Image anhand der Docker-Datei, die in der heruntergeladenen ZIP-Datei enthalten ist.

   • Benennt das Image my_echo_service_image.

   • Wendet das Tag tutorial auf das Image an.

2. Um die URL des Image-Repositorys zu identifizieren, das Sie in einem früheren Abschnitt erstellt haben, führen Sie den folgenden Befehl aus:

   REPO_URL=$(snow spcs image-repository url tutorial_image_database.tutorial_image_schema.tutorial_image_repo --role tutorial_role)
   echo $REPO_URL
   

   Copy

   Die URL des Image-Repositorys wird in der Variable $REPO_URL erfasst und anschließend auf der Konsole ausgegeben. Sie benötigen diesen Wert im nächsten Schritt.

3. Um ein Tag für das Image zu erstellen, das die Image-URL enthält, führen Sie den folgenden Docker CLI-Befehl aus:

   docker tag <image_name> <image_url>/<image_name>
   

   Copy

   Dieser Befehl erfordert zwei Parameter:

   • <image_name> gibt den Namen von Image und Tag an.

   • <image_url>/<image_name> gibt die URL des Image-Repositorys an, in das das Image hochgeladen wird, sowie den Image-Namen und das Tag, wo das Image im externen Repository gespeichert werden soll.

   Verwenden Sie für dieses Tutorial $REPO_URL und my_echo_service_image:tutorial:

   docker tag my_echo_service_image:tutorial $REPO_URL/my_echo_service_image:tutorial
   

   Copy

4. Um sich mit der Snowflake-Registry zu authentifizieren, führen Sie den folgenden Snowflake CLI-Befehl aus:

   snow spcs image-registry login [-c connection_name]
   

   Copy

   Mit diesem Befehl werden die erforderlichen Anmeldeinformationen geladen, die Docker CLI benötigt, um die Image-Repositorys in Ihrem Snowflake-Konto zu verwenden. Wenn Sie nicht die Standardeinstellung verwenden, müssen Sie den Namen der Verbindung angeben.

   Wenn alles erfolgreich war, wird die Meldung Login Succeeded angezeigt.

5. Um das Docker-Image in das Image-Repository hochzuladen, führen Sie den folgenden docker push-Befehl aus:

   docker push $REPO_URL/<image_name>
   

   Copy

   Wenn Sie denselben Wert wie <image_name> aus den vorherigen Schritten verwenden, lautet dieser Befehl:

   docker push $REPO_URL/my_echo_service_image:tutorial
   

   Copy

6. Bestätigen Sie, dass das Image erfolgreich hochgeladen wurde, indem Sie den folgenden Befehl ausführen:

   snow spcs image-repository list-images tutorial_image_database.tutorial_image_schema.tutorial_image_repo --role tutorial_role
   

   Copy

In diesem Abschnitt haben Sie ein Docker-Image erstellt, das den Echo-Dienst enthält, und dieses Image in das Image-Repository tutorial_repository verschoben, das Sie zuvor in diesem Tutorial erstellt haben.

Im nächsten Abschnitt werden Sie ein Anwendungspaket erstellen, das dieses Image verwendet.

Manifest-Datei für das Anwendungspaket erstellen¶

Um die erforderliche Manifest-Datei für das Anwendungspaket zu erstellen, gehen Sie wie folgt vor:

1. Ändern Sie die Datei na-spcs-tutorial/app/manifest.yml so, dass sie Folgendes enthält:

   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

   Dieses Beispiel enthält die folgenden Eigenschaften:

   • Die Eigenschaft artifacts gibt die Speicherorte der Ressourcen an, die von einer App mit Containern benötigt werden, einschließlich des Speicherorts des Docker-Images, das Sie in einem vorherigen Schritt erstellt haben, sowie die Projekt-README, die in Snowsight sichtbar sein wird.

   • Die Eigenschaft privileges ermöglicht es einem Dienst, auf öffentliche Anforderungen zu antworten und seinen eigenen Computepool zu erstellen. Diese Eigenschaften werden für die Instanziierung unseres Dienstes im nächsten Schritt des Tutorials benötigt.

Setup-Skript für das Anwendungspaket erstellen¶

Um das erforderliche Setup-Skript für das Anwendungspaket zu erstellen, gehen Sie wie folgt vor:

1. Ändern Sie die Datei na-spcs-tutorial/app/setup_script.sql so, dass Sie Folgendes enthält:

   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

Readme-Datei für das Anwendungspaket erstellen¶

1. Ändern Sie die Datei na-spcs-tutorial/app/README.md so, dass sie Folgendes enthält:

   Welcome to your first app with containers!
   

   Copy

Diese Readme-Datei ist für Verbraucher sichtbar, die Ihre App installiert haben.

Projektdefinitionsdatei erstellen¶

In diesem Abschnitt erstellen Sie die Projektdefinitionsdatei, die von Snowflake CLI benötigt wird.

1. Ändern Sie die Datei na-spcs-tutorial/snowflake.yml so, dass sie Folgendes enthält:

   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

In diesem Abschnitt haben Sie eine lokale Dateistruktur definiert, die einem Snowflake-Konto als Snowflake Native App with Snowpark Container Services bereitgestellt werden kann. Im nächsten Abschnitt werden Sie diese Bereitstellung mit Snowflake CLI ausführen.

Anwendung bereitstellen¶

Um die Anwendung im Modus der Stagingbereichsentwicklung bereitzustellen, gehen Sie wie folgt vor:

1. Erstellen Sie das Anwendungspaket und das Objekt in Ihrem Konto, indem Sie den folgenden Befehl im Ordner na-spcs-tutorial ausführen:

   snow app run [-c connection_name]
   

   Copy

   Dieser Befehl zeigt eine Bestätigung an, dass ein Anwendungspaket namens na_spcs_tutorial_pkg und ein Anwendungsobjekt namens na_spcs_tutorial_app in Ihrem Konto erstellt wurden. Diese Namen entsprechen den Namen in der Projektdefinitionsdatei snowflake.yml, die Sie in einem vorherigen Abschnitt erstellt haben.

Sie können die URL-Ausgabe auf der Konsole verwenden, um die Anwendung anzuzeigen. Sie müssen jedoch zunächst sicherstellen, dass die Anwendung über alle erforderlichen Berechtigungen verfügt, um ihren containerbasierten Dienst zu erstellen.

Dies werden Sie im nächsten Abschnitt tun.

Berechtigungen erteilen und App testen¶

In diesem Abschnitt erteilen Sie der App die erforderlichen Berechtigungen und testen die App, indem Sie die Dienste im Container aufrufen.

Sie können die SQL-Befehle entweder über Snowsight oder Snowflake CLI ausführen.

Um die Berechtigungen zu erteilen und die App zu testen, führen Sie die folgenden Schritte aus.

Bemerkung

Für die Ausführung in Snowflake CLI verwenden Sie die folgende Syntax:

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

Copy

Wie in den vorherigen Schritten können Sie -c connection_name hinzufügen, um eine nicht standardmäßige Verbindung zu wählen.

1. Erteilen Sie der App die Berechtigung CREATE COMPUTE POOL, indem Sie Folgendes ausführen:

   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. Führen Sie die Prozedur app_public.start_app aus, die wir in der Datei setup_script.sql definiert haben.

   CALL na_spcs_tutorial_app.app_public.start_app();
   

   Copy

   Diese Prozedur erstellt den Computepool, instanziiert den Dienst und erstellt die Dienstfunktion.

3. Bestätigen Sie, dass die Funktion erstellt wurde, indem Sie Folgendes ausführen:

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

   Copy

   Bemerkung

   Verbraucher können den aktivierten Dienst nicht sehen, da er als Teil der Snowflake Native App ausgeführt wird. Wenn Sie zum Beispiel SHOW SERVICES IN APPLICATION na_spcs_tutorial_app; ausführen, ist das Ergebnis leer.

4. Um zu überprüfen, ob der Dienst erstellt wurde und funktioniert, führen Sie den folgenden Befehl aus:

   CALL na_spcs_tutorial_app.app_public.service_status();
   

   Copy

   Dieser Befehl ruft die Prozedur app_public.service_status auf, die Sie im Setup-Skript definiert haben:

   Wenn diese Prozedur READY zurückgibt, fahren Sie mit dem nächsten Schritt fort.

5. Um die Dienstfunktion aufzurufen, um eine Anfrage an den Dienst zu senden und die Antwort zu überprüfen, führen Sie den folgenden Befehl aus:

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

   Copy

   Es wird eine Meldung von dem Dienst angezeigt, den wir in einem früheren Abschnitt hochgeladen haben: Bob said hello.