Sandbox templates

샌드박스 템플릿은 조직 범위의 재사용 가능한 부분 샌드박스 사양입니다. 모든 생성 요청마다 동일한 컨테이너 이미지, 리소스, 서비스 및 네트워크 규칙을 반복하는 대신, 한 번 템플릿으로 저장하고 run당 다른 부분에만 재정의 값을 적용하여 샌드박스를 시작합니다. 템플릿은 권한을 가지지 않습니다. 샌드박스 사양의 시작점이며, 러너의 정책이 강제 적용하는 유일한 것입니다. 템플릿에서 생성된 샌드박스는 전체 사양을 직접 작성한 것처럼 정책에 대해 검증됩니다. 이 페이지는 템플릿을 생성하고 관리하는 방법, 템플릿에서 샌드박스를 시작하는 방법, 그리고 일반적인 사용 사례에 대한 완전한 템플릿 문서를 보여줍니다. [TEMPLATE-ID]를 템플릿의 UUID로, [SNAPSHOT-ID]를 파일 시스템 스냅샷 ID로, [GITHUB-ORG]를 GitHub Container Registry 조직 또는 사용자 이름으로 바꾸세요.

템플릿 생성

템플릿은 조직 관리자가 관리합니다. 쓰기 오퍼레이션에는 sandbox_admin 역할이 필요합니다. 조직 내 모든 샌드박스 사용자는 템플릿을 조회하고 이를 사용하여 샌드박스를 시작할 수 있습니다.

CLI
curl

파일에서 템플릿을 생성합니다:

cwic sandbox template create -f template.json

기존 템플릿을 검사하고 목록을 조회합니다:

cwic sandbox template describe [TEMPLATE-ID]

cwic sandbox template get

Create a template

curl -X POST https://api.coreweave.com/v1/sandboxTemplates \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d @template.json

요청 본문은 래퍼 객체가 아니라 템플릿 문서 자체입니다.

최소한의 개발 상자 템플릿은 다음과 같습니다:

template.json

{
  "displayName": "python-dev-box",
  "spec": {
    "containers": [
      {
        "name": "main",
        "image": "python:3.11",
        "resourceRequirements": {
          "requests": { "cpu": "1", "memory": "2Gi" },
          "limits": { "cpu": "2", "memory": "4Gi" }
        }
      }
    ],
    "maxLifetimeSeconds": 14400,
    "tags": ["dev-box"]
  }
}

모든 템플릿 쓰기 작업에 적용되는 규칙:

displayName은 필수이며 조직의 활성 템플릿 내에서 고유해야 합니다. 앞뒤 공백을 제거한 후 1~128자여야 합니다. ID 우선 조회와 충돌하지 않도록 UUID 형식이 아닌 이름을 사용하는 것이 좋습니다.
spec은 부분적인 샌드박스 사양이며 크기는 최대 1 MiB입니다. 생성 요청과 동일한 필드를 사용하며, 포함된 모든 값은 생성 시 재정의할 수 있습니다.
spec은 아직 인스턴스 유형을 선택하거나 샌드박스 네트워크를 연결할 수 없습니다. instanceType 또는 networkIds를 설정하는 템플릿은 미구현 기능으로 간주되어 거부됩니다.
템플릿 내용은 조직의 모든 샌드박스 사용자에게 공개됩니다. 템플릿은 시크릿 배포 채널이 아니므로 자격 증명 값을 직접 포함해서는 안 됩니다.

템플릿에서 샌드박스 시작하기

ID를 사용하여 템플릿에서 샌드박스를 시작하세요. 선택에는 UUID만 사용할 수 있습니다. 표시 이름은 조회와 목록 확인에 사용할 수 있지만, 생성에는 사용할 수 없습니다.

Create a sandbox from a template

curl -X POST https://api.cwsandbox.com/v1/sandboxes:createFromTemplate \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "templateId": "[TEMPLATE-ID]" }'

run마다 설정을 변경하려면 샌드박스 사양과 동일한 형태로 overrides를 전달하세요. 오버라이드는 필드가 지정되면 해당 필드 전체를 대체하며, 병합되지 않습니다.

메시지를 설정하면 템플릿의 메시지 전체가 대체됩니다. 메시지를 생략하면 템플릿의 값이 유지됩니다.
목록이나 맵을 설정하면 템플릿의 컬렉션 전체가 대체되며, 빈 값으로 설정한 경우에도 마찬가지입니다. 항목 하나를 제거하려면 원하는 내용이 담긴 전체 컬렉션을 보내야 합니다.
컨테이너 필드를 하나라도 오버라이드하면 컨테이너 목록 전체가 대체됩니다. 템플릿 컨테이너를 부분적으로 패치하는 방법은 없으므로, 컨테이너를 변경하는 오버라이드에는 image를 포함한 전체 컨테이너 정의가 들어 있어야 합니다.

Override the container per run

