Compose 파일에서 샌드박스 생성

POST /v1/sandboxes:createFromFile는 업로드된 파일에서 샌드박스를 시작합니다. 파일 유형과 파일 바이트를 전송하면, 샌드박스 게이트웨이가 문서를 샌드박스 사양으로 변환하고 POST /v1/sandboxes와 동일한 생성 경로를 실행합니다. 도커 Compose(SANDBOX_FILE_TYPE_COMPOSE)가 유일하게 허용되는 파일 유형입니다. 파일의 모든 서비스는 단일 샌드박스의 컨테이너가 되며, 사용자가 지정한 하나의 서비스가 샌드박스 주 서비스가 됩니다. 게이트웨이는 파일 바이트를 저장하지 않습니다. GET /v1/sandboxes/{sandboxId}는 변환된 사양을 반환합니다. 이것은 도커 Compose와 동등하지 않습니다. 기존 프로젝트를 임포트하기 전에 Compose 지원를 읽어보십시오.

시작하기 전에

다음 예시에서는 Forge API 키를 사용합니다. 자세한 내용은 시작하기를 참조하세요. 키는 x-wandb-api-key 헤더에 담아 전송하세요. 기본 entity가 아닌 다른 Forge entity에 샌드박스를 생성하려면 x-entity-id도 함께 전송하세요.

export FORGE_API_KEY="[FORGE-API-KEY]"

CKS 배치를 포함하여 SANDBOX_USER 액션이 있는 CoreWeave API 액세스 토큰을 사용할 수도 있습니다. 사용자 인증 정보 선택 및 조회의 안내에 따라 진행한 다음 토큰을 설정하세요.

export CWSANDBOX_API_KEY="[API-ACCESS-TOKEN]"

해당 토큰을 사용하려면 이 가이드의 모든 요청에서 -H "x-wandb-api-key: $FORGE_API_KEY"를 -H "Authorization: Bearer $CWSANDBOX_API_KEY"로 바꾸세요. 인증 방식과 오류 형식은 다른 API와 동일합니다. 자세한 내용은 API 개요를 참조하세요.

요청 필드

필드	필수	설명
`type`	예	문서 종류입니다. `SANDBOX_FILE_TYPE_COMPOSE`를 사용하세요.
`contents`	예	JSON에서 base64로 인코딩된 파일 바이트입니다. UTF-8, 최대 256KiB입니다.
`primaryService`	예	샌드박스의 주 서비스가 되는 서비스입니다. `contents`에 정의된 서비스 이름을 지정해야 합니다. 기본값은 없습니다.
`imageOverrides`	아니요	서비스별 이미지 참조입니다. 키는 파일에 정의된 서비스 이름이어야 합니다. 원래는 빌드가 필요한 서비스에 pull 가능한 이미지를 제공하려면 이 필드를 사용하세요.
`defaultResources`	조건부	`deploy.resources`를 생략한 각 서비스에 복사되는 CPU 및 메모리 값입니다. 프로젝트 budget이 아니라 컨테이너별 값입니다. 여기에 GPU를 지정하면 거부됩니다. 파일에 서비스가 두 개 이상 있고 그중 하나라도 `deploy.resources`를 생략한 경우 필수입니다.

이 요청에는 mode, maxLifetimeSeconds, tags, network, objectStorageAccess, annotations, runnerIds, requestId도 지정할 수 있으며, 각 필드의 의미는 POST /v1/sandboxes와 동일합니다. networkIds를 지정하면 UNIMPLEMENTED가 반환됩니다. CKS에 배치하려면 CoreWeave API 액세스 토큰을 사용하고, 샌드박스 배치 및 스필오버에 설명된 대로 배치 필드를 설정하세요. 객체 저장소 사전 요구 사항은 샌드박스에 AI Object Storage 액세스 권한 부여를 참조하세요. 이 필드 목록 외의 필드는 지원되지 않습니다. 볼륨, instance type, 런타임 클래스, 이미지 pull 사용자 인증 정보, 게시된 서비스는 이 엔드포인트에서 사용할 수 없습니다. 이러한 항목이 필요하면 POST /v1/sandboxes를 사용하세요.

샌드박스 만들기

Compose 파일을 작성하세요:

Write compose.yaml

