Kubernetes 002 – Architecture : declaratif vs imperatif

TL;DR

L’imperatif consiste a dire a Kubernetes quoi faire maintenant. Le declaratif consiste a decrire l’etat final attendu. Kubernetes est construit pour fonctionner autour de cette seconde approche: les objets sont stockes dans l’API, puis des controleurs travaillent en continu pour respecter cet etat.

La video de reference

Video: https://www.youtube.com/watch?v=56i8lXmAtUw

Cet episode prepare directement les usages de kubectl, des manifests et des objets comme Pod ou ReplicaSet.

Imperatif: pratique pour apprendre

Une commande imperative est directe:

kubectl run nginx --image=nginx
kubectl delete pod nginx

Elle est utile pour decouvrir, tester rapidement ou diagnostiquer. Le probleme apparait quand il faut rejouer la meme action, la relire en equipe ou l’integrer a une chaine GitOps.

Declaratif: le modele Kubernetes naturel

Avec le declaratif, on ecrit un fichier YAML qui represente l’etat souhaite:

apiVersion: v1
kind: Pod
metadata:
  name: nginx
spec:
  containers:
    - name: nginx
      image: nginx

Puis on applique:

kubectl apply -f pod.yaml

Le fichier devient une source de verite lisible, versionnable et partageable.

Pourquoi l’architecture pousse vers le declaratif

Kubernetes fonctionne par reconciliation. Les controleurs comparent l’etat desire et l’etat observe. Si un pod manque, il est recree. Si un objet change, les controleurs reagissent. Cette boucle permanente donne tout son sens au declaratif.

Quand utiliser chaque approche ?

| Approche | Usage naturel |

|---|---|

| Imperatif | apprentissage, test rapide, debug |

| Declaratif | configuration durable, collaboration, automatisation |

| Mixte | generer un YAML avec `--dry-run=client -o yaml`, puis le versionner |

Liens utiles

• Video: https://www.youtube.com/watch?v=56i8lXmAtUw
• Gestion declarative des objets: https://kubernetes.io/docs/tasks/manage-kubernetes-objects/declarative-config/
• Commandes imperatives: https://kubernetes.io/docs/tasks/manage-kubernetes-objects/imperative-command/
• Kubectl reference: https://kubernetes.io/docs/reference/kubectl/

FAQ

Peut-on tout faire en imperatif ?

Techniquement beaucoup de choses, mais ce n’est pas ideal pour la maintenance. Le declaratif est plus robuste pour un vrai projet.

Pourquoi les fichiers YAML sont-ils partout dans Kubernetes ?

Parce qu’ils representent les objets de l’API Kubernetes et peuvent etre versionnes dans Git.

kubectl apply est-il toujours preferable ?

Pour des ressources suivies dans le temps, oui. Pour un test ponctuel, une commande imperative reste pratique.

Le piege des commandes qui marchent une fois

Le mode imperatif donne une sensation de vitesse. On tape une commande, l’objet apparait, on continue. Le probleme arrive quand il faut expliquer ce qui a ete fait, reproduire l’environnement ou corriger une option oubliee. L’historique shell n’est pas une documentation fiable, et il n’est pas partage par toute l’equipe.

Le declaratif resout ce probleme en deplacant la connaissance dans des fichiers. Un manifest dit: voila l’objet attendu. Il peut etre relu en revue de code, teste dans un environnement de lab, compare entre branches et applique automatiquement par une chaine CI/CD ou GitOps.

Comprendre create, apply et replace

Trois verbes reviennent souvent:

kubectl create -f objet.yaml
kubectl apply -f objet.yaml
kubectl replace -f objet.yaml

create cree un objet qui n’existe pas encore. replace remplace une ressource existante par la definition fournie. apply est plus adapte a une gestion declarative continue: Kubernetes garde une logique de mise a jour autour de l’etat souhaite. Pour une formation, apply est souvent le meilleur reflexe quand on travaille avec des manifests.

Generer un YAML pour apprendre

Un bon compromis consiste a utiliser l’imperatif comme generateur de base, puis a basculer vers le declaratif:

kubectl run nginx --image=nginx --dry-run=client -o yaml > pod.yaml
kubectl apply -f pod.yaml

Ensuite, on ouvre pod.yaml, on lit les champs, on supprime ce qui n’est pas necessaire et on comprend progressivement la structure.

Erreurs frequentes

• Appliquer du YAML sans regarder le kind et l’apiVersion.
• Modifier un objet a la main avec kubectl edit, puis oublier de reporter le changement dans Git.
• Confondre le manifest souhaite et l’objet enrichi retourne par l’API.
• Melanger commandes imperatives en production et manifests declaratifs sans discipline.

A retenir

L’imperatif est utile pour apprendre et depanner. Le declaratif est indispensable pour construire une pratique durable. Kubernetes a ete concu autour de l’etat souhaite; plus on avance dans la serie, plus cette idee devient centrale.

Lire un manifest comme une intention

Un manifest Kubernetes doit etre lu comme une intention, pas comme un script. Il ne dit pas toujours exactement quelles commandes seront executees, ni dans quel ordre tous les composants internes vont agir. Il decrit un objet attendu dans l’API.

