# Modèle de configuration

> Variables consommées, pool de l'environnement et configuration du service — comment une valeur arrive dans un conteneur, et d'où elle peut venir.

La configuration d'un service se construit en trois étages : ce que le service **attend**, ce que l'environnement **met à disposition**, et le **choix** fait pour chaque variable dans chaque service déployé. Séparer ces étages permet de décrire une fois les besoins d'un service, puis de lui donner des valeurs différentes en dev, en staging et en prod.

## Définition

| Étage | Où | Ce que vous y faites |
|---|---|---|
| **Variables consommées** | Définition du service, dans l'architecture : onglet **Variables consommées** | Déclarer chaque variable attendue : son nom (ou son chemin de fichier), sa valeur par défaut, sa description |
| **Pool de l'environnement** | Onglet **Configuration** de l'environnement | Ajouter des variables en clair et des secrets ; consulter ce que la plateforme fournit |
| **Configuration du service** | Service déployé, onglet **Configuration du service** | Pour chaque variable consommée, choisir sa source |

Une variable ne parvient au conteneur que si elle est **déclarée** dans la définition du service. Une entrée du pool n'est jamais injectée d'office : « chaque service choisit explicitement quelles variables il consomme », comme le rappelle l'écran **Configuration**. Une variable du pool qui porte le même nom qu'une variable consommée ne lui est pas reliée automatiquement.

## Pourquoi ça existe

Un service ne devrait pas savoir d'où vient sa configuration : il lit `DATABASE_URL`, qu'elle vienne d'une base managée en prod ou d'une base dans le cluster en dev. Les variables consommées forment ce contrat. Le pool rassemble au même endroit tout ce qu'un environnement peut fournir, et la configuration du service relie les deux. Les secrets, eux, ne quittent jamais le coffre : la console ne connaît que leur nom.

## Comment ça marche

### Les sources d'une variable

Dans **Configuration du service**, la liste déroulante de chaque variable propose ces sources. Une fois l'entrée choisie, un badge rappelle son origine.

| Source à l'écran | Badge | Ce que reçoit le conteneur | Valeur visible dans la console |
|---|---|---|---|
| **Utiliser la valeur par défaut** | — | La valeur par défaut de la définition ; sans valeur par défaut, la variable est absente | Oui |
| **Saisir une valeur libre** | — | La valeur saisie, éventuellement composée avec `{{ CLE }}` | Oui |
| Variable en clair de l'environnement | utilisateur | Sa valeur | Oui |
| Secret de l'environnement | secret | La valeur du coffre | Non |
| Variable de la plateforme | plateforme | Une valeur commune à toute la plateforme, définie par Wakastart | Oui |
| Valeur calculée | auto | Le nom de l'app, de l'environnement, les URLs internes des services (`SVC_*`) et les URLs publiques des routes (`ROUTE_*`) | Oui |
| Champ d'une base de données | base | L'URL de connexion, l'hôte, le port, le nom de la base, l'utilisateur, le mot de passe ou le mode SSL | Sauf `URL` et `PASSWORD` |
| Champ d'un bucket | stockage | L'URL S3, l'endpoint, la région, le nom du bucket, la clé d'accès ou la clé secrète | Sauf `S3_URL` et `SECRET_ACCESS_KEY` |

Les entrées **harbor** du pool sont les identifiants du registre d'images de l'app. La plateforme s'en sert pour télécharger vos images ; vos services n'en ont pas besoin.

La liste complète des clés calculées est dans la [référence](/v1.0/variables-et-secrets/reference#valeurs-fournies-par-la-plateforme).

### Valeurs libres et modèles `{{ CLE }}`

Une valeur libre peut citer une entrée **non sensible** du pool : `{{ ROUTE_FRONT_URL }}auth/callback` ou `postgres://{{ MAIN_HOST }}:{{ MAIN_PORT }}`. Une clé `ROUTE_*` contient déjà le schéma et le chemin de la route : pour la route `/`, `ROUTE_FRONT_URL` vaut `https://app.exemple.fr/`, et le premier exemple donne `https://app.exemple.fr/auth/callback`. La plateforme remplace chaque `{{ CLE }}` au moment du déploiement. Une entrée sensible (secret, mot de passe, URL de base) ne peut pas être citée : reliez-la directement à la variable.

### Ce qui arrive dans le conteneur

- Les valeurs non sensibles sont écrites dans la définition du déploiement du service.
- Les valeurs sensibles (secrets, mots de passe, URLs de connexion, clés S3) sont copiées depuis le coffre de l'application vers un secret du cluster, puis référencées par le conteneur. Elles ne transitent jamais par la console.
- Une variable déclarée comme **Fichier monté** reçoit le contenu d'un secret, déposé en lecture seule au chemin indiqué. Voir [Monter un fichier secret](/v1.0/variables-et-secrets/monter-un-fichier-secret).
- Une entrée qui ne peut pas être résolue (base pas encore prête, entrée supprimée) est omise : la variable manque dans le conteneur.

### Variables et secrets dans le pool

| | Variable | Secret |
|---|---|---|
| Stockage | En clair, en base | Chiffré, dans le coffre de l'application |
| Affichage | Valeur visible | Valeur jamais relisible |
| Modification dans la console | Non : créez une nouvelle entrée | Oui : **Remplacer la valeur du secret** |
| Saisie | Texte | Texte ou fichier |

## Exemples

- **Niveau de log** : la définition déclare `LOG_LEVEL` avec la valeur par défaut `info`. En dev, la configuration du service choisit une valeur libre `debug` ; en prod, elle garde **Utiliser la valeur par défaut**.
- **Clé d'un service tiers** : la définition déclare `STRIPE_API_KEY` sans valeur par défaut. Chaque environnement a son secret `STRIPE_API_KEY`, relié dans la configuration du service.
- **Base de données** : la définition déclare `DATABASE_URL`. La configuration du service choisit l'entrée `MAIN_URL` (badge **base**) de la base `main`.
- **Appel entre services** : le front déclare `API_INTERNAL_URL`, relié à l'entrée calculée `SVC_API_URL`.
- **Keycloak par environnement** : la définition déclare `KEYCLOAK_URL` ; chaque environnement fournit l'URL de son instance Keycloak. Voir [Authentification](/v1.0/authentification).

## Pour aller plus loin

- [Prise en compte des changements](/v1.0/variables-et-secrets/prise-en-compte-des-changements)
- [Configurer un service](/v1.0/variables-et-secrets/configurer-un-service)
- [Référence des variables et des écrans](/v1.0/variables-et-secrets/reference)
