Referenz der Dienstspezifikation¶

Felder containers.name und containers.image¶

Für jeden Container sind nur der Name und das Image erforderliche Felder.

• name ist der Names des Images. Dieser Name kann zur Identifizierung eines bestimmten Containers zum Zwecke der Beobachtbarkeit verwendet werden (z. B. Protokolle, Metriken).

• image bezieht sich auf den Namen des Images, das Sie in ein Snowflake-Image-Repository Ihres Snowflake-Kontos hochgeladen haben.

Beispiel:

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

Felder containers.command und containers.args¶

Verwenden Sie diese optionalen Felder, um zu steuern, welche ausführbare Datei in Ihrem Container gestartet wird und welche Argumente an die ausführbare Datei übergeben werden. Sie können diese Konfigurationen zum Zeitpunkt der Erstellung des Images konfigurieren, normalerweise in einer Dockerdatei. Mit diesen Feldern zur Dienstspezifikation können Sie diese Vorgaben (und damit die Verhaltensweise des Containers) ändern, ohne Ihr Container-Image neu erstellen zu müssen:

• containers.command übersteuert den ENTRYPOINT von Dockerfile. Auf diese Weise können Sie eine andere ausführbare Datei in dem Container ausführen.

• containers.args übersteuert den CMD von Dockerfile. Auf diese Weise können Sie dem Befehl (der ausführbaren Datei) verschiedene Argumente bereitstellen.

Beispiel

Ihre Dockerfile-Datei enthält den folgenden Code:

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

Diese Dockerfile-Einträge führen den python3-Befehl aus und übergeben zwei Argumente: main.py und Bob. Sie können diese Werte in der Spezifikationsdatei wie folgt überschreiben:

• Um ENTRYPOINT zu überschreiben, fügen Sie das Feld containers.command in die Spezifikationsdatei ein:

  spec:
    containers:
    - name: echo
      image: <image_name>
      command:
      - python3.9
      - main.py
  

  Copy

• Um das Argument „Bob“ zu überschreiben, fügen Sie das Feld containers.args in die Spezifikationsdatei ein:

  spec:
    containers:
    - name: echo
      image: <image_name>
      args:
        - Alice
  

  Copy

Feld containers.env¶

Verwenden Sie das Feld containers.env, um Variablen für die Umgebung des Containers zu definieren. Alle Prozesse im Container haben Zugriff auf diese Umgebungsvariablen:

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

Beispiel

In Tutorial 1 liest der Anwendungscode (echo_service.py) die Umgebungsvariablen wie gezeigt:

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

Beachten Sie, dass das Beispiel Standardwerte für die Variablen an die Funktion getenv übergibt. Wenn die Umgebungsvariablen nicht definiert sind, werden diese Standardwerte verwendet.

• CHARACTER_NAME: Wenn der Echo-Dienst eine HTTP POST-Anforderung mit einer Zeichenfolge (z. B. „Hallo“) empfängt, gibt der Dienst „I said Hello“ (Ich sagte Hallo) zurück. Sie können diesen Standardwert in der Spezifikationsdatei überschreiben. Wenn Sie beispielsweise den Wert auf „Bob“ setzen, gibt der Echo-Dienst die Antwort „Bob said Hello“ (Bob sagte Hallo) zurück.

• SERVER_PORT: In dieser Standardkonfiguration überwacht der Echo-Dienst Port 8080. Sie können den Standardwert überschreiben und einen anderen Port angeben.

Die folgende Dienstspezifikation setzt diese beiden Werte der Umgebungsvariablen außer Kraft:

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

Da Sie die Port-Nummer geändert haben, an der Ihr Dienst lauscht, muss die Spezifikation auch den Endpunkt aktualisieren (endpoints.port field Wert), wie gezeigt.

Feld containers.readinessProbe¶

Verwenden Sie das Feld containers.readinessProbe, um einen Bereitschaftstest in Ihrer Anwendung zu identifizieren. Snowflake ruft diesen Test auf, um festzustellen, ob Ihre Anwendung bereit ist, Anforderungen zu bedienen.

