Utilisez votre propre bucket pour les instantanés du système de fichiers

Ce guide explique comment stocker les instantanés du système de fichiers (FSS) 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 :

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.
Une stratégie de bucket sur votre bucket, qui accorde à cette identité fédérée l’accès limité nécessaire à FSS.
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.

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é :

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.
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.
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.
`[REGION]`	La CoreWeave Availability Zone où se trouve votre bucket, utilisée comme région S3.	Toutes les 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.

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 :

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

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

{
  "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.

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

Example output

{
  "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 :

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 :

Démarrez un sandbox avec un nouveau système de fichiers :

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" }
  }'

É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 :

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
  }'

Restaurez-le dans un nouveau sandbox. Remplacez [SNAPSHOT-ID] par le fileSystemSnapshotId renvoyé à l’étape précédente :

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

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.

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 : 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 : fonctionnement de la fédération OIDC et de la configuration dans la Cloud Console.
Créer des buckets : créez le bucket dont ce guide suppose l’existence.
Toutes les Availability Zones : les zones à utiliser comme région pour votre bucket.
Gérer les jetons d’accès à l’API : créez le jeton utilisé à l’étape 3.
Politiques d’accès IAM : accordez l’action SANDBOX_ADMIN requise à l’étape 3.

Sandbox

Utiliser les Sandbox

Gérer les bacs à sable

Référence

Utilisez votre propre bucket pour les instantanés du système de fichiers

Comment FSS utilise votre bucket

Valeurs nécessaires

Étape 1 : Enregistrer le fournisseur OIDC

Étape 2 : joindre la stratégie de bucket

Rôle de chaque instruction

Étape 3 : Enregistrer le bucket auprès de CoreWeave

Étape 4 : Vérifier

Modifier ou rétablir votre bucket

Résolution des problèmes

Référence

Règles de nommage des buckets

Actions S3 accordées

Revendications du jeton utilisées par la stratégie

​Comment FSS utilise votre bucket

​Valeurs nécessaires

​Étape 1 : Enregistrer le fournisseur OIDC

​Étape 2 : joindre la stratégie de bucket

​Rôle de chaque instruction

​Étape 3 : Enregistrer le bucket auprès de CoreWeave

​Étape 4 : Vérifier

​Modifier ou rétablir votre bucket

​Résolution des problèmes

​Référence

​Règles de nommage des buckets

​Actions S3 accordées

​Revendications du jeton utilisées par la stratégie

​Ressources associées

Comment FSS utilise votre bucket

Valeurs nécessaires

Étape 1 : Enregistrer le fournisseur OIDC

Étape 2 : joindre la stratégie de bucket

Rôle de chaque instruction

Étape 3 : Enregistrer le bucket auprès de CoreWeave

Étape 4 : Vérifier

Modifier ou rétablir votre bucket

Résolution des problèmes

Référence

Règles de nommage des buckets

Actions S3 accordées

Revendications du jeton utilisées par la stratégie

Ressources associées