Q: What is `kubectl diff`?
Shows what would change if you applied a manifest, compared to what's currently running. Like terraform plan for Kubernetes.
Want to master this scenario in a live sandbox? KodeKloud's CKA & CKAD Hands-On Certification Track covers this exact problem with hands-on terminal drills.
🛠️ Production Runbook & Step-by-Step Resolution
Direct Answer: <strong>kubectl diff</strong> shows what would change in the cluster if you ran <code>kubectl apply</code> on the same manifests, without changing anything. It sends the objects through a server-side dry run, so defaulting and admission mutation are included, then prints a unified diff against live state. Interviewers ask about it to see whether you review changes before shipping them, understand its exit codes for CI gates, and know why diffs sometimes contain noise from server-managed fields.
Mental model: kubectl diff is a safe preview of apply
The command takes the same inputs as apply (-f, -k, stdin) and compares the result of a server-side dry-run with the live object.
- Read-only: nothing is persisted; it needs
get, and permission to perform the dry-run (patch/create) in the namespace. - Server-aware: because the server computes the result, defaulted fields and mutating webhook changes show up.
- Output: unified diff with
+/-lines per object. - Kustomize and Helm: works with
-k, and withhelm template ... | kubectl diff -f -.
Hands-on: diff a manifest, a kustomization, and a chart
Typical pre-deploy commands.
kubectl diff -f deploy.yaml
# - replicas: 3
# + replicas: 5
kubectl diff -k overlays/prod -n prod
helm template my-app ./chart -n prod -f values-prod.yaml | kubectl diff -n prod -f -
KUBECTL_EXTERNAL_DIFF="colordiff -u" kubectl diff -f deploy.yaml
- Single file:
kubectl diff -f deploy.yaml. - Kustomize:
kubectl diff -k overlays/prod. - Rendered Helm: pipe
helm templateintokubectl diff -f -; or use the helm-diff plugin for release-aware output. - Custom viewer: set
KUBECTL_EXTERNAL_DIFF(for examplecolordiff) to change the tool.
Verify and gate: exit codes in CI
The exit code is what makes diff scriptable.
kubectl diff -f deploy.yaml > plan.diff
rc=$?
case $rc in
0) echo "No changes" ;;
1) echo "Changes detected"; cat plan.diff ;;
*) echo "kubectl diff failed ($rc)"; exit $rc ;;
esac
- 0: no differences.
- 1: differences found (not an error).
- Greater than 1: the command itself failed, for example invalid manifest or forbidden.
- Pipelines: treat 1 as expected for a review step and post the diff as a pull request comment.
Failure modes and false positives
Diffs can be larger or smaller than expected.
- Managed fields:
metadata.managedFields,resourceVersionand timestamps are filtered by kubectl, but fields mutated by controllers (HPA-controlledreplicas) can look like drift. - Missing namespace or CRD: a dry-run against a namespace or custom resource that does not exist yet fails, so diff cannot preview a first install of dependencies.
- Webhook side effects: admission webhooks must declare
sideEffectsasNoneorNoneOnDryRun, or the dry-run is rejected. - Secrets: treat diff output as sensitive, since Secret changes can appear in CI logs; restrict who can read them.
- Server-side apply: if you apply with
--server-side, usekubectl diff --server-sideso field ownership matches.
Production practice: diff as a deployment gate
Make the preview part of the workflow.
- Pull request check: run diff against the target cluster read-only credentials and attach output.
- Drift detection: scheduled diff of Git manifests versus cluster highlights manual
kubectl editchanges. - GitOps: Argo CD and Flux provide equivalent diff views; kubectl diff is the manual equivalent.
- Least privilege: give CI a role limited to what the dry-run needs.
- <code>kubectl diff</code> previews what <code>kubectl apply</code> would change by comparing server-side dry-run output with live state.
- I rely on its exit codes: 0 no change, 1 changes, above 1 error, and run it for kustomize and Helm-rendered manifests.
- I automate it as a pull request check and as scheduled drift detection.
Senior hiring managers and bar raisers evaluate how you prioritize during outages. Avoid these common anti-patterns:
- Treating exit code 1 as a failed command Exit code 1 means differences exist; a CI step that fails on any non-zero code blocks every legitimate change.
- Diffing against the wrong context or namespace The diff is only meaningful for the cluster you target; a stale kubeconfig context shows a misleading result.
- Expecting diff to preview objects whose namespace or CRD does not exist The server-side dry-run fails when dependencies are missing, so apply order matters.
- Mixing client-side and server-side apply Field ownership differs, so diffs and applies can disagree about who owns a field.