Horizontal Pod Autoscaler (HPA) — Mise à l'échelle automatique

Le Horizontal Pod Autoscaler (HPA) ajuste automatiquement le nombre de réplicas d’une application pour suivre la charge observée. Il interroge périodiquement les métriques de vos Pods et augmente ou réduit leur nombre en fonction de seuils que vous définissez. C’est le mécanisme principal de mise à l’échelle horizontale dans Kubernetes.

Ce guide couvre la configuration du HPA avec autoscaling/v2, le rôle critique des requests, le contrôle du comportement de scaling, et le debug — tout ce qu’il faut pour la CKAD et la production.

Ce que vous allez apprendre

• Comment le HPA prend ses décisions et la formule de calcul
• Le rôle critique des requests pour le calcul d’utilisation
• Configurer un HPA basé sur CPU, mémoire ou plusieurs métriques
• Contrôler la vitesse de scaling avec behavior
• Débugger un HPA qui affiche <unknown> ou ne scale pas
• Ce qu’il faut savoir pour la CKAD

À quoi sert le HPA ?

Le HPA observe les métriques de vos Pods et ajuste leur nombre pour maintenir un niveau d’utilisation cible :

Situation	Action du HPA
Charge élevée (métriques > seuil)	Augmente le nombre de réplicas
Charge faible (métriques < seuil)	Réduit le nombre de réplicas (prudemment)
Métriques indisponibles	Attend sans modifier les réplicas

Glissez pour voir

Ce que le HPA ne fait pas

Le HPA ajuste le nombre de Pods, pas leur taille. Pour modifier les requests/limits d’un Pod existant, utilisez le Vertical Pod Autoscaler (VPA). Pour ajouter des nœuds au cluster, utilisez le Cluster Autoscaler.

HPA vs VPA vs Cluster Autoscaler

Outil	Agit sur	Cas d’usage
HPA	Nombre de Pods	Applications stateless, montée en charge
VPA	Taille des Pods (requests/limits)	Applications avec besoins variables
Cluster Autoscaler	Nombre de nœuds	Capacité cluster insuffisante

Glissez pour voir

Conditions préalables

Avant de créer un HPA, deux éléments sont impératifs :

1. Le Metrics Server doit être installé

Le HPA récupère les métriques via le Metrics Server. Vérifiez qu’il est opérationnel :

kubectl get deployment -n kube-system metrics-server
kubectl top pods -A

Si kubectl top affiche des valeurs CPU/mémoire, le Metrics Server fonctionne.

Installation si absent :

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

Délai d'initialisation

Après installation, attendez 1-2 minutes que le Metrics Server collecte les premières métriques. kubectl top pods retournera des erreurs pendant ce temps.

2. Les Pods doivent avoir des requests définies

C’est le point le plus important pour le HPA.

Pour un HPA basé sur averageUtilization, le calcul d’utilisation est :

Utilisation = (consommation actuelle / request) × 100

Sans requests définies, le HPA ne peut pas calculer le pourcentage d’utilisation et affichera <unknown> dans TARGETS.

# ✅ OBLIGATOIRE pour le HPA basé sur Utilization
resources:
  requests:
    cpu: "100m"
    memory: "128Mi"

Requests vs Limits

Pour le HPA, ce sont les requests qui comptent, pas les limits. Les limits servent à la protection (OOMKill, throttling), mais le HPA calcule son ratio uniquement sur les requests.

Comment le HPA décide du nombre de réplicas

La formule de base

Réplicas voulus = Réplicas actuels × (Utilisation actuelle / Objectif)

Exemple : 2 Pods à 80% d’utilisation, objectif 50%

Réplicas voulus = 2 × (80 / 50) = 3.2 → 4 Pods

Comportement réel (plus nuancé)

La formule représente le principe général, mais le HPA applique aussi :

• Une tolérance de ±10% avant de décider d’un scaling (évite les oscillations)
• L’exclusion des Pods non Ready ou en cours de suppression
• Une fenêtre de stabilisation avant de scale down (par défaut 5 minutes)
• L’attente si des métriques sont manquantes

Scale down prudent

Le scale up est rapide (réaction à la charge). Le scale down est volontairement plus lent pour éviter les oscillations. Par défaut, le HPA attend 5 minutes de stabilisation avant de réduire les réplicas.

