kubectl edit, patch et replace : modifier des ressources Kubernetes

Vous devez modifier une ressource Kubernetes en production — vite, proprement, sans casser. Faut-il ouvrir un éditeur avec kubectl edit, envoyer un patch ciblé avec kubectl patch, ou remplacer l’objet depuis un fichier avec kubectl replace ? Ce guide vous aide à choisir la bonne commande selon le contexte, avec des recettes copier-coller prêtes pour la prod.

Ce que vous allez apprendre

À la fin de ce guide, vous saurez :

• Choisir entre edit, patch, replace et apply selon votre besoin (urgence, scriptabilité, traçabilité)
• Utiliser kubectl edit pour un hotfix en incident, en évitant le piège du drift non tracé
• Écrire des patches ciblés avec les 3 types (strategic merge, JSON merge, JSON patch) et savoir lequel choisir
• Remplacer une ressource complète avec kubectl replace, comprendre --force et ses risques
• Sécuriser toute modification en prod : snapshot avant, vérification après, rollback si nécessaire

Choisir la bonne commande

Avant de modifier quoi que ce soit, posez-vous cette question : est-ce un changement ponctuel d’urgence, un ajustement scriptable, ou une mise à jour complète du manifest ?

Besoin	Commande	Pourquoi
Hotfix manuel en incident	kubectl edit	Édition interactive via éditeur — immédiat, mais non tracé
Changement ciblé, scriptable, reproductible	kubectl patch	Mise à jour in-place d’un ou plusieurs champs sans toucher au reste
Remplacement complet depuis un fichier	kubectl replace -f	Soumet la spec entière — demande le YAML complet
Déclaratif standard (recommandé au quotidien)	kubectl apply -f	Gestion déclarative avec 3-way merge — voir le guide create et apply

Glissez pour voir

Règle générale

En dehors de l’urgence pure, préférez kubectl apply pour toute modification qui doit être tracée et reproductible. Les commandes de cette page sont des outils complémentaires pour des cas spécifiques.

3 recettes de prod à copier

Avant les explications détaillées, voici les commandes que vous utiliserez le plus souvent :

# 1) Changer l'image d'un conteneur (le plus courant)
kubectl set image deploy/mon-app mon-conteneur=nginx:1.27 -n prod

# 2) Patch ciblé : scaler à 5 réplicas (scriptable)
kubectl patch deploy mon-app -n prod \
  --type='json' -p='[{"op":"replace","path":"/spec/replicas","value":5}]'

# 3) Sauvegarder puis remplacer une ressource complète
kubectl get deploy mon-app -n prod -o yaml > mon-app-backup.yaml
# (modifier le fichier)
kubectl replace -f mon-app-backup.yaml

kubectl edit : l’outil d’incident

kubectl edit ouvre une ressource dans un éditeur de texte. Après sauvegarde et fermeture, Kubernetes applique automatiquement les changements. C’est rapide, mais non tracé : aucun fichier n’est commité, aucune PR n’est créée.

Quand l’utiliser

• Incident en cours : vous devez modifier quelque chose maintenant
• Exploration : vous voulez voir et modifier un objet rapidement en dev
• Jamais en routine : pour les changements planifiés, préférez apply -f depuis un fichier versionné

Syntaxe

kubectl edit <type> <nom> [-n namespace]

Comment kubectl choisit l’éditeur

kubectl cherche un éditeur dans cet ordre :

1. Variable KUBE_EDITOR (priorité maximale)
2. Variable EDITOR
3. Fallback : vi (Linux/macOS) ou notepad (Windows)

# Forcer un éditeur pour cette commande
KUBE_EDITOR="nano" kubectl edit deploy mon-app -n prod

# Ou définir une fois pour toutes dans votre shell
export KUBE_EDITOR="code --wait"   # VS Code
export KUBE_EDITOR="nano"          # nano

Le piège du drift : toujours snapshoter avant et après

Le danger de edit : la modification existe uniquement dans le cluster. Si quelqu’un refait kubectl apply -f depuis le repo Git, votre changement sera écrasé. C’est ce qu’on appelle le drift (divergence entre le cluster et la source de vérité).

1. Snapshotez l’état actuel avant la modification

   kubectl get deploy mon-app -n prod -o yaml > mon-app.before.yaml

2. Faites votre edit

   kubectl edit deploy mon-app -n prod

3. Exportez le résultat après modification

   kubectl get deploy mon-app -n prod -o yaml > mon-app.after.yaml

4. Reportez le changement dans votre repo Git

   Comparez les deux fichiers, intégrez la modification dans le manifest versionné, et créez une PR.

   diff mon-app.before.yaml mon-app.after.yaml

Drift = bombe à retardement

Toute modification faite via kubectl edit sans mise à jour du manifest Git sera perdue au prochain apply. C’est la cause numéro 1 des régressions en production. Reportez systématiquement vos changements dans le dépôt.

kubectl patch : le cœur de la modification ciblée