curl -X POST https://api.cwsandbox.com/v1/sandboxes:createFromTemplate \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "templateId": "[TEMPLATE-ID]",
    "overrides": {
      "containers": [
        {
          "name": "main",
          "image": "python:3.12",
          "command": "sleep",
          "args": ["infinity"]
        }
      ]
    }
  }'

샌드박스는 생성 시점에 구체화된 사양을 저장하며, source 템플릿 ID와 리비전도 함께 저장합니다. 나중에 템플릿을 편집하거나 삭제해도 이미 존재하는 샌드박스는 변경되지 않습니다. Python 및 TypeScript 클라이언트는 이 엔드포인트를 Sandbox.run_from_template() 및 client.runFromTemplate()으로 wrap합니다. SDK 워크플로에 대한 자세한 내용은 클라이언트 문서를 참조하세요.

템플릿 예시

아래 예시는 cwic sandbox template create -f template.json에 사용할 수 있는 완전한 문서입니다. 정책과 달리 조직에는 여러 템플릿을 저장할 수 있으므로, 반복되는 워크로드 유형별로 하나씩 만들어 함께 활용할 수 있습니다.

공개 HTTPS 엔드포인트가 있는 웹 서비스

플랫폼에서 발급한 HTTPS 엔드포인트를 통해 공개 인터넷에 HTTP를 서빙하는 샌드박스용 템플릿입니다. 부여된 URL은 생성 후 샌드박스에 출력됩니다.

template.json

{
  "displayName": "public-http-service",
  "spec": {
    "containers": [
      {
        "name": "main",
        "image": "python:3.11",
        "command": "python",
        "args": ["-m", "http.server", "8000"]
      }
    ],
    "services": [
      {
        "name": "http",
        "port": 8000,
        "visibility": "VISIBILITY_PUBLIC",
        "endpoint": {
          "kind": "ENDPOINT_KIND_HTTPS",
          "auth": "ENDPOINT_AUTH_OPEN"
        }
      }
    ]
  }
}

공개 노출은 선택한 러너의 advertised network capability에 의해 제어되므로, 이 템플릿은 public 엔드포인트용으로 설정된 러너에서만 작동합니다.

Workspace restored from a snapshot

매번 동일한 파일 시스템 스냅샷에서 시작되는 스크래치 볼륨을 가진 템플릿: 각 샌드박스가 비공개로 포크하는 골든 워크스페이스.

template.json

{
  "displayName": "golden-workspace",
  "spec": {
    "containers": [
      {
        "name": "main",
        "image": "python:3.11",
        "volumeMounts": [{ "volume": "workspace", "mountPath": "/workspace" }]
      }
    ],
    "volumes": [
      {
        "name": "workspace",
        "scratch": {
          "size": "10Gi",
          "restoreFromSnapshotId": "[SNAPSHOT-ID]"
        }
      }
    ]
  }
}

이 템플릿에서 복원할 스냅샷을 생성하는 방법은 파일 시스템 스냅샷을 참조하세요.

선별된 아웃바운드 트래픽

고정된 대상 집합에 대한 접근을 허용하는 템플릿입니다. 포트 443의 CIDR 범위 하나와 같은 조직 내의 형제 샌드박스가 포함됩니다. 모든 규칙은 러너 정책의 allowedEgress 허용 범위 안에 있어야 하며, 그렇지 않으면 생성 요청이 거부됩니다.

template.json

{
  "displayName": "curated-egress",
  "spec": {
    "containers": [{ "name": "main", "image": "python:3.11" }],
    "network": {
      "egress": [
        { "cidr": { "cidr": "140.82.112.0/20" }, "ports": [{ "port": 443 }] },
        { "tenant": "TENANT_SCOPE_SAME_ORG" }
      ]
    }
  }
}

network.egress가 비어 있거나 생략된 템플릿에는 정책의 defaultEgress가 대신 적용됩니다. 워크로드의 대상을 알고 있다면 템플릿에 아웃바운드 트래픽 목록을 지정하고, 정책 기본값이 적절한 보안 태세라면 비워 두세요.

CKS 전용: 파드 연결 설정

자체 CKS 클러스터에서는 Admin이 템플릿에 attachments 블록을 추가할 수 있습니다. 이 블록은 해당 템플릿으로 생성된 모든 샌드박스에 적용되는 Kubernetes 파드 사양의 일부입니다. 이를 통해 템플릿에서 샌드박스 사양 자체에는 필드가 없는 노드 선택, 톨러레이션 또는 이미지 풀 시크릿을 고정할 수 있습니다.

template.json

{
  "displayName": "gpu-training",
  "spec": {
    "containers": [
      {
        "name": "main",
        "image": "ghcr.io/[GITHUB-ORG]/train:latest",
        "resourceRequirements": {
          "requests": { "cpu": "8", "memory": "32Gi" },
          "limits": { "cpu": "8", "memory": "32Gi" }
        }
      }
    ]
  },
  "attachments": {
    "spec": {
      "nodeSelector": { "workload": "gpu" },
      "tolerations": [
        { "key": "nvidia.com/gpu", "operator": "Exists", "effect": "NoSchedule" }
      ],
      "imagePullSecrets": [{ "name": "regcred" }]
    },
    "metadata": {
      "labels": { "team": "ml" }
    }
  }
}

