파일 시스템 스냅샷

auth를 생략한 예시에서는 CWSANDBOX_API_KEY에 설정된 CoreWeave API 액세스 토큰을 사용합니다. Forge API 키로 인증하려면 시작하기의 안내에 따라 생성한 AuthHeaders를 오퍼레이션에 전달하세요.HTTP API 예시에서는 FORGE_API_KEY에 설정된 Forge API 키를 사용합니다. CoreWeave API 액세스 토큰을 대신 사용하려면 CWSANDBOX_API_KEY를 해당 토큰으로 설정하고, 각 요청에서 -H "x-wandb-api-key: $FORGE_API_KEY"를 -H "Authorization: Bearer $CWSANDBOX_API_KEY"로 바꾸세요. 사용자 인증 정보는 샌드박스와 해당 스냅샷을 소유한 계정의 것을 사용해야 합니다.

파일 시스템 스냅샷(FSS)을 사용하면 샌드박스에서 로컬 작업 디렉터리에 데이터를 쓰고, 해당 디렉터리를 불변 스냅샷으로 캡처하여 객체 저장소에 저장한 후, 나중에 새 샌드박스로 복원할 수 있습니다. FSS를 사용하여 run 간에 샌드박스의 파일 시스템을 일시 중단하고 재개하거나, 하나의 스냅샷을 여러 샌드박스로 포크하여 각각 독립적으로 변경하세요.

작동 방식

FSS가 적용된 샌드박스는 선택한 경로에 쓰기 가능한 임시 파일 시스템을 마운트합니다. 러너는 객체 저장소를 직접 마운트하는 대신 EmptyDir를 이 마운트의 기반으로 사용합니다. 스냅샷 및 복원 오퍼레이션은 로컬 파일 시스템과 조직 범위의 객체 저장소 버킷 간에 tarball을 복사합니다. 각 스냅샷은 서버가 부여한 fileSystemSnapshotId로 식별되는 FileSystemSnapshot 리소스입니다. 스냅샷에는 다음 세 가지 주요 속성이 있습니다.

불변성: 스냅샷을 생성하면 아카이브 하나가 기록됩니다. 스냅샷을 복원해도 원본 스냅샷은 변경되지 않으므로 이후에 복원할 때도 항상 원본 바이트를 사용합니다.
조직 범위: 자신의 조직에서 생성한 스냅샷만 복원할 수 있습니다. 다른 조직의 스냅샷 ID는 찾을 수 없는 것으로 처리됩니다.
독립적인 라이프사이클: 스냅샷은 샌드박스와 별도로 관리됩니다. 샌드박스를 삭제해도 해당 스냅샷은 삭제되지 않으며, 스냅샷을 삭제해도 해당 스냅샷에서 이미 실행 중인 샌드박스에는 영향을 주지 않습니다.

기본적으로 CoreWeave가 스냅샷을 보관하는 객체 저장소 버킷을 프로비저닝하고 관리합니다. 직접 소유하고 제어하는 버킷에 스냅샷을 저장하려면 자체 버킷 사용에서 CoreWeave 계정 및 버킷 사전 요구 사항을 참조하세요.

스냅샷 마운트로 샌드박스 시작하기

샌드박스는 새로 생성된 빈 임시 파일 시스템 또는 기존 스냅샷을 복원한 파일 시스템 중 하나를 기반으로 시작할 수 있습니다.

새 임시 공간

새 임시 파일 시스템은 빈 상태로 시작하며 나중에 스냅샷을 생성할 수 있습니다. run 중 쓰기 가능한 로컬 상태가 필요한 워크플로에 사용하세요.

Python
HTTP API

from cwsandbox import Sandbox, FileSystemSnapshotOptions

with Sandbox.run(
    container_image="ubuntu:22.04",
    file_system_snapshot=FileSystemSnapshotOptions(mount_path="/work", size="10Gi"),
) as sandbox:
    sandbox.exec(["sh", "-c", "echo hello > /work/data.txt"]).result()

fileSystem.mountPath와 fileSystem.size를 설정하세요. 빈 상태로 시작하려면 fileSystemSnapshot을 설정하지 마세요.

curl -X POST https://api.cwsandbox.com/v1beta2/sandboxes \
  -H "x-wandb-api-key: $FORGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "containerImage": "ubuntu:22.04",
    "command": "sleep",
    "args": ["3600"],
    "fileSystem": {
      "mountPath": "/work",
      "size": "10Gi"
    }
  }'

스냅샷에서 복원

복원은 기존 스냅샷에서 파일 시스템을 시작합니다. 마운트의 스냅샷 소스에 스냅샷 ID를 설정하세요.

Python
HTTP API

from cwsandbox import Sandbox, FileSystemSnapshotOptions

