kubectl scale, autoscale, rollout et set : mise à l'échelle et mises à jour

Votre application reçoit 3 fois plus de trafic que prévu, ou vous venez de déployer une nouvelle version qui fait crasher les pods. Kubernetes gère ces deux situations avec 4 commandes complémentaires : kubectl scale ajuste le nombre de réplicas à la volée, kubectl autoscale le fait automatiquement selon la charge, kubectl rollout pilote les mises à jour et les rollbacks, et kubectl set modifie la config d'un Deployment sans toucher au YAML. Ce guide vous montre comment les utiliser en production.

Ce que vous allez apprendre

• Scaler manuellement un Deployment ou StatefulSet avec kubectl scale
• Configurer l'auto-scaling avec un HPA (Horizontal Pod Autoscaler)
• Déployer une mise à jour progressive (rolling update) et suivre sa progression
• Annuler un déploiement raté avec kubectl rollout undo
• Modifier l'image, les variables d'environnement ou les limites de ressources avec kubectl set
• Combiner ces commandes dans un workflow de déploiement complet

Quelle commande pour quel besoin ?

Les quatre commandes agissent toutes sur un Deployment, mais pas sur le même champ ni au même moment. scale et autoscale touchent au nombre de réplicas, set et rollout au contenu et au cycle de vie des pods. Une distinction structurante à retenir dès maintenant : scale et autoscale sont incompatibles sur un même objet, l'autoscaler reprenant la main dans les secondes qui suivent un scale manuel.

Besoin	Commande	Ce qu'elle fait
Ajouter/retirer des réplicas immédiatement	kubectl scale	Change le nombre de pods manuellement
Adapter les réplicas automatiquement à la charge	kubectl autoscale	Crée un HPA qui scale selon CPU/mémoire
Suivre/annuler une mise à jour	kubectl rollout	Contrôle le cycle de vie des rolling updates
Changer l'image, les env ou les ressources	kubectl set	Modifie un Deployment sans éditer le YAML

Glissez pour voir

kubectl scale : ajuster les réplicas manuellement

kubectl scale modifie le champ spec.replicas d'un Deployment, ReplicaSet ou StatefulSet. Le changement est immédiat : Kubernetes crée ou supprime les pods nécessaires.

Syntaxe

Le type d'objet est obligatoire : kubectl scale refuse un nom seul, car plusieurs types peuvent porter le même nom dans un namespace. L'option -n est également requise dès que l'objet n'est pas dans le namespace courant.

kubectl scale <type>/<nom> --replicas=<nombre> [-n namespace]

Recettes courantes

Cinq usages couvrent l'essentiel du besoin quotidien, du scale le plus direct aux formes qui sécurisent une exécution scriptée. Toutes prennent effet immédiatement et de façon persistante : la valeur est écrite dans la spec de l'objet et survit à un redémarrage du plan de contrôle.

Scaler un Deployment

Le cas nominal. La commande rend la main aussitôt, sans attendre que les nouveaux pods soient prêts : c'est la vérification qui suit qui confirme le résultat.

kubectl scale deploy/api-gateway --replicas=5 -n prod

deployment.apps/api-gateway scaled

Vérification :

kubectl get deploy api-gateway -n prod

NAME          READY   UP-TO-DATE   AVAILABLE   AGE
api-gateway   5/5     5            5           30d

Scaler un StatefulSet

Même commande, mais un comportement différent : les pods d'un StatefulSet sont créés et supprimés un par un, dans un ordre déterminé, et chacun conserve son volume persistant.

kubectl scale statefulset/postgres --replicas=3 -n prod

StatefulSet : scale-down ordonné

Un StatefulSet supprime les pods dans l'ordre inverse de leur création (pod-2 avant pod-1 avant pod-0). C'est important pour les bases de données : le dernier réplica est supprimé en premier. Assurez-vous que la réplication est bien configurée avant de réduire.

Scaler à zéro (suspendre une application)

--replicas=0 est la façon propre de suspendre un service sans le supprimer : la configuration, les Services et les volumes sont conservés, seule l'exécution s'arrête.

