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

# 파일 시스템 스냅샷에 자체 버킷 사용

> 샌드박스 파일 시스템 스냅샷을 CoreWeave가 관리하는 기본 버킷 대신 직접 소유한 객체 저장소 버킷에 저장하세요.

이 가이드에서는 CoreWeave가 관리하는 기본 버킷 대신 직접 소유한 객체 저장소 버킷에 [파일 시스템 스냅샷(FSS)](/ko/products/sandboxes/file-system-snapshots)을 저장하는 방법을 설명합니다.

기본적으로 CoreWeave는 조직의 FSS 버킷을 자동으로 프로비저닝하고 관리합니다. 별도로 할 일은 없습니다. 샌드박스 스냅샷을 직접 소유하고 제어하는 버킷에 저장하려는 경우에만 이 가이드를 따르세요.

다음 세 가지를 순서대로 설정합니다.

1. CoreWeave가 발급하는 샌드박스별 토큰을 조직의 임시 자격 증명으로 교환할 수 있도록 CoreWeave 조직에 **OIDC 공급자(워크로드 아이덴티티 제휴 설정)**를 설정합니다.
2. 연동된 ID에 FSS가 필요로 하는 범위의 액세스 권한을 부여하는 **버킷 정책**을 버킷에 설정합니다.
3. 한 번의 API 호출로 CoreWeave에 **버킷을 등록**합니다.

<Note>
  시작하기 전에 사용할 버킷을 생성하세요. 이 가이드에서는 버킷 생성을 다루지 않습니다. [버킷 생성](/products/storage/object-storage/buckets/create-bucket)을 참조하세요.
</Note>

<h2 id="how-fss-uses-your-bucket">
  FSS가 버킷을 사용하는 방식
</h2>

CoreWeave에 정적 액세스 키를 전달할 필요가 없습니다. 대신 샌드박스가 스냅샷을 생성하거나 복원할 때마다 다음 과정이 진행됩니다.

1. CoreWeave는 해당 샌드박스용으로 수명이 짧은 OIDC JWT를 발급합니다. 이 토큰은 `https://oidc.cwsandbox.com`에서 발급되며, 대상은 `cw-credential-vendor`이고, 조직, 사용자, 버킷 및 샌드박스가 액세스할 수 있는 정확한 객체를 파악할 수 있는 클레임을 포함합니다.
2. 샌드박스 내부에서 AWS SDK는 Workload Identity Federation을 통해 해당 토큰을 버킷으로 범위가 제한된 임시 S3 자격 증명으로 교환하고, 이를 자동으로 교체합니다.
3. 버킷 정책은 해당 제휴 ID에 권한을 부여합니다. 액세스를 사용자별 접두사와 해당 조직으로만 제한합니다.

Workload Identity Federation 설정(1단계)은 조직이 CoreWeave 토큰 발급자를 신뢰하도록 합니다. 버킷 정책(2단계)은 교환된 자격 증명을 평가하는 기준입니다. 둘 다 필요합니다.

<h2 id="values-you-need">
  필요한 값
</h2>

시작하기 전에 다음 값을 준비하세요. **고정**으로 표시된 값은 모든 고객에게 동일하며, 나머지 값은 고객마다 다릅니다.

