服务规范参考¶

containers.name 和 containers.image 字段¶

对于每个容器，仅名称和镜像是必填字段。

• name 是镜像名称。此名称可以用来识别特定的容器，以便进行可观察性操作（例如，日志、指标）。

• image 是您上传到 Snowflake 账户中 Snowflake 镜像仓库的镜像的名称。

例如：

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

containers.command 和 containers.args 字段¶

使用这些可选字段，控制容器中启动的可执行文件以及传递给该可执行文件的实参。您可以在创建镜像时配置这些字段的默认值，通常在 Dockerfile 中进行配置。使用这些服务规范字段，您可以更改这些默认值（从而改变容器行为），而无需重建容器镜像：

• containers.command 可替换 Dockerfile ENTRYPOINT。这允许您在容器中运行不同的可执行文件。

• containers.args 可替换 Dockerfile CMD。这允许您为命令（可执行文件）提供不同的实参。

示例

Dockerfile 包括以下代码：

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

这些 Dockerfile 条目执行 python3 命令并传递两个实参：main.py 和 Bob。您可按如下方式替换规范文件中的这些值：

• 要替换 ENTRYPOINT，请在规范文件中添加 containers.command 字段：

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

  Copy

• 要替换实参“Bob”，请在规范文件中添加 containers.args 字段：

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

  Copy

containers.env 字段¶

使用 containers.env 字段定义容器环境变量。容器中的所有进程都可以访问以下环境变量：

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

示例

在 教程 1 中，应用程序代码 (echo_service.py) 读取环境变量，如下所示：

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

请注意，该示例将变量的默认值传递给 getenv 函数。如果未定义环境变量，则使用这些默认值。

• CHARACTER_NAME：当 Echo 服务收到带字符串（例如，“Hello”）的 HTTP POST 请求时，服务默认返回“I said Hello”。 您可在规范文件中覆盖此默认值。例如，将值设置为“Bob”，则 Echo 服务会返回“Bob said Hello”的响应。

• SERVER_PORT：在此默认配置中，Echo 服务监听端口 8080。您可以替换该默认值并指定另一端口。

以下服务规范将替换这两个环境变量值：

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

请注意，由于您更改了服务监听的端口号，因此规范也必须更新端点（endpoints.port field 值），如上所示。

containers.readinessProbe 字段¶

使用 containers.readinessProbe 字段识别应用程序中的就绪探针。Snowflake 调用此探测以确定应用程序何时准备好处理请求。

Snowflake 在指定的端口和路径上向指定的就绪情况探测发出 HTTP GET 请求，并查找您的服务以返回 HTTP 200 OK 状态，以确保只有正常运行的容器才能提供流量。

使用以下字段提供所需信息：

• port：服务正在监听就绪情况探测请求的网络端口。您无需将此端口声明为端点。

• path：Snowflake 使用此路径向服务发出 HTTP GET 请求。

示例

在教程 1 中，应用程序代码 (echo_python.py) 实现以下就绪情况探测：

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

因此，规范文件包括 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

就绪情况探测指定的端口可以不是已配置的端点。服务可以仅出于就绪情况探测的目的来监听不同的端口。

containers.volumeMounts 字段¶

因为 spec.volumes 和 spec.containers.volumeMounts 字段是一起使用的，所以将在一个小节中一起介绍它们。有关更多信息，请参阅 spec.volumes 字段（可选）。

containers.resources 字段¶

计算池定义一组可用资源（CPU、内存和存储），Snowflake 确定在计算池的什么位置运行服务。

建议您在规范中明确指出特定容器的资源需求，并设置适当的限制。请注意，您指定的资源受到计算池中节点的实例系列的约束。有关更多信息，请参阅 CREATE COMPUTE POOL。

使用 containers.resources 字段来指定特定应用程序容器的明确资源要求：

• containers.resources.requests：您指定的请求应是您预计的服务的平均资源使用量。Snowflake 使用此信息来确定服务实例在计算池中的位置。 Snowflake 确保在给定节点上放置的资源请求的总和不会超过节点上的可用资源。