Snowflake stellt eine HTTP-GET-Anforderung an den angegebenen Bereitschaftstest mit dem angegebenen Port und Pfad und wartet darauf, dass Ihr Dienst einen HTTP 200-OK-Status zurückgibt, um sicherzustellen, dass nur funktionstüchtige Container den Datenverkehr bedienen.

Verwenden Sie die folgenden Felder, um die erforderlichen Informationen anzugeben:

• port: Der Netzwerkport, den der Dienst auf Anforderungen des Bereitschaftstests hin überwacht. Dieser Port muss nicht als Endpunkt deklariert sein.

• path: Snowflake stellt HTTP-GET-Anforderungen an den Dienst mit diesem Pfad.

Beispiel

In Tutorial 1 implementiert der Anwendungscode (echo_python.py) den folgenden Bereitschaftstest:

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

Dementsprechend enthält die Spezifikationsdatei das Feld containers.readinessProbe:

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

Der vom Bereitschaftstest angegebene Port muss kein konfigurierter Endpunkt sein. Ihr Dienst könnte einen anderen Port nur für den Zweck des Bereitschaftstests überwachen.

Feld containers.volumeMounts¶

Da die Felder spec.volumes und spec.containers.volumeMounts zusammenarbeiten, werden sie zusammen in einem Abschnitt erläutert. Weitere Informationen dazu finden Sie unter Feld spec.volumes (optional).

Feld containers.resources¶

Ein Computepool definiert eine Reihe von verfügbaren Ressourcen (CPU, Arbeitsspeicher und Speicher) und Snowflake bestimmt, wo im Computepool Ihre Dienste ausgeführt werden sollen.

Es wird empfohlen, die Anforderungen an die Ressourcen für den jeweiligen Container explizit anzugeben und in der Spezifikation entsprechende Beschränkungen vorzunehmen. Beachten Sie, dass die von Ihnen angegebenen Ressourcen durch die Instanz-Familie der Knoten in Ihrem Computepool eingeschränkt sind. Weitere Informationen dazu finden Sie unter CREATE COMPUTE POOL.

Verwenden Sie das Feld containers.resources, um explizite Anforderungen an die Ressourcen für einen bestimmten Container anzugeben:

• containers.resources.requests: Die Anfragen, die Sie angeben, sollten der durchschnittlichen Nutzung der Ressourcen entsprechen, die Sie von Ihrem Service erwarten. Snowflake verwendet diese Informationen, um die Platzierung der Dienstinstanz im Computepool zu bestimmen. Snowflake stellt sicher, dass die Summe der auf einem bestimmten Knoten gestellten Anfragen nach Ressourcen mit den verfügbaren Ressourcen auf dem Knoten übereinstimmt.

• containers.resources.limits: Die von Ihnen angegebenen Beschränkungen veranlassen Snowflake, keine Ressourcen zuzuweisen, die die angegebenen Grenzen überschreiten. So können Sie Kostenüberschreitungen vermeiden.

Sie können Anforderungen und Grenzen für die folgenden Ressourcen festlegen:

• memory: Dies ist der für Ihren Anwendungscontainer benötigte Arbeitsspeicher. Für die Angabe der Werte können entwender dezimale oder binäre Einheiten verwendet werden. Zum Beispiel steht 2G für eine Anfrage nach 2.000.000.000 Bytes und 2Gi für eine Anfrage nach 2 x 1024 x 1024 x 1024 Bytes.

  Bei der Angabe von Arbeitsspeicher ist eine Einheit erforderlich. Beispiel: 100M oder 5Gi Die unterstützten Einheiten sind: M, Mi, G, Gi.

• cpu: Dies bezieht sich auf virtuelle Verarbeitungseinheiten (vCPU). Beispielsweise ist die 1 CPU-Einheit gleichbedeutend mit 1 vCPU. Erlaubt sind auch Anforderungen von Bruchteilen, wie „0.5“, die auch als „500m“ ausgedrückt werden können.