kubectl patch modifie un ou plusieurs champs d’une ressource sans toucher au reste. C’est la commande idéale pour les changements scriptables et reproductibles.

Syntaxe

kubectl patch <type> <nom> [-n namespace] --type=<type-patch> -p '<modification>'

Quel type de patch choisir ?

kubectl supporte 3 types de patch, chacun avec un comportement différent :

Type	Flag	Comportement	Usage
Strategic merge	--type=strategic (défaut)	Fusionne intelligemment les listes (ajoute au lieu de remplacer)	Ressources natives K8s — choix par défaut
JSON merge	--type=merge	Fusionne les objets, remplace les listes entièrement (RFC 7386)	Quand vous voulez remplacer une liste (et non y ajouter)
JSON patch	--type=json	Opérations explicites add/replace/remove sur des chemins précis (RFC 6902)	Maximum de contrôle, idéal pour les scripts

Glissez pour voir

CRD et strategic merge

Le strategic merge patch n’est pas supporté pour les Custom Resources (CRD) — elles n’ont pas les directives de merge intégrées aux types natifs. Utilisez --type=merge ou --type=json pour patcher des CRD.

Recettes de patches classiques en production

Changer l’image d’un conteneur

La façon la plus lisible pour changer une image est kubectl set image :

kubectl set image deploy/mon-app mon-conteneur=nginx:1.27 -n prod

L’équivalent en patch strategic (si vous avez besoin du format patch, pour un script par exemple) :

kubectl patch deploy mon-app -n prod -p \
  '{"spec":{"template":{"spec":{"containers":[{"name":"mon-conteneur","image":"nginx:1.27"}]}}}}'

Vérification :

kubectl get deploy mon-app -n prod -o jsonpath='{.spec.template.spec.containers[0].image}'
# nginx:1.27

Ajouter une annotation (ex: référence incident)

kubectl patch deploy mon-app -n prod -p \
  '{"metadata":{"annotations":{"incident-ref":"INC-2026-0142"}}}'

Modifier une variable d’environnement

Avec le patch JSON pour cibler précisément le conteneur et la variable :

# D'abord, trouvez l'index du conteneur et de la variable
kubectl get deploy mon-app -n prod -o jsonpath='{.spec.template.spec.containers[0].env}' | python3 -m json.tool

# Puis patchéz (ici : ajout d'une variable)
kubectl patch deploy mon-app -n prod --type='json' \
  -p='[{"op":"add","path":"/spec/template/spec/containers/0/env/-","value":{"name":"LOG_LEVEL","value":"debug"}}]'

Augmenter un timeout de probe

kubectl patch deploy mon-app -n prod --type='json' \
  -p='[{"op":"replace","path":"/spec/template/spec/containers/0/readinessProbe/timeoutSeconds","value":10}]'

Scaler le nombre de réplicas

kubectl patch deploy mon-app -n prod --type='json' \
  -p='[{"op":"replace","path":"/spec/replicas","value":5}]'

Trouver le chemin JSON exact

Avant de patcher, affichez la structure JSON de la ressource pour trouver le chemin exact :

kubectl get deploy mon-app -n prod -o json | less

Les chemins JSON patch utilisent la notation /spec/replicas (avec /, pas .). Les index de liste commencent à 0.

Comparer strategic merge et JSON merge

Pour comprendre la différence, imaginez que votre deployment a 2 conteneurs et que vous patchéz la liste containers :

Type de patch	Comportement sur la liste containers
Strategic merge	Ajoute ou met à jour le conteneur ciblé (par name), conserve les autres
JSON merge	Remplace toute la liste par celle du patch — les conteneurs non listés disparaissent
JSON patch	Opère sur un index précis (/containers/0) — contrôle total

Glissez pour voir

C’est pourquoi le strategic merge est le défaut pour les ressources natives : il évite de supprimer accidentellement des conteneurs, des volumes ou des ports.

kubectl replace : le remplacement complet

kubectl replace soumet une spec complète au serveur API. Contrairement à patch qui touche un champ, replace remplace tout l’objet tel que décrit dans le fichier.

Quand l’utiliser

• Vous avez un fichier YAML complet et vérié comme source de vérité
• Vous voulez appliquer un gros changement structurel d’un coup
• La ressource a été exportée, modifiée hors du cluster, et doit être réamorcée

Syntaxe

kubectl replace -f <fichier.yaml>

Workflow typique

1. Exportez la ressource actuelle

   kubectl get deploy mon-app -n prod -o yaml > mon-app.yaml

2. Modifiez le fichier YAML dans votre éditeur

3. Remplacez la ressource

   kubectl replace -f mon-app.yaml

4. Vérifiez le résultat

   kubectl get deploy mon-app -n prod
   kubectl describe deploy mon-app -n prod | tail -20

Champs immuables

Certains champs ne peuvent pas être modifiés après création (par ex. spec.selector d’un Deployment). Si replace échoue avec field is immutable, vous devrez supprimer et recréer la ressource — ce qui implique un downtime.

