kubectl et l'API

Pourquoi

Tout ce que fait Kubernetes passe par son API, et presque tout ce que vous ferez passera par kubectl, son client en ligne de commande. C'est l'outil que vous utiliserez chaque jour pour déployer, regarder, diagnostiquer. Mal compris, il est aussi la source d'incidents bien réels : une commande lancée sur le cluster de production alors qu'on se croyait sur la préproduction, un kubectl apply qui écrase la modification d'un collègue, un delete dans le mauvais namespace.

Cette leçon crée le cluster qui servira tout le cours, puis donne les bases solides : à quel cluster parle kubectl et sous quelle identité, comment l'API est organisée, et comment lire et modifier les objets sans surprise.

Les concepts

Le fichier kubeconfig

kubectl lit sa configuration dans un fichier appelé kubeconfig. Par défaut, c'est ~/.kube/config ; la variable d'environnement KUBECONFIG en désigne un autre (ou plusieurs, séparés par :, que kubectl fusionne), et l'option --kubeconfig en impose un pour une commande. Le fichier contient trois listes :

• des clusters : un nom, l'adresse du serveur d'API, le certificat de l'autorité qui l'a signé ;
• des utilisateurs (users) : un nom et des identifiants (certificat client, jeton, ou commande qui en produit un) ;
• des contextes : l'association d'un cluster, d'un utilisateur et éventuellement d'un namespace par défaut, sous un nom.

Le contexte courant (current-context) désigne celui qu'utilise chaque commande kubectl. C'est la ligne la plus importante du fichier : changer de contexte, c'est changer de cluster ou d'identité.

La structure d'un objet

La leçon 1 a montré un premier manifeste. La documentation pose la règle : tout objet décrit dans un manifeste a quatre champs de premier niveau.

S'y ajoute status, l'état observé, que vous n'écrivez jamais : les composants du cluster le remplissent. Quelques objets n'ont pas de spec (un ConfigMap a data), mais le principe reste.

Groupes, versions et ressources

L'API est découpée en groupes, chacun avec ses versions :

• le groupe principal (core), historique, qui n'a pas de nom : son apiVersion s'écrit simplement v1 (Pod, Service, ConfigMap, Secret, Namespace) ;
• des groupes nommés : apps/v1 (Deployment, ReplicaSet, DaemonSet, StatefulSet), batch/v1 (Job, CronJob), networking.k8s.io/v1 (Ingress, NetworkPolicy), rbac.authorization.k8s.io/v1...

Une version v1 est stable ; v1beta1 est en bêta, v1alpha1 expérimentale et désactivée par défaut. Les versions bêta finissent par disparaître au profit de la stable, ce qui casse les manifestes qui les utilisent encore : c'est la principale chose à vérifier avant une montée de version du cluster.

Côté HTTP, chaque type correspond à une ressource au pluriel, avec un chemin : les Deployments du namespace signalements sont sous /apis/apps/v1/namespaces/signalements/deployments, les Pods sous /api/v1/namespaces/signalements/pods. On agit sur une ressource par des verbes : get, list, watch, create, update, patch, delete. Ce sont aussi les mots que l'on retrouve dans les règles d'autorisation (cours Sécurité de Kubernetes).

Les namespaces Kubernetes

Un namespace Kubernetes est un espace de noms logique : deux objets peuvent porter le même nom dans deux namespaces différents. Il sert à ranger (une application, une équipe, un environnement), à attribuer des droits et à limiter des ressources par namespace. Le mot est le même que pour les espaces de noms du noyau Linux vus dans le cours Docker, mais l'objet n'a rien à voir : un namespace Kubernetes n'isole pas le réseau ni les processus. Deux Pods de deux namespaces peuvent se parler par défaut.

Un cluster neuf contient au moins default, kube-system (les composants du système, leçon 2), kube-public et kube-node-lease (les signaux de vie des nœuds). Certains objets n'appartiennent à aucun namespace : les nœuds, les namespaces eux-mêmes, les classes de stockage.

Étiquettes et annotations

