La synchronisation de licence
Une fois rattachée, votre instance :
- valide la licence au démarrage ;
- synchronise ses données de consommation toutes les heures par défaut (réglable par
LICENSE_SYNC_INTERVAL_SECONDS, entre 60 et 3 600 secondes) ; - met en cache les limites en local, pour des vérifications de quota rapides ;
- remonte l'état de santé de l'instance et les statistiques de ses services.
La synchronisation s'exécute dans le processus : vous n'avez ni tâche cron externe ni CronJob Kubernetes à configurer. Votre instance commence à se synchroniser toute seule après son démarrage.
En cas d'échec d'une synchronisation
Si le centre de licences est injoignable ou refuse la synchronisation, votre instance continue d'utiliser les limites en cache pendant 24 heures de durée de vie du cache, plus 24 heures de délai de grâce, avant que la création de ressources ne soit bloquée. En pratique, une coupure brève est invisible pour vos utilisateurs.
La dernière erreur de la synchronisation ratée la plus récente est conservée et affichée sur votre tableau de bord d'administration (/admin), dans un bandeau rouge portant le texte de l'erreur et son horodatage — sans avoir à consulter les logs du serveur ni un tableau de bord Kubernetes. Un bouton Retry Sync, sur la même carte, déclenche une synchronisation immédiate sans redémarrer l'instance.
La réponse de synchronisation
La synchronisation renvoie les limites et les indicateurs de fonctionnalité dont votre instance se sert pour encadrer ce qui est permis :
{
"valid": true,
"limits": {
"projects": 20,
"apps": 50,
"databases": 25,
"domains": 50,
"customDomains": 10,
"freeSubdomains": 5,
"purchasableDomains": 0,
"teamMembers": 20,
"buildMinutes": 2000,
"storageBytes": 268435456000,
"instances": 3
},
"features": {
"whiteLabel": false,
"customDomains": true,
"domainPurchase": false,
"aiAssistant": true,
"multiServer": true,
"prioritySupport": false
},
"effectiveRemaining": {
"projects": 8,
"apps": 22,
"databases": 12,
"domains": 20,
"customDomains": 4,
"purchasedDomains": 5,
"freeSubdomains": 7,
"teamMembers": 5,
"buildMinutes": 1150,
"storageBytes": 214748364800
},
"warnings": [],
"billingPeriodReset": "2025-02-01T00:00:00Z",
"gracePeriodHours": 24,
"cacheExpiresAt": "2025-01-12T00:00:00Z"
}
Les limites de domaines
La réponse comprend des limites propres aux domaines :
| Limite | Description |
|---|---|
domains | Le nombre total d'emplacements de domaines (historique) |
customDomains | Les domaines personnalisés autorisés |
freeSubdomains | Les sous-domaines gratuits en *.kuploy.app autorisés |
purchasableDomains | Les domaines achetables via la plateforme (Enterprise uniquement) |
Les quotas globaux sur plusieurs instances
Si votre offre autorise plusieurs instances — 3 pour Business, un nombre illimité pour Enterprise — la consommation est cumulée sur toutes les instances d'une même licence.
Par exemple, sur une offre Growth limitée à 20 projets :
- l'instance A a 8 projets ;
- l'instance B en a 5 ;
- l'instance C en a 3 ;
- cumul : 16/20, soit 80 % — un avertissement se déclenche.
Plutôt que de renvoyer à chaque instance les décomptes bruts de toutes les autres, kuploy.app transmet à chacune un nombre effectiveRemaining par ressource : combien d'exemplaires de chaque ressource cette instance peut encore créer sous la licence. Dans l'exemple ci-dessus, chaque instance verrait projects: 4 dans sa réponse, et son contrôle local canCreate() autoriserait 4 projets supplémentaires avant d'atteindre la limite cumulée.
Une instance ne voit jamais les décomptes individuels de ses voisines : seulement la marge, déjà calculée. Les avertissements et les seuils sont eux aussi calculés côté serveur et inclus dans la réponse.
Le comportement hors ligne
Si votre instance ne parvient pas à joindre le centre de licences :
- les limites en cache continuent de s'appliquer ;
- l'application locale des quotas reste active ;
- les variations de consommation sont mises en file pour la synchronisation suivante ;
- un bandeau d'avertissement apparaît dans le tableau de bord.
Dès que la connexion revient, votre instance transmet toutes les données en attente.
Les états du cache
Le cache de licence suit cette progression d'états :
| État | Description | Comportement |
|---|---|---|
fresh | Licence valide, cache dans sa durée de vie | Fonctionnement complet |
stale | Licence valide, cache expiré, dans le délai de grâce | Opérations autorisées, bandeau d'avertissement affiché |
frozen | Délai de grâce écoulé, serveur injoignable | Création de nouvelles ressources bloquée |
empty | Aucune licence configurée | Bloque la création si une LICENSE_KEY est attendue |
invalid | La validation de la licence a échoué | Création de nouvelles ressources bloquée |