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. Elles supposent un Deployment nommé mon-app dans le namespace prod : adaptez ces deux valeurs, le reste fonctionne tel quel. Chacune illustre l'une des trois approches détaillées ensuite, du plus simple au plus complet.

# 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

Le critère de décision est le délai, pas la complexité du changement : edit se justifie quand écrire un fichier et ouvrir une PR coûte plus cher que l'incident en cours.

• 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

Sans -n, kubectl travaille sur le namespace du contexte courant, ce qui est la source d'erreur la plus fréquente sur cette commande. Précisez-le toujours en production.

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

Un changement non reporté sera écrasé

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 : la modification ciblée et scriptable

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

Le contenu passé à -p doit être entouré de guillemets simples : il contient des guillemets doubles JSON que le shell interpréterait autrement. Si --type est omis, kubectl applique un strategic merge patch.

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

Les cinq recettes ci-dessous couvrent la quasi-totalité des patches passés en incident. Elles n'utilisent pas toutes le même type de patch, et ce n'est pas un hasard : le strategic merge suffit quand on désigne un élément par son nom, alors que le JSON patch devient nécessaire dès qu'il faut viser un index de liste ou ajouter un élément en fin de tableau. Toutes s'appliquent sur un Deployment et déclenchent un redéploiement progressif des pods.

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)

Le strategic merge patch est ici le bon choix : il ajoute la clé sans effacer les annotations déjà présentes, et il évite d'avoir à échapper les / que contiennent souvent les clés d'annotation.

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 patchez (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

L'opération replace du JSON patch échoue si le chemin n'existe pas : la readinessProbe doit déjà être déclarée avec un timeoutSeconds. Pour créer le champ, utilisez add à la place.

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

Ce patch fait le même travail que kubectl scale, avec l'avantage d'être exprimé dans le même format que les autres patches d'un script. Si un HorizontalPodAutoscaler pilote ce Deployment, il ramènera le nombre de réplicas à sa propre décision peu après.

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

Prenons un deployment qui déclare 2 conteneurs, et un patch qui ne mentionne que l'un des deux dans 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

Le point commun de ces trois situations : vous détenez déjà le manifest complet et souhaitez qu'il fasse autorité sur l'état du cluster, y compris pour les champs que vous n'avez pas modifiés.

• Vous avez un fichier YAML complet et vérifié 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

La ressource doit déjà exister : contrairement à apply, replace ne crée rien et échoue si l'objet est absent. Le namespace provient du champ metadata.namespace du fichier lorsqu'il est renseigné, d'où l'intérêt d'exporter le manifest depuis le cluster plutôt que de le réécrire.

kubectl replace -f <fichier.yaml>

Workflow typique

Ce déroulé produit au passage une sauvegarde exploitable : le fichier exporté à l'étape 1, conservé avant modification, est exactement ce qu'il vous faudra pour revenir en arrière. Ne sautez pas l'étape de vérification, replace peut réussir tout en cassant le déploiement si un champ obligatoire a disparu du fichier.

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. Il s'agit littéralement d'un delete suivi d'un create, pas d'une mise à jour.

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 ?

La distinction se résume à ce qui part sur le réseau : replace envoie l'objet entier et écrase tout ce que le fichier ne mentionne pas, apply calcule la différence et préserve les champs gérés ailleurs. C'est pour cette raison qu'apply est le choix par défaut dès qu'un contrôleur ou un opérateur écrit lui aussi sur la ressource.

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

Les erreurs de ces trois commandes se répartissent en deux familles. Les unes viennent du serveur API, qui refuse une modification interdite ou détecte une écriture concurrente ; les autres viennent de votre ligne de commande, chemin JSON erroné ou guillemets mal fermés. Le message d'erreur permet de trancher immédiatement, et la dernière ligne du tableau rappelle que l'absence d'erreur ne garantit rien si le changement n'a pas été reporté dans Git.

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 →