Les étiquettes (labels) sont des paires clé-valeur attachées aux objets, faites pour être sélectionnées. C'est par elles qu'un Deployment reconnaît ses Pods, qu'un Service trouve les Pods vers lesquels envoyer le trafic, et que vous filtrez vos commandes. La documentation recommande un jeu d'étiquettes communes, préfixées par app.kubernetes.io/ : name, instance, version, component, part-of, managed-by.

Les annotations sont aussi des paires clé-valeur, mais non sélectionnables : elles portent des informations destinées aux outils ou aux humains (un lien vers le dépôt, une configuration pour un contrôleur, la date d'un déploiement). Argo CD, par exemple, en pose pour suivre les objets qu'il gère.

Impératif et déclaratif

kubectl permet deux styles :

• impératif : kubectl create deployment, kubectl scale, kubectl set image, kubectl delete. Chaque commande est un ordre. Pratique pour explorer, dangereux pour gérer : l'état du cluster n'est écrit nulle part ;
• déclaratif : kubectl apply -f fichier.yaml. Vous donnez l'état voulu complet ; kubectl calcule ce qui change. Les fichiers se versionnent et se relisent : c'est la façon de travailler de ce cours.

kubectl apply existe en deux variantes. L'apply côté client, historique et encore utilisé par défaut, calcule la différence sur votre poste à partir d'une annotation kubectl.kubernetes.io/last-applied-configuration posée sur l'objet. L'apply côté serveur (server-side apply, stable depuis Kubernetes 1.22) confie ce calcul au serveur d'API, qui suit qui possède chaque champ dans metadata.managedFields. Quand deux gestionnaires (vous, un contrôleur, Argo CD) veulent écrire le même champ avec des valeurs différentes, l'apply côté serveur signale un conflit au lieu d'écraser en silence.

En pratique

Installer kind et créer le cluster

kind se télécharge en un seul binaire, publié avec sa somme de contrôle sur la page des versions du projet :

$ curl -Lo kind https://kind.sigs.k8s.io/dl/v0.33.0/kind-linux-amd64
$ curl -Lo kind.sha256sum https://github.com/kubernetes-sigs/kind/releases/download/v0.33.0/kind-linux-amd64.sha256sum
$ sha256sum --check <(sed 's/kind-linux-amd64/kind/' kind.sha256sum)
$ chmod +x kind && sudo mv kind /usr/local/bin/kind

La commande sed adapte le nom de fichier inscrit dans la somme de contrôle au nom sous lequel vous avez enregistré le binaire ; sha256sum doit répondre kind: OK. Sur un processeur ARM, remplacez amd64 par arm64.

Décrivez le cluster dans un fichier kind-formation.yaml : un nœud de plan de contrôle et deux nœuds de travail, pour que l'ordonnanceur ait le choix.

kind: Cluster
apiVersion: kind.x-k8s.io/v1alpha4
name: formation
nodes:
- role: control-plane
- role: worker
- role: worker

Puis créez le cluster dans un kubeconfig dédié :

$ mkdir -p ~/k8s-formation && cd ~/k8s-formation
$ export KUBECONFIG=$PWD/kubeconfig
$ NOEUD=kindest/node:v1.36.4@sha256:099e049362a1526b2db71494e1947aae99bd16290d7c895f2b7ea312e3cbfaed
$ kind create cluster --config kind-formation.yaml --image "$NOEUD" --kubeconfig "$KUBECONFIG" --wait 120s

• --image épingle l'image de nœud sur Kubernetes 1.36.4, par son empreinte, comme le demandent les notes de version de kind 0.33. Sans elle, kind 0.33 crée un cluster 1.37.0, sa version par défaut, que votre kubectl 1.36 sait aussi piloter (écart d'une version mineure), mais qui n'est pas celle du cours.
• --kubeconfig et KUBECONFIG isolent le cluster de formation de vos autres clusters. La fiche kind et la leçon 1 du cours GitOps détaillent le piège : sans ces options, kind ajoute le cluster à ~/.kube/config et en fait le contexte courant.
• --wait 120s attend que le plan de contrôle soit prêt.

