How do I use kubectl diff safely before applying a change?

Run kubectl diff on the same file or kustomization you plan to apply. It compares the live configuration with what apply would produce and prints YAML. Exit code 0 means no differences, 1 means differences were found, and anything higher means an error. Secret values are masked unless you pass the show secrets option.

What it does

The kubectl reference describes diff as comparing configurations given by file name or standard input between the current online configuration and the configuration as it would be if applied. The output is always YAML. By default it uses the diff program on your path with unified output, and you can substitute your own with the KUBECTL_EXTERNAL_DIFF environment variable.

Useful options from the reference:

• -k to process a kustomization directory.
• --server-side to run the comparison with server side apply.
• --prune to include resources that would be deleted by pruning.
• -l to filter by label selector.
• --show-secrets to stop masking secret values, which means the default masks them.

The exit code trap

If your CI treats any non-zero code as failure, a legitimate change will fail the step. Handle code 1 as an expected result and codes above 1 as errors:

set +e
kubectl diff -f rendered.yaml > diff.txt
code=$?
set -e
if [ "$code" -gt 1 ]; then echo "kubectl diff failed"; exit 1; fi

Note that the documentation says an external diff command, if you use one, is expected to follow the same convention.

Using the diff as a review artifact

A diff of the live object is a better review aid than a diff of the source. It shows the effect, including fields that other tools or controllers set. Look for:

1. Security context fields being removed or loosened.
2. New host paths, host networking or added capabilities.
3. Image tags changing, or a digest being dropped.
4. RBAC rules widening.
5. Replica or resource limit changes that affect availability.

Attach the diff to the pull request or change ticket. Keep it out of public logs if it could hold anything sensitive, and avoid the show secrets option in shared pipelines.

Where it fits

Diff tells you what would change. A server dry run tells you whether the cluster would accept it. Use both. See dry run client versus server.

Try it yourself

Click through it at your own pace, or open it full screen.

In the demo, notice that the reviewer sees the effect of the change before merge. A diff of the live object gives you the same view for cluster changes.

Quick check

Safeguard runs policies and gates on pull requests, so a failed rule can hold a merge, and its dependency and SBOM scanning covers the packages your infrastructure code pulls in. You can try a free scan at gold.safeguard.sh/scan.

Sources

• kubectl diff reference, Kubernetes documentation

Last reviewed: 19 October 2026.