• nvidia.com/gpu: Wenn GPUs erforderlich sind, müssen diese angefordert werden, und es muss auch ein limit-Wert für dieselbe Menge angegeben werden. Wenn Ihr Container keine Anforderungen und Limits für die GPU-Kapazität angibt, ist kein Zugriff auf GPUs möglich. Die Anzahl der GPUs, die Sie anfordern können, ist durch die maximale Anzahl von GPUs begrenzt, die von dem Instanz-Typ in INSTANCE_TYPE unterstützt wird, den Sie beim Erstellen eines Computepools auswählen.

resource.requests und resource.limits beziehen sich auf die Knotenkapazität (vCPU und Speicher) der Instanzfamilie des zugehörigen Computepools.

• Wenn keine Ressourcenanfrage (CPU, Speicher oder beides) gestellt wird, leitet Snowflake eine für Sie ab:

  • Für cpu ist der abgeleitete Wert entweder 0,5 oder die von Ihnen angegebene cpu-Grenze, je nachdem, welcher Wert kleiner ist.

  • Für memory ist der abgeleitete Wert entweder 0,5 GiB oder die von Ihnen angegebene memory-Grenze, je nachdem, welcher Wert kleiner ist.

• Wenn keine Ressourcengrenze (CPU, Speicher oder beides) angegeben wird, setzt Snowflake die Grenzen auf die Knotenkapazität für die Instanzfamilie des zugehörigen Computepools.

• Wenn Sie resource.limits zur Verfügung stellen und diese die Knotenkapazität überschreiten, wird Snowflake die Grenze auf die Knotenkapazität begrenzen.

• Snowflake wertet diese Ressourcenanforderungen unabhängig voneinander für cpu und memory aus.

Beachten Sie, dass CREATE SERVICE fehlschlägt, wenn es für Snowflake theoretisch unmöglich ist, den Dienst auf dem angegebenen Computepool zu planen. Wenn es theoretisch unmöglich ist, wird davon ausgegangen, dass der Computepool über die maximale Anzahl von Knoten verfügt und es keine anderen Dienstes auf dem Computepool ausgeführt werden. Das heißt, dass Snowflake die angefragten Ressourcen nicht innerhalb der Grenzen des Computepools zuweisen kann. Wenn es theoretisch möglich ist, aber die erforderlichen Ressourcen bereits genutzt werden, wird CREATE SERVICE erfolgreich sein. Einige Dienstinstanzen melden einen Status, der besagt, dass der Dienst aufgrund unzureichender Ressourcen nicht geplant werden kann, bis die Ressourcen verfügbar sind.

Beispiel 1

In der folgenden Spezifikation beschreibt das Feld containers.resources die Ressourcenanforderungen für den Container:

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

In diesem Beispiel wird Snowflake aufgefordert, dem Container mindestens 2 GB Arbeitsspeicher, eine GPU und einen halben CPU-Kern zuzuweisen. Gleichzeitig darf der Container nicht mehr als 4 GB Arbeitsspeicher und eine GPU verwenden.

Beispiel 2

Nehmen Sie an:

• Sie erstellen einen Computepool mit zwei Knoten; jeder Knoten verfügt über 27 GB Arbeitsspeicher und einen GPU:

  CREATE COMPUTE POOL tutorial_compute_pool
    MIN_NODES = 2
    MAX_NODES = 2
    INSTANCE_FAMILY = gpu_nv_s
  

  Copy

• Sie erstellen einen Dienst, der Snowflake auffordert, zwei Instanzen des Dienstes auszuführen:

  CREATE SERVICE echo_service
    MIN_INSTANCES=2
    MAX_INSTANCES=2
    IN COMPUTE POOL tutorial_compute_pool
    FROM @<stage_path>
    SPEC=<spec-file-stage-path>;
  

  Copy

  Sowohl MIN_INSTANCES als auch MAX_INSTANCES werden auf 2 gesetzt. Daher wird Snowflake zwei Instanzen des Dienstes ausführen.

Betrachten Sie nun diese Szenarien:

• Wenn Ihr Dienst nicht ausdrücklich Anforderungen an die Ressourcen in Ihrer Anwendungsspezifikation enthält, entscheidet Snowflake, ob diese Instanzen auf demselben Knoten oder auf verschiedenen Knoten im Computepool ausgeführt werden.