• containers.resources.limits：您指定的限制指示 Snowflake 不分配超过指定限制的资源。因此，您可以防止成本超支。

您可以为以下资源指定请求和限制：

• memory：这是应用程序容器所需的内存。您可以使用 小数或二进制单位 来表示值。例如，2G 表示请求 2,000,000,000 个字节，而 2Gi 表示请求 2 x 1024 x 1024 x 1024 个字节。

  指定内存时，单位是必填项。例如，100M 或 5Gi。支持的单位有：M、Mi、G、Gi。

• cpu：这是指虚拟核心 (vCPU) 单位。例如，1 个 CPU 单位相当于 1 个 vCPU。允许小数请求，例如 0.5，也可表示为 500m。

• nvidia.com/gpu：如果需要 GPUs，则必须请求它们，并且对于相同的数量也必须指定 limit。如果容器未指定 GPU 容量的请求和限制，则它无法访问任何 GPUs。您可请求的 GPUs 的数量由您在创建 计算池 时选择的 INSTANCE_TYPE 所支持的最大 GPUs 数量限制。

resource.requests 和 resource.limits 与关联的 计算池 的实例系列的节点容量（vCPU 和内存）有关。

• 如果没有提供资源需求（CPU、内存或两者），Snowflake 会为您派生一个：

  • For cpu, the derived value is either 0.5 or the cpu limit you provided, whichever is greater.

  • For memory, the derived value is either 0.5 GiB or the memory limit you provided, whichever is greater.

• 如果未提供资源限制（CPU、内存或两者），Snowflake 默认会将限制设置为相关 计算池 的实例系列的节点容量。

• 如果您提供 resource.limits 并且超出了节点容量，Snowflake 将设置节点容量上限。

• Snowflake 独立评估 cpu 和 memory 的资源需求。

请注意，如果 Snowflake 理论上无法在给定的计算池上安排服务，CREATE SERVICE 将会失败。理论上不可能假设计算池具有允许的最大节点数，并且计算池上没有运行其他服务。也就是说，Snowflake 无法在计算池限制内分配请求的资源。如果理论上可行，但所需资源正在使用中，那么 CREATE SERVICE 将会成功。一些服务实例会报告状态，表明由于资源不足，无法安排服务，直到资源可用为止。

示例 1

在以下规范中，containers.resources 字段描述容器的资源需求：

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

在此示例中，要求 Snowflake 为容器至少分配 2 个 GB 内存，1 个 GPU 和 0.5 个 CPU 核心。同时，不允许容器使用超过 4 个 GB 内存和 1 个 GPU。

示例 2

假设：

• 创建包含两个节点的计算池；每个节点有 27 GB 内存和 1 个 GPU：

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

  Copy

• 您创建一个服务，该服务要求 Snowflake 运行该服务的两个实例：

  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

  将 MIN_INSTANCES 和 MAX_INSTANCES 均设置为 2。因此，Snowflake 将运行该服务的两个实例。

现在，考虑以下场景：

• 如果服务未在应用程序规范中明确包含资源需求，那么 Snowflake 将决定是在计算池中的同一节点还是不同节点上运行这些实例。

• 您确实在服务规范中包含了资源要求，并为容器请求 10 GB 内存。

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

  Copy

  计算池节点有 27 GB 内存，并且 Snowflake 无法在同一节点上运行两个容器。Snowflake 将在计算池中的不同节点上运行这两个服务实例。

• 您在服务规范中包含资源要求，并为容器请求 1 GB 内存和 1 个 GPU：

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

  Copy

  您正在为每个容器请求 1 个 GPU，并且每个节点只有 1 个 GPU。在这种情况下，尽管内存不是问题，但 Snowflake 无法在一个节点上安排两个服务实例。此需求迫使 Snowflake 在两个单独的计算池节点上运行两个服务实例。

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

