Commandes du serveur d'API Kubernetes : exemples pratiques pour les opérateurs

Introduction

Le serveur d'API Kubernetes est la porte d'entrée de votre cluster. Chaque commande kubectl, action de contrôleur et décision de planificateur transite par lui. Lorsqu'il échoue ou se comporte de manière inattendue, c'est tout le plan de contrôle qui peut s'arrêter. Connaître les bonnes commandes pour l'inspecter n'est pas une option pour quiconque exploite Kubernetes en production.

Cet article vous propose une référence pratique de commandes pour le kube-apiserver. Vous apprendrez à vérifier sa santé, à inspecter sa configuration, à consulter ses journaux, à tester l'authentification et l'autorisation, et à récupérer après des modes de défaillance courants. Chaque commande est accompagnée d'un exemple avec la sortie attendue lorsque c'est utile, ainsi que de notes sur les prérequis et l'impact potentiel. Nous aborderons également les erreurs fréquentes commises par les opérateurs lorsqu'ils manipulent le serveur d'API et comment les éviter.

Nous privilégions les commandes sûres à exécuter en premier : des observations en lecture seule qui vous disent ce qui se passe sans rien modifier. Ensuite, nous passerons à des changements contrôlés avec des étapes de vérification et des chemins de récupération. Que vous soyez un développeur en train de déboguer des problèmes d'accès, un ingénieur DevOps confronté à un incident, ou une équipe plateforme documentant des runbooks, ces exemples vous aideront à travailler avec plus de confiance.

Inventaire de version et d'environnement

Avant d'exécuter toute commande, connaissez la version de votre cluster et la manière dont le serveur d'API est déployé. Selon la distribution et la version de Kubernetes, les chemins de commande, les indicateurs et les points de terminaison peuvent varier. Commencez par quelques commandes en lecture seule pour établir le contexte.

Vérifier la version du cluster

Utilisez kubectl pour obtenir à la fois la version du client et celle du serveur.

kubectl version --short

Sortie attendue :

Client Version: v1.28.2
Server Version: v1.28.2

Si la version du serveur n'apparaît pas, votre kubeconfig peut contenir des identifiants invalides ou le serveur d'API est injoignable.

Identifier le pod du serveur d'API

Dans un cluster kubeadm ou autogéré, le kube-apiserver s'exécute comme un pod statique sur les nœuds du plan de contrôle. Listez les pods du plan de contrôle dans l'espace de noms kube-system.

kubectl get pods -n kube-system -l component=kube-apiserver

Sortie attendue :

NAME                    READY   STATUS    RESTARTS   AGE
kube-apiserver-node1   1/1     Running   0          4d

Dans les clusters managés comme EKS, AKS ou GKE, vous ne verrez pas le pod du serveur d'API car le plan de contrôle est géré par le fournisseur. Vous interagissez avec le serveur d'API via le point de terminaison managé.

Vérifier les points de terminaison du serveur d'API

Le service Kubernetes dans l'espace de noms default pointe vers le serveur d'API.

kubectl get endpoints kubernetes

Sortie attendue :

NAME         ENDPOINTS             AGE
kubernetes   192.168.1.10:6443     10d

C'est à cette adresse IP et ce port que kubectl envoie ses requêtes. Vérifiez que votre kubeconfig pointe vers la même adresse avec kubectl config view.

Afficher les arguments du conteneur du serveur d'API

Si vous avez accès au pod, inspectez ses arguments de ligne de commande. Ces indicateurs définissent le comportement du serveur d'API : authentification, autorisation, contrôle d'admission, etc.

kubectl get pod kube-apiserver-node1 -n kube-system -o jsonpath='{.spec.containers[0].command}' | tr ' ' '\n'

Vous verrez des indicateurs comme --authorization-mode=Node,RBAC, --enable-admission-plugins=..., et --tls-cert-file=.... Enregistrez cette sortie pour le dépannage ultérieur ; ne la partagez pas publiquement car les chemins peuvent révéler des noms internes.

Chemin de configuration sûr

Modifier la configuration du serveur d'API est délicat. Un mauvais indicateur ou un certificat malformé peut casser tout le plan de contrôle. Suivez toujours cette séquence :

1. Observez l'état actuel.
2. Sauvegardez le manifeste ou le fichier de configuration.
3. Faites un seul petit changement.
4. Vérifiez que le serveur d'API redémarre avec succès.
5. Ayez un plan de retour en arrière prêt.

Localiser le manifeste du pod statique

Dans les clusters kubeadm, le manifeste du serveur d'API se trouve à /etc/kubernetes/manifests/kube-apiserver.yaml sur le nœud du plan de contrôle. Le kubelet surveille ce répertoire et redémarre automatiquement le pod lorsque le fichier change.

sudo ls -l /etc/kubernetes/manifests/kube-apiserver.yaml

