Snowpark Container Services: Verwenden von Diensten¶

Langlaufenden Dienst erstellen¶

Verwenden Sie CREATE SERVICE, um einen langlaufenden Dienst zu erstellen.

• Erstellen Sie einen Dienst unter Verwendung einer Inline-Spezifikation. In den meisten Fällen werden Sie sich bei der Entwicklung für die Inline-Spezifikation entscheiden, wie hier gezeigt:

  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

• Erstellen Sie einen Dienst unter Verwendung von Stagingbereichsinformationen: Wenn Sie den Dienst jedoch in einer Produktionsumgebung einsetzen, ist es ratsam, das Designprinzip von der Trennung der Zuständigkeiten („Separation of Concerns“) anzuwenden und die Spezifikation in einen Stagingbereich hochzuladen, Stagingbereichsinformationen im CREATE SERVICE-Befehl bereitzustellen, wie hier gezeigt:

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

  Copy

Jobdienst ausführen¶

Verwenden Sie EXECUTE JOB SERVICE, um einen Jobdienst zu erstellen. Dieser Befehl wird synchron ausgeführt und gibt eine Antwort zurück, nachdem alle Container des Jobdienstes beendet wurden.

• Führen Sie einen Jobdienst mit einer Inline-Spezifikation aus:

  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

• Führen Sie einen Jobdienst unter Verwendung von Stagingbereich-Informationen aus:

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

  Copy

Mehrere Dienstinstanzen erstellen und automatische Skalierung aktivieren¶

Standardmäßig führt Snowflake eine Instanz des Dienstes in dem angegebenen Computepool aus. Um umfangreiche Workloads zu bewältigen, können Sie mehrere Dienstinstanzen ausführen, indem Sie die Eigenschaften MIN_INSTANCES und MAX_INSTANCES spezifizieren, die die Mindestanzahl der zu startenden Instanzen des Dienstes und die maximale Anzahl der Instanzen angeben, auf die Snowflake bei Bedarf skalieren kann.

Beispiel

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

Wenn mehrere Dienstinstanzen ausgeführt werden, stellt Snowflake automatisch einen Load Balancer zum Verteilen der eingehenden Anforderungen bereit.

Führen Sie die folgenden Schritte aus, um Snowflake für die automatische Skalierung der Anzahl der ausgeführten Dienstinstanzen zu konfigurieren:

1. Geben Sie die CPU und die Anforderungen an Arbeitsspeicher und für Ihre Dienstinstanz an. Weitere Informationen dazu finden Sie unter Feld „container.resources“.

   Beispiel

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

   Copy

2. Wenn Sie den Befehl CREATE SERVICE ausführen, legen Sie die Parameter MIN_INSTANCES und MAX_INSTANCES fest. Sie können auch ALTER SERVICE verwenden, um diese Werte zu ändern. Die Autoskalierung erfolgt, wenn die angegebene MAX_INSTANCES größer als MIN_INSTANCES ist.

Snowflake beginnt mit der Erstellung der Mindestanzahl von Dienstinstanzen auf dem angegebenen Computepool. Snowflake skaliert dann die Anzahl der Diensteinstanzen anhand eines Schwellenwerts von 80 % (sowohl für CPU als auch für Speicher) hoch oder runter. Snowflake überwacht kontinuierlich die Ressourcennutzung (Arbeitsspeicher oder CPU) innerhalb des Computepools und aggregiert die Nutzungsdaten aller aktuell ausgeführten Dienstinstanzen.

Wenn die aggregierte Ressourcennutzung (für alle Dienstinstanzen) 80 % übersteigt, stellt Snowflake eine zusätzliche Dienstinstanz im Computepool bereit. Wenn die aggregierte Ressourcennutzung unter 80 % fällt, skaliert Snowflake herunter, indem eine der aktiven Dienstinstanzen entfernt wird. Snowflake verwendet ein fünfminütiges Stabilisierungsfenster, um häufiges Skalieren zu verhindern.

Beachten Sie das folgende Skalierungsverhalten:

• Die Skalierung der Dienstinstanzen wird durch die für den Dienst konfigurierten Parameter MIN_INSTANCES und MAX_INSTANCES eingeschränkt.