| 값 | 설명 | 확인 위치 |
| - | - | - |
| OIDC 발급자 | CoreWeave 토큰 발급자 URL입니다. | **고정:** `https://oidc.cwsandbox.com` |
| 대상 (`aud`) | CoreWeave가 FSS 토큰에 지정하는 대상입니다. | **고정:** `cw-credential-vendor` |
| `[BUCKET-NAME]` | FSS용으로 생성한 버킷입니다. | 직접 정한 값입니다. [버킷 이름 규칙](#bucket-name-rules)을 참조하세요. |
| `[REGION]` | 버킷이 위치한 CoreWeave Availability Zone으로, S3 리전으로 사용됩니다. | [All Availability Zones](/platform/regions/all-availability-zones)(예: `US-EAST-01A`). |
| `[ORG-ID]` | CoreWeave 조직 ID로, 버킷을 소유하고 샌드박스를 실행하는 조직의 6자리 ID입니다. | Cloud Console. |
| `[CW-TOKEN]` | 조직 관리자의 CoreWeave API 액세스 토큰입니다. 3단계를 진행하려면 `SANDBOX_ADMIN` IAM 액션이 필요합니다. | [API 액세스 토큰 관리](/security/authn-authz/manage-api-access-tokens). |

<Note>
  조직 ID는 아래 정책에서 보안 주체 ARN, 각 `oidc:[ORG-ID]:...` condition key, 그리고 `org_id` 조건과 비교되는 값 등 나타나는 모든 위치에서 동일한 값을 사용합니다.
</Note>

<h2 id="step-1-register-the-oidc-provider">
  1단계: OIDC 공급자 등록
</h2>

CoreWeave Cloud Console에서 Workload Identity Federation OIDC 페이지로 이동하세요:

```text theme={"system"}
https://console.coreweave.com/organization/iam/workload-federation/oidc
```

다음 값으로 새 OIDC 공급자를 추가하세요:

| 필드 | 값 |
| - | - |
| 발급자 | `https://oidc.cwsandbox.com` |
| 대상 | `cw-credential-vendor` |

이 설정은 조직이 CoreWeave에서 샌드박스용으로 발급하는 토큰을 신뢰하도록 합니다. 이 설정이 없으면 [FSS의 버킷 사용 방식](#how-fss-uses-your-bucket)에 설명된 자격 증명 교환이 버킷 정책을 평가하기 전에 실패합니다.

OIDC Workload Identity Federation과 Cloud Console 설정의 작동 방식에 대한 배경 정보는 [OIDC로 Workload Identity Federation 사용](/products/storage/object-storage/auth-access/workload-identity-federation/use-oidc-tokens)을 참조하세요.

<h2 id="step-2-attach-the-bucket-policy">
  2단계: 버킷 정책 연결
</h2>

다음 정책을 버킷에 연결하세요. CoreWeave가 관리형 FSS 버킷에 적용하는 정책과 동일하며, 조직 ID로 매개변수화되어 있습니다.

자리표시자를 교체하세요:

* `[BUCKET-NAME]`을 버킷 이름으로 교체하세요.
* `[ORG-ID]`를 나타나는 모든 곳에서 6자리 조직 ID로 교체하세요.

```json theme={"system"}
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "OIDCFederatedScopedAccess",
      "Effect": "Allow",
      "Principal": {
        "AWS": "arn:aws:iam::[ORG-ID]:role/https://oidc.cwsandbox.com:*"
      },
      "Action": [
        "s3:GetObject",
        "s3:PutObject",
        "s3:AbortMultipartUpload",
        "s3:ListMultipartUploadParts",
        "s3:CreateMultipartUpload",
        "s3:UploadPart",
        "s3:CompleteMultipartUpload"
      ],
      "Resource": "arn:aws:s3:::[BUCKET-NAME]/${oidc:[ORG-ID]:user_hash}/*",
      "Condition": {
        "StringEquals": {
          "oidc:[ORG-ID]:org_id": "[ORG-ID]",
          "oidc:[ORG-ID]:bucket_name": "[BUCKET-NAME]"
        }
      }
    },
    {
      "Sid": "OIDCFederatedRestoreObjectScope",
      "Effect": "Allow",
      "Principal": {
        "AWS": "arn:aws:iam::[ORG-ID]:role/https://oidc.cwsandbox.com:*"
      },
      "Action": "s3:GetObject",
      "Resource": "arn:aws:s3:::[BUCKET-NAME]/${oidc:[ORG-ID]:restore_object_key}",
      "Condition": {
        "StringEquals": {
          "oidc:[ORG-ID]:org_id": "[ORG-ID]",
          "oidc:[ORG-ID]:bucket_name": "[BUCKET-NAME]"
        }
      }
    },
    {
      "Sid": "DenyCrossOrg",
      "Effect": "Deny",
      "Principal": {
        "AWS": "arn:aws:iam::[ORG-ID]:role/https://oidc.cwsandbox.com:*"
      },
      "Action": "s3:*",
      "Resource": [
        "arn:aws:s3:::[BUCKET-NAME]",
        "arn:aws:s3:::[BUCKET-NAME]/*"
      ],
      "Condition": {
        "StringNotEquals": {
          "oidc:[ORG-ID]:org_id": "[ORG-ID]"
        }
      }
    }
  ]
}
```

<h3 id="what-each-statement-does">
  각 문이 하는 일
</h3>

* \*\*`OIDCFederatedScopedAccess`\*\*는 스냅샷 작업을 위한 조회 및 쓰기 권한입니다. 이는 사용자별 접두사 `${oidc:[ORG-ID]:user_hash}/*`로 범위가 지정됩니다. 주어진 사용자의 토큰은 자신의 해시된 접두사 아래의 키만 확인할 수 있으므로, 조직의 사용자는 서로의 스냅샷을 덮어쓸 수 없습니다. `bucket_name` 조건은 다른 버킷용으로 발급된 토큰이 여기서 사용되는 것을 방지합니다.
* \*\*`OIDCFederatedRestoreObjectScope`\*\*는 복원이 읽고 있는 정확한 객체에 대한 제한된 `GetObject` 권한입니다. `${oidc:[ORG-ID]:restore_object_key}`입니다. 이를 통해 한 샌드박스가 조직의 다른 사용자가 생성한 스냅샷을 복원할 수 있으며, 사용자별 쓰기 범위 지정은 여전히 유지됩니다.
* \*\*`DenyCrossOrg`\*\*는 심층 방어입니다. 토큰의 `org_id` 클레임이 조직이 아닌 경우 모든 것을 거부하므로, 유출되거나 잘못 라우팅된 토큰도 버킷에 액세스할 수 없습니다.

<Note>
  조건 키는 CoreWeave AI Object Storage가 평가하는 `oidc:[ORG-ID]:[CLAIM]` 형식을 사용합니다. CoreWeave는 샌드박스의 토큰에서 요청 시 `${oidc:[ORG-ID]:user_hash}` 및 `${oidc:[ORG-ID]:restore_object_key}` 변수를 채웁니다. 이를 대체하지 마십시오. 그대로 두십시오. 내부의 `[ORG-ID]`만 입력하면 됩니다.
</Note>

<h2 id="step-3-register-the-bucket-with-coreweave">
  3단계: CoreWeave에 버킷 등록
</h2>

조직의 FSS 버킷 설정을 지정하여 CoreWeave가 사용자의 버킷을 사용하도록 하세요. 이 작업은 조직의 설정 전체를 교체하는 단일 `PUT` 요청입니다.

```bash theme={"system"}
curl -X PUT https://api.cwsandbox.com/v1beta2/file-system-snapshots/bucket-config \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer [CW-TOKEN]" \
  -d '{
    "bucketName": "[BUCKET-NAME]",
    "region": "[REGION]"
  }'
```

* `api.cwsandbox.com`은 표준 샌드박스 API 호스트이며, 데이터 플레인이 샌드박스 시작 등 다른 Call에 사용하는 호스트와 동일합니다.
* 이 호출에는 [Access Policies](/security/iam/access-policies/manage) 페이지에서 부여하는 `SANDBOX_ADMIN` IAM 액션이 필요합니다. 버킷을 변경하면 이후 생성되는 모든 스냅샷의 저장 위치가 달라지므로 관리자만 사용할 수 있습니다. [버킷 변경 또는 되돌리기](#change-or-revert-your-bucket)를 참조하세요.
* `bucketName`과 `region`은 둘 다 필수입니다. 둘 중 하나만 전송하면 `CWSANDBOX_INVALID_REQUEST`로 거부됩니다.

성공 응답은 자체 버킷 사용 모드가 적용되었음을 확인해 줍니다:

```json title="Example output" theme={"system"}
{
  "bucketName": "my-fss-bucket",
  "region": "US-EAST-01A",
  "mode": "FILE_SYSTEM_SNAPSHOT_BUCKET_MODE_BRING_YOUR_OWN",
  "effectiveBucketName": "my-fss-bucket"
}
```

언제든지 설정을 다시 조회할 수 있습니다. 조직의 모든 구성원이 Admin 역할 없이 조회할 수 있습니다:

```bash theme={"system"}
curl https://api.cwsandbox.com/v1beta2/file-system-snapshots/bucket-config \
  -H "Authorization: Bearer [CW-TOKEN]"
```

<h2 id="step-4-verify">
  4단계: 확인
</h2>

실제 샌드박스에서 스냅샷 생성 및 복원 과정을 실행하세요:

1. 새 파일 시스템으로 샌드박스를 시작하세요:

   ```bash theme={"system"}
   curl -X POST https://api.cwsandbox.com/v1beta2/sandboxes \
     -H "Authorization: Bearer [CW-TOKEN]" \
     -H "Content-Type: application/json" \
     -d '{
       "containerImage": "ubuntu:22.04",
       "command": "sleep",
       "args": ["3600"],
       "fileSystem": { "mountPath": "/work", "size": "10Gi" }
     }'
   ```

2. `/work` 아래에 파일을 작성한 다음, 샌드박스를 중지하면서 스냅샷을 생성하세요. `[SANDBOX-ID]`를 시작한 샌드박스의 ID로 바꾸세요. 응답에 `fileSystemSnapshotId`가 반환됩니다:

   ```bash theme={"system"}
   curl -X POST https://api.cwsandbox.com/v1beta2/sandboxes/[SANDBOX-ID]/stop \
     -H "Authorization: Bearer [CW-TOKEN]" \
     -H "Content-Type: application/json" \
     -d '{
       "sandboxId": "[SANDBOX-ID]",
       "fileSystemSnapshotOnStop": true,
       "waitForReady": true,
       "maxTimeoutSeconds": 600
     }'
   ```

3. 스냅샷을 새 샌드박스에 복원하세요. `[SNAPSHOT-ID]`를 이전 단계에서 반환된 `fileSystemSnapshotId`로 바꾸세요:

   ```bash theme={"system"}
   curl -X POST https://api.cwsandbox.com/v1beta2/sandboxes \
     -H "Authorization: Bearer [CW-TOKEN]" \
     -H "Content-Type: application/json" \
     -d '{
       "containerImage": "ubuntu:22.04",
       "command": "sleep",
       "args": ["3600"],
       "fileSystem": {
         "mountPath": "/work",
         "size": "10Gi",
         "fileSystemSnapshot": { "fileSystemSnapshotId": "[SNAPSHOT-ID]" }
       }
     }'
   ```

작성한 파일이 복원된 샌드박스에 있으면 버킷이 정상적으로 작동하는 것입니다. 스냅샷이 버킷에 저장되었는지 직접 확인할 수도 있습니다: `GetFileSystemSnapshot`과 `ListFileSystemSnapshots`가 반환하는 각 `FileSystemSnapshot`에는 스냅샷이 저장된 버킷을 나타내는 `objectBucket` 필드가 포함되어 있습니다.

<h2 id="change-or-revert-your-bucket">
  버킷 변경 또는 되돌리기
</h2>

3단계의 `PUT`은 전체 교체 방식이므로, 설정을 변경하거나 취소할 때도 이 방법을 사용합니다.

* **CoreWeave 관리형으로 되돌리기**: 빈 본문(`{}`)으로 `PUT`을 요청하세요. CoreWeave가 자동으로 버킷 관리를 재개합니다.
* **다른 버킷으로 이동**: 새 `bucketName`과 `region`으로 `PUT`을 요청하세요.

<Warning>
  버킷을 변경하기 전에 다음 내용을 확인하세요. FSS 버킷을 변경하거나 지우면 이전 버킷에 저장된 스냅샷에 더 이상 액세스할 수 없습니다. CoreWeave는 버킷 간에 데이터를 복사하지 않습니다.

  * 스냅샷이 저장된 버킷이 현재 버킷과 다르면 복원 시 `CWSANDBOX_FSS_BUCKET_MISMATCH`가 반환되며, 이 오류에는 스냅샷의 버킷과 현재 버킷이 함께 표시됩니다. 이렇게 남겨진 스냅샷은 목록 및 조회 Call에는 계속 나타나지만, 다른 버킷이 활성 상태인 동안에는 복원할 수 없습니다.
  * 이 작업은 되돌릴 수 있습니다. 설정에서 이전 버킷을 다시 지정하면 해당 스냅샷을 다시 복원할 수 있습니다.
  * 이미 실행 중인 샌드박스는 영향을 받지 않습니다. 실행 중인 샌드박스는 시작 시 연결된 버킷에 계속 스냅샷을 저장합니다. 버킷 변경은 이후에 생성되는 샌드박스에만 적용됩니다.
</Warning>

<h2 id="troubleshooting">
  문제 해결
</h2>

| 증상 | 예상 원인 | 해결 방법 |
| - | - | - |
| 스냅샷 생성 또는 복원 시 `AccessDenied` | 버킷 정책의 보안 주체, `org_id` 값 또는 `bucket_name` 조건이 일치하지 않거나, 워크로드 아이덴티티 제휴 설정(1단계)이 없거나 대상이 잘못되었습니다. | OIDC 공급자의 발급자가 `https://oidc.cwsandbox.com`이고 대상이 `cw-credential-vendor`인지 확인하세요. 정책의 `[ORG-ID]`와 `[BUCKET-NAME]`이 올바른지 확인하세요. |
| 복원 시 `CWSANDBOX_FSS_BUCKET_MISMATCH` | FSS 버킷을 변경했습니다. 스냅샷이 현재 버킷과 다른 버킷에 있습니다. | 스냅샷이 저장된 버킷으로 설정을 되돌리세요. |
| `PUT` 시 `CWSANDBOX_INVALID_REQUEST` | 설정이 불완전하거나(버킷은 있지만 리전이 없거나 그 반대), 버킷 이름이 잘못되었습니다. | `bucketName`과 `region`을 함께 전송하세요. [버킷 이름 규칙](#bucket-name-rules)을 확인하세요. |
| `PUT` 시 `PermissionDenied` | 토큰의 사용자에게 `SANDBOX_ADMIN` IAM 액션 권한이 없습니다. | [Access Policies](/security/iam/access-policies/manage) 페이지에서 `SANDBOX_ADMIN` 권한을 부여하세요. |
| `PathStyleRequestNotAllowed` | 경로 스타일 S3 주소 지정이 사용되었습니다. | CoreWeave AI Object Storage는 가상 호스팅 스타일 주소 지정을 요구합니다. |
| 스냅샷 생성 시 `CWSANDBOX_FSS_AUTH_FAILED` | 자격 증명 교환 또는 버킷 권한 부여에 실패했습니다. | 1단계(OIDC 공급자)와 2단계(버킷 정책)를 다시 확인하세요. 문제가 지속되면 CoreWeave Support에 문의하세요. |

샌드박스에 허용 목록 기반 이그레스만 허용하는 정책이 적용되어 있는 경우, CoreWeave 자격 증명 엔드포인트(`https://api.coreweave.com`)에 연결할 수 있는지 확인하세요. 그렇지 않으면 자격 증명 조회 시간이 초과되어 첫 번째 S3 오퍼레이션이 실패합니다.

<h2 id="reference">
  레퍼런스
</h2>

다음 섹션에서는 버킷 이름 규칙, 정책이 부여하는 S3 액션, 그리고 정책이 참조하는 토큰 클레임을 설명합니다.

<h3 id="bucket-name-rules">
  버킷 이름 규칙
</h3>

3단계에서 버킷을 등록하면 CoreWeave가 표준 객체 저장소 규칙에 따라 이름을 검증합니다.

<Accordion title="Bucket naming rules">
  Bucket names must be globally unique and adhere to the following rules:

  * **Length:** 3 to 63 characters.
  * **Characters:** Only lowercase letters (`a-z`), numbers (`0-9`), and hyphens (`-`). No dots, uppercase letters, underscores, spaces, or other special characters.
  * **Start and end:** Must begin and end with a letter or number. Cannot start or end with a hyphen (`-`).
  * **Prohibited patterns:** Cannot start with `xn--`.
  * **Reserved:** Must not begin with `cw-`, `vip-`, or `log-stitcher-ch-`. Must not be the exact name `int`. CoreWeave reserves these for internal use.
</Accordion>

`region`은 CoreWeave Availability Zone(예: `US-EAST-01A`)이며, 버킷이 위치한 영역과 일치해야 합니다. 전체 영역 목록은 [모든 Availability Zone](/platform/regions/all-availability-zones)을 참조하세요.

<h3 id="s3-actions-granted">
  S3 액션 부여
</h3>

정책은 FSS에 필요한 액션만 정확히 부여하며 그 이상은 부여하지 않습니다: `s3:GetObject`, `s3:PutObject`, `s3:CreateMultipartUpload`, `s3:UploadPart`, `s3:CompleteMultipartUpload`, `s3:AbortMultipartUpload`, `s3:ListMultipartUploadParts`. 쓰기는 멀티파트 업로드를 사용하며, 복원은 `GetObject`를 사용합니다.

<h3 id="token-claims-used-by-the-policy">
  정책에서 사용하는 토큰 클레임
</h3>

CoreWeave는 이러한 클레임을 각 샌드박스별 토큰에 스탬프합니다. 버킷 정책 조건은 이를 `oidc:[ORG-ID]:[CLAIM]`으로 참조합니다.

| Claim | Used for |
| - | - |
| `org_id` | 모든 `Allow`와 `DenyCrossOrg` 가드에서 조직과 일치합니다. |
| `user_hash` | 사용자별 쓰기 접두사 (`[USER-HASH]/...`). |
| `bucket_name` | 토큰을 이 버킷에 연결합니다. |
| `restore_object_key` | 복원에서 조회할 수 있는 정확한 객체입니다. |

<h2 id="related-resources">
  관련 리소스
</h2>

* [파일 시스템 스냅샷](/ko/products/sandboxes/file-system-snapshots): 스냅샷, 복원, 포크의 작동 방식을 설명합니다.
* [OIDC로 Workload Identity Federation 사용하기](/products/storage/object-storage/auth-access/workload-identity-federation/use-oidc-tokens): OIDC 페더레이션과 Cloud Console 설정의 작동 방식을 설명합니다.
* [버킷 생성](/products/storage/object-storage/buckets/create-bucket): 이 가이드에서 이미 있다고 가정하는 버킷을 생성합니다.
* [All Availability Zones](/platform/regions/all-availability-zones): 버킷 리전으로 사용할 영역을 확인합니다.
* [API 액세스 토큰 관리](/security/authn-authz/manage-api-access-tokens): 3단계에서 사용할 토큰을 생성합니다.
* [IAM Access Policies](/security/iam/access-policies/manage): 3단계에 필요한 `SANDBOX_ADMIN` 액션을 부여합니다.