kubectl scale deploy/batch-processor --replicas=0 -n dev

Tous les pods sont supprimés. Le Deployment reste, prêt à être rescalé.

Scale conditionnel (seulement si le nombre actuel correspond)

--current-replicas transforme l'opération en écriture conditionnelle : si la valeur ne correspond pas, la commande échoue au lieu d'appliquer le changement.

kubectl scale deploy/api-gateway --replicas=5 --current-replicas=3 -n prod

Le scale ne s'applique que si le Deployment a actuellement 3 réplicas. Utile dans les scripts pour éviter les races.

Scaler plusieurs Deployments d'un coup

Plusieurs objets peuvent être listés sur la même ligne, tous recevant la même valeur de réplicas. Pratique pour remonter un ensemble de services après une maintenance.

kubectl scale deploy/api-gateway deploy/worker deploy/scheduler --replicas=3 -n prod

Scale et capacité du cluster

kubectl scale réussit toujours, même si le cluster n'a pas les ressources pour honorer la demande : la commande ne fait qu'écrire un nombre dans la spec, le scheduler se débrouille ensuite. Un scale « réussi » suivi de pods qui ne démarrent jamais est donc un scénario courant, et le seul moyen de le détecter est de regarder l'état des pods.

Plus de pods que de place dans le cluster

Si vous scalez à 10 réplicas mais que le cluster n'a pas assez de CPU/mémoire, les pods supplémentaires restent en Pending. Vérifiez avec :

kubectl get pods -n prod | grep Pending
kubectl describe pod <pod-pending> -n prod | grep -A5 Events

Le message Insufficient cpu ou Insufficient memory confirme le problème. Solutions : augmenter les nœuds (Cluster Autoscaler), réduire les requests des pods, ou drainer un nœud sous-utilisé.

kubectl autoscale : scaler automatiquement

kubectl autoscale crée un Horizontal Pod Autoscaler (HPA) qui ajuste le nombre de réplicas automatiquement selon l'utilisation CPU ou mémoire.

Prérequis

Le Metrics Server doit être installé dans le cluster pour que le HPA puisse lire les métriques :

# Vérifier que le Metrics Server est en place
kubectl top nodes

Si kubectl top retourne une erreur Metrics API not available, installez le Metrics Server :

kubectl apply -f https://github.com/kubernetes-sigs/metrics-server/releases/latest/download/components.yaml

Syntaxe

Trois bornes définissent le comportement : le minimum de réplicas, le maximum, et le seuil d'utilisation CPU visé. La commande crée un objet HorizontalPodAutoscaler distinct du Deployment, qu'il faudra supprimer séparément.

kubectl autoscale <type>/<nom> --min=<min> --max=<max> --cpu-percent=<seuil>

Créer un HPA basé sur le CPU

Le seuil s'exprime en pourcentage des requests du pod, pas de la capacité du nœud : --cpu-percent=70 avec requests: cpu: 200m déclenche l'ajout de pods au-delà de 140 millicores consommés en moyenne.

kubectl autoscale deploy/api-gateway --min=2 --max=10 --cpu-percent=70 -n prod