• Wenn ein Hochskalieren erforderlich ist und die Knoten des Computepools nicht über die erforderliche Ressourcenkapazität verfügen, um eine weitere Dienstinstanz zu starten, kann die automatische Skalierung des Computepools ausgelöst werden. Weitere Informationen dazu finden Sie unter Automatisches Skalieren von Computepool-Knoten.

• Wenn Sie beim Erstellen eines Services die Parameter MAX_INSTANCES und MIN_INSTANCES angeben, aber in der Dienstspezifikationsdatei Ihrer Dienstinstanz keine CPU- und Arbeitsspeicheranforderungen spezifiziert sind, erfolgt keine automatische Skalierung. Snowflake beginnt dann mit der durch den Parameter MIN_INSTANCES angegebenen Anzahl von Instanzen und führt keine automatische Skalierung durch.

Verwenden von Spezifikationsvorlagen¶

Es kann vorkommen, dass Sie mehrere Dienste mit der gleichen Spezifikation, aber mit unterschiedlichen Konfigurationen erstellen möchten. Nehmen Sie zum Beispiel an, dass Sie in einer Dienstspezifikation eine Umgebungsvariable definieren und Sie mehrere Services erstellen möchten, die dieselbe Spezifikation, aber unterschiedliche Werte für die Umgebungsvariable verwenden.

Spezifikationsvorlagen ermöglichen es Ihnen, Variablen für Feldwerte in der Spezifikation zu definieren. Wenn Sie einen Service erstellen, geben Sie Werte für diese Variablen an.

Die Verwendung von Spezifikationsvorlagen ist ein zweistufiger Prozess:

1. Erstellen Sie eine Spezifikation mit Variablen als Werte für verschiedene Spezifikationsfelder. Verwenden Sie die Syntax {{ variable_name }}, um diese Variablen anzugeben. Die folgende Spezifikation verwendet zum Beispiel eine Variable namens „tag_name“ für den Namen des Image-Tags, so dass Sie für jeden Dienst ein anderes Image-Tag angeben.

   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. Erstellen Sie einen Dienst, indem Sie die Spezifikationsvorlage in einem CREATE SERVICE-Befehl bereitstellen. Sie verwenden SPECIFICATION_TEMPLATE oder SPECIFICATION_TEMPLATE_FILE, um die Vorlage anzugeben. Verwenden Sie den Parameter USING, um den Wert der Variable anzugeben. Die folgende Anweisung verwendet zum Beispiel eine Spezifikationsvorlage aus einem Snowflake-Stagingbereich. Der Parameter USING setzt die Variable tag_name auf den Wert '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, ... ] );

Beispiele¶

Diese Beispiele zeigen das Erstellen von Diensten mithilfe von Spezifikationsvorlagen. Die CREATE SERVICE-Befehle in diesen Beispielen verwenden Inline-Spezifikationen.

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"]$$ );

Beendigung des Dienstes¶

Wenn Sie einen Service aussetzen (ALTER SERVICE … SUSPEND) oder einen Service beenden (DROP SERVICE), beendet Snowflake alle Dienstinstanzen. Ähnlich verhält es sich, wenn Sie den Dienstcode aktualisieren (ALTER SERVICE … <fromSpecification>), wendet Snowflake fortlaufende Upgrades an, indem es jeweils eine Dienstinstanz beendet und neu bereitstellt.

Wenn eine Dienstinstanz beendet wird, sendet Snowflake zunächst ein SIGTERM-Signal an jeden Dienstcontainer. Der Container hat die Möglichkeit, das Signal zu verarbeiten und mit einem 30-Sekunden-Fenster ordnungsgemäß herunterzufahren. Andernfalls beendet Snowflake nach Ablauf des Zeitraums alle Prozesse im Container.

Aktualisieren des Dienstcodes und erneutes Bereitstellen des Dienstes¶

Nachdem ein Dienst erstellt wurde, verwenden Sie den Befehl ALTER SERVICE … <fromSpecification>, um den Dienstcode zu aktualisieren und den Dienst erneut bereitzustellen.

Sie laden zunächst den geänderten Anwendungscode in Ihr Image-Repository hoch und rufen dann ALTER SERVICE auf, bei Sie entweder die Dienstspezifikation inline bereitstellen oder den Pfad zu einer Spezifikationsdatei im Snowflake-Stagingbereich angeben. Beispiel:

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

Nach Erhalt der Anforderung stellt Snowflake den Dienst mit dem neuen Code erneut bereit.