연결 설정 change how the template behaves:

연결 설정이 있는 템플릿은 CKS 전용입니다. requiresCks 출력 필드가 true이며, mode를 SANDBOX_MODE_SERVERLESS로 설정하여 생성하면 FailedPrecondition 오류가 발생합니다. 설정되지 않은 모드는 CKS로 처리됩니다.
연결 설정은 Admin 소유입니다. sandbox_admin만 작성할 수 있으며, 일반 생성 요청으로는 제공할 수 없고, 생성 시 오버라이드는 변경하거나 제거할 수 없습니다.
프래그먼트는 Kubernetes JSON을 사용합니다. spec 및 metadata 아래에 camelCase 키를 사용하며, 템플릿의 다른 샌드박스 사양 필드와 다릅니다. 알 수 없는 키는 거부됩니다.
허용된 범위는 의도적으로 좁습니다: nodeSelector, tolerations, imagePullSecrets, volumes, topologySpreadConstraints, hostAliases, DNS 설정, 그리고 name, env, envFrom, volumeMounts, volumeDevices로 제한된 단일 containers 항목, 그리고 파드 레이블 및 어노테이션과 같은 스케줄링 및 런타임 관련 항목입니다. 보안에 민감한 필드는 거부됩니다: securityContext, runtimeClassName, initContainers, affinity, 호스트 namespace, hostPath 볼륨, 기본이 아닌 service account 등입니다.
연결 설정은 정책의 base 프래그먼트 위에 계층화됩니다. 목록 값 필드는 정책 기본값과 결합됩니다: imagePullSecrets 및 tolerations는 중복 제거되며, topologySpreadConstraints, hostAliases, readinessGates는 추가됩니다. nodeSelector 키와 같은 단일 값 필드는 기본값을 특수화합니다. 두 계층 간에 동일한 이름의 볼륨, 환경 변수 또는 마운트 경로 충돌이 발생하면 생성이 거부됩니다.

템플릿 관리

CLI
curl

cwic sandbox template edit [TEMPLATE-ID] -f template.json

cwic sandbox template delete [TEMPLATE-ID]

Update a template

curl -X PATCH https://api.coreweave.com/v1/sandboxTemplates/[TEMPLATE-ID] \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d @template.json

Delete a template

curl -X DELETE https://api.coreweave.com/v1/sandboxTemplates/[TEMPLATE-ID] \
  -H "Authorization: Bearer $TOKEN"

조회 시 ID 또는 표시 이름을 사용할 수 있습니다. 경로 세그먼트가 UUID로 파싱되면 ID로 조회하고, 그렇지 않으면 활성 템플릿 중에서 표시 이름으로 조회합니다.
업데이트에 성공할 때마다 템플릿의 revision이 증가합니다. 샌드박스는 생성 당시의 리비전을 기록하므로, 템플릿 변경 이전에 생성된 샌드박스를 확인할 수 있습니다.
삭제는 소프트 삭제로 처리됩니다. 기존 샌드박스는 영향을 받지 않지만, 새로 생성할 때는 더 이상 해당 템플릿을 선택할 수 없습니다. 또한 해당 표시 이름을 새 템플릿에 다시 사용할 수 있습니다.

다음 단계

정책 예시: 이 템플릿과 함께 사용할 전체 러너 정책입니다.
샌드박스 정책 설정: 템플릿의 사양을 검증할 때 기준이 되는 제약 조건 그룹입니다.
정책 개요: 이전에 프로필이 담당하던 작업을 템플릿과 정책이 어떻게 나누어 맡는지 설명합니다.
자체 컴퓨팅 사용하기: 러너 설정과 첫 샌드박스 실행 방법을 다룹니다.

샌드박스

샌드박스 사용하기

샌드박스 관리

레퍼런스

템플릿 생성

템플릿에서 샌드박스 시작하기

템플릿 예시

공개 HTTPS 엔드포인트가 있는 웹 서비스

Workspace restored from a snapshot

선별된 아웃바운드 트래픽

CKS 전용: 파드 연결 설정

템플릿 관리

다음 단계

​템플릿 생성

​템플릿에서 샌드박스 시작하기

​템플릿 예시

​공개 HTTPS 엔드포인트가 있는 웹 서비스

​Workspace restored from a snapshot

​선별된 아웃바운드 트래픽

​CKS 전용: 파드 연결 설정

​템플릿 관리

​다음 단계

템플릿 생성

템플릿에서 샌드박스 시작하기

템플릿 예시

공개 HTTPS 엔드포인트가 있는 웹 서비스

Workspace restored from a snapshot

선별된 아웃바운드 트래픽

CKS 전용: 파드 연결 설정

템플릿 관리

다음 단계