서비스 사양 참조¶

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와 같습니다. 500m으로 표현될 수도 있는 0.5와 같은 분수 요청이 허용됩니다.

• nvidia.com/gpu: GPU가 필요한 경우 이를 요청해야 하며, 동일한 수량에 대해 지정된 limit 도 있어야 합니다. 컨테이너가 GPU 용량에 대한 요청과 제한을 지정하지 않으면 어떤 GPU에도 액세스할 수 없습니다. 요청할 수 있는 GPUs의 수는 컴퓨팅 풀 을 생성할 때 선택한 INSTANCE_TYPE 이 지원하는 최대 GPUs에 의해 제한됩니다.

resource.requests 및 resource.limits 는 연결된 컴퓨팅 풀 에 대한 인스턴스 제품군의 노드 용량(vCPU 및 메모리)에 상대적입니다.

• 리소스 요청(CPU, 메모리 또는 둘 다)이 제공되지 않으면 Snowflake가 사용자를 대신하여 해당 리소스에 대한 한도를 도출합니다.

  • cpu 의 경우 도출된 값은 0.5 또는 공급자가 제공한 cpu 한도 중 더 작은 값입니다.

  • memory 의 경우 도출된 값은 0.5GiB 또는 공급자가 제공한 memory 한도 중 더 작은 값입니다.

• 리소스 제한(CPU, 메모리 또는 둘 다)이 제공되지 않는 경우, 관련 컴퓨팅 풀 의 인스턴스 제품군에 대한 노드 용량에 대한 한도가 기본값으로 설정됩니다.

• 사용자가 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는 컨테이너에 대해 최소 2GB 메모리, GPU 1개, 하프 CPU 코어를 할당하라는 요청을 받습니다. 그와 동시에 컨테이너가 4GB 이상의 메모리와 하나의 GPU를 사용할 수는 없습니다.

예 2

가정:

• 두 개의 노드로 구성된 컴퓨팅 풀을 생성하고, 각 노드에는 27 GB의 메모리와 1GPU의 메모리가 있습니다.

  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

  컨테이너당 GPU 1개를 요청하고 있으며 각 노드에는 GPU가 1개만 있습니다. 이 경우 메모리는 문제가 되지 않지만 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를 사용하여 Native App(컨테이너가 포함된 앱)을 생성할 때는 오브젝트 참조가 적용됩니다.

  • 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 컨테이너가 2GB 메모리 볼륨도 사용하는 경우 사양을 수정하여 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)