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

# Monter un bucket de stockage objet dans un sandbox

export const SandboxConfigHint = () => {
  if (typeof document === "undefined") {
    return null;
  } else {
    return <Note>Before running the example code in this document, please ensure you have properly configured environment variables. For details, please refer to <a href="/docs/fr/guides/sandbox-your-first-agent-sandbox#configure-environment-variables">Configure Environment Variables</a>.</Note>;
  }
};

Chaque instance de sandbox est provisionnée par défaut avec 20 Go de stockage disque système éphémère pour les opérations temporaires sur les données. <u>Lors de la terminaison ou de l’expiration du sandbox, toutes les données présentes dans cet espace de stockage sont automatiquement purgées</u>. Par conséquent, les données persistantes nécessitant une conservation à long terme doivent être stockées dans des services de stockage cloud externes.

<Tip>
  Les spécifications d’allocation du stockage des sandbox sont susceptibles d’être modifiées. Consultez la documentation [Tarification](/docs/fr/guides/sandbox-pricing) pour connaître les allocations de ressources actuelles et les coûts associés.
</Tip>

Le stockage objet représente une architecture de stockage cloud hautement scalable, durable et économique, proposée par les principaux fournisseurs de services cloud. Dans les environnements sandbox, le stockage objet peut être accessible via deux méthodologies principales : une interaction programmatique directe au moyen des SDK ou des utilitaires CLI des fournisseurs cloud, ou des implémentations FUSE (Filesystem in Userspace) qui présentent les buckets de stockage objet comme des montages de systèmes de fichiers standard compatibles POSIX.

