VESSL Cloud Documentation

Workspace와 Job의 컨테이너는 일회성이에요. 데이터셋, 모델 체크포인트, 큰 설정 파일을 학습 스크립트가 사용할 수 있게 하려면 영구 볼륨에 올리고 그 볼륨을 워크로드에 마운트해야 해요. 이 가이드에서는 데이터를 볼륨에 올리는 실용적인 방법들을 안내해요.

데이터를 Job 명령어에 직접 인코딩해서 넣지 마세요. gzip+base64 블롭, 긴 heredoc, 그 외 큰 페이로드를 --cmd에 붙여 넣는 방식은 API 단에서 거절돼요. 명령어 본문이 256 KiB를 넘거나, 환경변수 값이 8 KiB를 넘거나, 환경변수 쌍이 128개를 초과하면 4xx 오류로 응답해요. 아래 패턴 중 하나를 사용하세요.

한눈에 보기

어떤 종류의 볼륨인지에 따라 접근 방식이 달라요.

볼륨 종류	데이터 적재 방법
Object storage	내 컴퓨터에서 `vesslctl volume upload`로 직접 업로드하거나, `vesslctl volume token`으로 발급받은 자격증명을 쓰는 S3 호환 클라이언트로 업로드해요.
Cluster storage	볼륨을 Workspace에 마운트한 뒤, 그 Workspace 안에서 마운트 경로로 데이터를 가져와요.

Object storage: 내 컴퓨터에서 업로드

vesslctl volume upload가 기본 경로예요. 파일이 내 컴퓨터에서 S3로 바로 전송되기 때문에, 전송 크기는 네트워크 대역폭과 스토리지 할당량으로만 제한돼요.

Object storage 볼륨 선택 또는 생성

vesslctl volume list --type object

새 볼륨이 필요하다면 볼륨 만들기를 참고하거나 CLI로 만들 수 있어요:

vesslctl volume create \
  --name training-data \
  --storage <object-storage-slug> \
  --teams <team-name>

--teams는 이 볼륨을 마운트할 수 있는 팀을 지정해요. Object storage에서는 필수예요.

로컬 파일 업로드

vesslctl volume upload <volume-slug> ./dataset/ \
  --remote-prefix datasets/v1/ \
  --exclude "*.pyc" \
  --exclude "__pycache__"

--dry-run은 실제 전송 없이 파일 목록을 미리 보여줘요. --overwrite는 기존 원격 키를 덮어쓰고, 기본값은 동일 키를 건너뛰어요. 전체 플래그는 vesslctl volume upload를 참고하세요.

확인하고 마운트

vesslctl volume ls <volume-slug> --prefix datasets/v1/

Workspace에 마운트하거나, Job에 --object-volume <volume-slug>:/shared로 전달하세요.

다른 도구(aws s3 cp, rclone, DVC, 또는 자체 파이프라인)에서 업로드를 돌리고 싶다면 vesslctl volume token <volume-slug>로 해당 볼륨에만 한정된 임시 S3 자격증명과 엔드포인트 URL을 받을 수 있어요. vesslctl volume token 참고.

Cluster storage: Workspace를 거쳐서 적재

vesslctl volume upload는 Cluster storage 볼륨을 지원하지 않아요. 대신 Cluster storage 볼륨을 Workspace에 마운트한 뒤, 그 Workspace 안에서 마운트 경로로 데이터를 가져오세요.

볼륨을 마운트한 Workspace 만들기

Persistent volume에서 Cluster storage 볼륨을 명확한 경로(예: /data)에 마운트하세요:

vesslctl workspace create \
  --name data-loader \
  --cluster <cluster-slug> \
  --resource-spec <spec-slug> \
  --image quay.io/vessl-ai/torch:2.9.1-cuda13.0.1-py3.13-slim \
  --cluster-volume <cluster-volume-slug>:/data

필요한 도구(curl, wget, aws, huggingface-cli, git-lfs 등)가 들어 있는 어떤 컨테이너 이미지든 괜찮아요. 데이터를 옮기는 동안의 시간당 비용을 최소화하려면 vesslctl resource-spec list에서 CPU only 스펙을 골라요.

Workspace에 접속

