> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cloud.vessl.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 볼륨에 데이터 가져오기

> Object storage에는 CLI로 업로드하고, Cluster storage에는 볼륨이 마운트된 Workspace를 통해 데이터를 가져오는 방법을 안내해요.

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

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

## 한눈에 보기

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

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

***

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

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

<Steps>
  <Step title="Object storage 볼륨 선택 또는 생성">
    ```bash theme={null}
    vesslctl volume list --type object
    ```

    새 볼륨이 필요하다면 [볼륨 만들기](/ko/member/volume/create)를 참고하거나 CLI로 만들 수 있어요:

    ```bash theme={null}
    vesslctl volume create \
      --name training-data \
      --storage <object-storage-slug> \
      --teams <team-name>
    ```

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

  <Step title="로컬 파일 업로드">
    ```bash theme={null}
    vesslctl volume upload <volume-slug> ./dataset/ \
      --remote-prefix datasets/v1/ \
      --exclude "*.pyc" \
      --exclude "__pycache__"
    ```

    `--dry-run`은 실제 전송 없이 파일 목록을 미리 보여줘요. `--overwrite`는 기존 원격 키를 덮어쓰고, 기본값은 동일 키를 건너뛰어요. 전체 플래그는 [`vesslctl volume upload`](/ko/cli/commands/volume#upload)를 참고하세요.
  </Step>

  <Step title="확인하고 마운트">
    ```bash theme={null}
    vesslctl volume ls <volume-slug> --prefix datasets/v1/
    ```

    [Workspace](/ko/member/workspace/create#persistent-volume)에 마운트하거나, Job에 `--object-volume <volume-slug>:/shared`로 전달하세요.
  </Step>
</Steps>

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

***

## Cluster storage: Workspace를 거쳐서 적재

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

<Steps>
  <Step title="볼륨을 마운트한 Workspace 만들기">
    [Persistent volume](/ko/member/workspace/create#persistent-volume)에서 Cluster storage 볼륨을 명확한 경로(예: `/data`)에 마운트하세요:

    ```bash theme={null}
    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** 스펙을 골라요.
  </Step>

  <Step title="Workspace에 접속">
    Workspace가 `running` 상태가 될 때까지 기다린 뒤 SSH 또는 JupyterLab으로 접속하세요. [Workspace에 접속하기](/ko/member/workspace/connect)를 참고하세요.

    접속한 뒤 `cd /data`(또는 지정한 마운트 경로)로 이동하세요. 이 경로 아래에 쓰는 모든 데이터는 Cluster storage 볼륨에 저장되고, Workspace를 일시정지하거나 terminate해도 유지돼요.
  </Step>

  <Step title="데이터 가져오기(아래 패턴 중 선택)">
    데이터가 어디에 있는지에 따라 다음 패턴 중 하나를 고르세요.
  </Step>

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

    ```bash theme={null}
    vesslctl workspace pause <workspace-slug>
    ```

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

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

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

```bash theme={null}
# 볼륨이 /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로 마운트 경로에 직접 복사하세요.

```bash theme={null}
# 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에 접속하기](/ko/member/workspace/connect)를 참고하세요. 수 GB 이상의 전송은 `rsync`가 더 안전해요. 연결이 끊겨도 이어서 진행할 수 있고(`--partial`), 다시 실행하면 변경된 파일만 보내요.

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

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

```bash theme={null}
# 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 → 포트](/ko/member/workspace/create) 참고) 마운트 경로에서 직접 서비스하면 돼요.

```bash theme={null}
# 브라우저용 간단 업로드 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로 데이터를 푸시해야 하는 경우예요.

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

***

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

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

```bash theme={null}
# 이렇게 하지 마세요. 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로 응답해요.

언제든 데이터는 볼륨에 올린 뒤(이 페이지) 마운트해서 사용하세요.

***

## 다음으로

* [스토리지 이해하기](/ko/member/volume/overview): Cluster storage와 Object storage의 특성과 가격을 비교해요.
* [볼륨 만들기](/ko/member/volume/create): 콘솔에서 새 Object storage 볼륨을 만들어요.
* [Workspace 만들기](/ko/member/workspace/create): Workspace 생성 시 볼륨을 마운트해요.
* [`vesslctl volume`](/ko/cli/commands/volume): upload, download, token, 관리 명령의 전체 CLI 레퍼런스.