Tutorial 2: Eine App mit Containern erstellen¶

Was Sie in diesem Tutorial lernen¶

In diesem Tutorial lernen 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.

Einrichten Ihrer Snowflake-Umgebung¶

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.

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.

Projektdatei mit dem Snowflake CLI erstellen¶

1. Um eine Projektdatei zu erstellen, führen Sie den folgenden Befehl aus:

   snow init --template app_basic na-spcs-tutorial
   

   Copy

2. Geben Sie einen Wert für den Projektbezeichner ein.

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

Dieser Befehl erstellt einen Ordner mit dem Namen na-spcs-tutorial unter Verwendung der Projektvorlage app_basic.

Innerhalb des Ordners na-spcs-tutorial erstellt dieser Befehl die folgenden Dateien und Ordner:

├── README.md
├── app
    └── manifest.yml
    └── README.md
    └── setup_script.sql
├── snowflake.yml

In späteren Abschnitten ändern Sie diese Dateien und fügen zusätzliche Ressourcen zu Ihrer App hinzu.

Servicedateien zum App-Projekt hinzufügen¶

Im vorigen Abschnitt haben Sie ein Projekt erstellt, das die für Ihre Anwendung erforderlichen Standardanwendungsdateien enthält. In diesem Abschnitt fügen Sie die erforderlichen Dateien hinzu, um die Container für Ihre App zu erstellen.

1. 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.

2. Um die für das Tutorial benötigten Docker-Dateien zu erhalten, laden Sie die Datei na_spcs_tutorial.zip auf Ihr lokales Dateisystem herunter.

3. Entpacken Sie den Inhalt der Zip-Datei 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

Überprüfen Sie die Verzeichnisstruktur Ihres Projekts¶

Nachdem Sie das Projekt für Ihre App erstellt und die Dateien für den Dienst und den Docker-Container hinzugefügt haben, sollte das Projekt im Ordner na-spcs-tutorial die folgende Struktur aufweisen:

├── app
      └── manifest.yml
      └── README.md
      └── setup_script.sql
├── README.md
├── service
      └── echo_service.py
      ├── echo_spec.yaml
      ├── Dockerfile
      └── templates
         └── basic_ui.html
├── snowflake.yml

Docker-Image erstellen und in das Image-Repository hochladen¶

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

1. Wechseln Sie in einem Terminalfenster in den Ordner na-spcs-tutorial/service.

2. 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.

3. 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 -c tut-connection)
   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.

4. 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

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

   snow spcs image-registry login -c tut-connection
   

   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.

6. 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

7. 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 -c tut-connection
   

   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.

Standard-Manifestdatei ändern¶

Um die Manifestdatei für die App zu ändern, 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.

Standard-Setup-Skript ändern¶

Um das Standard-Setup-Skript für das Anwendungspaket zu ändern, 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 TABLE ()
   LANGUAGE SQL
   EXECUTE AS OWNER
   AS $$
      BEGIN
            LET stmt VARCHAR := 'SHOW SERVICE CONTAINERS IN SERVICE core.echo_service;
            LET res RESULTSET := (EXECUTE IMMEDIATE :stmt);
            RETURN TABLE(res);
      END;
   $$;
   
   GRANT USAGE ON PROCEDURE app_public.service_status() TO APPLICATION ROLE app_user;
   

   Copy

Standard-README ändern¶

Um die README-Datei für die App zu ändern, gehen Sie wie folgt vor:

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, nachdem sie Ihre App installiert haben.

Standard-Projektdefinitionsdatei ändern¶

In diesem Abschnitt ändern Sie die Projektdefinitionsdateien, die von Snowflake CLI verwendet 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.

Laden Sie Dateien in den Stagingbereich hoch und erstellen Sie das Anwendungsobjekt¶

Um eine App im Entwicklungsmodus zu erstellen, gehen Sie wie folgt vor:

1. Wechseln Sie in einem Terminal in den Ordner na-spcs-tutorial.

2. Erstellen Sie das Anwendungspaket und das Objekt in Ihrem Konto, indem Sie den folgenden Befehl ausführen:

   snow app run -c tut-connection
   

   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 geändert 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.

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 in einem Snowflake-Arbeitsblatt aus:

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

   Diese Anweisung ruft die Prozedur app_public.service_status auf, die Sie im Setup-Skript definiert haben. Die Prozedur gibt Informationen über die Container für diesen Dienst zurück.

   Wenn der Wert in der Spalte status nicht READY ist, führen Sie die Anweisung erneut aus, bis der Status des Dienstcontainers READY lautet.

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 die folgende Meldung von dem Dienst angezeigt, den Sie in einem früheren Abschnitt konfiguriert haben:

   ``Bob said hello``
   

   Copy