Workspace가 running 상태가 될 때까지 기다린 뒤 SSH 또는 JupyterLab으로 접속하세요. Workspace에 접속하기를 참고하세요.접속한 뒤 cd /data(또는 지정한 마운트 경로)로 이동하세요. 이 경로 아래에 쓰는 모든 데이터는 Cluster storage 볼륨에 저장되고, Workspace를 일시정지하거나 terminate해도 유지돼요.

데이터 가져오기(아래 패턴 중 선택)

데이터가 어디에 있는지에 따라 다음 패턴 중 하나를 고르세요.

작업이 끝나면 Workspace 일시정지

Cluster storage 데이터는 pause 후에도 유지돼요. 데이터를 보관하려고 Workspace를 계속 켜둘 필요는 없어요. 일시정지하면 컴퓨트 비용 청구가 멈춰요:

vesslctl workspace pause <workspace-slug>

데이터를 추가하거나 수정해야 할 때는 vesslctl workspace start <workspace-slug>로 다시 시작할 수 있어요.

패턴 A: 인터넷에서 직접 다운로드

가장 단순하고 흔한 경우예요. 데이터가 이미 공개 URL(또는 토큰 인증 URL)에 있을 때 쓰세요.

# 볼륨이 /data에 마운트된 Workspace 셸 안에서
cd /data

# 일반 HTTP(S) 다운로드
wget https://example.com/datasets/imagenet-subset.tar.gz
tar -xzf imagenet-subset.tar.gz

# Hugging Face datasets / 모델 저장소
pip install -U "huggingface_hub[cli]"
huggingface-cli download <org>/<repo> --local-dir ./hf-cache --repo-type dataset

# S3 / GCS / Azure (각 클라우드의 CLI 사용)
aws s3 sync s3://my-bucket/datasets/v1/ ./datasets/v1/

대용량 전송에서는 aria2c -x 16이 HTTP 다운로드를 병렬화해 주고, rclone copy는 클라우드 스토리지 제공자별 retry/검증을 자동으로 처리해요.

패턴 B: 내 컴퓨터에서 SSH로 푸시

데이터가 내 컴퓨터에만 있고 인터넷을 한 번 거치는 게 번거로울 때, SSH로 마운트 경로에 직접 복사하세요.

# scp: 단일 파일 또는 디렉터리
scp -i /path/to/<key> -P <port> ./dataset.tar.gz \
  root@<workspace-host>:/data/

# rsync: 재시작 가능, 변경분만 전송. 큰 디렉터리에 추천.
rsync -avh --progress -e "ssh -i /path/to/<key> -p <port>" \
  ./dataset/ root@<workspace-host>:/data/

호스트, 포트, 키 경로는 Workspace의 Connect 탭에서 확인할 수 있어요. 자세한 내용은 Workspace에 접속하기를 참고하세요. 수 GB 이상의 전송은 rsync가 더 안전해요. 연결이 끊겨도 이어서 진행할 수 있고(--partial), 다시 실행하면 변경된 파일만 보내요.

패턴 C: Object storage를 중간 단계로 거치기

내 컴퓨터의 데이터를 다른 클러스터의 Cluster storage(또는 한 클러스터에서 다른 클러스터)로 일회성 복사할 때, Object storage를 휴대 가능한 중간 저장소로 활용해요. Object storage는 모든 클러스터에서 접근 가능하니까요.

# 1. 내 컴퓨터에서: Object storage 볼륨에 업로드
vesslctl volume upload <object-volume-slug> ./dataset/ \
  --remote-prefix v1/

# 2. 두 볼륨을 모두 마운트한 data-loader Workspace 생성
vesslctl workspace create \
  --name data-loader \
  --cluster <cluster-slug> \
  --resource-spec <spec-slug> \
  --image quay.io/vessl-ai/torch:2.9.1-cuda13.0.1-py3.13-slim \
  --object-volume <object-volume-slug>:/shared \
  --cluster-volume <cluster-volume-slug>:/data

# 3. Workspace 안에서: /shared의 내용을 /data로 복사
cp -r /shared/v1/. /data/v1/

복사가 끝나면 Object storage에 있는 사본은 보관 여부를 선택할 수 있어요. 더 이상 필요 없으면 볼륨에서 지우거나, 백업 용도로 그대로 두면 돼요.

패턴 D: Custom HTTP 포트 열기

