> ## 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.
# Utilisez votre propre bucket pour les instantanés du système de fichiers
> Stockez les instantanés du système de fichiers des sandboxes dans un bucket de stockage d’objets qui vous appartient, plutôt que dans le bucket managé par CoreWeave utilisé par défaut.
Ce guide explique comment stocker les [instantanés du système de fichiers (FSS)](/fr/products/sandboxes/file-system-snapshots) dans un bucket de stockage d’objets qui vous appartient, plutôt que dans le bucket par défaut managé par CoreWeave.
Par défaut, CoreWeave provisionne et gère automatiquement un bucket FSS pour votre organisation, sans aucune action de votre part. Ne suivez ce guide que si vous souhaitez que les instantanés de vos bacs à sable soient stockés dans un bucket que vous possédez et contrôlez.
Vous allez configurer trois éléments, dans l’ordre :
1. **Un fournisseur OIDC (configuration de Fédération d’identités de charges de travail)** dans votre organisation CoreWeave, afin que les jetons émis par CoreWeave pour chaque sandbox puissent être échangés contre des identifiants d’authentification temporaires dans votre organisation.
2. **Une stratégie de bucket** sur votre bucket, qui accorde à cette identité fédérée l’accès limité nécessaire à FSS.
3. **L’enregistrement du bucket** auprès de CoreWeave, en un seul appel d’API.
Avant de commencer, créez le bucket que vous souhaitez utiliser. Ce guide ne traite pas de la création de buckets. Voir [Créer des buckets](/products/storage/object-storage/buckets/create-bucket).
Comment FSS utilise votre bucket
Vous ne fournissez jamais de clé d’accès statique à CoreWeave. À la place, chaque fois qu’une sandbox crée ou restaure un instantané :
1. CoreWeave génère un JWT OIDC de courte durée pour cette sandbox. Le jeton est émis par `https://oidc.cwsandbox.com`, a pour audience `cw-credential-vendor` et contient des claims qui identifient l’organisation, l’utilisateur, le bucket et l’objet précis auquel la sandbox est autorisée à accéder.
2. Dans la sandbox, l’AWS SDK échange ce jeton, via la Fédération d’identités de charges de travail, contre des identifiants d’authentification S3 temporaires limités à votre bucket, puis les fait pivoter automatiquement.
3. Votre stratégie de bucket autorise cette identité fédérée. Elle restreint l’accès à un préfixe propre à chaque utilisateur et à votre seule organisation.
C’est la configuration de la Fédération d’identités de charges de travail (étape 1) qui permet à votre organisation de faire confiance à l’émetteur de jetons de CoreWeave. C’est par rapport à la stratégie de bucket (étape 2) que les identifiants d’authentification ainsi obtenus sont évalués. Les deux sont requises.
Valeurs nécessaires
Rassemblez ces valeurs avant de commencer. Les valeurs marquées **fixe** sont identiques pour tous les clients. Les autres vous sont propres.
| Valeur | Description | Provenance |
| - | - | - |
| Émetteur OIDC | L’URL de l’émetteur de jetons CoreWeave. | **Fixe :** `https://oidc.cwsandbox.com` |
| Audience (`aud`) | L’audience que CoreWeave appose sur les jetons FSS. | **Fixe :** `cw-credential-vendor` |
| `[BUCKET-NAME]` | Le bucket que vous avez créé pour FSS. | Vous l’avez choisi. Voir [Règles de nommage des buckets](#bucket-name-rules). |
| `[REGION]` | La CoreWeave Availability Zone où se trouve votre bucket, utilisée comme région S3. | [Toutes les Availability Zones](/platform/regions/all-availability-zones), par exemple `US-EAST-01A`. |
| `[ORG-ID]` | L’identifiant de votre organisation CoreWeave, c’est-à-dire l’identifiant à 6 caractères de l’organisation propriétaire du bucket et qui exécute vos bacs à sable. | Cloud console. |
| `[CW-TOKEN]` | Un jeton d’accès à l’API CoreWeave appartenant à un administrateur de l’organisation. L’action IAM `SANDBOX_ADMIN` est requise pour l’étape 3. | [Gérer les jetons d’accès à l’API](/security/authn-authz/manage-api-access-tokens). |
L’identifiant de votre organisation est le même partout où il apparaît dans la politique ci-dessous : dans l’ARN du principal, dans chaque clé de condition `oidc:[ORG-ID]:...` et comme valeur de référence de la condition `org_id`.
Étape 1 : Enregistrer le fournisseur OIDC
Dans la Cloud Console CoreWeave, accédez à la page OIDC de la fédération d’identités de charges de travail :
```text theme={"system"}
https://console.coreweave.com/organization/iam/workload-federation/oidc
```
Ajoutez un nouveau fournisseur OIDC avec les valeurs suivantes :
| Champ | Valeur |
| - | - |
| Émetteur | `https://oidc.cwsandbox.com` |
| Audience | `cw-credential-vendor` |
Cette configuration indique à votre organisation de faire confiance aux jetons que CoreWeave émet pour vos sandboxes. Sans elle, l’échange d’identifiants d’authentification décrit dans [Comment FSS utilise votre bucket](#how-fss-uses-your-bucket) échoue avant même qu’une stratégie de bucket ne soit évaluée.
Pour en savoir plus sur le fonctionnement de la Fédération d’identités de charges de travail OIDC et de la configuration dans la Cloud Console, consultez [Utiliser la Fédération d’identités de charges de travail avec OIDC](/products/storage/object-storage/auth-access/workload-identity-federation/use-oidc-tokens).
Étape 2 : joindre la stratégie de bucket
Joignez la stratégie suivante à votre bucket. Il s’agit de la même stratégie que celle appliquée par CoreWeave aux buckets FSS managés, paramétrée avec l’identifiant de votre organisation.
Remplacez les valeurs de substitution :
* `[BUCKET-NAME]` par le nom de votre bucket.
* `[ORG-ID]` par l’identifiant à 6 caractères de votre organisation, à chaque occurrence.
```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]"
}
}
}
]
}
```
Rôle de chaque instruction
* **`OIDCFederatedScopedAccess`** accorde l’accès en lecture et en écriture nécessaire aux opérations sur les instantanés. Elle est limitée à un préfixe propre à chaque utilisateur, `${oidc:[ORG-ID]:user_hash}/*`. Le jeton d’un utilisateur donné ne se résout qu’en clés situées sous son propre préfixe haché, de sorte que les utilisateurs de votre organisation ne peuvent pas écraser les instantanés les uns des autres. La condition `bucket_name` empêche qu’un jeton émis pour un autre bucket soit utilisé ici.
* **`OIDCFederatedRestoreObjectScope`** est une autorisation `GetObject` restreinte à l’objet précis lu lors d’une restauration, `${oidc:[ORG-ID]:restore_object_key}`. Elle permet à une sandbox de restaurer un instantané créé par un autre utilisateur de votre organisation, tout en préservant la limitation des écritures par utilisateur.
* **`DenyCrossOrg`** assure une défense en profondeur. Elle refuse tout accès si la revendication `org_id` du jeton ne correspond pas à votre organisation, de sorte que même un jeton divulgué ou mal acheminé ne peut pas accéder à votre bucket.
Les clés de condition utilisent la forme `oidc:[ORG-ID]:[CLAIM]` évaluée par CoreWeave AI Object Storage. CoreWeave renseigne les variables `${oidc:[ORG-ID]:user_hash}` et `${oidc:[ORG-ID]:restore_object_key}` à partir du jeton de la sandbox au moment de la requête. Ne les remplacez pas : laissez-les telles quelles. Seul le `[ORG-ID]` qu’elles contiennent est à renseigner par vos soins.
Étape 3 : Enregistrer le bucket auprès de CoreWeave
Indiquez à CoreWeave d'utiliser votre bucket en définissant la configuration du bucket FSS de votre organisation. Une seule requête `PUT` suffit ; elle remplace intégralement la configuration de l'organisation.
```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` est l’hôte standard de l’API des sandboxes, celui-là même qu’utilise le plan de données pour d’autres appels, comme le démarrage d’une sandbox.
* Cet appel requiert l’action IAM `SANDBOX_ADMIN`, accordée sur la page [Access Policies](/security/iam/access-policies/manage). Il est réservé aux administrateurs, car modifier le bucket détermine l’emplacement où seront stockés tous les futurs instantanés. Voir [Modifier ou rétablir votre bucket](#change-or-revert-your-bucket).
* `bucketName` et `region` doivent être fournis ensemble. Toute requête contenant l’un sans l’autre est rejetée avec l’erreur `CWSANDBOX_INVALID_REQUEST`.
Une réponse réussie confirme que le mode « bring your own bucket » (utilisation de votre propre bucket) est actif :
```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"
}
```
Vous pouvez consulter la configuration à tout moment. Tout membre de l’organisation peut la lire, sans avoir besoin du rôle d’administrateur :
```bash theme={"system"}
curl https://api.cwsandbox.com/v1beta2/file-system-snapshots/bucket-config \
-H "Authorization: Bearer [CW-TOKEN]"
```
Étape 4 : Vérifier
Effectuez un cycle complet d’instantané et de restauration sur un sandbox réel :
1. Démarrez un sandbox avec un nouveau système de fichiers :
```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. Écrivez un fichier dans `/work`, puis arrêtez le sandbox en créant un instantané à l’arrêt. Remplacez `[SANDBOX-ID]` par l’ID du sandbox que vous avez démarré. La réponse renvoie un `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. Restaurez-le dans un nouveau sandbox. Remplacez `[SNAPSHOT-ID]` par le `fileSystemSnapshotId` renvoyé à l’étape précédente :
```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]" }
}
}'
```
Si le fichier que vous avez écrit figure dans le sandbox restauré, votre bucket fonctionne. Vous pouvez également vérifier directement que l’instantané a bien été enregistré dans votre bucket : chaque `FileSystemSnapshot` renvoyé par `GetFileSystemSnapshot` et `ListFileSystemSnapshots` comprend un champ `objectBucket` qui indique le bucket dans lequel l’instantané a été stocké.
Modifier ou rétablir votre bucket
Le `PUT` de l’étape 3 effectue un remplacement complet : c’est donc aussi par ce moyen que vous modifiez ou annulez votre configuration.
* **Revenir à un bucket managé par CoreWeave** : envoyez un corps vide (`{}`) avec `PUT`. CoreWeave reprend alors automatiquement la gestion d’un bucket pour vous.
* **Passer à un autre bucket** : envoyez le nouveau `bucketName` et la nouvelle `region` avec `PUT`.
Lisez ce qui suit avant de modifier un bucket. Si vous modifiez ou effacez votre bucket FSS, vous perdez l’accès aux instantanés stockés dans le bucket précédent. CoreWeave ne copie pas les données d’un bucket à l’autre.
* La restauration d’un instantané stocké dans un bucket autre que votre bucket actuel renvoie `CWSANDBOX_FSS_BUCKET_MISMATCH`, qui indique le bucket de l’instantané et le bucket actuel. Les instantanés orphelins apparaissent toujours dans les appels de liste et d’obtention, mais ils ne peuvent pas être restaurés tant qu’un autre bucket est actif.
* Cette opération est réversible : faites de nouveau pointer la configuration vers l’ancien bucket, et ces instantanés redeviennent restaurables.
* Les bacs à sable en cours d’exécution ne sont pas concernés. Une sandbox en cours d’exécution continue d’enregistrer ses instantanés dans le bucket auquel elle était liée au démarrage. Un changement de bucket ne s’applique qu’aux futurs bacs à sable.
Résolution des problèmes
| Symptôme | Cause probable | Solution |
| - | - | - |
| `AccessDenied` lors d’un instantané ou d’une restauration | Le principal de la stratégie de bucket, la valeur `org_id` ou la condition `bucket_name` ne correspond pas, ou bien la configuration de la Fédération d’identités de charges de travail (étape 1) est absente ou utilise une audience incorrecte. | Vérifiez que le fournisseur OIDC a pour émetteur `https://oidc.cwsandbox.com` et pour audience `cw-credential-vendor`. Vérifiez que les valeurs `[ORG-ID]` et `[BUCKET-NAME]` de la stratégie sont correctes. |
| `CWSANDBOX_FSS_BUCKET_MISMATCH` lors d’une restauration | Vous avez changé de bucket FSS. L’instantané se trouve dans un autre bucket que le bucket actuel. | Rétablissez dans la configuration le bucket qui contient l’instantané. |
| `CWSANDBOX_INVALID_REQUEST` lors du `PUT` | Configuration partielle (bucket sans région ou inversement) ou nom de bucket non valide. | Envoyez `bucketName` et `region` ensemble. Consultez les [règles de nommage des buckets](#bucket-name-rules). |
| `PermissionDenied` lors du `PUT` | L’utilisateur associé au jeton ne dispose pas de l’action IAM `SANDBOX_ADMIN`. | Accordez `SANDBOX_ADMIN` depuis la page [Access Policies](/security/iam/access-policies/manage). |
| `PathStyleRequestNotAllowed` | Un adressage S3 de type chemin (path-style) a été utilisé. | CoreWeave AI Object Storage exige un adressage de type hôte virtuel (virtual-hosted-style). |
| `CWSANDBOX_FSS_AUTH_FAILED` lors d’un instantané | L’échange d’identifiants d’authentification ou l’autorisation du bucket a échoué. | Vérifiez à nouveau l’étape 1 (fournisseur OIDC) et l’étape 2 (stratégie de bucket). Si le problème persiste, contactez le Support CoreWeave. |
Si une sandbox est soumise à une politique qui limite le trafic sortant à une liste d’autorisation, assurez-vous qu’elle peut joindre le point de terminaison d’identifiants d’authentification de CoreWeave (`https://api.coreweave.com`). Sinon, la récupération des identifiants d’authentification expire et la première opération S3 échoue.
Référence
Les sections suivantes décrivent les règles relatives au nom du bucket, les actions S3 autorisées par la politique et les revendications du jeton auxquelles la politique fait référence.
Règles de nommage des buckets
Lorsque vous enregistrez un bucket à l’étape 3, CoreWeave vérifie que son nom respecte les règles standard du stockage d’objets.
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.
Le paramètre `region` désigne une CoreWeave Availability Zone, par exemple `US-EAST-01A`, et doit correspondre à la zone où se trouve votre bucket. Pour la liste complète des zones, voir [Toutes les Availability Zones](/platform/regions/all-availability-zones).
Actions S3 accordées
La politique accorde exactement les actions dont FSS a besoin, et rien de plus : `s3:GetObject`, `s3:PutObject`, `s3:CreateMultipartUpload`, `s3:UploadPart`, `s3:CompleteMultipartUpload`, `s3:AbortMultipartUpload` et `s3:ListMultipartUploadParts`. Les écritures s'effectuent par chargement en plusieurs parties, et la restauration s'appuie sur `GetObject`.
Revendications du jeton utilisées par la stratégie
CoreWeave inscrit ces revendications dans chaque jeton propre à une sandbox. Les conditions de la stratégie de bucket y font référence sous la forme `oidc:[ORG-ID]:[CLAIM]`.
| Revendication | Rôle |
| - | - |
| `org_id` | Comparée à votre organisation dans chaque `Allow` ainsi que dans la garde `DenyCrossOrg`. |
| `user_hash` | Le préfixe d’écriture propre à chaque utilisateur (`[USER-HASH]/...`). |
| `bucket_name` | Associe le jeton à ce bucket. |
| `restore_object_key` | L’objet précis qu’une restauration est autorisée à lire. |
* [Instantanés du système de fichiers](/fr/products/sandboxes/file-system-snapshots) : fonctionnement des instantanés, de la restauration et de la création de branches.
* [Utiliser la fédération d’identités de charges de travail avec OIDC](/products/storage/object-storage/auth-access/workload-identity-federation/use-oidc-tokens) : fonctionnement de la fédération OIDC et de la configuration dans la Cloud Console.
* [Créer des buckets](/products/storage/object-storage/buckets/create-bucket) : créez le bucket dont ce guide suppose l’existence.
* [Toutes les Availability Zones](/platform/regions/all-availability-zones) : les zones à utiliser comme région pour votre bucket.
* [Gérer les jetons d’accès à l’API](/security/authn-authz/manage-api-access-tokens) : créez le jeton utilisé à l’étape 3.
* [Politiques d’accès IAM](/security/iam/access-policies/manage) : accordez l’action `SANDBOX_ADMIN` requise à l’étape 3.