# Fonctionnement d'un bucket

> Déclaration et instances par environnement, hébergement OVHcloud, régions, compte d'accès dédié et les six identifiants fournis à vos services.

Un bucket Wakastart est un espace de stockage objet compatible S3, propre à un environnement de votre application. Wakastart le crée chez OVHcloud, lui associe un compte d'accès dédié et transmet ses identifiants à vos services par liaison de variables.

## Définition

Comme une base de données, un bucket existe à deux niveaux :

- la **déclaration**, dans l'architecture de l'application, porte un nom, un identifiant court et une région par défaut ;
- l'**instance**, dans un environnement, est le bucket réel. Chaque environnement a le sien : les fichiers de `dev` ne sont jamais mélangés à ceux de `prod`.

Un bucket n'est pas un disque monté dans vos conteneurs : votre code y lit et y écrit par l'API S3, avec un SDK.

## Comment ça marche

### Hébergement et région

Les buckets créés depuis la console sont hébergés sur OVHcloud Object Storage, dans la région choisie à la déclaration : **Gravelines (GRA)** par défaut, **Strasbourg (SBG)**, **Beauharnois (BHS)** ou **Varsovie (WAW)**. Le point d'accès S3 dépend de la région, par exemple `https://s3.gra.io.cloud.ovh.net`.

### Compte d'accès dédié

Pour chaque bucket, Wakastart crée un utilisateur OVHcloud et une clé d'accès S3. Ce compte peut :

- lister le contenu du bucket et en connaître la région ;
- lire, écrire et supprimer des objets ;
- gérer les envois en plusieurs parties (multipart).

Il ne peut ni créer d'autre bucket, ni lister les buckets du projet, ni supprimer le bucket lui-même. Une fuite de ces identifiants n'expose donc que ce bucket.

### Les six identifiants

| Champ | Contenu | Exemple |
|---|---|---|
| `endpoint` | point d'accès S3 | `https://s3.gra.io.cloud.ovh.net` |
| `region` | code de région | `gra` |
| `bucket` | nom réel du bucket | à lire dans la variable |
| `access_key_id` | identifiant de la clé d'accès | à lire dans la variable |
| `secret_access_key` | clé secrète | jamais affichée |
| `s3_url` | URL au format `s3://<bucket>` | `s3://<bucket>` |

Quand le bucket est **Prêt**, ces champs apparaissent dans l'onglet **Configuration** de l'environnement, filtre **Stockage**, sous des clés `<IDENTIFIANT>_<CHAMP>` en majuscules. Pour un bucket d'identifiant court `docs` : `DOCS_ENDPOINT`, `DOCS_REGION`, `DOCS_BUCKET`, `DOCS_ACCESS_KEY_ID`, `DOCS_SECRET_ACCESS_KEY`, `DOCS_S3_URL`. Les entrées `…_SECRET_ACCESS_KEY` et `…_S3_URL` sont sensibles.

Lisez toujours le nom du bucket dans `…_BUCKET` plutôt que de le recopier depuis la console : c'est la valeur que reçoit votre conteneur.

### Statuts

| Code | Libellé | Signification |
|---|---|---|
| `PENDING` | **En attente** | demande enregistrée |
| `PROVISIONING` | **Provisionnement** | création du bucket et du compte d'accès |
| `READY` | **Prêt** | bucket utilisable, identifiants disponibles, explorateur actif |
| `FAILED` | **Erreur** | création échouée ; Wakastart réessaie |
| `DESTROYING` | **Suppression** | suppression en cours |
| `DESTROYED` | **Supprimé** | bucket supprimé |

## Exemples

- **Une application qui reçoit des pièces jointes** : un bucket `docs` déclaré avec la création automatique, donc présent dans `dev`, `staging` et `prod`. Le back relie `S3_ENDPOINT`, `S3_REGION`, `S3_BUCKET`, `S3_ACCESS_KEY_ID` et `S3_SECRET_ACCESS_KEY` aux entrées `DOCS_…`.
- **Des exports lourds séparés des documents** : un second bucket `exports`, avec son propre compte d'accès, que seul le service de génération d'exports consomme.

## Pour aller plus loin

- [Déclarer un bucket](/v1.0/stockage/declarer-un-bucket)
- [Connecter un service à un bucket](/v1.0/stockage/connecter-un-service)
- [Référence du stockage objet](/v1.0/stockage/reference)