Cette nuance est essentielle. Quand on applique un manifest, kubectl transmet l’objet a l’API Server. Ensuite, les controleurs concernes observent cet objet et font leur travail. Un Deployment cree ou met a jour un ReplicaSet. Un ReplicaSet maintient des pods. Un Service selectionne des endpoints a partir de labels.

Pourquoi Git fonctionne bien avec le declaratif

Le declaratif se marie naturellement avec Git. Les fichiers peuvent etre relus, compares, commentes, valides et appliques par une chaine automatique. On peut savoir qui a change une image, une variable d’environnement, un nombre de replicas ou une limite de ressources.

Sans fichiers declaratifs, il devient difficile de reconstituer l’etat voulu. Une commande lancee un jour dans un terminal n’est pas une source de verite suffisante pour une equipe.

Attention aux modifications directes

kubectl edit est pratique, mais il peut creer un ecart entre ce qui tourne et ce qui est versionne. Si une correction faite a chaud n’est pas reportee dans les manifests, elle risque de disparaitre au prochain deploiement.

Une bonne pratique consiste a distinguer clairement:

• les tests rapides en lab;
• les corrections d’urgence documentees;
• les manifests sources suivis dans Git;
• les changements appliques automatiquement par CI/CD ou GitOps.

Le probleme n’est pas l’outil, mais l’absence de discipline entre imperatif et declaratif.

Petit exercice de comparaison

Pour comprendre la difference, creez un pod de deux manieres:

kubectl run imperatif --image=nginx
kubectl run declaratif --image=nginx --dry-run=client -o yaml > declaratif.yaml
kubectl apply -f declaratif.yaml

Puis comparez ce que vous pouvez relire le lendemain. Le pod imperatif existe peut-etre encore, mais la commande exacte est deja moins visible. Le manifest, lui, reste une trace claire et partageable.

Notions et definitions

• API Server: porte d’entree de toutes les operations Kubernetes.
• Objet declaratif: document qui decrit l’etat voulu plutot qu’une suite d’actions imperatives.
• Controleur: composant qui agit pour rapprocher le reel du desire.

Ces definitions donnent le vocabulaire minimal pour suivre l’article sans reduire Kubernetes a une simple commande. Chaque notion doit etre reliee a un objet visible avec kubectl ou a un composant du cluster.

Exemple concret

Un manifest Deployment ne dit pas comment creer chaque pod pas a pas; il declare le resultat attendu, et Kubernetes se charge de converger vers cet etat.

Cet exemple sert de fil conducteur: il montre quel probleme operationnel Kubernetes cherche a resoudre et quelle ressource permet de le formaliser.

How-to rapide

• Explorer le schema de l’objet avec kubectl explain.
• Creer l’objet declarativement avec kubectl apply -f.
• Observer status, conditions et events.
• Modifier le YAML puis reappliquer pour comprendre la reconciliation.

Le how-to est volontairement court: l’idee est d’obtenir un resultat observable, puis d’utiliser les commandes de verification pour comprendre ce qui s’est passe.

Approfondir cet article

Cet episode doit surtout permettre de maitriser le modele mental Kubernetes: API declarative, etat desire, controleurs et observation continue du cluster. L’objectif n’est pas seulement de refaire les commandes, mais de comprendre quel objet Kubernetes est cree, quel composant le prend en charge et comment verifier le resultat.

Questions a se poser

• Quel est l’etat desire exprime dans Kubernetes ?
• Quel composant observe cet etat et tente de le reconciler ?
• Quels symptomes montrent que l’objet est cree mais pas encore operationnel ?
• Quelle commande donne l’information la plus fiable pour diagnostiquer ?

Commandes de verification

• kubectl api-resources pour lister les objets disponibles
• kubectl explain <ressource> pour comprendre le schema d’un objet
• kubectl get events --sort-by=.lastTimestamp pour suivre ce que le cluster decide

Ces commandes ne sont pas a apprendre par coeur. Elles servent a construire un reflexe: partir de l’objet Kubernetes, lire son etat, puis descendre vers les pods, les events, les logs ou le noeud uniquement si c’est necessaire.

Points de vigilance

• voir Kubernetes comme une suite de commandes au lieu d’une API d’etat
• oublier la difference entre creer un objet et obtenir un workload fonctionnel
• ne pas regarder les events et les conditions avant de chercher trop loin

Exercice conseille

Prenez un objet simple, creez-le en imperatif, exportez son YAML, supprimez-le, puis recréez-le en declaratif pour comparer les deux approches.

Pour valider la comprehension, gardez une trace courte: manifest utilise, commandes lancees, resultat attendu, resultat observe et correction appliquee. Cette methode rend les episodes suivants beaucoup plus faciles a enchainer.

Lien interne conseille

Pour poursuivre la progression, consultez aussi Kubernetes 003 – Schema de l’architecture : comment ca marche ?.

Conclusion

Ce chapitre est fondamental: comprendre la difference entre imperatif et declaratif, c’est comprendre le coeur de Kubernetes. Les episodes suivants deviennent alors plus clairs, car chaque objet est une declaration que le cluster va tenter de respecter.