Le contexte créé s'appelle kind-formation (kind préfixe toujours le nom du cluster par kind-). Vérifiez :

$ kubectl config current-context
$ kubectl cluster-info
$ kubectl get nodes

cluster-info affiche l'adresse du serveur d'API (une adresse locale, https://127.0.0.1:<port>) et celle de CoreDNS. get nodes doit lister trois nœuds à l'état Ready : formation-control-plane, formation-worker et formation-worker2. Pensez à exporter KUBECONFIG dans chaque nouveau terminal.

Lire et modifier un kubeconfig

Plutôt que d'éditer le fichier à la main, kubectl config le manipule. Pour voir comment il est construit, fabriquons-en un de toutes pièces, dans un fichier d'essai qui ne pointe vers aucun cluster réel :

$ export KUBECONFIG=$PWD/kubeconfig-essai
$ kubectl config set-cluster formation --server=https://127.0.0.1:6443
Cluster "formation" set.
$ kubectl config set-credentials camille --token=jeton-d-exemple
User "camille" set.
$ kubectl config set-context formation --cluster=formation --user=camille --namespace=signalements
Context "formation" created.
$ kubectl config use-context formation
Switched to context "formation".
$ kubectl config get-contexts
CURRENT   NAME        CLUSTER     AUTHINFO   NAMESPACE
*         formation   formation   camille    signalements

Ces sorties sont réelles. Le fichier obtenu :

$ kubectl config view
apiVersion: v1
clusters:
- cluster:
    server: https://127.0.0.1:6443
  name: formation
contexts:
- context:
    cluster: formation
    namespace: signalements
    user: camille
  name: formation
current-context: formation
kind: Config
users:
- name: camille
  user:
    token: REDACTED

Remarquez token: REDACTED : kubectl config view masque les secrets. kubectl config view --raw les affiche, ce qui est précisément ce qu'il ne faut pas faire dans un terminal partagé. Le fichier a été créé avec les droits 600 (lecture et écriture pour vous seul).

Deux commandes reviennent tous les jours :

$ kubectl config set-context --current --namespace=signalements
$ kubectl config view --minify -o jsonpath='{.contexts[0].context.namespace}'

La première change le namespace par défaut du contexte courant : les commandes suivantes s'y appliqueront sans -n. La seconde l'affiche (--minify réduit la vue au contexte courant). Revenez ensuite au kubeconfig du cluster : export KUBECONFIG=$PWD/kubeconfig.

Explorer l'API

$ kubectl api-resources
$ kubectl api-resources --api-group=apps
$ kubectl api-resources --namespaced=false
$ kubectl explain deployment.spec.strategy
$ kubectl explain pod.spec.containers --recursive | less

• api-resources liste chaque ressource : son nom, ses abréviations (deploy, svc, cm, ns, po), son groupe et sa version, si elle appartient à un namespace, et son kind. La deuxième commande filtre un groupe, la troisième ne garde que les ressources hors namespace (nœuds, namespaces...).
• explain affiche la documentation de chaque champ, tirée du schéma que publie le serveur : c'est la référence la plus fiable, puisqu'elle correspond exactement à la version de votre cluster. --recursive montre toute l'arborescence.

Créer un namespace et appliquer le Deployment

$ kubectl create namespace signalements
$ kubectl config set-context --current --namespace=signalements
$ kubectl apply -f signalements-deployment.yaml
deployment.apps/signalements created

La dernière ligne est celle que kubectl affiche pour une création. Le fichier est celui de la leçon 1 ; il ne précise pas de namespace, donc l'objet est créé dans celui du contexte.

Lire : get, formats de sortie, describe

$ kubectl get deployments
$ kubectl get pods -o wide
$ kubectl get deployment signalements -o yaml
$ kubectl describe deployment signalements

• get affiche un tableau court. Pour les Pods : nom, conteneurs prêts sur total (READY), état (STATUS), nombre de redémarrages, âge. -o wide ajoute l'adresse IP du Pod et son nœud : vous devez voir les deux Pods sur deux nœuds différents, ou sur le même, selon les choix de l'ordonnanceur.
• -o yaml affiche l'objet complet tel que le serveur le connaît : votre spec, complétée par toutes les valeurs par défaut, plus metadata remplie par le système et status. Comparez avec votre fichier : la différence montre tout ce que Kubernetes a décidé pour vous.
• describe présente l'objet de façon lisible, avec les événements récents qui le concernent : c'est le premier réflexe de diagnostic (leçon 12).

Les formats de sortie permettent d'extraire exactement ce que l'on veut, sans grep fragile :

$ kubectl get pods -o name
$ kubectl get deployment signalements -o jsonpath='{.spec.template.spec.containers[0].image}{"\n"}'
$ kubectl get pods -o custom-columns=NOM:.metadata.name,NOEUD:.spec.nodeName,IP:.status.podIP
$ kubectl get deployment signalements -o kyaml

Le format KYAML est un sous-ensemble strict de YAML, introduit en alpha dans Kubernetes 1.34 et activé par défaut depuis la 1.35 : chaînes toujours entre guillemets, accolades et crochets explicites, indentation sans importance. Il évite des pièges classiques de YAML, comme la valeur NO lue comme un booléen. Voici le début d'une sortie réelle, produite sans cluster à partir d'un objet généré :

$ kubectl create deployment signalements --image=ghcr.io/lyneko-formation/signalements:1.2.0 \
    --dry-run=client -o kyaml
---
{
  kind: "Deployment",
  apiVersion: "apps/v1",
  metadata: {
    name: "signalements",
    labels: {
      app: "signalements",
    },
  },
  spec: {
    replicas: 1,

Modifier : apply, diff, dry-run

Modifiez signalements-deployment.yaml pour passer à trois exemplaires (replicas: 3). Avant d'appliquer, regardez ce qui va changer :

$ kubectl diff -f signalements-deployment.yaml
$ kubectl apply -f signalements-deployment.yaml --dry-run=server
$ kubectl apply -f signalements-deployment.yaml
deployment.apps/signalements configured

• kubectl diff envoie le manifeste au serveur en mode simulation et affiche la différence avec l'objet réel, au format diff -u. Il sort avec le code 1 s'il y a une différence, 0 sinon : utilisable en intégration continue.
• --dry-run=server fait passer la requête par toutes les étapes du serveur (authentification, autorisation, admission, validation) sans l'enregistrer. Il détecte bien plus d'erreurs que --dry-run=client, qui ne fait que générer l'objet localement.
• configured remplace created : l'objet existait, il a été mis à jour.

Pour essayer l'apply côté serveur :

$ kubectl apply -f signalements-deployment.yaml --server-side
$ kubectl get deployment signalements -o yaml --show-managed-fields | less

Les gestionnaires de champs apparaissent dans managedFields : votre kubectl, et le contrôleur qui écrit le statut. Faites ensuite kubectl scale deployment signalements --replicas=4 (une commande impérative, qui devient gestionnaire du champ replicas), puis réappliquez le fichier avec --server-side : le serveur signale un conflit sur .spec.replicas au lieu d'écraser. Vous choisissez alors : retirer le champ de votre fichier, ou forcer avec --force-conflicts et en reprendre la propriété.

Étiquettes et sélecteurs

$ kubectl get pods --show-labels
$ kubectl get pods -l app=signalements
$ kubectl label deployment signalements app.kubernetes.io/part-of=signalements
$ kubectl get deployments -l 'app.kubernetes.io/part-of in (signalements, vignettes)'
$ kubectl annotate deployment signalements lyneko.com/depot=https://github.com/lyneko-formation/signalements

• -l (ou --selector) filtre par étiquettes, avec égalité (=, !=) ou ensembles (in, notin, existence d'une clé).
• kubectl label et kubectl annotate ajoutent une étiquette ou une annotation à la volée. Utile pour explorer ; dans la durée, elles doivent être dans le manifeste, sinon le prochain apply ne les connaît pas.

kubectl label sait aussi travailler sans cluster, sur un fichier, avec --local. La sortie suivante est réelle :

$ kubectl label --local -f signalements-deployment.yaml niveau=formation -o yaml | head -8
apiVersion: apps/v1
kind: Deployment
metadata:
  labels:
    app: signalements
    niveau: formation
  name: signalements
  namespace: signalements

(Le fichier utilisé ici avait été généré avec -n signalements, d'où la ligne namespace.)

Confort : complétion et alias

$ source <(kubectl completion bash)
$ echo 'source <(kubectl completion bash)' >> ~/.bashrc
$ alias k=kubectl
$ complete -o default -F __start_kubectl k

La complétion complète les commandes, les types et même les noms d'objets du cluster courant. L'alias k est universel dans les équipes. Les extensions de kubectl (plugins) se gèrent avec krew ; deux sont très répandues pour changer de contexte et de namespace (kubectx et kubens), mais commencez sans, pour bien connaître kubectl config.

Sous le capot

kubectl n'est qu'un client HTTP. L'option -v augmente la verbosité ; à partir de -v=6, kubectl affiche chaque requête et son code de réponse, et -v=8 le contenu des réponses. Essayez kubectl get pods -v=6 : vous verrez le GET sur /api/v1/namespaces/signalements/pods, exactement le chemin décrit plus haut, et ce qu'un Argo CD ou un contrôleur fait de la même façon.

Comment apply décide ce qui change. Avec l'apply côté client, kubectl compare trois versions : le fichier, l'objet vivant, et la dernière configuration appliquée qu'il a rangée dans l'annotation. C'est ce qui lui permet de savoir qu'un champ retiré du fichier doit être retiré de l'objet, et non pas qu'il a été ajouté par quelqu'un d'autre. Avec l'apply côté serveur, cette connaissance est dans managedFields, par gestionnaire et par champ, et le calcul se fait sur le serveur : deux outils différents (votre pipeline, Argo CD, un opérateur) peuvent ainsi gérer chacun leurs champs d'un même objet sans s'écraser.

Pourquoi --dry-run=server est précieux. Le serveur exécute les contrôleurs d'admission, les valeurs par défaut et la validation complète, puis jette le résultat. Un manifeste qui passe --dry-run=server passera l'apply, sauf changement entre-temps.

Pièges courants

Le mauvais contexte. C'est l'incident le plus classique : une commande destinée à la préproduction lancée sur la production. Parades : un fichier kubeconfig par cluster et KUBECONFIG explicite, le contexte affiché dans l'invite du shell, des droits en lecture seule par défaut sur la production, et kubectl config current-context avant toute commande destructrice.

Le mauvais namespace. Sans -n, une commande vise le namespace du contexte, default le plus souvent. Un kubectl apply sans namespace dans le fichier crée alors l'application au mauvais endroit. Mettez le namespace dans les manifestes, ou fixez-le explicitement.

Mélanger impératif et déclaratif. Un kubectl scale ou un kubectl edit modifie l'objet ; le fichier versionné ne le sait pas, et le prochain apply annule le changement (ou, avec l'apply côté serveur, signale un conflit). Dans une équipe, le fichier est la vérité.

Un kubectl trop éloigné du cluster. Le cluster par défaut de kind 0.33 est en 1.37 : avec un kubectl 1.36, ça fonctionne (une version d'écart), avec un kubectl 1.34, non garanti.

Une version d'API retirée. Un manifeste en extensions/v1beta1 ou en policy/v1beta1 est refusé par un cluster récent. kubectl explain et kubectl api-resources disent quelles versions votre cluster sert.

Sécurité

• Le kubeconfig est une clé. Celui de kind contient un certificat client d'administrateur du cluster, qui donne tous les droits. Un kubeconfig de production le plus souvent aussi, ou un jeton. Droits 600, jamais dans un dépôt Git, jamais copié dans un ticket ; kubectl config view masque les secrets, --raw les montre.
• Une identité par personne et par outil. Partager le certificat d'administrateur interdit de savoir qui a fait quoi. Sur un cluster managé, préférez l'authentification par le fournisseur (identité IAM) ou par un fournisseur d'identité, avec des droits limités par namespace (cours Sécurité de Kubernetes).
• Les plugins sont du code exécuté avec vos droits. Un plugin kubectl installé depuis Internet utilise votre kubeconfig : installez-les depuis des sources fiables.
• -v=8 et plus affichent les échanges, dont parfois des en-têtes d'authentification : ne collez pas ces sorties sans les relire.

En production

• Un kubeconfig par cluster, et un contexte clairement nommé (prod-lyneko-apps, pas admin@cluster). Chez Scaleway, la CLI sait produire le kubeconfig d'un cluster Kapsule (scw k8s kubeconfig), détaillé dans le cours Kapsule.
• Les humains lisent, les pipelines écrivent. En production, les droits d'écriture vont à l'outil de déploiement (Argo CD chez Lyneko), et les personnes ont surtout un accès en lecture, avec une procédure pour les interventions.
• kubectl diff en intégration continue sur chaque demande de fusion qui touche des manifestes, et --dry-run=server comme garde-fou avant un apply.
• Des étiquettes communes (app.kubernetes.io/...) sur tous les objets : elles servent aux sélecteurs, aux tableaux de bord, à la facturation par équipe.

Exercices

1. Deux clusters (niveau 100). Créez un second cluster kind essai, d'un seul nœud, dans un autre fichier kubeconfig. Montrez comment lancer kubectl get nodes sur chacun des deux clusters sans jamais modifier la variable KUBECONFIG exportée. Supprimez ensuite le cluster essai.

2. Que décide Kubernetes ? (niveau 100). Comparez votre fichier signalements-deployment.yaml avec kubectl get deployment signalements -o yaml. Citez trois champs de spec que Kubernetes a remplis par défaut, et deux champs de metadata remplis par le système.

3. Le conflit (niveau 100). Reproduisez le conflit de l'apply côté serveur décrit dans la leçon. Quel message obtenez-vous, et quelles sont les deux façons d'en sortir ? Laquelle est la bonne si le nombre d'exemplaires doit être géré par une mise à l'échelle automatique ?

4. Sélecteurs (niveau 100). Écrivez les commandes qui listent : (a) tous les Pods du cluster qui ont l'étiquette app=signalements, tous namespaces confondus ; (b) les Deployments qui n'ont pas d'étiquette app.kubernetes.io/part-of ; (c) le nom et le nœud de chaque Pod du namespace kube-system, en deux colonnes.

Récapitulatif

• kubectl lit un kubeconfig (~/.kube/config, KUBECONFIG, --kubeconfig) qui associe clusters, utilisateurs et contextes ; le contexte courant décide du cluster, de l'identité et du namespace par défaut.
• kind crée le cluster du cours, épinglé sur kindest/node:v1.36.4 par son empreinte, dans un kubeconfig dédié ; le contexte s'appelle kind-formation.
• Un objet a apiVersion, kind, metadata, spec (écrit par vous) et status (écrit par le système).
• L'API se découpe en groupes (v1 pour le groupe principal, apps/v1, batch/v1...), versions (alpha, bêta, stable) et ressources sur lesquelles on applique des verbes.
• Un namespace Kubernetes range et sert de frontière de droits et de quotas ; il n'isole pas le réseau.
• Les étiquettes se sélectionnent (-l), les annotations non.
• get (avec -o wide|yaml|json|jsonpath|custom-columns|name|kyaml), describe (avec les événements), explain (la documentation du schéma).
• Déclaratif : apply -f, précédé de diff et de --dry-run=server. L'apply côté serveur suit la propriété des champs et signale les conflits.
• Le kubeconfig de kind contient un certificat d'administrateur : c'est un secret.

Pour aller plus loin

• La page Organizing Cluster Access Using kubeconfig Files de la documentation, pour la fusion de plusieurs fichiers.
• La page Server-Side Apply, pour le détail de la propriété des champs et de la résolution des conflits.
• La kubectl Quick Reference, à garder à portée de main.
• La leçon suivante, qui s'intéresse à l'unité de base de Kubernetes : le Pod.