Exemple minimal : HPA basé sur CPU

Déploiement avec requests

apiVersion: apps/v1
kind: Deployment
metadata:
  name: nginx-deployment
spec:
  replicas: 1
  selector:
    matchLabels:
      app: nginx
  template:
    metadata:
      labels:
        app: nginx
    spec:
      containers:
      - name: nginx
        image: nginx:1.28
        resources:
          requests:
            cpu: "100m"        # ← OBLIGATOIRE pour le HPA
            memory: "128Mi"
          limits:
            cpu: "200m"
            memory: "256Mi"
        ports:
        - containerPort: 80
---
apiVersion: v1
kind: Service
metadata:
  name: nginx-service
spec:
  selector:
    app: nginx
  ports:
  - port: 80
    targetPort: 80
  type: ClusterIP

Créer le HPA

apiVersion: autoscaling/v2
kind: HorizontalPodAutoscaler
metadata:
  name: nginx-hpa
spec:
  scaleTargetRef:
    apiVersion: apps/v1
    kind: Deployment
    name: nginx-deployment
  minReplicas: 1
  maxReplicas: 10
  metrics:
  - type: Resource
    resource:
      name: cpu
      target:
        type: Utilization
        averageUtilization: 50

Ce que ça signifie : Le HPA maintiendra l’utilisation CPU moyenne des Pods autour de 50%. Si elle dépasse, il ajoute des Pods. Si elle descend, il en retire (après stabilisation).

Appliquer et vérifier

kubectl apply -f nginx-deployment.yaml
kubectl apply -f nginx-hpa.yaml

kubectl get hpa
# NAME        REFERENCE                     TARGETS   MINPODS   MAXPODS   REPLICAS
# nginx-hpa   Deployment/nginx-deployment   10%/50%   1         10        1

Types de métriques supportées

Le HPA avec autoscaling/v2 supporte quatre types de métriques :

Type	Description	Exemple
Resource	CPU, mémoire des conteneurs	averageUtilization: 50
Pods	Métrique agrégée par Pod	Requêtes/seconde par Pod
Object	Métrique liée à un objet K8s	Requêtes sur un Ingress
External	Métrique externe au cluster	Queue AWS SQS, Pub/Sub

Glissez pour voir

Exemple avec plusieurs métriques

apiVersion: autoscaling/v2
kind: HorizontalPodAutoscaler
metadata:
  name: multi-metric-hpa
spec:
  scaleTargetRef:
    apiVersion: apps/v1
    kind: Deployment
    name: my-app
  minReplicas: 2
  maxReplicas: 20
  metrics:
  # Métrique 1 : CPU
  - type: Resource
    resource:
      name: cpu
      target:
        type: Utilization
        averageUtilization: 60
  # Métrique 2 : Mémoire
  - type: Resource
    resource:
      name: memory
      target:
        type: Utilization
        averageUtilization: 70

Calcul avec plusieurs métriques

Quand plusieurs métriques sont définies, le HPA calcule le nombre de réplicas requis pour chaque métrique et prend le maximum. Cela garantit que toutes les métriques restent sous leurs seuils.

Métriques custom et external

Pour les métriques custom (Pods, Object) ou external, vous avez besoin d’un adaptateur de métriques comme :

• Prometheus Adapter — expose les métriques Prometheus au HPA
• KEDA — autoscaler événementiel avec nombreuses sources

Le Metrics Server seul suffit uniquement pour CPU et mémoire.

Contrôler la vitesse de scaling avec behavior

Le champ behavior permet de contrôler finement la vitesse de scale up et scale down :

apiVersion: autoscaling/v2
kind: HorizontalPodAutoscaler
metadata:
  name: controlled-hpa
spec:
  scaleTargetRef:
    apiVersion: apps/v1
    kind: Deployment
    name: my-app
  minReplicas: 2
  maxReplicas: 50
  metrics:
  - type: Resource
    resource:
      name: cpu
      target:
        type: Utilization
        averageUtilization: 50
  behavior:
    scaleDown:
      stabilizationWindowSeconds: 300    # Attendre 5 min avant scale down
      policies:
      - type: Percent
        value: 10                         # Réduire max 10% par période
        periodSeconds: 60
    scaleUp:
      stabilizationWindowSeconds: 0      # Scale up immédiat
      policies:
      - type: Percent
        value: 100                        # Doubler si nécessaire
        periodSeconds: 15
      - type: Pods
        value: 4                          # Ou ajouter max 4 pods
        periodSeconds: 15
      selectPolicy: Max                   # Prendre la politique la plus agressive

