> ## 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.

# Bring your own bucket for file system snapshots

> Store sandbox file system snapshots in an object storage bucket you own instead of the CoreWeave-managed default.

このガイドでは、CoreWeave が管理するデフォルトのバケットではなく、ご自身が所有するオブジェクトストレージバケットに[ファイルシステムスナップショット (FSS)](/ja/products/sandboxes/file-system-snapshots) を保存する方法を説明します。

デフォルトでは、CoreWeave が組織の FSS バケットを自動的にプロビジョニングし、管理します。特に操作は必要ありません。サンドボックスのスナップショットを、ご自身が所有・管理するバケットに保存する場合にのみ、このガイドに従ってください。

次の 3 つを順番に設定します。

1. CoreWeave 組織内の **OIDC プロバイダー (Workload Identity Federation 設定)**。これにより、CoreWeave がサンドボックスごとに発行するトークンを、組織内の一時的な認証情報と交換できます。
2. バケットの**バケットポリシー**。フェデレーションされたアイデンティティに、FSS に必要な範囲のアクセス権を付与します。
3. 1 回の呼び出しによる、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. バケットポリシーは、そのフェデレーションされたアイデンティティを承認します。アクセスをユーザーごとの接頭辞と、お客様の組織のみに制限します。

Workload Identity Federation の設定 (ステップ 1) により、お客様の組織が CoreWeave のトークン発行者を信頼します。バケットポリシー (ステップ 2) は、交換された認証情報を評価する基準となります。どちらも必須です。

<h2 id="values-you-need">
  必要な値
</h2>

始める前にこれらを収集してください。**fixed** とマークされた値はすべての顧客で同じです。残りはお客様固有のものです。

| 値 | 説明 | 取得元 |
| - | - | - |
| OIDC 発行者 | CoreWeave トークン発行者 URL。 | **Fixed:** `https://oidc.cwsandbox.com` |
| オーディエンス (`aud`) | CoreWeave が FSS トークンにスタンプするオーディエンス。 | **Fixed:** `cw-credential-vendor` |
| `[BUCKET-NAME]` | FSS 用に作成したバケット。 | お客様が選択しました。[バケット名ルール](#bucket-name-rules) を参照してください。 |
| `[REGION]` | バケットが存在する CoreWeave Availability Zone で、S3 リージョンとして使用されます。 | [すべてのアベイラビリティゾーン](/platform/regions/all-availability-zones)、例: `US-EAST-01A`。 |
| `[ORG-ID]` | CoreWeave 組織 ID で、バケットを所有しサンドボックスを実行する組織の 6 文字の ID です。 | Cloud console。 |
| `[CW-TOKEN]` | 組織管理者の CoreWeave API アクセストークン。ステップ 3 では `SANDBOX_ADMIN` IAM action が必要です。 | [API アクセストークンを管理する](/security/authn-authz/manage-api-access-tokens)。 |

<Note>
  組織 ID は、以下のポリシーで出現するすべての場所で同じ値です: プリンシパル ARN 内、各 `oidc:[ORG-ID]:...` 条件キー内、および `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`** は、リストアで読み取る特定のオブジェクト `${oidc:[ORG-ID]:restore_object_key}` のみに `GetObject` を許可します。これにより、ユーザーごとの書き込み範囲の制限を維持しながら、サンドボックスで組織内の別のユーザーが作成したスナップショットをリストアできます。
* **`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 ホストで、データプレーンがサンドボックスの起動などの他の呼び出しに使用するものと同じです。
* この呼び出しには、[アクセスポリシー](/security/iam/access-policies/manage) ページで付与される `SANDBOX_ADMIN` IAM action が必要です。バケットを変更すると、以降のすべてのスナップショットの保存先が変わるため、管理者権限が必要です。[バケットの変更または元に戻す方法](#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` が返され、スナップショットのバケットと現在のバケットが示されます。アクセスできなくなったスナップショットは、list と get の呼び出し結果には引き続き表示されます。ただし、別のバケットが有効な間はリストアできません。
  * この変更は元に戻せます。設定を以前のバケットに戻すと、それらのスナップショットを再びリストアできるようになります。
  * 実行中のサンドボックスには影響しません。実行中のサンドボックスは、起動時に関連付けられたバケットへのスナップショットの保存を継続します。バケットの変更は、今後作成されるサンドボックスにのみ影響します。
</Warning>

<h2 id="troubleshooting">
  Troubleshooting
</h2>

| 症状 | 考えられる原因 | 対処方法 |
| - | - | - |
| スナップショットまたはリストア時の `AccessDenied` | バケットポリシーのプリンシパル、`org_id` の値、または `bucket_name` の条件が一致しない、または Workload Identity Federation の設定 (手順 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 action がありません。 | [アクセス ポリシー](/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 の action、およびポリシーが参照するトークンのクレームについて説明します。

<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`) であり、バケットが存在するゾーンと一致する必要があります。ゾーンの全一覧については、[すべてのアベイラビリティゾーン](/platform/regions/all-availability-zones)を参照してください。

<h3 id="s3-actions-granted">
  許可される S3 action
</h3>

このポリシーは、FSS に必要な action のみを許可します: `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]` として参照します。

| クレーム | 用途 |
| - | - |
| `org_id` | すべての `Allow` と `DenyCrossOrg` ガードで組織と照合します。 |
| `user_hash` | ユーザーごとの書き込み用接頭辞 (`[USER-HASH]/...`) 。 |
| `bucket_name` | トークンをこのバケットに紐付けます。 |
| `restore_object_key` | リストア時に読み取り可能な特定のオブジェクト。 |

<h2 id="related-resources">
  関連リソース
</h2>

* [ファイルシステムスナップショット](/ja/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): このガイドで作成済みと想定しているバケットを作成します。
* [すべてのアベイラビリティゾーン](/platform/regions/all-availability-zones): バケットのリージョンとして使用するゾーン。
* [API アクセストークンを管理する](/security/authn-authz/manage-api-access-tokens): ステップ 3 で使用するトークンを作成します。
* [IAM アクセスポリシー](/security/iam/access-policies/manage): ステップ 3 に必須の `SANDBOX_ADMIN` action を付与します。