# Définitions et instances

> Déclarer une fois dans l'architecture, provisionner dans chaque environnement : valeurs par défaut, surcharges et propagation des changements.

L'hébergement Wakastart repose sur une règle unique : ce que votre application **est** se déclare une fois, au niveau de l'application ; ce qui **tourne** existe une fois par environnement. La déclaration s'appelle une [définition](/v1.0/glossaire#définition), la ressource réelle une [instance](/v1.0/glossaire#instance).

## Définition

Une définition décrit une ressource et ses valeurs par défaut, sans la créer. Une instance est sa matérialisation dans un environnement : elle hérite des valeurs par défaut et peut surcharger chacune d'elles.

```mermaid
flowchart LR
  subgraph ARCH["Architecture de l'application"]
    SD["Service « api »<br/>CPU 250m · mémoire 512Mi · port 3000"]
  end
  subgraph DEV["Environnement dev"]
    SI1["Service déployé<br/>CPU : hérité (250m)<br/>mémoire : hérité (512Mi)<br/>image : main-20261023-091244"]
  end
  subgraph PRD["Environnement prod"]
    SI2["Service déployé<br/>CPU : 1000m (surcharge)<br/>mémoire : 2Gi (surcharge)<br/>3 réplicas"]
  end
  SD --> SI1
  SD --> SI2
```

| Définition (architecture) | Instance (par environnement) | Où la créer dans la console |
|---|---|---|
| Service | service déployé | onglet **Services** > **Déployer un service** |
| Base de données | base de l'environnement | onglet **Databases** > **Nouvelle instance** |
| Bucket | bucket de l'environnement | onglet **Storage** > **Provisionner** |
| URL et route | route en ligne | onglet **URLs & IAM** > **Instancier** |
| Variable attendue | liaison à une valeur | service déployé > **Configuration du service** |

Les définitions se gèrent dans **Architecture** : **Services**, **Dépendances** (bases et buckets), **URLs**. Les instances se gèrent dans chaque environnement.

## Pourquoi ça existe

Sans cette séparation, chaque environnement serait une copie de la description de l'application, et les copies dériveraient : un port changé en production mais oublié en staging, une base ajoutée d'un côté seulement. Avec elle, l'architecture fait foi. Les environnements ne portent que leurs écarts assumés : plus de réplicas en production, une base managée plutôt que dans le cluster, des secrets différents.

## Comment ça marche

### Héritage et surcharges

Chaque champ d'une instance est soit vide, et la valeur de la définition s'applique, soit renseigné, et il l'emporte. Si la définition ne fixe pas non plus la valeur, Wakastart applique un défaut.

| Valeur effective d'un service déployé | Ordre de résolution |
|---|---|
| CPU demandé / limite | instance, puis définition, puis `100m` / `500m` |
| Mémoire demandée / limite | instance, puis définition, puis `128Mi` / `512Mi` |
| Port | définition, puis port par défaut de la technologie (`3000` pour `nestjs` et `nextjs`), puis `8080` |
| Image | le tag choisi au déploiement |

| Valeur effective d'une base | Ordre de résolution |
|---|---|
| Mode (dans le cluster ou managée), plan, région, taille disque | instance, puis définition |
| Version | instance, puis définition, puis `16` |
| Réplicas | instance, puis définition, puis `1` |

Pour revenir à la valeur par défaut, videz le champ de l'instance.

### Propagation des changements

Modifier une définition incrémente sa génération, puis Wakastart met à jour les instances concernées :

- une **ressource ou une sonde par défaut** modifiée redéploie les instances qui ne la surchargent pas ; les autres gardent leur valeur ;
- un **réglage réseau** modifié (port, protocole) redéploie toutes les instances du service ;
- chaque redéploiement laisse une ligne dans l'historique des déploiements de l'environnement.

### Création des instances

| Ressource | Création de l'instance |
|---|---|
| Service | toujours explicite : il faut choisir l'image et le nombre de réplicas |
| Base de données | explicite, environnement par environnement |
| Bucket | explicite ; ou automatique dans chaque environnement existant si vous cochez **Créer automatiquement les instances** en déclarant le bucket |
| Route | explicite, par **Instancier** |
| Liaison de variable | explicite ; sans liaison, la variable prend sa valeur par défaut, ou elle est absente si elle n'en a pas |

### Repérer ce qui manque

L'encart **Ce qu'il reste à configurer**, dans le **Résumé** de chaque environnement, compare l'architecture à ce qui existe : services déclarés mais pas déployés, variables obligatoires sans valeur, bases et buckets non provisionnés, routes non instanciées, services sans build réussi. En production, il signale aussi les ressources sans sauvegarde et les services à un seul réplica. Il informe sans rien bloquer.

## Exemples

**Augmenter la mémoire partout.** Vous passez la mémoire par défaut du service `api` de `512Mi` à `1Gi` dans l'architecture. Les environnements dev et staging, qui n'ont pas de surcharge, sont redéployés avec `1Gi`. La production, qui surcharge à `2Gi`, ne bouge pas.

**Ajouter une base.** Vous déclarez une base PostgreSQL `main` dans **Dépendances**. Rien ne se crée encore. Dans chaque environnement, **Databases** > **Nouvelle instance** la provisionne, dans le cluster en dev, managée en prod. L'encart **Ce qu'il reste à configurer** signale les environnements qui n'en ont pas.

## Pour aller plus loin

- [Applications et environnements](/v1.0/applications) : l'architecture et ses environnements, en pratique.
- [Cycle de vie des ressources](/v1.0/concepts/cycle-de-vie-des-ressources) : ce qui se passe entre la création d'une instance et son passage en service.
- [Services](/v1.0/services), [Bases de données](/v1.0/bases-de-donnees), [Stockage objet](/v1.0/stockage) : chaque type de ressource en détail.
- [Variables et secrets](/v1.0/variables-et-secrets) : variables attendues et liaisons.