브라우저로 끌어다 놓는 업로드 UI, 동기화 서버, 외부 서비스의 webhook 같은 게 필요할 때 쓰세요. Workspace 생성 시 custom HTTP 또는 TCP 포트를 열고(Workspace 만들기 → Advanced settings → 포트 참고) 마운트 경로에서 직접 서비스하면 돼요.

# 브라우저용 간단 업로드 UI를 custom HTTP 포트(예: 8000)에 띄우기
pip install --no-cache-dir uvicorn fastapi python-multipart
# … 또는 작은 업로드 서버 도구: filebrowser, miniserve --upload-files 등

# rclone serve: /data를 HTTP/WebDAV/SFTP로 노출
rclone serve http /data --addr :8000  # 내 컴퓨터의 rclone에서 이 엔드포인트로 동기화

CLI 업로드(Object)도, SSH 복사(패턴 B)도 맞지 않을 때 쓰세요. 예를 들어 SSH 접근 권한이 없는 동료가 파일을 떨궈야 하거나, 외부 서비스가 Workspace로 데이터를 푸시해야 하는 경우예요.

Custom 포트는 Workspace URL이 닿을 수 있는 어디서든 접근 가능해요. 다른 공개 엔드포인트와 똑같이 다뤄야 해요. basic auth, 일회성 토큰을 붙이거나, 적재가 끝나면 포트를 닫아 주세요.

안티패턴: `--cmd`에 데이터를 박지 마세요

특히 LLM 코딩 에이전트가 빠지기 쉬운 함정이 있어요. 데이터셋을 gzip+base64로 인코딩해 셸 한 줄로 --cmd에 통째로 넣는 방식이에요:

# 이렇게 하지 마세요. API가 256 KiB 초과 --cmd를 거절하고,
# 그보다 짧더라도 인라인 블롭은 재현·관찰이 어려워져요.
vesslctl job create \
  --cmd "echo 'H4sIAA...<3 MiB의 base64>...' | base64 -d | gunzip > /tmp/data && python eval.py"

API가 이를 거절해요. Job.command는 256 KiB, 환경변수 값은 각 8 KiB, 환경변수 쌍의 총 개수는 128개로 제한되고, 이 한도를 넘으면 4xx로 응답해요. 언제든 데이터는 볼륨에 올린 뒤(이 페이지) 마운트해서 사용하세요.

다음으로

스토리지 이해하기: Cluster storage와 Object storage의 특성과 가격을 비교해요.
볼륨 만들기: 콘솔에서 새 Object storage 볼륨을 만들어요.
Workspace 만들기: Workspace 생성 시 볼륨을 마운트해요.
vesslctl volume: upload, download, token, 관리 명령의 전체 CLI 레퍼런스.

시작하기

예제

vesslctl CLI

VESSL Cloud 사용하기

조직 운영하기

VM Clusters

용어집

서포트

볼륨에 데이터 가져오기

한눈에 보기

Object storage: 내 컴퓨터에서 업로드

Cluster storage: Workspace를 거쳐서 적재

패턴 A: 인터넷에서 직접 다운로드

패턴 B: 내 컴퓨터에서 SSH로 푸시

패턴 C: Object storage를 중간 단계로 거치기

패턴 D: Custom HTTP 포트 열기

안티패턴: `--cmd`에 데이터를 박지 마세요

다음으로

​한눈에 보기

​Object storage: 내 컴퓨터에서 업로드

​Cluster storage: Workspace를 거쳐서 적재

​패턴 A: 인터넷에서 직접 다운로드

​패턴 B: 내 컴퓨터에서 SSH로 푸시

​패턴 C: Object storage를 중간 단계로 거치기

​패턴 D: Custom HTTP 포트 열기

​안티패턴: --cmd에 데이터를 박지 마세요

​다음으로

한눈에 보기

Object storage: 내 컴퓨터에서 업로드

Cluster storage: Workspace를 거쳐서 적재

패턴 A: 인터넷에서 직접 다운로드

패턴 B: 내 컴퓨터에서 SSH로 푸시

패턴 C: Object storage를 중간 단계로 거치기

패턴 D: Custom HTTP 포트 열기

안티패턴: `--cmd`에 데이터를 박지 마세요

다음으로