Mise à l'échelle

Répliques, limites CPU et mémoire et mise à l'échelle automatique d'une application, sur le serveur qui l'exécute.

Ce qui exige une licence

Régler soi-même ses répliques et ses limites sur sa propre machine est possible avec toutes les formules. Seul l'automatisme est soumis à licence :

Mise à l'échelle manuelle

sh0 scale <app> <répliques> démarre ou arrête des conteneurs pour que l'application tourne avec le nombre de répliques demandé ; --status affiche la configuration (sortie réelle) :

$ sh0 scale my-api 2
my-api: scaled 1 -> 2 replica(s)

$ sh0 scale my-api --status
Scaling status for my-api:
  Current replicas:   2
  Min replicas:       1
  Max replicas:       1
  Autoscaling:        disabled
  CPU threshold:      80%
  Memory threshold:   80%
  LB policy:          round_robin
  Cooldown:           300s

Par l'API :

curl -X POST https://panel.example.com/api/v1/apps/<app-id>/scale \
  -H "Authorization: Bearer $SH0_TOKEN" -H "Content-Type: application/json" \
  -d '{"replicas":2}'

L'API accepte de 1 à 50 répliques ; la CLI refuse au-delà de 10 (« Replicas must be between 1 and 10 »). Mettre à l'échelle exige le rôle developer sur le projet de l'application.

Limites CPU et mémoire

Chaque conteneur d'application tourne avec un quota CPU et une limite mémoire. Modifiez-les avec PUT /api/v1/apps/<id>/resources (réponse réelle) :

$ curl -X PUT https://panel.example.com/api/v1/apps/<app-id>/resources \
    -H "Authorization: Bearer $SH0_TOKEN" -H "Content-Type: application/json" \
    -d '{"cpu_limit":500,"memory_limit":256}'
{"data":{"app_id":"<app-id>","autoscale_cpu_threshold":80,"autoscale_enabled":false,"autoscale_memory_threshold":80,"cooldown_seconds":300,"cpu_limit":500,"created_at":"2026-10-02 02:55:05","current_replicas":2,"id":"4930c97a-d6ab-44ac-bfd0-368d2c6ac4cd","last_scale_at":null,"lb_policy":"round_robin","max_replicas":1,"memory_limit":256,"min_replicas":1,"updated_at":"2026-10-02 02:55:05"}}

• cpu_limit s'exprime en millicœurs (1000 = un cœur), memory_limit en Mo. Un champ omis reste inchangé ; 0 le remet à sa valeur par défaut.
• Valeurs par défaut quand rien n'est réglé : 512 Mo de mémoire, et la moitié des cœurs de la machine pour le CPU (au moins 0,5 cœur).
• Les bornes viennent de la machine : CPU de 100 millicœurs au nombre de cœurs, mémoire de 64 Mo à la RAM de la machine. Au-delà, l'erreur donne les chiffres réels, par exemple :
• Les nouvelles limites s'appliquent aux conteneurs créés ensuite : redéployez l'application pour que le conteneur en cours les reçoive.

{"error":{"code":"VALIDATION_ERROR","message":"memory_limit must be between 64 and 7751 MB (this machine has 7751 MB of RAM), or 0 to reset"}}

Mise à l'échelle automatique

Avec une licence Business, sh0 ajuste le nombre de répliques selon l'usage CPU et mémoire. Créez la configuration une fois :

curl -X POST https://panel.example.com/api/v1/apps/<app-id>/scaling \
  -H "Authorization: Bearer $SH0_TOKEN" -H "Content-Type: application/json" \
  -d '{"min_replicas":1,"max_replicas":4,"target_cpu_percent":70,"target_memory_percent":80,"cooldown_seconds":300,"enabled":true}'

• min_replicas, max_replicas -- de 1 à 50, le maximum pas en dessous du minimum. Tous deux valent 1 par défaut.
• target_cpu_percent, target_memory_percent -- de 10 à 100, 80 par défaut.
• cooldown_seconds -- de 60 à 3600, 300 par défaut : aucune nouvelle action avant ce délai après la précédente.
• lb_policy -- round_robin (par défaut), least_conn ou random.
• cpu_limit, memory_limit -- facultatifs, même sens et mêmes bornes que plus haut.

Une configuration existe dès que des limites ont été réglées, et un second POST est refusé (« Scaling config already exists for this app. Use PATCH to update. »). Modifiez-la avec PATCH /api/v1/apps/<id>/scaling/update, tous les champs étant facultatifs. Sans licence Business, le refus est un 403 de code LICENSE_REQUIRED.

Comment décide l'autoscaler

• L'autoscaler passe toutes les 30 secondes (sh0 serve --autoscale-interval, 0 le désactive) et lit les métriques CPU et mémoire de l'application sur les deux dernières minutes.
• À la hausse quand la moyenne CPU ou la moyenne mémoire dépasse sa cible.
• À la baisse quand les deux moyennes sont sous la moitié de leur cible, avec au moins 10 mesures de chaque.
• Une réplique à la fois, dans les bornes, et jamais pendant le délai de refroidissement.
• La formule est vérifiée à chaque passage : si la licence expire, la mise à l'échelle automatique s'arrête.

Répartition de charge

Toutes les répliques sont derrière les mêmes domaines : Caddy leur répartit les requêtes selon lb_policy. Dans le réseau du projet, l'alias de l'application (my-api.internal) résout vers chacune des répliques.

Limites

• Un seul serveur. Les répliques tournent sur le serveur qui héberge l'application ; elles apportent du parallélisme CPU et de la résistance à un plantage, pas une machine de plus.
• Montages. Les répliques ajoutées par sh0 scale démarrent sans les volumes montés de l'application. Ne mettez pas à l'échelle une application qui écrit dans un volume.
• État. Les requêtes d'un même utilisateur peuvent atteindre des répliques différentes : gardez sessions et fichiers envoyés hors du conteneur (base de données, Redis, stockage objet).
• Bases de données. Les serveurs de bases de données ont leurs propres réglages de ressources ; cette page porte sur les applications.