Sortie attendue :

-rw------- 1 root root 2438 Jan 12 10:22 /etc/kubernetes/manifests/kube-apiserver.yaml

Sauvegarder le manifeste

Avant de modifier, créez une sauvegarde horodatée.

sudo cp /etc/kubernetes/manifests/kube-apiserver.yaml /etc/kubernetes/manifests/kube-apiserver.yaml.bak.$(date +%Y%m%d%H%M%S)

Modifier le manifeste en toute sécurité

Utilisez un éditeur non destructif et enregistrez soigneusement. Par exemple, pour ajouter un chemin de journal d'audit, vous ajouteriez --audit-log-path=/var/log/kube-audit.log à la liste des commandes. Mais vérifiez d'abord que le répertoire du journal existe et est accessible en écriture par le conteneur du serveur d'API.

sudo mkdir -p /var/log/kube-audit
sudo chown root:root /var/log/kube-audit

Modifiez ensuite le manifeste et ajoutez l'indicateur avec le montage de volume approprié. Après l'enregistrement, le kubelet tentera de redémarrer le pod du serveur d'API. Surveillez l'état du pod.

kubectl get pods -n kube-system -l component=kube-apiserver -w

Si le pod ne démarre pas, consultez les journaux (voir ci-dessous) et revenez au manifeste de sauvegarde.

Vérification et diagnostics

Une fois le serveur d'API en cours d'exécution, vous devez vérifier qu'il est sain et répond correctement aux requêtes. Ces commandes vous aident à diagnostiquer les problèmes sans faire de modifications.

Points de terminaison de santé

Le serveur d'API expose des points de terminaison de contrôle de santé pour la vivacité et la préparation.

curl -sk https://<api-server-ip>:6443/healthz?verbose

Sur un nœud du plan de contrôle, vous pouvez utiliser localhost.

curl -sk https://localhost:6443/healthz?verbose

Sortie attendue lorsque tout est sain :

[+]ping ok
[+]log ok
[+]etcd ok
[+]poststarthook/start-kube-apiserver-admission-initializer ok
...
healthz check passed

Si un contrôle échoue, la sortie indique le composant défaillant. Cela vous oriente vers le prochain domaine à investiguer (par exemple, la connectivité etcd).

Vérifier les métriques du serveur d'API

Le serveur d'API expose les métriques Prometheus à /metrics. Vous pouvez les récupérer avec curl si vous disposez du bon certificat client, ou utiliser kubectl proxy pour plus de commodité.

kubectl proxy --port=8001 &
curl -s http://localhost:8001/metrics | grep -E '^apiserver_request_total|^apiserver_current_inflight_requests'

Exemple de ligne :

apiserver_current_inflight_requests{requestKind="readOnly",resource="pods"} 1

Un nombre élevé de requêtes en vol peut indiquer un backend lent ou un serveur d'API surchargé.

Consulter les journaux du serveur d'API

Pour les clusters à pods statiques, utilisez kubectl logs.

kubectl logs -n kube-system kube-apiserver-node1

Pour les pods non statiques ou un serveur d'API géré par systemd, utilisez journalctl.

journalctl -u kube-apiserver -f

Recherchez les messages d'erreur répétés, les échecs de poignée de main TLS ou les délais d'attente etcd. L'horodatage et la corrélation avec d'autres composants du plan de contrôle (etcd, gestionnaire de contrôleurs) sont essentiels.

Tester l'authentification et l'autorisation

Utilisez kubectl auth can-i pour vérifier ce qu'un utilisateur ou un compte de service peut faire.

kubectl auth can-i create deployments --as=system:serviceaccount:default:deployer

Sortie attendue :

yes

Si vous obtenez no, vérifiez les rôles RBAC et les liaisons. Cette commande ne nécessite aucune modification et peut être exécutée en toute sécurité.

Modes de défaillance et récupération

Même avec une gestion soignée, le serveur d'API peut échouer. Voici les modes de défaillance courants, comment les détecter et les étapes de récupération.

Pod du serveur d'API en CrashLoopBackOff

Si le pod n'est pas prêt et redémarre, inspectez immédiatement les journaux.

kubectl describe pod kube-apiserver-node1 -n kube-system

Vérifiez la section Events pour des messages comme Back-off restarting failed container ou des erreurs spécifiques telles que Error: --etcd-servers must be specified.

Causes courantes :

• Points de terminaison etcd mal configurés (indicateur --etcd-servers)
• Chemins de certificat TLS incorrects ou certificats expirés
• Configuration de plugin d'admission invalide

Récupération : corrigez le manifeste, laissez le kubelet redémarrer le pod et surveillez avec kubectl get pods -n kube-system -w.

etcd injoignable

Le serveur d'API dépend d'etcd. Si etcd est en panne, le serveur d'API peut devenir non sain mais continuer à fonctionner.

