서비스 사양 참조¶

일반 지침¶

서비스/작업 사양에는 다음과 같은 최상위 spec 필드가 있습니다.

• spec.containers (필수 사항): 하나 이상의 애플리케이션 컨테이너 목록입니다. 컨테이너화된 애플리케이션에는 컨테이너가 하나 이상 있어야 합니다.

• spec.endpoints (선택 사항): 서비스에서 노출하는 엔드포인트의 목록입니다. 서비스에 대한 네트워크 수신 액세스를 허용하는 공용 엔드포인트를 선택할 수 있습니다.

• spec.volumes (선택 사항): 컨테이너에서 사용할 저장소 볼륨 목록입니다.

• spec.logExporters (선택 사항): 이 필드는 계정의 이벤트 테이블로 내보낸 컨테이너 로그 수준을 관리합니다.

name 필드(컨테이너, 엔드포인트 및 볼륨 이름)에는 다음 형식 지침이 적용됩니다.

• 최대 63자까지 가능

• 일련의 소문자 영숫자 또는 ‘-’ 문자를 포함할 수 있음

• 알파벳 문자로 시작해야 함

• 영숫자 문자로 끝나야 함

다음 섹션에서는 각 최상위 spec 필드를 설명합니다.

spec.containers 필드(필수 사항)¶

containers 필드는 애플리케이션의 OCI 컨테이너 목록입니다. 각 컨테이너에 대해 name 및 image 만 필수 항목입니다. image 필드는 Snowflake 계정의 Snowflake 이미지 리포지토리에 업로드한 이미지의 이름을 나타냅니다. 예:

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

서비스(또는 작업)를 생성하면 Snowflake는 지정된 컴퓨팅 풀의 단일 노드에서 이러한 컨테이너를 실행하여 동일한 네트워크 인터페이스를 공유합니다. 여러 서비스 인스턴스를 실행할 수 있으며, 이 경우 실행 중인 이들 컨테이너 세트를 각각 서비스 인스턴스라고 합니다.

다음 섹션에서는 containers 필드의 유형을 설명합니다.

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

spec.endpoints 필드(선택 사항)¶

애플리케이션이 노출하는 TCP 네트워크 포트의 이름 목록을 지정하려면 spec.endpoints 필드를 사용하십시오. Snowpark Container Services는 많은 엔드포인트에 0을 노출할 수 있습니다. 엔드포인트를 설명하려면 다음 필드를 사용하십시오.

• name: 엔드포인트의 고유한 이름입니다. 서비스 함수에서 엔드포인트를 참조할 때 이 이름을 지정합니다.

• port: 애플리케이션이 수신 대기 중인 네트워크 포트입니다.

• protocol: 엔드포인트가 지원하는 프로토콜입니다. 지원되는 값은 TCP, HTTP, HTTPS입니다. 기본적으로 프로토콜은 HTTP입니다. 이 엔드포인트가 공용이거나 서비스 함수의 대상인 경우 프로토콜은 HTTP 또는 HTTPS이어야 합니다(서비스 사용하기 참조).

• public: 이 엔드포인트를 인터넷에서 액세스할 수 있도록 하려면 이 필드를 true 로 설정하십시오.

예

다음은 자습서 1 에서 사용되는 애플리케이션 사양입니다.

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

이 애플리케이션 컨테이너는 하나의 엔드포인트를 노출합니다. 또한 Snowflake 외부에서 엔드포인트에 대한 액세스(인터넷 액세스)를 활성화하는 선택적 public 필드도 포함되어 있습니다. 기본적으로 public 은 false 입니다.

spec.volumes 필드(선택 사항)¶

이 섹션에서는 spec.volumes 및 spec.containers.volumeMounts 필드를 모두 설명합니다. volumes 는 공유 파일 시스템을 정의합니다. volumeMount 는 컨테이너에서 볼륨이 나타나는 위치를 정의합니다. 여러 컨테이너가 동일한 볼륨을 공유할 수 있습니다. 따라서 volumes 는 spec 수준 필드이고 volumeMount 는 컨테이너 사양의 일부입니다.