Paramètres de behavior

Paramètre	Description	Défaut
stabilizationWindowSeconds	Temps d’attente avant d’appliquer le scaling	300s (down), 0s (up)
policies[].type	Pods (nombre absolu) ou Percent	-
policies[].value	Valeur du changement	-
policies[].periodSeconds	Période d’évaluation	-
selectPolicy	Max, Min, ou Disabled	Max

Glissez pour voir

Éviter le flapping

Si votre HPA oscille entre scale up et scale down, augmentez stabilizationWindowSeconds pour le scale down. Cela lisse les variations de charge.

Exemple : Scale down très conservateur

behavior:
  scaleDown:
    stabilizationWindowSeconds: 600    # 10 minutes
    policies:
    - type: Pods
      value: 1                          # 1 pod max par minute
      periodSeconds: 60

Tester le scaling

Méthode recommandée : charge depuis un Pod

Plutôt que d’installer des outils sur votre machine, générez la charge depuis un Pod dans le cluster :

# Lancer un Pod de charge avec wget en boucle
kubectl run load-generator --image=busybox:1.36 --rm -it -- /bin/sh -c \
  "while true; do wget -q -O- http://nginx-service; done"

Dans un autre terminal, observez le HPA :

kubectl get hpa -w
# NAME        REFERENCE                     TARGETS    MINPODS   MAXPODS   REPLICAS
# nginx-hpa   Deployment/nginx-deployment   12%/50%    1         10        1
# nginx-hpa   Deployment/nginx-deployment   78%/50%    1         10        1
# nginx-hpa   Deployment/nginx-deployment   78%/50%    1         10        2
# nginx-hpa   Deployment/nginx-deployment   45%/50%    1         10        2

Délai de scaling

Le scale up prend généralement 15-30 secondes après détection de la surcharge. Le scale down prend plusieurs minutes (stabilization window par défaut de 5 minutes).

Arrêter le test et observer le scale down

Arrêtez la charge avec Ctrl+C et observez :

kubectl get hpa -w
# Après plusieurs minutes...
# nginx-hpa   Deployment/nginx-deployment   5%/50%     1         10        2
# nginx-hpa   Deployment/nginx-deployment   5%/50%     1         10        1

Débugger un HPA

Commandes essentielles

# Vue rapide
kubectl get hpa

# Détails complets avec conditions et événements
kubectl describe hpa nginx-hpa

# YAML avec status actuel
kubectl get hpa nginx-hpa -o yaml

# Vérifier les métriques des Pods
kubectl top pods -l app=nginx

# Vérifier le Metrics Server
kubectl top nodes

Lire les conditions du HPA

kubectl describe hpa affiche des conditions qui expliquent l’état du HPA :

kubectl describe hpa nginx-hpa

Conditions:
  Type            Status  Reason              Message
  ----            ------  ------              -------
  AbleToScale     True    ReadyForNewScale    recommended size matches current size
  ScalingActive   True    ValidMetricFound    the HPA was able to successfully calculate a replica count
  ScalingLimited  False   DesiredWithinRange  the desired count is within the acceptable range

Condition	Signification
AbleToScale: True	Le HPA peut modifier les réplicas
ScalingActive: True	Les métriques sont disponibles et valides
ScalingLimited: True	Bloqué par minReplicas ou maxReplicas

Glissez pour voir

Problèmes courants et solutions

Symptôme	Cause probable	Solution
TARGETS: <unknown>/50%	Pas de requests définies	Ajouter resources.requests au Deployment
TARGETS: <unknown>/50%	Metrics Server absent	Installer le Metrics Server
TARGETS: <unknown>/50%	Pods pas encore Ready	Attendre que les Pods démarrent
ScalingActive: False	Métrique introuvable	Vérifier le nom de la métrique
HPA ne scale pas up	Charge insuffisante	Augmenter la charge de test
HPA ne scale pas down	Stabilization window	Attendre 5+ minutes
ScalingLimited: True	maxReplicas atteint	Augmenter maxReplicas