Le HPA maintient entre 2 et 10 réplicas. Si la charge CPU moyenne dépasse 70%, il ajoute des pods. Si elle descend, il en retire (jusqu'au minimum de 2).

horizontalpodautoscaler.autoscaling/api-gateway autoscaled

Vérifier l'état du HPA

La colonne TARGETS est celle à surveiller : elle affiche l'utilisation mesurée face au seuil. Un <unknown> à cet endroit signifie que le HPA ne fonctionne pas, faute de métriques ou de requests.

kubectl get hpa -n prod

NAME          REFERENCE                TARGETS   MINPODS   MAXPODS   REPLICAS   AGE
api-gateway   Deployment/api-gateway   45%/70%   2         10        3          5m

• TARGETS : 45%/70% = utilisation actuelle / seuil cible
• REPLICAS : nombre actuel de pods gérés par le HPA

Pour plus de détails :

kubectl describe hpa api-gateway -n prod

HPA sur la mémoire ou des métriques custom

kubectl autoscale ne permet de cibler que le CPU. Pour scaler sur la mémoire ou des métriques personnalisées (requêtes/seconde, longueur de queue…), écrivez un manifest HPA v2 :

apiVersion: autoscaling/v2
kind: HorizontalPodAutoscaler
metadata:
  name: api-gateway
  namespace: prod
spec:
  scaleTargetRef:
    apiVersion: apps/v1
    kind: Deployment
    name: api-gateway
  minReplicas: 2
  maxReplicas: 10
  metrics:
    - type: Resource
      resource:
        name: cpu
        target:
          type: Utilization
          averageUtilization: 70
    - type: Resource
      resource:
        name: memory
        target:
          type: Utilization
          averageUtilization: 80

kubectl apply -f hpa-api-gateway.yaml

requests obligatoires pour le HPA

Le HPA calcule le pourcentage d'utilisation par rapport aux requests définis dans le pod. Sans resources.requests, le HPA ne peut pas fonctionner et affiche <unknown> dans la colonne TARGETS.

resources:
  requests:
    cpu: 200m
    memory: 256Mi

Supprimer un HPA

Supprimer le HPA ne change rien au nombre de pods : le Deployment conserve le nombre de réplicas calculé en dernier. Remettez-le explicitement à la valeur voulue juste après.

kubectl delete hpa api-gateway -n prod

HPA vs scale manuel

Si un HPA est actif sur un Deployment, ne faites pas de kubectl scale manuel dessus. Le HPA écrasera votre changement dans les secondes qui suivent pour revenir à sa valeur calculée. Supprimez d'abord le HPA si vous voulez scaler manuellement.

kubectl rollout : piloter les mises à jour

Quand vous modifiez un Deployment (changement d'image, de variable d'env, de resources…), Kubernetes déclenche un rolling update : les anciens pods sont progressivement remplacés par les nouveaux. kubectl rollout vous permet de suivre, mettre en pause, reprendre et annuler ce processus.

Les sous-commandes de rollout

Six sous-commandes, dont deux seulement modifient l'état du cluster : undo et restart. Les autres observent ou suspendent. status est la seule à bloquer le terminal jusqu'à la fin du rollout, ce qui en fait la brique naturelle d'un script de déploiement.

Sous-commande	Ce qu'elle fait
rollout status	Affiche la progression en temps réel
rollout history	Liste les révisions précédentes
rollout undo	Revient à la révision précédente (ou une révision spécifique)
rollout pause	Met en pause un rollout en cours
rollout resume	Reprend un rollout en pause
rollout restart	Relance tous les pods (même sans changement de spec)

Glissez pour voir

Suivre un déploiement en cours

La commande affiche l'avancement ligne par ligne et ne rend la main qu'à la fin du rollout, réussi ou échoué. Ajoutez --timeout pour borner l'attente, sans quoi un rollout bloqué fige le terminal indéfiniment.

kubectl rollout status deploy/api-gateway -n prod

Waiting for deployment "api-gateway" rollout to finish: 2 out of 5 new replicas have been updated...
Waiting for deployment "api-gateway" rollout to finish: 3 out of 5 new replicas have been updated...
deployment "api-gateway" successfully rolled out

Le code retour est 0 si le rollout réussit, 1 sinon, exploitable dans les scripts.

Voir l'historique des révisions

Chaque modification de la spec du pod crée une révision, conservée sous forme de ReplicaSet. C'est cet historique qui rend le rollback possible : sans lui, rollout undo n'a nulle part où revenir. La colonne CHANGE-CAUSE reste vide tant que vous n'annotez pas vos déploiements.

kubectl rollout history deploy/api-gateway -n prod

REVISION  CHANGE-CAUSE
1         <none>
2         Mise à jour nginx 1.25 → 1.27
3         Ajout variable LOG_LEVEL=debug

Pour voir le détail d'une révision spécifique :

kubectl rollout history deploy/api-gateway -n prod --revision=2

Documenter les changements avec change-cause

L'annotation kubernetes.io/change-cause alimente la colonne CHANGE-CAUSE. Ajoutez-la après chaque modification :

kubectl annotate deploy api-gateway -n prod \
  kubernetes.io/change-cause="Mise à jour nginx 1.25 → 1.27"

Voir le guide labels et annotations pour plus de détails.

Rollback : annuler un déploiement

Si la nouvelle version pose problème :

# Revenir à la révision précédente
kubectl rollout undo deploy/api-gateway -n prod

# Revenir à une révision spécifique
kubectl rollout undo deploy/api-gateway -n prod --to-revision=2

deployment.apps/api-gateway rolled back

Vérifiez ensuite que le rollback est terminé :

kubectl rollout status deploy/api-gateway -n prod

Workflow de déploiement sécurisé

Les six étapes ci-dessous enchaînent les commandes vues jusqu'ici dans l'ordre où elles se protègent mutuellement : on prévisualise avant d'appliquer, on suit avant de conclure, on vérifie les logs avant d'annoter. C'est la séquence à scripter dans une CI, chaque commande retournant un code d'erreur exploitable.

1. Prévisualisez les changements

   kubectl diff -f api-gateway.yaml

2. Appliquez la mise à jour

   kubectl apply -f api-gateway.yaml

3. Suivez le rollout en temps réel

   kubectl rollout status deploy/api-gateway -n prod --timeout=300s

4. Vérifiez que les pods sont sains

   kubectl get pods -l app=api-gateway -n prod
   kubectl logs -l app=api-gateway -n prod --tail=20

5. Si problème, rollback immédiat

   kubectl rollout undo deploy/api-gateway -n prod

6. Annotez le changement pour l'historique

   kubectl annotate deploy api-gateway -n prod \
     kubernetes.io/change-cause="v2.4.1 : correctif timeout connexion DB"

Mettre en pause et reprendre un rollout

Le rollout en pause permet de faire un canary partiel : une partie des pods est mise à jour, vous vérifiez, puis vous continuez ou annulez.

# Mettre en pause avant que tous les pods soient remplacés
kubectl rollout pause deploy/api-gateway -n prod

# Vérifier l'état (ex: 2 pods sur 5 sont au nouveau code)
kubectl get pods -l app=api-gateway -n prod -o wide

# Si tout va bien, reprendre
kubectl rollout resume deploy/api-gateway -n prod

# Si ça ne va pas, annuler
kubectl rollout undo deploy/api-gateway -n prod

Redémarrer les pods (rollout restart)

rollout restart relance tous les pods un par un (rolling restart), même sans changement de spec. Utile pour :

• Prendre en compte un nouveau Secret ou ConfigMap monté en volume
• Forcer le pull d'une image avec tag latest
• Réinitialiser l'état applicatif

kubectl rollout restart deploy/api-gateway -n prod

Configurer la stratégie de rolling update

Le comportement du rolling update est contrôlé par spec.strategy dans le Deployment :

spec:
  strategy:
    type: RollingUpdate
    rollingUpdate:
      maxSurge: 1        # Nombre de pods supplémentaires pendant la mise à jour
      maxUnavailable: 0   # Nombre de pods indisponibles pendant la mise à jour

Paramètre	Valeur	Effet
maxSurge: 1, maxUnavailable: 0	Zéro downtime	Un pod de plus est créé, l'ancien n'est supprimé que quand le nouveau est Ready
maxSurge: 0, maxUnavailable: 1	Ressources minimales	Un pod est supprimé, puis un nouveau est créé (léger downtime possible)
maxSurge: 25%, maxUnavailable: 25%	Défaut Kubernetes	Compromis vitesse/stabilité

Glissez pour voir

maxUnavailable: 0 pour la prod

En production, préférez maxUnavailable: 0 pour garantir qu'il n'y a jamais moins de pods que le nombre souhaité pendant un rollout. Cela ralentit légèrement le déploiement mais élimine le risque de surcharge des pods restants.

kubectl set : modifier sans éditer le YAML

kubectl set permet de modifier un Deployment en une seule commande, sans ouvrir de fichier. Chaque modification déclenche automatiquement un rolling update.

set image : changer l'image d'un conteneur

La commande la plus utilisée :

kubectl set image deploy/api-gateway api-gateway=nginx:1.27 -n prod

deployment.apps/api-gateway image updated

Vérification :

kubectl get deploy api-gateway -n prod -o jsonpath='{.spec.template.spec.containers[0].image}'
# nginx:1.27

Mettre à jour tous les conteneurs d'un Deployment :

kubectl set image deploy/api-gateway *=nginx:1.27 -n prod

set env : ajouter ou modifier des variables d'environnement

Le tiret suffixe est la syntaxe de suppression : LOG_LEVEL- retire la variable au lieu de l'affecter. Les options --from=configmap/ et --from=secret/ injectent toutes les clés de l'objet référencé en une seule commande.

# Ajouter ou modifier une variable
kubectl set env deploy/api-gateway LOG_LEVEL=debug -n prod

# Supprimer une variable
kubectl set env deploy/api-gateway LOG_LEVEL- -n prod

# Ajouter depuis un ConfigMap
kubectl set env deploy/api-gateway --from=configmap/app-config -n prod

# Ajouter depuis un Secret
kubectl set env deploy/api-gateway --from=secret/db-credentials -n prod

Voir les variables actuelles :

kubectl set env deploy/api-gateway --list -n prod

set resources : modifier les limites CPU/mémoire

--requests fixe ce que le scheduler réserve, --limits ce que le conteneur ne peut pas dépasser. Modifier les requests d'un Deployment piloté par un HPA change mécaniquement le seuil de déclenchement, puisque le pourcentage se calcule par rapport à elles.

kubectl set resources deploy/api-gateway -n prod \
  --requests=cpu=200m,memory=256Mi \
  --limits=cpu=500m,memory=512Mi

set serviceaccount : changer le compte de service

Le ServiceAccount détermine les droits dont disposent les pods sur l'API Kubernetes. En changer relance donc tous les pods avec un jeu de permissions différent : vérifiez que le compte cible existe déjà dans le namespace, sinon les pods démarreront sans jeton valide.

kubectl set serviceaccount deploy/api-gateway api-sa -n prod

set déclenche un rolling update

Chaque commande set modifie la spec du pod template et déclenche un rolling update. Si vous devez faire plusieurs changements (image + env + resources), enchaînez-les rapidement ou faites-les dans un fichier YAML avec un seul apply.

Bonnes pratiques

Ces règles viennent des incidents les plus fréquents en exploitation : un scale manuel écrasé par un autoscaler, un déploiement supposé réussi qui ne l'était pas, un rollback impossible faute d'historique lisible. Elles sont regroupées par domaine pour être relues rapidement avant une mise en production.

Scaling

Les quatre points ci-dessous se ramènent à une règle : décidez qui pilote le nombre de réplicas, vous ou le HPA, et tenez-vous-y.

• Utilisez kubectl scale pour les réponses immédiates (pic de charge, incident)
• Pour la gestion au quotidien, configurez un HPA, le scaling manuel ne tient pas sur la durée
• Définissez toujours des resources.requests sur vos pods, sans eux, le HPA ne fonctionne pas et le scheduler planifie les pods à l'aveugle
• Ne faites pas de kubectl scale sur un Deployment géré par un HPA, le HPA écrasera votre changement

Déploiements

Un déploiement n'est terminé que lorsque vous l'avez vérifié. Ces cinq réflexes rendent le retour en arrière possible et rapide le jour où il devient nécessaire.

• Suivez toujours un rollout avec kubectl rollout status, ne partez pas en supposant que tout s'est bien passé
• Annotez chaque déploiement avec change-cause, votre futur vous remerciera quand il faudra comprendre quelle révision a cassé quelque chose
• Utilisez maxUnavailable: 0 en production pour du zero-downtime
• Testez vos rollbacks avant d'en avoir besoin, faites un undo en dev pour vérifier que la procédure fonctionne
• Préférez kubectl set image à kubectl edit pour les changements d'image, c'est plus lisible, scriptable et tracé

Général

Deux principes transverses, qui valent bien au-delà de ces quatre commandes : enchaîner des étapes vérifiables plutôt qu'une commande unique, et garder la configuration au même endroit que le code.

• Combinez diff → apply → rollout status → wait pour un workflow de déploiement complet et vérifiable
• Documentez votre stratégie de rolling update dans le manifest du Deployment, pas dans un wiki séparé

Dépannage

La plupart de ces symptômes ont un point commun : la commande a réussi et pourtant rien ne se passe comme prévu. Kubernetes étant déclaratif, kubectl se contente d'enregistrer une intention ; l'écart entre cette intention et la réalité se lit toujours ailleurs, dans l'état des pods ou dans les événements. Le tableau relie chaque symptôme à sa cause et à la commande qui le confirme.

Symptôme	Cause probable	Solution
scale ne change rien	Un HPA est actif et écrase la valeur	Supprimez le HPA avec kubectl delete hpa NOM -n NS avant de scaler manuellement
Pods restent Pending après scale	Pas assez de ressources dans le cluster	Vérifiez avec kubectl describe pod POD -n NS les events. Ajoutez des nœuds ou réduisez les requests
HPA affiche unknown dans TARGETS	Metrics Server absent ou requests non définis	Installez le Metrics Server et définissez resources.requests sur vos pods
HPA ne scale pas vers le bas	Période de cooldown (5 min par défaut)	Attendez 5 minutes. Le HPA évite les oscillations en ajoutant un délai avant le scale-down
Rollout bloqué : pods en CrashLoopBackOff	La nouvelle version crashe	Faites kubectl rollout undo deploy/NOM -n NS pour revenir à la version précédente
rollout undo ne fait rien	Vous êtes déjà à la première révision	Vérifiez avec kubectl rollout history. Il n'y a pas de révision antérieure
rollout status timeout	Le rolling update est trop lent ou bloqué	Vérifiez maxSurge/maxUnavailable, les PDB et l'état des pods avec kubectl get pods
set image ne déclenche pas de rollout	L'image est identique à la valeur actuelle	Kubernetes ne rollout que si la spec change. Vérifiez l'image actuelle avec kubectl get deploy -o jsonpath
Rollout trop lent	maxSurge: 1 + beaucoup de réplicas	Augmentez maxSurge (ex: 25% ou 3) pour accélérer la mise à jour
no rollout history found	Aucune modification n'a été faite depuis la création	C'est normal pour un Deployment fraîchement créé

Glissez pour voir

À retenir

• kubectl scale ajuste les réplicas immédiatement, utilisez-le pour les urgences, un HPA pour le quotidien.
• kubectl autoscale crée un HPA qui scale automatiquement sur le CPU. Pour la mémoire ou des métriques custom, écrivez un manifest HPA v2.
• Le HPA exige des resources.requests sur les pods, sans eux, il affiche unknown et ne scale pas.
• kubectl rollout status suit un déploiement en temps réel. rollout undo revient à la révision précédente en une commande.
• rollout pause/resume permet des canary partiels : mettez à jour une partie des pods, vérifiez, puis continuez ou annulez.
• kubectl set modifie image, env ou resources sans éditer de YAML, chaque commande déclenche un rolling update.
• Le workflow de deploy en prod : diff → apply → rollout status → vérification → annotation change-cause.
• Configurez maxUnavailable: 0 en production pour garantir le zero-downtime.

Prochaines étapes

Créer et déployer avec create et apply L'approche déclarative standard, le apply qui déclenche le rollout.

diff et wait : prévisualiser et synchroniser Compléter le workflow : diff avant apply, wait après rollout.

Diagnostiquer avec get, describe et logs Comprendre pourquoi un rollout bloque ou un pod crashe.

Labels et annotations Annoter vos déploiements avec change-cause pour l'historique des révisions.

Cordon, drain et taint Scaler avant un drain pour absorber la charge sur les nœuds restants.

×

📖 Voir la documentation →