Wenn Sie den Befehl CREATE SERVICE … <from-Specification> ausführen, zeichnet Snowflake die spezifische Version des bereitgestellten Images auf. Snowflake setzt in den folgenden Szenarien dieselbe Image-Version ein, auch wenn das Image im Repository aktualisiert wurde:

• Wenn ein angehaltener Dienst wieder fortgesetzt wird (mit ALTER SERVICE … RESUME).

• Wenn Autoscaling weitere Dienstinstanzen hinzufügt.

• Wenn Dienstinstanzen während der Cluster-Wartung neu gestartet werden.

Wenn Sie jedoch ALTER SERVICE … <fromSpecification> aufrufen, wird ausgelöst, dass Snowflake die neueste Version im Repository für dieses Image verwendet.

Wenn Sie der Eigentümer des Services sind, enthält die Ausgabe des Befehls DESCRIBE SERVICE die Dienstspezifikation, die den Image-Digest (den Wert des Feldes sha256 in der Spezifikation) enthält, wie unten gezeigt:

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 kann die Kommunikation (siehe Verwenden eines Dienstes) mit dem Dienst beeinträchtigen.

• Wenn ALTER SERVICE … <fromSpecification> einen Endpunkt entfernt oder relevante Berechtigungen entfernt, die für die Nutzung eines Endpunkts erforderlich sind (siehe serviceRoles in Spezifikationsreferenz), schlägt der Zugriff auf den Service fehl. Weitere Informationen finden Sie unter Verwendung eines Dienstes.

• Während des Upgrades werden neue Verbindungen möglicherweise auf die neue Version geroutet. Wenn die neue Version des Dienstes nicht abwärtskompatibel ist, wird die aktive Nutzung des Dienstes unterbrochen. Zum Beispiel können laufende Abfragen mit einer Dienstfunktion fehlschlagen.

Gewährung der Berechtigung USAGE auf allen Endpunkten, die die Standardrolle des Dienstes verwenden¶

Wenn Sie einen Dienst (einschließlich eines Jobdienstes) erstellen, erstellt Snowflake auch eine Standard-Dienstrolle mit dem Namen ALL_ENDPOINTS_USAGE. Diese Rolle hat die USAGE-Berechtigung für alle Endpunkte, die der Dienst zur Verfügung stellt. Sie können anderen Rollen diese Standard-Dienstrolle mit dem Befehl GRANT SERVICE ROLE zuweisen:

GRANT SERVICE ROLE my_echo_service_image!ALL_ENDPOINTS_USAGE TO ROLE some_other_role;

Benutzer, die some_other_role verwenden, haben die USAGE-Berechtigung für alle Dienstendpunkte.

Wenn Sie einen Dienst löschen, löscht Snowflake alle mit dem Dienst verbundenen Dienstrollen (Standard-Dienstrolle und die in der Dienstspezifikation definierten Dienstrollen) und nimmt alle Dienstrolle-Zuweisungen wieder zurück.

Erteilung der Berechtigung USAGE an bestimmte Endpunkte unter Verwendung von in der Spezifikation definierten Dienstrollen¶

Verwenden Sie Dienstrollen, um den fein abgestuften Zugriff auf Dienstendpunkte zu verwalten. Sie definieren die Dienstrollen zusammen mit der Liste der Endpunkte, für die sie die USAGE-Berechtigung erhalten, in der Dienstspezifikation.

Das Erteilen von Berechtigungen für bestimmte Endpunkte eines Dienstes erfolgt in zwei Schritten:

1. Dienstrolle definieren: Verwenden Sie eine Dienstspezifikation, um eine Dienstrolle zu definieren, indem Sie einen Rollennamen und eine Liste von einem oder mehreren Endpunkten angeben, für die Sie die USAGE-Berechtigung erteilen möchten. Im folgenden Spezifikationsfragment definiert beispielsweise das Top-Level-Feld serviceRoles zwei Dienstrollen, jede mit USAGE-Berechtigung für bestimmte Endpunkte.

   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. Dienstrolle anderen Rollen zuweisen. Mit dem Befehl GRANT SERVICE ROLE weisen Sie die Dienstrolle anderen Rollen (Konto-, Anwendungs- oder Datenbankrollen) zu. Beispiel:

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

   Copy