Glissez pour voir

Debug détaillé

# Voir les événements du HPA
kubectl describe hpa nginx-hpa | grep -A 10 "Events:"

# Vérifier que la cible existe
kubectl get deployment nginx-deployment

# Vérifier les métriques brutes
kubectl get --raw "/apis/metrics.k8s.io/v1beta1/namespaces/default/pods" | jq .

Créer un HPA en ligne de commande (CKAD)

Pour les situations où vous devez aller vite :

# Créer un HPA basé sur CPU
kubectl autoscale deployment nginx-deployment \
  --cpu-percent=50 \
  --min=1 \
  --max=10

# Vérifier
kubectl get hpa nginx-deployment

Pour la CKAD

kubectl autoscale crée un HPA autoscaling/v1 (CPU uniquement). Pour plusieurs métriques ou behavior, vous devez écrire le YAML avec autoscaling/v2.

Générer le YAML

kubectl autoscale deployment nginx-deployment \
  --cpu-percent=50 --min=1 --max=10 \
  --dry-run=client -o yaml > hpa.yaml

Ce qu’il faut savoir pour la CKAD

1. Lire un HPA existant

   kubectl get hpa
   kubectl describe hpa <nom>

2. Créer un HPA CPU rapidement

   kubectl autoscale deployment <nom> --cpu-percent=50 --min=1 --max=10

3. Comprendre le lien requests → HPA

   Sans requests, le HPA affiche <unknown> et ne fonctionne pas.

4. Vérifier les métriques

   kubectl top pods
   kubectl top nodes

5. Diagnostiquer TARGETS <unknown>

   • Metrics Server installé ?
   • requests définies dans le Deployment ?
   • Pods en état Running ?

Commandes à connaître par cœur

# Créer rapidement
kubectl autoscale deployment myapp --cpu-percent=50 --min=2 --max=10

# Voir l'état
kubectl get hpa
kubectl describe hpa myapp

# Voir les métriques
kubectl top pods
kubectl top pods -l app=myapp

# Modifier à chaud
kubectl patch hpa myapp -p '{"spec":{"maxReplicas":20}}'

# Supprimer
kubectl delete hpa myapp

Dépannage

FailedGetResourceMetric ou missing request

Warning  FailedComputeMetricsReplicas  unable to get metrics for resource cpu:
         no metrics returned from resource metrics API

Cause : Le Metrics Server ne retourne pas de métriques pour ce Pod.

Solution :

# Vérifier le Metrics Server
kubectl get deployment -n kube-system metrics-server
kubectl logs -n kube-system deployment/metrics-server

# Vérifier que les Pods ont des requests
kubectl get deployment nginx-deployment -o yaml | grep -A5 resources

Le HPA est bloqué à 1 réplica

Causes possibles :

1. La charge est insuffisante (utilisation < 50% × tolérance)
2. minReplicas: 1 empêche de descendre plus bas
3. ScalingLimited: True — vérifier maxReplicas

Le HPA oscille (flapping)

Cause : La charge varie autour du seuil et provoque des scale up/down répétés.

Solution : Augmenter la fenêtre de stabilisation :

behavior:
  scaleDown:
    stabilizationWindowSeconds: 600
  scaleUp:
    stabilizationWindowSeconds: 60

À retenir

1. Le HPA ajuste le nombre de réplicas, pas la taille des Pods (c’est le VPA)
2. Les requests sont obligatoires pour averageUtilization — sans elles, <unknown>
3. Le Metrics Server est requis pour les métriques CPU/mémoire standard
4. Le scale down est volontairement lent (5 min par défaut) pour éviter les oscillations
5. behavior permet de contrôler finement la vitesse de scaling
6. kubectl describe hpa montre les conditions et événements pour débugger
7. kubectl autoscale crée rapidement un HPA CPU (utile pour la CKAD)
8. Pour les métriques custom/external, il faut un adaptateur (Prometheus Adapter, KEDA)

Prochaines étapes

Requests et Limits Comprendre les requests, essentielles pour le HPA

Deployments L'objet principal ciblé par le HPA

Probes Le HPA ignore les Pods non Ready

Debug Applications Méthodologie de diagnostic Kubernetes

×

📖 Voir la documentation →