Referenz der Dienstspezifikation¶

Allgemeine Richtlinien¶

Eine Dienst-/Jobspezifikation hat auf oberster Ebene die folgenden spec-Felder:

• spec.containers (erforderlich): Eine Liste von einem oder mehreren Anwendungscontainern. Ihre containerisierte Anwendung muss mindestens einen Container haben.

• spec.endpoints (optional): Eine Liste der Endpunkte, die der Dienst öffentlich bereitstellt. Sie können einen öffentlichen Endpunkt wählen, der den Netzwerkzugang (Eingehende Daten) zum Dienst ermöglicht.

• spec.volumes (optional): Eine Liste von Speichervolumes, die von den Containern verwendet werden sollen.

• spec.logExporters (optional): Dieses Feld verwaltet die Ebene der Containerprotokolle, die in die Ereignistabelle Ihres Kontos exportiert werden.

Für die name-Felder (Container-, Endpunkt- und Volume-Namen) gelten die folgenden Formatrichtlinien:

• Kann bis zu 63 Zeichen lang sein

• Kann eine Sequenz von alphanumerischen Kleinbuchstaben oder „-“-Zeichen enthalten

• Muss mit einem alphabetischen Zeichen beginnen

• Muss mit einem alphanumerischen Zeichen enden

In den folgenden Abschnitten werden die einzelnen spec-Felder der obersten Ebene erläutert.

Feld spec.containers (erforderlich)¶

Das Feld containers enthält eine Liste der OCI-Container in Ihrer Anwendung. Für jeden Container sind nur die Felder name und image Pflichtfelder. Das Feld 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

Wenn Sie einen Dienst (oder einen Job) erstellen, führt Snowflake diese Container auf einem Einzelknoten im angegebenen Computepool aus, der dieselbe Netzwerkschnittstelle nutzt. Sie können mehrere Dienstinstanzen ausführen; in diesem Fall wird jeder Satz dieser Container als Dienstinstanz bezeichnet.

In den folgenden Abschnitten werden die Typen von containers-Feldern erläutert.

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

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

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

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

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

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

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

secrets:                            # optional list
  - snowflakeSecret:
    secretKeyRef:
    envVarName:                      # specify this or directoryPath
    directoryPath:                   # specify this or envVarName

Feld spec.endpoints (optional)¶

Verwenden Sie das Feld spec.endpoints, um eine Liste von Namen für die TCP-Netzwerkports anzugeben, die Ihre Anwendung öffentlich bereitstellt. Snowpark Container Services können null bis viele Endpunkte bereitstellen. Verwenden Sie die folgenden Felder, um einen Endpunkt zu beschreiben:

• name: Eindeutiger Name des Endpunkts. Wenn Sie sich in einer Dienstfunktion auf den Endpunkt beziehen, geben Sie diesen Namen an.

• port: Der Netzwerkport, den Ihre Anwendung auf Anforderungen hin überwacht.

• protocol: Das Protokoll, das der Endpunkt unterstützt. Folgende Werte werden unterstützt: TCP, HTTP und HTTPS. Das Standardprotokoll ist HTTP. Das Protokoll muss HTTP oder HTTPS sein, wenn dieser Endpunkt öffentlich oder das Ziel einer Dienstfunktion ist (siehe Verwenden eines Dienstes).

• public: Wenn dieser Endpunkt über das Internet zugänglich sein soll, setzen Sie dieses Feld auf true.

Beispiel

Im Folgenden finden Sie die Anwendungsspezifikation, die in Tutorial 1 verwendet wird:

spec:
  container:
  - name: echo
    image: <image-name>
    env:
      SERVER_PORT: 8000
      CHARACTER_NAME: Bob
    readinessProbe:
      port: 8000
      path: /healthcheck
  endpoint:
  - name: echoendpoint
    port: 8000
    public: true

Dieser Anwendungscontainer stellt einen Endpunkt öffentlich zur Verfügung. Der Container enthält auch das optionale Feld public, um den Zugriff auf den Endpunkt von außerhalb von Snowflake (Internetzugang) zu ermöglichen. Standardmäßig ist public auf false eingestellt.

Feld spec.volumes (optional)¶

Dieser Abschnitt erklärt die beiden Felder spec.volumes und spec.containers.volumeMounts. volumes definiert ein freigegebenes Dateisystem. Der Wert von volumeMount definiert, wo ein Volume in einem Container erscheint. Mehrere Container können das gleiche Volume gemeinsam nutzen. Daher ist volumes ein Feld auf spec-Ebene, und volumeMount ist Teil einer Container-Spezifikation.

Verwenden Sie diese Felder, um sowohl die Volumes als auch die Volumebereitstellungen zu beschreiben.

• Verwenden Sie spec.volumes, um die für Ihre Container verfügbaren Volumes anzugeben. volumes ist eine Liste. Das heißt, es kann mehrere Volumes geben. Verwenden Sie die folgenden Felder, um ein Volume zu beschreiben:

  • name: Eindeutiger Name des Volumes. Er wird mit spec.containers.volumeMounts.name bezeichnet.

  • source: Dies kann local, memory oder "@<stagename>" sein.

  • uid: Bei einem Snowflake-Stagingbereichs-Volume ist dies die „uid“ der eingebundenen Datei.

  • gid: Bei einem Snowflake-Stagingbereichs-Volume ist dies die „gid“ der eingebundenen Datei.

  • size: Bei einem Arbeitsspeicher-Volume ist dies die Größe des Volumes.