在服务规范中使用 containers.secrets 字段，为应用程序容器提供 Snowflake 管理的凭据。首先将凭据存储在 Snowflake 密钥 对象中。然后，在服务规范中，引用密钥对象并指定在容器内放置凭据的位置。

以下是关于如何使用 containers.secrets 字段的摘要：

• 指定 Snowflake 密钥： 使用 snowflakeSecret 字段指定 Snowflake 密钥对象名称或对象引用。对象引用在使用 Snowpark Container Services 创建原生应用程序（带容器的应用程序）时适用。

  • 使用 secretKeyRef 提供 Snowflake 密钥中密钥的名称。

• 在应用程序容器中指定密钥位置： 使用 envVarName 字段以环境变量或 directoryPath 形式传递密钥，或将密钥写入本地容器文件。

有关更多信息，请参阅 使用 Snowflake 密钥将凭据传递到容器。

请注意，创建服务的角色（所有者角色）需要对引用的密钥具有 READ 权限。

关于支持的卷类型¶

Snowflake 支持应用程序容器使用以下这些卷类型：本地、内存、块和 Snowflake 暂存区。

• 本地卷： 服务实例中的容器可使用本地磁盘来共享文件。例如，如果应用程序有两个容器 – 一个应用程序容器和一个日志分析器，则应用程序可将日志写入本地卷，而日志分析器可读取日志。

  请注意，如果您正在运行一个服务的多个实例，则只有属于一个服务实例的容器才能共享卷。属于不同服务实例的容器不共享卷。

• 内存： 您可以使用 RAM 支持的文件系统供容器使用。

• 块： 容器也可以使用块存储卷。有关更多信息，请参阅 将块存储卷与服务一起使用。

• Snowflake 暂存区： 您还可以让容器方便访问账户中 Snowflake 暂存区上的文件。有关更多信息，请参阅 将 Snowflake 暂存区卷与服务搭配使用。

示例

机器学习应用程序包括以下两个容器：

• 一个适用于主应用程序的 app 容器

• 一个收集日志并将其上传到 Amazon S3 的 logger-agent 容器

这些容器使用以下两个卷：

• local 卷：此应用程序写入日志代理读取的日志。

• Snowflake 暂存区 – @model_stage：主应用程序从此暂存区中读取文件。

在以下示例规范中，app 容器挂载 logs 和 models 两个卷，而 logging-agent 容器仅挂载 logs 卷：

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

如果服务的多个实例正在运行，则一个服务实例中的 logging-agent 和 app 容器共享 logs 卷。logs 卷不在服务实例之间共享。

如果除这些卷之外，您的 app 容器还使用一个 2-GB 内存的卷，请修改规范，以将该卷包含在 volumes 列表中，并在 app 容器 volumeMounts 列表中添加另一个卷挂载：

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

请注意，当您指定 memory 作为卷 source 时，您还必须指定 volumes.size 字段来表示内存大小。有关您可以指定的内存大小单位的信息，请参阅 关于单位。

关于挂载卷上的文件权限¶

挂载 Snowflake 暂存区或块存储卷的容器通常以根用户身份运行。但是，有时您的容器可能会以非根用户身份运行。例如：

• 如果应用程序使用第三方库，则该库将使用非根用户在容器内运行应用程序代码。

• 出于安全性等其他原因，您可以在容器内以非根用户身份运行应用程序。

为避免与文件用户权限相关的潜在错误，将容器的 UID（用户 ID）和 GID（组 ID）设置为规范的一部分非常重要。这对于使用特定用户和组在容器内启动或运行应用程序的容器来说，这一点尤为重要。通过设置适当的 UID 和 GID，您可以使用以非根用户身份运行的容器。例如：

spec:
  ...

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

Snowflake 使用此信息以适当的权限挂载暂存区。

要获取容器的 UID 和 GID，请执行以下步骤：

1. 使用 docker run 在本地运行容器。

2. 使用 docker container list 命令查找容器 ID。部分样本输出：

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

3. 在容器内运行 docker id 命令来获取 UID 和 GID：

   docker exec -it <container-id> id
   

   Copy

   示例输出：

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