cat > compose.yaml <<'EOF'
services:
  helper:
    image: docker.io/library/busybox:1.36
    command: ["sleep", "3600"]
    expose: ["8080"]
    healthcheck:
      test: ["CMD", "true"]
      interval: 1s
      timeout: 1s
      retries: 3
  main:
    image: docker.io/library/busybox:1.36
    command: ["sleep", "3600"]
    environment:
      HELPER_HOST: helper
    depends_on:
      helper:
        condition: service_healthy
EOF

contents를 base64로 인코딩하여 POST 요청으로 전송하세요:

Create a sandbox from compose.yaml

jq -n --rawfile yaml compose.yaml '{
  type: "SANDBOX_FILE_TYPE_COMPOSE",
  contents: ($yaml | @base64),
  primaryService: "main",
  defaultResources: { requests: { cpu: "100m", memory: "128Mi" } },
  maxLifetimeSeconds: 3600,
  tags: ["from-file"]
}' | curl -sS -X POST https://api.cwsandbox.com/v1/sandboxes:createFromFile \
  -H "x-wandb-api-key: $FORGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d @-

응답은 STATE_CREATING 상태의 샌드박스입니다. STATE_RUNNING 또는 종료 상태에 도달할 때까지 해당 sandboxId를 폴링하세요:

Poll the sandbox

export SANDBOX_ID="[SANDBOX-ID]"

curl -sS "https://api.cwsandbox.com/v1/sandboxes/$SANDBOX_ID" \
  -H "x-wandb-api-key: $FORGE_API_KEY"

반환된 사양에는 컨테이너가 두 개 있으며, main은 주 컨테이너로 표시되고 HELPER_HOST는 여전히 helper로 설정되어 있습니다. 샌드박스 내부에서 helper는 127.0.0.1로 해석됩니다. 생성을 안전하게 재시도하려면 requestId를 보내세요. 동일한 requestId와 동일하게 선언된 입력을 보내면 기존 샌드박스가 반환됩니다. 동일한 requestId에 공백만 변경한 경우를 포함하여 다른 바이트를 보내면 사유가 CWSANDBOX_REQUEST_ID_CONFLICT인 ALREADY_EXISTS가 반환됩니다.

Compose 지원

모든 서비스는 하나의 파드와 하나의 네트워크 namespace를 공유합니다. 서비스 이름은 127.0.0.1로 확인되므로 HELPER_HOST: helper 및 API_BASE: http://main:8080과 같은 값은 파일을 다시 작성하지 않고도 작동합니다. 샌드박스에는 서비스별 IP 주소, 브리지 네트워크 또는 레플리카가 없습니다. 다음 동작은 도커 Compose와 다릅니다:

시작은 순차적입니다. primary가 아닌 모든 서비스는 primary 서비스보다 먼저 하나씩 시작됩니다. 이를 위해 maxLifetimeSeconds를 설정하세요. 준비되지 않는 서비스는 샌드박스를 STATE_CREATING 상태로 남겨둡니다.
RUNNING은 primary 서비스만 추적합니다. 시작 후 크래시가 발생한 헬퍼는 샌드박스를 실패로 만들지 않습니다.
healthcheck는 exec 전용 시작 프로브가 됩니다. test는 문자열, CMD, CMD-SHELL 또는 NONE이어야 하며, 지속 시간은 정수 초여야 합니다. 프로브가 재시도 횟수를 모두 소진하면 컨테이너는 unhealthy로 표시되지 않고 중지됩니다.
포트는 파드에 남아 있습니다. expose와 ports는 수신 포트를 선언하지만 외부에 게시되지는 않습니다.
이미지는 pull 가능해야 합니다. 모든 서비스는 파일에 image:가 있거나 imageOverrides에 항목이 있어야 합니다. 여전히 build:가 필요한 서비스는 UNIMPLEMENTED를 반환합니다.
command와 entrypoint는 도커의 shell 및 exec 형식을 따릅니다. 생략하면 이미지 기본값을 사용합니다. 명시적인 null과 []은 거부됩니다.
GPU는 primary 서비스 전용이며, gpu 기능과 양의 정수 개수를 가진 deploy.resources.reservations.devices를 통해 할당됩니다.
이름은 DNS-1123 레이블(my-app, My_App이 아님)이어야 하며, 예약된 cw-object-store-agent, cw-object-store-agent-restore 또는 dns-egress 접두사를 사용할 수 없습니다.