with Sandbox.run(
    container_image="ubuntu:22.04",
    file_system_snapshot=FileSystemSnapshotOptions(
        mount_path="/work",
        file_system_snapshot_id="fss_...",
    ),
) as sandbox:
    contents = sandbox.exec(["cat", "/work/data.txt"]).result()
    print(contents.stdout)

curl -X POST https://api.cwsandbox.com/v1beta2/sandboxes \
  -H "x-wandb-api-key: $FORGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "containerImage": "ubuntu:22.04",
    "command": "sleep",
    "args": ["3600"],
    "fileSystem": {
      "mountPath": "/work",
      "size": "10Gi",
      "fileSystemSnapshot": {
        "fileSystemSnapshotId": "fss_..."
      }
    }
  }'

스냅샷은 복원하기 전에 READY 상태여야 합니다. CREATING 상태인 스냅샷을 복원하면 실패합니다. 스냅샷 상태 및 실패를 참조하세요.

스냅샷 생성

스냅샷은 두 가지 방식으로 캡처할 수 있습니다. 샌드박스가 종료될 때 캡처하거나, 실행 중인 샌드박스에서 캡처할 수 있습니다.

중지 시 스냅샷 생성

샌드박스가 종료될 때 파일 시스템을 보존하려면 중지 시 스냅샷 생성 기능을 활성화한 상태로 샌드박스를 중지하세요. 일시 중단 및 재개는 다음 방식으로 진행합니다. 스냅샷을 생성하며 중지한 다음, 나중에 해당 스냅샷을 복원하는 새 샌드박스를 시작합니다.

Python
HTTP API

sandbox.stop(snapshot_on_stop=True).result()
print(sandbox.file_system_snapshot_id)

StopSandbox는 스냅샷 요청이 수락되면 fileSystemSnapshotId를 반환합니다. waitForReady를 true로 설정하면 호출은 maxTimeoutSeconds로 제한된 시간 내에서 스냅샷이 READY 또는 FAILED 상태에 도달할 때까지 기다립니다. 이를 설정하지 않으면 스냅샷이 아직 CREATING 상태일 때 호출이 반환될 수 있습니다. [SANDBOX-ID]를 중지할 샌드박스의 ID로 바꾸세요.

curl -X POST https://api.cwsandbox.com/v1beta2/sandboxes/[SANDBOX-ID]/stop \
  -H "x-wandb-api-key: $FORGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "sandboxId": "[SANDBOX-ID]",
    "fileSystemSnapshotOnStop": true,
    "waitForReady": true,
    "idempotencyKey": "stop-[SANDBOX-ID]-snapshot-1",
    "maxTimeoutSeconds": 600
  }'

실행 중 스냅샷

실행 중 스냅샷은 실행 중인 샌드박스를 중지하지 않고 캡처합니다. 스냅샷을 생성한 후에도 샌드박스는 계속 실행됩니다.

Python
HTTP API

snapshot()은 기본적으로 스냅샷이 READY 상태가 될 때까지 기다린 후 스냅샷 ID를 반환합니다.

snapshot_id = sandbox.snapshot().result()
print(f"Created snapshot {snapshot_id}")

CreateFileSystemSnapshot은 중지 시 스냅샷과 동일한 idempotencyKey, waitForReady, maxTimeoutSeconds 제어 옵션을 지원합니다. 단, StopSandbox와 달리 waitForReady의 기본값은 true입니다. [SANDBOX-ID]를 스냅샷을 생성할 실행 중인 샌드박스의 ID로 바꾸세요.

curl -X POST https://api.cwsandbox.com/v1beta2/sandboxes/[SANDBOX-ID]/file-system-snapshots \
  -H "x-wandb-api-key: $FORGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "sandboxId": "[SANDBOX-ID]",
    "waitForReady": true,
    "maxTimeoutSeconds": 600
  }'

waitForReady를 false로 설정하면, 성공 응답은 스냅샷 행이 생성되고 스냅샷 명령이 전달되었다는 의미일 뿐입니다. 아카이브는 아직 CREATING 상태일 수 있으며, 나중에 FAILED 상태가 될 수도 있습니다. 스냅샷을 복원하기 전에 스냅샷 상태를 폴링하세요.

스냅샷 포크하기

동일한 스냅샷을 여러 샌드박스에 복원할 수 있습니다. 각 스냅샷은 변경할 수 없으므로, 복원된 샌드박스는 동일한 바이트로 시작한 후 쓰기 작업에 따라 서로 달라집니다.