이들 필드를 사용하여 볼륨과 볼륨 탑재를 모두 설명합니다.

• spec.volumes 를 사용하여 컨테이너에 사용 가능한 볼륨을 지정합니다. volumes 는 목록입니다. 즉, 여러 볼륨이 있을 수 있습니다. 다음 필드를 사용하여 볼륨을 설명합니다.

  • name: 볼륨의 고유한 이름입니다. spec.containers.volumeMounts.name 에서 이를 참조합니다.

  • source: local, memory 또는 "@<stagename>" 일 수 있습니다.

  • uid: Snowflake 스테이지 볼륨의 경우 탑재된 파일의 uid입니다.

  • gid: Snowflake 스테이지 볼륨의 경우 탑재된 파일의 gid입니다.

  • size: 메모리 볼륨의 경우 볼륨의 크기입니다.

• spec.containers.volumeMounts 를 사용하여 컨테이너의 파일 시스템에서 지정된 볼륨이 탑재되는 위치를 나타냅니다. containers.volumeMounts 역시 목록입니다. 즉, 각 컨테이너에 여러 개의 볼륨 탑재가 있을 수 있습니다. 다음 필드를 사용하여 볼륨 탑재를 설명합니다.

  • name: 탑재할 볼륨의 이름입니다. 단일 컨테이너가 동일한 볼륨을 여러 번 참조할 수 있습니다.

  • mountPath: 컨테이너 볼륨을 탑재해야 하는 파일 경로입니다.

Snowflake는 애플리케이션 컨테이너가 사용할 볼륨 유형(로컬 볼륨, 메모리, Snowflake 스테이지)을 지원합니다.

• 로컬 볼륨: 서비스 인스턴스의 컨테이너는 로컬 디스크를 사용하여 파일을 공유할 수 있습니다. 예를 들어 애플리케이션에 두 개의 컨테이너(애플리케이션 컨테이너와 로그 분석기)가 있는 경우 애플리케이션은 로컬 볼륨에 로그를 쓸 수 있고 로그 분석기는 로그를 읽을 수 있습니다.

  서비스의 여러 인스턴스를 실행하는 경우 서비스 인스턴스에 속한 컨테이너만 볼륨을 공유할 수 있습니다. 서로 다른 서비스 인스턴스에 속하는 컨테이너는 볼륨을 공유하지 않습니다.

• 메모리: 컨테이너 사용을 위해 RAM 지원 파일 시스템을 사용할 수 있습니다.