replace —force : delete + create (danger)

L’option --force supprime d’abord la ressource, puis la recrée à partir du fichier. C’est un delete + create sous le capot.

kubectl replace --force -f mon-app.yaml

Downtime garanti

replace --force supprime la ressource avant de la recréer. Pour un Deployment, cela signifie que tous les pods sont tués puis recréés — avec un downtime le temps de la recréation. Ne l’utilisez que si vous comprenez l’impact et que vous n’avez pas d’autre option (champs immuables à modifier).

replace vs apply : quelle différence ?

Critère	kubectl replace	kubectl apply
Ce qui est envoyé	La spec complète (tout le YAML)	Uniquement les champs modifiés (3-way merge)
Champs manuels conservés	Non — tout est remplacé	Oui — merge intelligent
Annotation last-applied	Non utilisée	Utilisée pour le merge
Idempotent	Non (échoue si l’objet n’existe pas)	Oui (crée ou met à jour)
Usage recommandé	Remplacement intégral contrôlé	Gestion déclarative quotidienne

Glissez pour voir

Avant toute modification en prod

Quelle que soit la commande, suivez cette checklist avant de modifier quoi que ce soit en production.

1. Vérifiez votre contexte et votre namespace

   kubectl config current-context
   # ⚠️ Êtes-vous bien sur le bon cluster ?

2. Identifiez précisément la ressource

   kubectl get deploy mon-app -n prod

3. Snapshotez l’état actuel

   kubectl get deploy mon-app -n prod -o yaml > mon-app.$(date +%F-%H%M).yaml

4. Faites la modification (edit, patch ou replace)

5. Vérifiez immédiatement le résultat

   kubectl get deploy mon-app -n prod
   kubectl rollout status deploy/mon-app -n prod

Rollback en cas de problème

Si la modification casse quelque chose :

• Pour un Deployment : utilisez le rollback natif

  # Voir l'historique des révisions
  kubectl rollout history deploy/mon-app -n prod
  
  # Revenir à la révision précédente
  kubectl rollout undo deploy/mon-app -n prod
  
  # Revenir à une révision spécifique
  kubectl rollout undo deploy/mon-app -n prod --to-revision=3

  Pour aller plus loin : voir le guide scale, autoscale et rollout.

• Pour les autres ressources : réappliquez le snapshot

  kubectl replace -f mon-app.2026-02-27-1430.yaml

Dépannage

Symptôme	Cause probable	Solution
error: no changes made (edit)	Aucune modification détectée à la sauvegarde	Vérifiez que vous avez bien modifié un champ et sauvegardé
error: the object has been modified	Quelqu’un a modifié la ressource entre votre lecture et votre écriture	Recommencez l’opération (edit ou replace)
field is immutable (replace)	Tentative de modifier un champ immuable (selector, volumeName…)	Supprimez et recréez la ressource, ou utilisez replace --force
error: cannot find path (patch JSON)	Le chemin JSON est incorrect	Vérifiez avec kubectl get <type> <nom> -o json
invalid JSON/YAML (patch)	Erreur de syntaxe dans le patch	Validez vos guillemets, crochets et accolades
Le patch ne change rien (strategic)	Le champ patché est identique à la valeur actuelle	Vérifiez la valeur avec kubectl get -o jsonpath='{...}'
Patch sur CRD échoue	Strategic merge non supporté pour les CRD	Utilisez --type=merge ou --type=json
Regression après edit	Quelqu’un a fait apply -f depuis Git et écrasé votre changement	Reportez toujours vos changements dans le repo Git

Glissez pour voir

À retenir

• kubectl edit est un outil d’urgence — modifiez en live, mais snapshotez avant et reportez dans Git après.
• kubectl patch est votre outil de modification ciblée — scriptable, reproductible, idéal pour l’automatisation.
• Les 3 types de patch : strategic merge (défaut, intelligent sur les listes), JSON merge (remplace les listes), JSON patch (opérations explicites add/replace/remove).
• Strategic merge patch ne fonctionne pas sur les CRD — utilisez --type=merge ou --type=json.
• kubectl replace remplace l’intégralité de l’objet — il exige la spec complète dans le fichier.
• replace --force = delete + create = downtime. À n’utiliser qu’en dernier recours.
• Avant toute modification en prod : vérifiez le contexte, snapshotez, modifiez, vérifiez, commitez.

Prochaines étapes

Créer et déployer avec create et apply L'approche déclarative standard pour gérer vos ressources au quotidien.

Scale, autoscale et rollout Mettre à l'échelle, gérer les mises à jour progressives et les rollbacks.

Diagnostiquer avec kubectl Runbook de diagnostic : get, describe, logs et top en situation d'incident.

Labels et annotations Ajouter et gérer les labels et annotations sur vos ressources.

Explorer l'API Kubernetes Trouver le bon type, la bonne apiVersion et les bons champs pour vos manifests.

×

📖 Voir la documentation →