중지 시 스냅샷 또는 실행 중 스냅샷을 사용하여 READY 스냅샷을 생성하세요.
fileSystemSnapshotId를 해당 스냅샷으로 설정하여 샌드박스 A를 시작하세요.
동일한 fileSystemSnapshotId로 샌드박스 B를 시작하세요.
샌드박스 A와 샌드박스 B의 쓰기 작업은 서로 독립적으로 이루어집니다. 원본 스냅샷은 변경되지 않으므로, 나중에 동일한 ID로 복원해도 어느 포크에서든 기록한 내용이 아닌 원본 스냅샷을 사용합니다.

from cwsandbox import Sandbox, FileSystemSnapshotOptions

# 동일한 스냅샷을 두 개의 독립적인 샌드박스에 복원합니다.
with Sandbox.run(
    file_system_snapshot=FileSystemSnapshotOptions(mount_path="/work", file_system_snapshot_id=snapshot_id),
) as fork_a, Sandbox.run(
    file_system_snapshot=FileSystemSnapshotOptions(mount_path="/work", file_system_snapshot_id=snapshot_id),
) as fork_b:
    fork_a.exec(["sh", "-c", "echo a >> /work/data.txt"]).result()
    fork_b.exec(["sh", "-c", "echo b >> /work/data.txt"]).result()

스냅샷 관리

스냅샷을 생성한 샌드박스와 독립적으로 스냅샷을 목록 조회, 가져오기, 삭제합니다.

Python
HTTP API

from cwsandbox import Sandbox

# 조직 내 모든 스냅샷을 목록 조회합니다.
snapshots = Sandbox.list_snapshots().result()

# 하나의 스냅샷 상세 정보를 조회합니다.
snapshot = Sandbox.get_snapshot(snapshot_id).result()
print(f"{snapshot.file_system_snapshot_id}: {snapshot.size_bytes} bytes")

# 스냅샷을 삭제합니다. missing_ok는 호출을 멱등하게 만듭니다.
Sandbox.delete_snapshot(snapshot_id, missing_ok=True).result()

스냅샷을 조회하거나 삭제할 [SNAPSHOT-ID]를 해당 스냅샷 ID로 교체하세요.

# 조직 범위 스냅샷을 목록 조회합니다.
curl https://api.cwsandbox.com/v1beta2/file-system-snapshots \
  -H "x-wandb-api-key: $FORGE_API_KEY"

# 하나의 스냅샷을 조회합니다.
curl https://api.cwsandbox.com/v1beta2/file-system-snapshots/[SNAPSHOT-ID] \
  -H "x-wandb-api-key: $FORGE_API_KEY"

# 하나의 스냅샷을 삭제합니다.
curl -X DELETE https://api.cwsandbox.com/v1beta2/file-system-snapshots/[SNAPSHOT-ID] \
  -H "x-wandb-api-key: $FORGE_API_KEY"

list_snapshots(), get_snapshot(), delete_snapshot()은 auth를 통해 AuthHeaders 객체도 받을 수 있습니다.

스냅샷 상태 및 실패

스냅샷은 비동기적으로 생성됩니다. 아카이브가 아직 기록 중이어도 스냅샷 요청이 성공하여 fileSystemSnapshotId를 반환할 수 있으며, 이후 스냅샷이 실패할 수 있습니다. 이는 waitForReady가 false이거나 러너가 아직 아카이브를 생성하는 동안 클라이언트 timeout이 발생할 때 가장 자주 일어납니다. 진행 상황을 확인하려면 스냅샷을 조회하고 두 필드를 확인하세요.

status: 라이프사이클 상태입니다. 최종 값은 READY와 FAILED입니다. HTTP API는 FILE_SYSTEM_SNAPSHOT_STATUS_READY와 같은 완전 수식된 형식을 반환합니다.
statusReason: status가 FAILED일 때 채워지며, 실패 이유를 설명합니다.

스냅샷을 복원하기 전에 READY 상태가 될 때까지 GetFileSystemSnapshot을 폴링하세요. Python 클라이언트의 snapshot()과 get_snapshot()은 결과를 기다릴 때 이 폴링을 대신 처리합니다. 다음 table은 일반적인 실패 이유와 각 이유에 대한 조치 방법을 나열합니다.

