kubectl edit

When to Use kubectl edit

kubectl edit opens a resource in your terminal editor for direct modification. It fetches the current state of the resource as YAML, lets you modify it, and applies the changes when you save and close the editor. It is useful for quick fixes and debugging but should not replace declarative management for production workloads.

How It Works

When you run kubectl edit, the following happens:

1. The full resource definition is fetched from the API server.
2. It opens in your configured editor (KUBE_EDITOR, EDITOR, or vi by default).
3. When you save and close, kubectl computes the diff and sends it to the API server.
4. If the API server rejects the change, the editor reopens with error details.

# Edit a deployment using the default editor
kubectl edit deployment my-app

# Use a specific editor
KUBE_EDITOR="code --wait" kubectl edit deployment my-app

# Set your preferred editor permanently in your shell profile
export KUBE_EDITOR=nano

Practical Use Cases

The edit command is ideal for situations where you need to make a quick change and can accept that the modification will not be tracked in version control:

# Quickly change an environment variable on a deployment
kubectl edit deployment my-app
# Find the env section and modify the value, then save

# Fix a misconfigured configmap
kubectl edit configmap app-config -n production

# Adjust resource limits during an incident
kubectl edit deployment my-app
# Modify resources.limits.memory, then save

Immutable Fields

Some fields cannot be changed after creation. If you try to modify an immutable field, the API server will reject the change:

• Pod spec fields: Most pod spec fields are immutable once the pod is created. You cannot change the image, command, or volume mounts on a running pod.
• Service clusterIP: The assigned cluster IP cannot be changed after creation.
• Job selectors: The selector on a Job is immutable.
• PVC storage size: Can only be expanded if the storage class supports it, never reduced.

When you need to change immutable fields, delete and recreate the resource, or in the case of Deployments, change the pod template which triggers a new rollout.

Editor Configuration

Configure your editor for the best experience:

# Use VS Code (requires --wait flag so kubectl waits for you to close)
export KUBE_EDITOR="code --wait"

# Use nano for simplicity
export KUBE_EDITOR=nano

# Use vim with YAML-friendly settings
export KUBE_EDITOR="vim"

Comparing with kubectl patch

While edit opens an interactive editor, kubectl patch applies changes programmatically. Use edit for interactive exploration and patch for scripted modifications:

# Interactive: explore and modify the full resource
kubectl edit deployment my-app

# Programmatic: change a specific field
kubectl patch deployment my-app -p '{"spec":{"replicas":5}}'

Editing as a Debugging Tool

During incidents, edit can be the fastest way to make changes. Common debugging edits include:

# Add a debug environment variable
kubectl edit deployment my-app
# Add: - name: DEBUG, value: "true" to env section

# Temporarily increase replicas
kubectl edit deployment my-app
# Change spec.replicas

# Modify a liveness probe that is causing restarts
kubectl edit deployment my-app
# Adjust initialDelaySeconds or timeoutSeconds

Configuration Drift Warning

Every change made through kubectl edit creates configuration drift between the cluster state and your version-controlled manifests. After using edit for an emergency fix, always update your source manifests to match. Use kubectl get deployment my-app -o yaml to capture the current state and reconcile it with your files.

# After an emergency edit, capture the current state
kubectl get deployment my-app -o yaml > deployment-current.yaml

# Diff against your version-controlled manifest
diff deployment.yaml deployment-current.yaml

This workflow ensures that emergency changes are not lost and that your Git repository remains the source of truth.