• Sie nehmen die Anforderungen an die Ressourcen in die Dienstspezifikation auf und fragen 10 GB Speicher für den Container an:

  - name: resource-test
    image: ...
    resources:
      requests:
        memory: 15G
  

  Copy

  Ihr Computepool-Knoten verfügt über 27 GB Arbeitsspeicher, wobei Snowflake nicht zwei Container auf demselben Knoten ausführen kann. Snowflake führt die beiden Dienstinstanzen auf separaten Knoten im Computepool aus.

• Sie nehmen die Anforderungen an die Ressourcen in die Dienstspezifikation auf und fragen 1 GB Speicher und einen GPU für den Container an:

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

  Copy

  Sie fordern eine GPU pro Container an, und jeder Knoten hat nur eine GPU. In diesem Fall kann Snowflake nicht beide Dienstinstanzen auf einem Knoten planen, obwohl der Speicher kein Problem darstellt. Diese Anforderung zwingt Snowflake dazu, die beiden Dienstinstanzen auf zwei separaten Computepool-Knoten auszuführen.

Feld containers.secrets¶

secrets:                                # optional list
  - snowflakeSecret:
      objectName: <object-name>         # specify this or objectReference
      objectReference: <reference-name> # specify this or objectName
    directoryPath: <path>               # specify this or envVarName
    envVarName: <name>                  # specify this or directoryPath
    secretKeyRef: username | password | secret_string # specify only with envVarName
  - snowflakeSecret: <object-name>      # equivalent to snowflakeSecret.objectName
    ...

Verwenden Sie das Feld containers.secrets in Ihrer Dienstspezifikation, um von Snowflake verwaltete Anmeldeinformationen für Ihre Anwendungscontainer bereitzustellen. Beginnen Sie mit der Speicherung der Anmeldeinformationen in Snowflake-Geheimnisobjekten. Dann verweisen Sie in der Dienstspezifikation auf das geheime Objekt und geben an, wo die Anmeldeinformationen im Container abgelegt werden sollen.

Im Folgenden finden Sie eine Zusammenfassung der Verwendung der Felder von containers.secrets:

• Snowflake-Geheimnis angeben: Verwenden Sie das Feld snowflakeSecret, um entweder den Namen eines geheimen Snowflake-Objekts oder eine Objektreferenz anzugeben. Objektreferenzen sind anwendbar, wenn Sie Snowpark Container Services verwenden, um eine Native App (eine App mit Containern) zu erstellen.

  • Verwenden Sie secretKeyRef, um den Namen des Schlüssels im Snowflake-Geheimnis anzugeben.

• Bestimmen Sie die Platzierung des Geheimnisses im Anwendungscontainer: Verwenden Sie das Feld envVarName, um das Geheimnis als Umgebungsvariable zu übergeben, oder directoryPath, um die Geheimnisse in lokale Container-Dateien zu schreiben.

Weitere Informationen dazu finden Sie unter Übergabe von Anmeldeinformationen an einen Container mit Snowflake-Geheimnissen.

Beachten Sie, dass die Rolle, die den Dienst erstellt (Eigentümerrolle), die Berechtigung READ für die referenzierten Geheimnisse benötigt.

Allgemeine Informationen zu unterstützten Volume-Typen¶

Snowflake unterstützt die folgenden Volume-Typen für Anwendungscontainer: lokal, Arbeitsspeicher, Block und Snowflake-Stagingbereich.

• Lokales Volume: Container in einer Dienstinstanz können einen lokalen Datenträger zur Freigabe von Dateien verwenden. Wenn Ihre Anwendung beispielsweise aus zwei Containern besteht – einem Anwendungscontainer und einem Protokollanalysator – kann die Anwendung Protokolle in das lokale Volume schreiben, und der Protokollanalysator kann die Protokolle lesen.

  Wenn Sie mehrere Instanzen eines Dienstes ausführen, müssen Sie beachten, dass nur Container, die zu einer Dienstinstanz gehören, Volumes gemeinsam nutzen können. Container, die zu verschiedenen Dienstinstanzen gehören, können Volumes nicht gemeinsam verwenden.

• Arbeitsspeicher: Sie können ein RAM-gestütztes Dateisystem für die Verwendung im Container verwenden.