이유	의미	조치 방법
`CWSANDBOX_FSS_BUCKET_PROVISIONING`	기본 스냅샷 버킷이 아직 프로비저닝 중입니다.	잠시 후 다시 시도하세요. 오류가 지속되면 지원팀에 문의하세요.
`CWSANDBOX_FSS_AUTH_FAILED`	자격 증명 교환 또는 버킷 권한 부여가 실패했습니다.	버킷 또는 WIF 정책을 수정한 후 다시 시도하세요. CoreWeave가 관리하는 버킷인 경우 지원팀에 문의하세요.
`CWSANDBOX_FSS_TRANSPORT_FAILED`	러너가 객체 저장소에 연결하지 못했거나 아카이브 전송이 실패했습니다.	다시 시도하세요. 문제가 반복되면 스냅샷 ID와 함께 지원팀에 문의하세요.
`CWSANDBOX_FSS_BACKEND_THROTTLED`	객체 저장소에서 지속적인 요청 제한 또는 백엔드 오류를 반환했습니다.	나중에 다시 시도하세요.
`CWSANDBOX_FSS_CREATE_TIMED_OUT`	설정된 timeout 내에 스냅샷 생성이 완료되지 않았습니다.	`maxTimeoutSeconds`를 늘려 다시 시도하거나 데이터 크기를 줄이세요.
`CWSANDBOX_FSS_CANCELED`	스냅샷이 취소되었습니다. 일반적으로 작업이 진행 중인 샌드박스를 강제로 삭제할 때 발생합니다.	데이터가 여전히 필요하면 스냅샷 생성을 다시 시도하세요.
`CWSANDBOX_FSS_QUOTA_EXCEEDED`	조직이 스냅샷 수 또는 저장소 한도에 도달했습니다.	사용하지 않는 스냅샷을 삭제하거나 할당량 증가를 요청하세요.
`CWSANDBOX_FSS_NOT_READY`	복원 작업이 `READY` 상태가 아닌 스냅샷을 참조했습니다.	스냅샷이 `READY` 상태가 될 때까지 폴링하거나 다른 스냅샷을 선택하세요.
`CWSANDBOX_FSS_NOT_FOUND`	조직에 스냅샷이 존재하지 않습니다.	스냅샷 ID와 조직을 확인하세요.
`CWSANDBOX_FSS_SIZE_EXCEEDED`	요청한 파일 시스템 크기가 지원되는 임시 공간 크기를 초과합니다.	더 작은 파일 시스템을 요청하거나 제한에 대해 지원팀에 문의하세요.

러너가 아카이브 업로드를 완료했지만 결과를 기록하지 못하면, 버킷에 객체가 존재하더라도 스냅샷 행이 FAILED 상태가 될 수 있습니다. 이 경우 스냅샷 생성을 다시 시도하세요. 비동기 실패의 경우 플랫폼은 sandbox.file_system_snapshot.async_fail 이벤트도 발생시키므로, 다운스트림 알림 시스템은 원래 호출이 반환된 후 실패한 스냅샷에 대응할 수 있습니다.

제한 사항

FSS 버전 1은 스냅샷 기반 로컬 임시 저장소를 제공합니다. 이는 공유 파일 시스템이 아니며 라이브 다중 작성자 마운트를 지원하지 않습니다. 샌드박스는 실행 중에 서로의 파일 시스템을 읽거나 쓰지 않습니다. 상태를 공유하는 유일한 방법은 스냅샷팅과 복원입니다.

SDK 예시

샌드박스를 시작하고, 실행 중 스냅샷을 생성하고, 이를 포크하고, 중지 시 스냅샷을 캡처하고, 스냅샷을 관리하는 완전한 실행 가능한 Python 예시는 cwsandbox-client 저장소의 file_system_snapshots.py를 참조하세요.

파일 시스템 스냅샷에 자체 버킷 사용: 소유한 버킷에 스냅샷을 저장하세요.
볼륨: 여러 샌드박스가 공유하는 임시 볼륨과 등록된 볼륨입니다.
샌드박스 라이프사이클: stop()과 샌드박스 상태의 작동 방식을 알아보세요.
Python 클라이언트: SDK를 설치하고 API를 살펴보세요.

샌드박스

샌드박스 사용하기

샌드박스 관리

레퍼런스

파일 시스템 스냅샷

작동 방식

스냅샷 마운트로 샌드박스 시작하기

새 임시 공간

스냅샷에서 복원

스냅샷 생성

중지 시 스냅샷 생성

실행 중 스냅샷

스냅샷 포크하기

스냅샷 관리

스냅샷 상태 및 실패

제한 사항

SDK 예시

​작동 방식

​스냅샷 마운트로 샌드박스 시작하기

​새 임시 공간

​스냅샷에서 복원

​스냅샷 생성

​중지 시 스냅샷 생성

​실행 중 스냅샷

​스냅샷 포크하기

​스냅샷 관리

​스냅샷 상태 및 실패

​제한 사항

​SDK 예시

​관련 리소스

작동 방식

스냅샷 마운트로 샌드박스 시작하기

새 임시 공간

스냅샷에서 복원

스냅샷 생성

중지 시 스냅샷 생성

실행 중 스냅샷

스냅샷 포크하기

스냅샷 관리

스냅샷 상태 및 실패

제한 사항

SDK 예시

관련 리소스