• Verwenden Sie spec.containers.volumeMounts, um anzugeben, wo die angegebenen Volumes im Dateisystem des Containers eingebunden sind. containers.volumeMounts ist ebenfalls eine Liste. Das heißt, jeder Container kann mehrere Volume-Bereitstellungen haben. Verwenden Sie die folgenden Felder, um eine Volume-Bereitstellung zu beschreiben:

  • name: Der Name des einzubindenden Volumes. Ein einzelner Container kann mehrfach auf dasselbe Volume verweisen.

  • mountPath: Der Dateipfad, unter dem das Volume für den Container eingebunden werden soll.

Snowflake unterstützt die folgenden Volume-Typen für Anwendungscontainer: lokale Volumes, Arbeitsspeicher 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.

• Snowflake-Stagingbereich: Sie können einen Snowflake-Stagingbereich erstellen und damit Containern schnellen Zugriff auf bereitgestellte Stagingdateien geben. Für das Einbinden eines Snowflake-Stagingbereichs gelten die folgenden Bedingungen:

  • Externe Stagingbereiche werden nicht unterstützt. Es werden nur interne Snowflake-Stagingbereiche mit SSE-Verschlüsselung (siehe Interne Stagingbereichsparameter) unterstützt. Verwenden Sie CREATE STAGE, um einen solchen Stagingbereich zu erstellen:

    CREATE STAGE my_stage ENCRYPTION = (type = 'SNOWFLAKE_SSE');
    

    Copy

  • Sie können einen Stagingbereich, z. B. @my_stage, oder ein Unterverzeichnis in einem Stagingbereich, z. B. @my_stage/folder, einbinden. Sie können aber keine Datei in einem Stagingbereich, z. B. @my_stage/folder/file, einbinden.

  • Die Dienstrolle bestimmt die Berechtigungen, die Containern für den Zugriff auf einen eingebundenen Stagingbereich erteilt werden. Die Dienstrolle ist die Rolle, mit der der Dienst oder Job erstellt wird. Es ist auch die Rolle, die von Dienst oder Job für alle Snowflake-Interaktionen verwendet.

    Wenn die Dienstrolle beispielsweise nicht über die WRITE-Berechtigung für einen Stagingbereich verfügt, ist die Einbindung dieses Stagingbereichs schreibgeschützt. Das heißt, die Container können die Dateien nur aus dem Stagingbereich lesen. Wenn die Dienstrolle die WRITE-Berechtigung für einen Stagingbereich hat, unterstützt die Einbindung dieses Stagingbereich sowohl das Lesen als auch das Schreiben. Snowflake lädt Dateiaktualisierungen asynchron hoch.

  • Ein Container, der einen Snowflake-Stagingbereich 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 die 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>
      

      Copy

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

      So erhalten Sie die UID und GID des Containers:

      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)
         

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.

Feld spec.logExporters (optional)¶

Verwenden Sie spec.logExporters, um zu konfigurieren, wie Snowflake Ihre Anwendungsprotokolle erfasst. Snowflake erfasst die Ausgaben des Codes Ihres Anwendungscontainers, die an die Standardausgabe oder den Standardfehler gehen.

Snowflake exportiert diese Protokolleinträge in eine Ereignistabelle in Ihrem Konto. Weitere Informationen dazu finden Sie unter Zugriff auf lokale Containerprotokolle. Geben Sie mit spec.logExporters.eventTableConfig an, welche Protokolle in der Ereignistabelle gespeichert werden sollen:

logExporters:
  eventTableConfig:
    logLevel: < INFO | ERROR | NONE >

Folgende logLevel-Werte werden unterstützt:

• INFO: Alle Benutzerprotokolleinträge exportieren.

• ERROR: Nur Fehlerprotokolleinträge exportieren. Snowflake exportiert nur die Protokolle aus dem „stderr“-Stream.

• NONE (Standard): Es werden keine Protokolleinträge in die Ereignistabelle exportiert.

Allgemeine Informationen zu Maßeinheiten¶

Eine Dienstspezifikation enthält an mehreren Stellen numerische Werte. Snowpark Container Services unterstützt eine Vielzahl von Einheiten, um diese Werte auszudrücken. Für große und kleine Werte können Sie, wie gezeigt, binäre und dezimale Maßeinheiten verwenden. In der folgenden Liste steht „#“ für einen Ganzzahlwert (Integer).

• Binäreinheiten:

  • numberKi bedeutet number*1024. Beispielsweise ist memory: 4Ki äquivalent zu memory: 4096.

  • numberMi bedeutet number*1024^2.

  • numberGi bedeutet number*1024^3.

• Dezimaleinheiten:

  • numberk bedeutet number*10^3. Beispielsweise ist memory: 4k äquivalent zu memory: 4000.

  • numberM bedeutet number*10^6.

  • numberG bedeute number*10^9.

• Bruchteileinheiten:

  • numberm bedeutet number*0.001. Beispielsweise ist cpu: 500m äquivalent zu cpu: 0.5.