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 ?

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

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

Recettes courantes

Scaler un Deployment

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

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)

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)

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

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

Scale et capacité du cluster

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

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

Créer un HPA basé sur le CPU

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

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

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

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

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

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é

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

# 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

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

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

Scaling

• 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

• 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

• 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

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 →