kubectl top pod qui répond « error: Metrics API not available » et un HPA qui n’affiche aucune métrique dans kubectl describe hpa partagent la même cause : metrics-server n’est pas installé. Ce n’est un prérequis d’aucun des deux outils au sens où on l’entend habituellement, c’est la source de données sans laquelle ils n’ont rien à lire, jamais nommée explicitement dans la documentation qui explique comment configurer un HPA.

Ce que metrics-server collecte, et ce qu’il ne collecte pas

metrics-server interroge périodiquement le kubelet de chaque nœud, qui expose lui-même les statistiques d’usage CPU et mémoire collectées par cAdvisor, et agrège le tout dans l’API metrics.k8s.io. C’est cette API que consultent kubectl top et le contrôleur HPA.

# Une fois metrics-server installé et fonctionnel
kubectl top nodes
kubectl top pods -n production

Ce que metrics-server ne fait jamais : conserver un historique. Chaque requête renvoie l’usage instantané le plus récent, rien de plus ; aucune donnée n’est stockée au-delà de la fenêtre la plus courte nécessaire au calcul. Pour un historique de métriques, des tableaux de bord ou des alertes basées sur des tendances, il faut une solution d’observabilité complète (Prometheus et les golden signals) : metrics-server n’a jamais été conçu pour ce rôle, seulement pour alimenter des décisions d’autoscaling en temps réel.

L’erreur de certificat la plus fréquente à l’installation

Une installation par défaut de metrics-server échoue souvent avec une erreur liée à la validation TLS du certificat du kubelet, particulièrement fréquente sur des clusters auto-gérés où le certificat kubelet n’est pas signé par une autorité que metrics-server reconnaît par défaut :

# Flag de contournement, à n'utiliser qu'après avoir compris pourquoi
# la validation échoue, jamais comme réflexe automatique
args:
  - --kubelet-insecure-tls

Ce flag désactive la vérification du certificat, ce qui résout le symptôme sans traiter la cause : sur un cluster où l’infrastructure PKI est correctement configurée, le vrai correctif consiste à faire reconnaître l’autorité de certification du kubelet à metrics-server, pas à désactiver la vérification. --kubelet-insecure-tls reste un choix pragmatique acceptable sur beaucoup de clusters auto-gérés, tant que la décision est consciente et pas copiée d’un tutoriel sans le lire.

Pourquoi le HPA reste silencieux sans lui

Un HPA configuré sur un cluster sans metrics-server ne produit aucune erreur visible immédiatement : il reste simplement bloqué, TARGETS affichant <unknown> dans kubectl get hpa, sans jamais scaler ni signaler pourquoi. Ce silence est la raison la plus fréquente pour laquelle un HPA « ne marche pas » alors que sa configuration YAML est parfaitement correcte : le problème n’est jamais dans le HPA lui-même, mais dans l’absence de la source de données dont il dépend entièrement.

Ce qui dépasse metrics-server : les métriques custom

Un HPA qui scale sur autre chose que CPU/mémoire (une longueur de file de messages, un taux de requêtes applicatif) ne peut pas s’appuyer sur metrics-server, limité aux ressources standard. Ce cas exige un adaptateur de métriques custom, généralement branché sur Prometheus, qui expose ces métriques via une API distincte (custom.metrics.k8s.io). C’est une extension du même principe, pas un remplacement : metrics-server reste la source pour CPU/mémoire, l’adaptateur custom prend le relais pour tout le reste.

À retenir

metrics-server est le prérequis silencieux qui alimente kubectl top et le HPA en données temps réel, sans historique et sans vocation à remplacer une stack d’observabilité complète. Un HPA bloqué avec des cibles <unknown> signale presque toujours son absence, pas une erreur de configuration. L’erreur de certificat à l’installation se résout en comprenant la chaîne de confiance PKI du cluster, pas en désactivant systématiquement la vérification. Ce socle fait partie de ce qui se pose dès les premières étapes d’une migration Kubernetes.