지원되지 않는 키

문서는 자체 포함되어야 합니다: 게이트웨이는 디스크를 읽지 않으며 환경을 확장하지 않습니다. 인식되지 않는 키는 무시되는 대신 문제가 되는 필드 경로와 함께 거부됩니다.

거부됨	참고
`$VAR` 및 `${VAR}` 보간	리터럴 `$`는 `$$`로 작성하세요.
`include`, `extends`, `env_file`	`environment` 또는 `env`만 인라인으로 작성하세요. 베어 키와 `null` 값도 거부됩니다.
`volumes`, `tmpfs`, `configs`, `secrets`, 바인드 마운트	명명된 볼륨 프로젝트는 임포트할 수 없습니다.
`restart`, `logging`, `profiles`, `stdin_open`, `tty`, `scale`	이 런타임에서는 구현되지 않았습니다.
`network_mode`, `pid`, `ipc`, `extra_hosts`, 명명된 네트워크	하나의 파드, 하나의 namespace.
호스트-컨테이너 포트 매핑, 바인드 주소, 포트 범위, 비-TCP 프로토콜, 서비스 간 중복 포트	엔트리당 하나의 TCP 수신 포트, 샌드박스 전체에서 고유해야 합니다.
`depends_on: service_completed_successfully` 또는 primary를 대상으로 하는 모든 `depends_on`	`service_healthy`와 `service_started`는 non-primary 서비스 간에 지원됩니다.
Compose 메모리 표기(`512m`, `2g`, `512mb`)	`512Mi` 또는 `1Gi`와 같은 Kubernetes 수량을 사용하세요.
명명된 `user` 값(`nobody`)	숫자 UID를 사용하세요.

게이트웨이는 version, 프로젝트 name, labels, x-* 확장 키를 무시합니다. labels가 샌드박스에 도달할 것이라고 기대하지 마십시오.

일반적인 오류

필드 위반은 경로와 제한을 명시하는 BadRequest 세부 정보로 도착합니다. 문서를 인용하지 않습니다.

상황	코드 및 이유	필드
`type` 누락	`INVALID_ARGUMENT`, `CWSANDBOX_INVALID_REQUEST`	`type`
Compose 이외의 유형	`UNIMPLEMENTED`, `CWSANDBOX_NOT_IMPLEMENTED`	`type`
`primaryService` 누락 또는 알 수 없음	`INVALID_ARGUMENT`, `CWSANDBOX_INVALID_REQUEST`	`primary_service`
`image:` 또는 `build:`가 없는 서비스	`INVALID_ARGUMENT`, `CWSANDBOX_INVALID_REQUEST`	`contents.services.<name>`
`build:`가 필요한 서비스	`UNIMPLEMENTED`, `CWSANDBOX_NOT_IMPLEMENTED`	`contents.services.<name>.build`
256 KiB를 초과하는 파일 또는 단일 UTF-8 YAML 문서가 아닌 경우	`INVALID_ARGUMENT`, `CWSANDBOX_INVALID_REQUEST`	`contents`
지원되지 않는 Compose 키	`INVALID_ARGUMENT`, `CWSANDBOX_INVALID_REQUEST`	키 경로
동일한 `requestId`, 다른 바이트	`ALREADY_EXISTS`, `CWSANDBOX_REQUEST_ID_CONFLICT`	없음

참고

시작하기: 첫 번째 샌드박스를 사양에서 생성하세요.
API 개요: 인증, 버전 관리 및 오류 처리.
샌드박스 환경 변수: 플랫폼이 모든 컨테이너에 주입하는 내용.

샌드박스

샌드박스 사용하기

샌드박스 관리

레퍼런스

Compose 파일에서 샌드박스 생성

시작하기 전에

요청 필드

샌드박스 만들기

Compose 지원

지원되지 않는 키

일반적인 오류

참고

​시작하기 전에

​요청 필드

​샌드박스 만들기

​Compose 지원

​지원되지 않는 키

​일반적인 오류

​참고

시작하기 전에

요청 필드

샌드박스 만들기

Compose 지원

지원되지 않는 키

일반적인 오류

참고