Vérifiez la santé d'etcd depuis un nœud du plan de contrôle.

sudo ETCDCTL_API=3 etcdctl --endpoints=https://127.0.0.1:2379 --cacert=/etc/kubernetes/pki/etcd/ca.crt --cert=/etc/kubernetes/pki/etcd/server.crt --key=/etc/kubernetes/pki/etcd/server.key endpoint health

Si etcd est en panne, récupérez d'abord etcd, puis redémarrez le serveur d'API si nécessaire.

Expiration des certificats

Des certificats de service expirés empêchent les clients de se connecter. Vérifiez les dates d'expiration des certificats.

sudo openssl x509 -in /etc/kubernetes/pki/apiserver.crt -noout -dates

Sortie attendue :

notBefore=Jan 12 10:00:00 2024 GMT
notAfter=Jan 11 10:00:00 2025 GMT

Si la date est dépassée, renouvelez le certificat en utilisant le processus de renouvellement de votre cluster (par exemple, kubeadm certs renew apiserver).

Échec du webhook d'admission

Un webhook d'admission défaillant peut bloquer toute création ou mise à jour de ressources. Si vous voyez des erreurs comme Internal error occurred: failed calling webhook, vérifiez la configuration du webhook.

kubectl get validatingwebhookconfigurations
kubectl get mutatingwebhookconfigurations

En cas d'urgence, vous pouvez temporairement supprimer la configuration du webhook fautif pour débloquer l'API, mais cela doit être un dernier recours et fait en connaissance des implications de sécurité.

Liste de contrôle opérationnelle

Utilisez cette liste de contrôle avant et après avoir apporté des modifications au serveur d'API ou lors du diagnostic de problèmes. Chaque élément inclut le rôle responsable et la fréquence de révision.

Exécutez cette liste de contrôle au moins une fois par semaine dans les clusters de production. Consignez les résultats dans un journal partagé pour l'analyse des tendances. Lorsqu'un contrôle échoue, attribuez un responsable et une date d'échéance pour la remédiation.

Pièges courants

Même les opérateurs expérimentés font des erreurs avec le serveur d'API. Voici les pièges fréquents et comment les éviter.

Exécuter des commandes destructives avant d'observer

Il est tentant de redémarrer le serveur d'API ou de supprimer un pod pour résoudre un problème, mais cela peut masquer la cause profonde. Exécutez d'abord des diagnostics en lecture seule et capturez les journaux et les métriques. Ensuite seulement, faites un changement.

Ignorer les différences de version

Les indicateurs et les chemins de fichiers changent entre les versions de Kubernetes. Une commande d'un article de blog pour la version 1.18 peut ne pas fonctionner sur la 1.28. Consultez toujours la documentation officielle pour votre version spécifique.

Modifier les manifestes de pods statiques sans sauvegarde

Une faute de frappe dans le manifeste peut faire tomber le serveur d'API. Sans sauvegarde, la récupération est lente. Copiez toujours le manifeste vers un emplacement sûr avant de le modifier. Utilisez le contrôle de version pour les manifestes si possible.

Utiliser kubectl proxy sans restreindre l'accès

kubectl proxy expose le serveur d'API sur localhost par défaut, mais si vous le liez à 0.0.0.0 ou utilisez le transfert de port sans précaution, vous pourriez exposer votre cluster. Utilisez toujours la liaison localhost par défaut et fermez le proxy lorsque vous avez terminé.

Négliger l'expiration des certificats

Les certificats expirés sont une cause fréquente de défaillance soudaine du serveur d'API. Mettez en place une surveillance et des alertes pour l'expiration des certificats au moins 30 jours à l'avance. Automatisez le renouvellement lorsque c'est possible.

Webhooks d'admission mal configurés

Les webhooks d'admission peuvent casser silencieusement les déploiements s'ils sont en panne ou mal configurés. Testez toujours les changements de webhook dans un cluster de préproduction et ayez un plan de retour en arrière. Surveillez la latence et la disponibilité des webhooks.

Conclusion

Exploiter le serveur d'API Kubernetes exige un équilibre prudent entre observation et intervention. Avec les commandes de cet article, vous pouvez systématiquement vérifier la santé, inspecter la configuration, diagnostiquer les défaillances et récupérer en toute sécurité. Rappelez-vous de toujours commencer par des commandes en lecture seule, de sauvegarder avant les changements, de vérifier après les changements et de documenter les étapes de récupération.

Ensuite, choisissez une vérification à faible risque dans la liste de contrôle et exécutez-la dans votre cluster dès aujourd'hui. Enregistrez l'état actuel, comparez-le avec la sortie attendue et investiguez toute différence. Passez en revue vos politiques RBAC et les dates d'expiration des certificats prochainement. Une routine opérationnelle bien rodée rendra les incidents futurs moins stressants et plus rapides à résoudre.