• Snowflake 스테이지: Snowflake 스테이지를 생성하고 컨테이너가 스테이징된 파일에 편리하게 액세스할 수 있도록 할 수 있습니다. Snowflake 스테이지를 탑재할 때 다음 조건이 적용됩니다.

  • 외부 스테이지는 지원되지 않습니다. SSE 암호화를 사용하는 Snowflake 내부 스테이지(내부 스테이지 매개 변수 참조)만 지원됩니다. 다음과 같은 스테이지를 만들려면 CREATE STAGE 를 사용하십시오.

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

    Copy

  • 스테이지 또는 하위 디렉터리(예: @my_stage, @my_stage/folder)를 스테이지에 탑재할 수 있습니다. 스테이지에 파일(예: @my_stage/folder/file)을 탑재할 수 없습니다.

  • 서비스 역할에 따라 탑재된 스테이지에 액세스하기 위해 컨테이너에 부여되는 권한이 결정됩니다. 서비스 역할은 서비스/작업을 생성하는 데 사용되는 역할입니다. 또한 서비스/작업이 모든 Snowflake 상호 작용에 사용하는 역할이기도 합니다.

    예를 들어 서비스 역할에 스테이지에 대한 WRITE 권한이 없으면 해당 스테이지에 대한 탑재는 읽기 전용이 됩니다. 즉, 컨테이너는 스테이지의 파일만 읽을 수 있습니다. 서비스 역할에 스테이지에 대한 WRITE 권한이 있는 경우 해당 스테이지에 대한 탑재는 읽기 및 쓰기를 모두 지원합니다. Snowflake는 파일 업데이트를 비동기적으로 업로드합니다.

  • Snowflake 스테이지를 탑재하는 컨테이너는 일반적으로 루트 사용자로 실행됩니다. 그러나 때로는 컨테이너가 루트가 아닌 사용자로 실행될 수도 있습니다. 예:

    • 애플리케이션이 서드 파티 라이브러리를 사용하는 경우 라이브러리는 루트가 아닌 사용자를 사용하여 컨테이너 내에서 애플리케이션 코드를 실행합니다.

    • 보안과 같은 다른 이유로 인해 컨테이너 내부에서 루트가 아닌 사용자로 애플리케이션을 실행할 수도 있습니다.

      파일 사용자 권한과 관련된 잠재적인 오류를 방지하려면 컨테이너의 UID(사용자 ID) 및 GID(그룹 ID)를 사양의 일부로 설정하는 것이 중요합니다. 이는 특히 컨테이너 내에서 애플리케이션을 시작하거나 실행하기 위해 특정 사용자와 그룹을 사용하는 컨테이너와 관련이 있습니다. 적절한 UID 및 GID를 설정하면 루트가 아닌 사용자로 실행되는 컨테이너를 사용할 수 있습니다. 예:

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

      Copy

      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)
         

예

머신 러닝 애플리케이션에는 다음 두 가지 컨테이너가 포함되어 있습니다.

• 주 애플리케이션용 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 필드도 지정해야 합니다. 지정할 수 있는 메모리 크기 단위에 대한 자세한 내용은 단위 정보 섹션을 참조하십시오.

spec.logExporters 필드(선택 사항)¶

spec.logExporters 를 사용하여 Snowflake가 애플리케이션 로그를 수집하는 방법을 구성합니다. Snowflake는 애플리케이션 컨테이너의 코드부터 표준 출력 또는 표준 오류까지 출력을 수집합니다.

Snowflake는 이러한 로그를 계정의 이벤트 테이블 로 내보냅니다. 자세한 내용은 로컬 컨테이너 로그에 액세스하기 섹션을 참조하십시오. spec.logExporters.eventTableConfig 를 사용하여 이벤트 테이블에 저장하려는 로그를 나타냅니다.

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

지원되는 logLevel 값은 다음과 같습니다.

• INFO: 모든 사용자 로그를 내보냅니다.

• ERROR: 오류 로그만 내보냅니다. Snowflake는 stderr 스트림의 로그만 내보냅니다.

• NONE (기본값): 로그를 이벤트 테이블로 내보내지 않습니다.

단위 정보¶

서비스 사양은 여러 위치에서 숫자 값을 사용합니다. Snowpark Container Services는 이러한 값을 표현하기 위해 다양한 단위를 지원합니다. 큰 값과 작은 값의 경우 표시된 대로 이진 및 십진 단위를 사용할 수 있습니다. 다음 목록에서 “#”는 정수 값을 나타냅니다.

• 이진 단위:

  • numberKi 는 number*1024 를 의미합니다. 예를 들어, memory: 4Ki 는 memory: 4096 과 같습니다.

  • numberMi 는 number*1024^2 을 의미합니다.

  • numberGi 는 number*1024^3 을 의미합니다.

• 십진 단위:

  • numberk 는 number*10^3 을 의미합니다. 예를 들어, memory: 4k 는 memory: 4000 과 같습니다.

  • numberM 은 number*10^6 을 의미합니다.

  • numberG 는 number*10^9 을 의미합니다.

• 분수 단위:

  • numberm 은 number*0.001 을 의미합니다. 예를 들어, cpu: 500m 은 cpu: 0.5 와 같습니다.