# Définitions et instances de service

> Ce que porte une définition de service, ce qu'une instance peut surcharger dans un environnement, et comment se calcule la valeur effective.

Un service existe à deux niveaux. Sa **définition**, dans l'architecture de l'application, dit comment le construire et le lancer. Ses **instances**, une par environnement au plus, le font tourner avec une image et des réglages propres à cet environnement.

## Définition

La [définition de service](/v1.0/glossaire#définition-de-service) est un modèle. Elle ne fait rien tourner par elle-même : créer une définition ne démarre aucun conteneur.

Elle porte :

- **le code** : le dépôt Git, le dossier racine du service dans ce dépôt, le Dockerfile et le contexte de build ;
- **l'image** : le registre, le projet et le nom de l'image produite par les builds ;
- **le réseau** : le port sur lequel le conteneur écoute ;
- **les valeurs par défaut** : ressources CPU et mémoire, activation des sondes de santé ;
- **les variables attendues** : les variables d'environnement dont le service a besoin.

L'**instance de service** relie une définition à un environnement. Elle fait tourner une image donnée — le résultat d'un build — avec un nombre de réplicas et, si besoin, des ressources différentes de la définition. Une définition a au plus une instance par environnement, et une instance n'est jamais créée automatiquement.

## Pourquoi ça existe

Le même code doit tourner partout, avec des moyens différents : un réplica et peu de mémoire en développement, plusieurs réplicas et davantage de mémoire en production. Séparer la définition de l'instance évite de redéclarer le dépôt, le port ou les variables à chaque environnement, tout en laissant chaque environnement décider de sa capacité et de sa version.

## Comment ça marche

### Valeur effective

Pour chaque réglage, Wakastart prend la valeur de l'instance si elle existe, sinon celle de la définition, sinon la valeur de la plateforme.

| Réglage | Instance | Définition | Valeur de la plateforme |
|---|---|---|---|
| CPU Request | si renseigné | **CPU Request** par défaut | `100m` |
| CPU Limit | si renseigné | **CPU Limit** par défaut | `500m` |
| Memory Request | si renseigné | **Memory Request** par défaut | `128Mi` |
| Memory Limit | si renseigné | **Memory Limit** par défaut | `512Mi` |
| Réplicas | **Nombre de réplicas** | — | `1` |
| Port | — | **Port** | selon la technologie : `3000` pour `nestjs` et `nextjs`, `8080` sinon |
| Sondes activées | — | **Health Probes** | vie et disponibilité activées, démarrage désactivé (le formulaire de création de la console part de trois sondes désactivées) |
| Image | dernière image déployée | registre, projet, nom de l'image | tag `latest` si aucune image n'a été déployée |

Le **request** est la part de CPU ou de mémoire réservée au conteneur ; la **limit** est le plafond qu'il ne peut pas dépasser. Un conteneur qui dépasse sa limite mémoire est arrêté et redémarré.

### Ce qui redéploie quoi

| Vous modifiez… | Effet |
|---|---|
| Les ressources ou les réplicas d'une instance | Seule cette instance est redéployée |
| Une ressource par défaut ou une sonde de la définition | Les instances qui ne surchargent pas ce réglage sont redéployées |
| Le port, le protocole ou l'exposition de la définition | Toutes les instances sont redéployées |
| L'image d'une instance | Seule cette instance reçoit la nouvelle image |
| Le dépôt, le dossier ou le Dockerfile de la définition | Rien ne bouge ; le prochain build en tient compte |

Chaque redéploiement apparaît dans l'historique des déploiements avec sa raison.

### Identité d'un service

Le **nom court** d'un service est dérivé de son nom à la création : les 12 premiers caractères alphanumériques, en minuscules. Il ne change plus ensuite. Il sert à nommer les objets du service dans chaque environnement (`svc-<application>-<environnement>-<nom court>`) et ses variables calculées.

## Exemples

- **API d'un monorepo.** Définition « API », dossier racine `services/api`, port `3000`, `512Mi` de limite mémoire. Instance en `dev` : 1 réplica, aucune surcharge. Instance en `prod` : 2 réplicas, `1Gi`.
- **Traitement de fond.** Définition de rôle Worker, sans route publique. Il consomme les mêmes variables que l'API et tourne avec 1 réplica partout.
- **Changement global.** Vous passez la limite mémoire par défaut de `512Mi` à `768Mi` : l'instance de `dev` est redéployée avec `768Mi`, l'instance de `prod` garde `1Gi`.

## Pour aller plus loin

- [Créer un service](/v1.0/services/creer-un-service)
- [Dimensionner un service](/v1.0/services/dimensionner-un-service)
- [Sondes de santé](/v1.0/services/sondes-de-sante)
- [Architecture et environnements](/v1.0/applications/architecture-et-environnements)
