kubectl diff: Command Reference for CI/CD

Preview exactly what an apply would change before you run it.

kubectl diff compares your manifests against the live cluster and prints what apply would change, server-side. It is the review step before a deploy. This reference covers its flags and the exit-code semantics that matter in CI.

Common flags and usage

diff -f <manifest|dir>: diff files against the live state
diff -k <dir>: diff a kustomize overlay
Exit 0: no differences; exit 1: differences found
Exit >1: an actual error occurred
--server-side: match the server-side apply merge you will run

Example

shell

# Post the planned change on the PR, do not fail the job on a diff
kubectl diff -f k8s/ --server-side > plan.txt; rc=$?
[ "$rc" -le 1 ] || { echo "diff errored"; exit 1; }
cat plan.txt

In CI

diff exits 1 when differences exist, which is expected, not an error, so test for exit >1 to catch real failures. Run it in a PR check to surface the planned change for review, mirroring a Terraform plan step before the apply on merge.

Key takeaways

Exit 1 means "there is a diff" and is not a failure; only >1 is an error.
Match --server-side here to the apply you will actually run.
A diff PR check is the Kubernetes equivalent of terraform plan.

Related guides

kubectl Cheat Sheet: Commands for Everyday KubernetesA kubectl cheat sheet - get, describe, logs, apply, rollout, debug, and context commands for daily Kubernetes… kubectl apply: Command Reference for CI/CDReference for kubectl apply: declarative create-or-update from manifests, server-side apply, dry-run validati… kubectl kustomize: Command Reference for CI/CDReference for kubectl kustomize: render a kustomize overlay to YAML, the difference from apply -k, and a CI e… kubectl get: Command Reference for CI/CDReference for kubectl get: list resources, output formats, label and field selectors, jsonpath extraction, an…