Dienstfunktionen: Verwenden eines Dienstes aus einer SQL-Abfrage¶

Eine Dienstfunktion ist eine benutzerdefinierte Funktion (UDF), die Sie mit CREATE FUNCTION (Snowpark Container Services) erstellen. Anstatt jedoch den Code von UDF direkt zu schreiben, verknüpfen Sie die UDF mit Ihrem Dienstendpunkt. Beachten Sie, dass Sie eine Funktion nur mit einem Dienstendpunkt verknüpfen können, der das Protokoll HTTP oder HTTPS unterstützt.

In Tutorial 1 erstellen Sie beispielsweise einen Dienst namens echo_service, der einen Endpunkt (echoendoint) gemäß der Definition in der Dienstspezifikation bereitstellt:

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

echoendpoint ist ein benutzerfreundlicher Endpunktname, der den entsprechenden Port (8080) darstellt. Um mit diesem Dienstendpunkt zu kommunizieren, erstellen Sie eine Dienstfunktion, indem Sie die Parameter SERVICE und ENDPOINT wie gezeigt angeben:

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

Der Parameter AS stellt den HTTP-Pfad zum Dienstcode bereit. Sie erhalten diesen Pfad-Wert aus dem Dienstcode. Die folgenden Zeilen stammen zum Beispiel aus service.py in Tutorial 1.

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

Wenn Sie die Dienstfunktion aufrufen, leitet Snowflake die Anforderung an den zugehörigen Dienstendpunkt und -pfad weiter.

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');

Dateneingang: Verwenden eines Dienstes von außerhalb von Snowflake¶

Ein Dienst kann einen oder mehrere Endpunkte als öffentlich bereitstellen, damit Benutzer den Dienst über das öffentliche Web nutzen können. In diesem Fall verwaltet Snowflake die Zugriffssteuerung. Beachten Sie, dass Ingress nur mit den Endpunkten HTTP oder HTTPS erlaubt ist.

Markieren Sie den Endpunkt in Ihrer Dienstspezifikationsdatei als öffentlich:

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

Dienst-zu-Dienst-Kommunikation¶

Dienste können über den DNS-Namen, den Snowflake jedem Dienst automatisch zuweist, miteinander kommunizieren. Ein Beispiel dazu finden Sie unter Tutorial 3. Beachten Sie, dass, wenn ein Dienstendpunkt nur erstellt wird, um die Kommunikation zwischen Diensten zu ermöglichen, das TCP-Protokoll verwendet werden sollte.

Das DNS-Namensformat ist:

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

Verwenden Sie SHOW SERVICES (oder DESCRIBE SERVICE), um den DNS-Namen eines Dienstes zu erhalten. Der obige DNS-Name ist ein vollständiger Name. Dienste, die im selben Schema erstellt wurden, können nur über den <service-name> kommunizieren. Dienste, die sich in derselben Datenbank, aber in unterschiedlichen Schemas befinden, müssen den Schemanamen angeben, z. B. <service-name>.<schema-name>.

Snowflake erlaubt die Netzwerkkommunikation zwischen Diensten, die von der gleichen Rolle erstellt wurden, und blockiert die Netzwerkkommunikation zwischen Diensten, die von verschiedenen Rollen erstellt wurden. Wenn Sie verhindern möchten, dass Ihre Dienste miteinander kommunizieren (z. B. aus Sicherheitsgründen), verwenden Sie verschiedene Snowflake-Rollen, um diese Dienste zu erstellen.

DNS-Namen haben die folgenden Einschränkungen:

• Ihre Datenbank-, Schema- oder Dienstnamen müssen gültige DNS-Bezeichnungen sein. (Siehe auch https://www.ietf.org/rfc/rfc1035.html#section-2.3.1). Andernfalls wird das Erstellen eines Dienstes fehlschlagen.

• Snowflake ersetzt einen Unterstrich (_) in den Namen (Datenbank-, Schema- und Dienstname) im DNS-Namen durch einen Bindestrich (-).

• Ändern Sie nach dem Erstellen eines Dienstes nicht die Datenbank oder den Schemanamen, da Snowflake den DNS-Namen des Dienstes nicht aktualisiert.

• Ein DNS-Name dient nur der internen Kommunikation innerhalb von Snowflake zwischen Diensten, die in demselben Konto ausgeführt werden. Er ist nicht über das Internet zugänglich.