<Tip>
  [FUSE (Filesystem in Userspace)](https://www.kernel.org/doc/html/next/filesystems/fuse.html) est un module du noyau et une bibliothèque en espace utilisateur qui permettent l’implémentation de systèmes de fichiers entièrement fonctionnels dans des applications en espace utilisateur. Ce framework fournit une couche d’abstraction qui présente les services de stockage cloud distants comme des hiérarchies de systèmes de fichiers standard, permettant des opérations de fichiers transparentes via des interfaces POSIX conventionnelles.
</Tip>

Cette documentation fournit des instructions complètes pour intégrer des buckets de stockage objet des principaux fournisseurs de services cloud dans des environnements sandbox au moyen de techniques de montage de systèmes de fichiers.

<Warning>
  Les montages de stockage objet basés sur FUSE introduisent une surcharge de performance I/O importante en raison de la latence réseau et des couches de traduction de protocole. Les applications ayant des exigences de performance strictes doivent éviter cette approche. De plus, les opérations de système de fichiers FUSE ne disposent pas des garanties d’atomicité propres aux API natives de stockage objet, ce qui crée des conditions de concurrence potentielles où des opérations locales sur le système de fichiers peuvent réussir alors que les opérations distantes correspondantes échouent, entraînant une incohérence des données.

  Cette approche de montage est optimale pour les charges de travail majoritairement en lecture, avec des opérations d’écriture peu fréquentes et des contraintes de performance souples. Pour les applications critiques en matière de performance ou les modèles d’écriture fréquents, l’intégration directe à l’aide des SDK des fournisseurs cloud ou des API REST natives est fortement recommandée.
</Warning>

<SandboxConfigHint />

## Amazon S3

Les buckets Amazon S3 peuvent être montés comme des systèmes de fichiers compatibles POSIX à l’aide de [s3fs-fuse](https://github.com/s3fs-fuse/s3fs-fuse), une implémentation de système de fichiers basée sur FUSE qui fournit un accès aux buckets S3 via des opérations de fichiers standard.

Le package s3fs-fuse peut être intégré lors de la création d’un [modèle de sandbox](/docs/fr/guides/sandbox-template-quickstart) en incorporant des commandes d’installation dans le `novita.Dockerfile`, ou installé dynamiquement dans des instances de sandbox actives pour des besoins ponctuels.

Le `novita.Dockerfile` suivant illustre l’intégration de s3fs-fuse lors de la construction du modèle :

<CodeGroup>
  ```dockerfile novita.Dockerfile icon="docker" theme={"system"}
  # Compatible with Debian-based distributions
  FROM ubuntu:latest

  # Critical: s3fs versions below 1.93 contain known mounting issues. Ensure version compatibility.
  RUN DEBIAN_FRONTEND=noninteractive apt-get update && apt-get install -y s3fs
  ```
</CodeGroup>

L’implémentation suivante illustre le montage programmatique d’un bucket S3 dans des environnements sandbox à l’aide de s3fs-fuse :

<CodeGroup>
  ```js JavaScript & TypeScript icon="js" theme={"system"}
  import { Sandbox } from 'novita-sandbox'

  const TEMPLATE_ID = process.env.NOVITA_TEMPLATE_ID
  const AWS_ACCESS_KEY_ID = process.env.AWS_ACCESS_KEY_ID
  const AWS_SECRET_ACCESS_KEY = process.env.AWS_SECRET_ACCESS_KEY
  const AWS_BUCKET_NAME = process.env.AWS_BUCKET_NAME
  const AWS_REGION = process.env.AWS_REGION
  if (!TEMPLATE_ID || !AWS_ACCESS_KEY_ID || !AWS_SECRET_ACCESS_KEY || !AWS_BUCKET_NAME || !AWS_REGION) {
      throw new Error('Required environment variables not configured: NOVITA_TEMPLATE_ID, AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_BUCKET_NAME, AWS_REGION')
  }

  const MOUNT_DIRECTORY = "/mnt/s3-bucket"

  const sandbox = await Sandbox.create(TEMPLATE_ID)

  // Initialize mount point directory structure
  await sandbox.files.makeDir(MOUNT_DIRECTORY)

  // Configure s3fs credentials using standard credential file location
  // s3fs-fuse reads AWS credentials from /root/.passwd-s3fs by default
  await sandbox.files.write('/root/.passwd-s3fs', `${AWS_ACCESS_KEY_ID}:${AWS_SECRET_ACCESS_KEY}`)

  // Enforce secure credential file permissions (owner read-only)
  await sandbox.commands.run('sudo chmod 600 /root/.passwd-s3fs')

  // Execute S3 bucket mount operation with optimized parameters
  // Configuration parameters:
  // - allow_other: Enable cross-user filesystem access
  // - endpoint: Specify the AWS region endpoint for your bucket
  // Reference: https://manpages.ubuntu.com/manpages/noble/en/man1/s3fs.1.html
  const mountOptions = `allow_other,endpoint=${AWS_REGION}`
  await sandbox.commands.run(`sudo s3fs ${AWS_BUCKET_NAME} ${MOUNT_DIRECTORY} -o ${mountOptions}`)

  // Validate mount functionality with write operation
  await sandbox.files.write(`${MOUNT_DIRECTORY}/test-file.txt`, 'test-file-content')

  // Verify mount integrity through read operation
  const content = await sandbox.files.read(`${MOUNT_DIRECTORY}/test-file.txt`)
  console.log(content)

  await sandbox.kill()
  ```

  ```python Python icon="python" theme={"system"}
  import os
  from novita_sandbox.core import Sandbox

  TEMPLATE_ID = os.environ.get("NOVITA_TEMPLATE_ID")
  AWS_ACCESS_KEY_ID = os.environ.get("AWS_ACCESS_KEY_ID")
  AWS_SECRET_ACCESS_KEY = os.environ.get("AWS_SECRET_ACCESS_KEY")
  AWS_BUCKET_NAME = os.environ.get("AWS_BUCKET_NAME")
  AWS_REGION = os.environ.get("AWS_REGION")
  if not TEMPLATE_ID or not AWS_ACCESS_KEY_ID or not AWS_SECRET_ACCESS_KEY or not AWS_BUCKET_NAME or not AWS_REGION:
      raise ValueError("Required environment variables not configured: NOVITA_TEMPLATE_ID, AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_BUCKET_NAME, AWS_REGION")

  MOUNT_DIRECTORY = "/mnt/s3-bucket"

  sandbox = Sandbox.create(TEMPLATE_ID)

  # Initialize mount point directory structure
  sandbox.files.make_dir(MOUNT_DIRECTORY)

  # Configure s3fs credentials using standard credential file location
  # s3fs-fuse reads AWS credentials from /root/.passwd-s3fs by default
  # Custom credential paths require explicit specification via -o passwd_file parameter
  sandbox.files.write("/root/.passwd-s3fs", f"{AWS_ACCESS_KEY_ID}:{AWS_SECRET_ACCESS_KEY}")

  # Enforce secure credential file permissions (owner read-only)
  sandbox.commands.run("sudo chmod 600 /root/.passwd-s3fs")

  # Execute S3 bucket mount operation with optimized parameters
  # Configuration parameters:
  # - allow_other: Enable cross-user filesystem access
  # - endpoint: Specify the AWS region endpoint for your bucket
  # Reference: https://manpages.ubuntu.com/manpages/noble/en/man1/s3fs.1.html
  mount_options = f"allow_other,endpoint={AWS_REGION}"
  sandbox.commands.run(f"sudo s3fs {AWS_BUCKET_NAME} {MOUNT_DIRECTORY} -o {mount_options}")

  # Validate mount functionality with write operation
  write_result = sandbox.files.write(f"{MOUNT_DIRECTORY}/test-file.txt", "test-file-content")

  # Verify mount integrity through read operation
  content = sandbox.files.read(f"{MOUNT_DIRECTORY}/test-file.txt")
  print("File content:", content)

  sandbox.kill()
  ```
</CodeGroup>