• Block: Container können auch Blockspeicher-Volumes verwenden. Weitere Informationen dazu finden Sie unter Verwenden von Blockspeicher-Volumes mit Diensten.

• Snowflake-Stagingbereich: Sie können Containern auch bequemen Zugriff auf Dateien in einem Snowflake-Stagingbereich Ihres Kontos geben. Weitere Informationen dazu finden Sie unter Snowflake-Stagingbereiche mit Diensten verwenden.

Beispiel

Ihre Anwendung für maschinelles Lernen umfasst die folgenden zwei Container:

• Container app für die Hauptanwendung

• Container logger-agent, der Protokolleinträge sammelt und sie zu Amazon S3 hochlädt

Diese Container verwenden die folgenden zwei Volumes:

• Volume local: Diese Anwendung schreibt Protokolleinträge, die der Logger-Agent liest.

• Snowflake-Stagingbereich @model_stage: Die Hauptanwendung liest Dateien aus diesem Stagingbereich.

In der folgenden Beispielspezifikation bindet der Container app sowohl das Volume logs als auch das Volume models ein, und der Container logging-agent bindet nur das Volume logs ein:

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

Wenn mehrere Instanzen des Dienstes ausgeführt werden, verwenden die Container logging-agent und app innerhalb einer Dienstinstanz das Volume logs gemeinsam. Das Volume logs ist nicht für mehrere Dienstinstanzen freigegeben.

Wenn Ihr app-Container zusätzlich zu diesen Volumes auch ein 2-GB-Arbeitsspeicher-Volume verwendet, überarbeiten Sie die Spezifikation, um das Volume in die volumes-Liste aufzunehmen, und fügen Sie außerdem eine weitere Volume-Bereitstellung in die volumeMounts-Liste des app-Containers ein:

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

Wenn Sie memory als Volume source angeben, müssen Sie auch das Feld volumes.size spezifizieren, um die Größe des Arbeitsspeichers anzugeben. Weitere Informationen zu den Größeneinheiten für Arbeitsspeicher, die Sie verwenden können, finden Sie unter Allgemeine Informationen zu Maßeinheiten.

Über Berechtigungen für Dateien auf gemounteten Volumes¶

Ein Container, der einen Snowflake-Stagingbereich oder ein Blockspeicher-Volume einbindet, wird normalerweise als Root-Benutzer ausgeführt. Es kann jedoch vorkommen, dass Ihr Container als Nicht-Root-Benutzer ausgeführt wird. Beispiel:

• Wenn Ihre Anwendung eine Drittanbieter-Bibliothek verwendet, benutzt die Bibliothek einen Nicht-Root-Benutzer, um den Anwendungscode innerhalb des Containers auszuführen.

• Sie können Ihre Anwendung auch aus anderen Gründen, z. B. aus Sicherheitsgründen, als Nicht-Root-Benutzer innerhalb des Containers ausführen.

Um mögliche Fehler im Zusammenhang mit den Dateibenutzerrechten zu vermeiden, ist es wichtig, die UID (Benutzer-ID) und GID (Gruppen-ID) des Containers als Teil der Spezifikation festzulegen. Dies ist besonders wichtig für Container, die einen bestimmten Benutzer und eine bestimmte Gruppe zum Starten oder Ausführen der Anwendung innerhalb des Containers verwenden. Durch Festlegen der entsprechenden UID und GID können Sie einen Container verwenden, der als ein Nicht-Root-Benutzer ausgeführt wird. Beispiel:

spec:
  ...

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

Snowflake verwendet diese Informationen, um den Stagingbereich mit den entsprechenden Berechtigungen einzubinden.

Um die UID und GID des Containers zu erhalten, gehen Sie wie folgt vor:

1. Führen Sie den Container lokal mit docker run aus.

2. Suchen Sie die Container-ID mit dem Befehl docker container list. Hier ist ein Ausschnitt einer Beispielausgabe:

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

3. Führen Sie den Befehl docker id innerhalb des Containers aus, um die Werte von UID und GID zu erhalten:

   docker exec -it <container-id> id
   

   Copy

   Beispielausgabe:

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