kubectl-diff

View differences between the live resource and file definition

$ kubectl diff [[-f|--filename]] [path/to/filename]

kubectl diff (-f FILENAME | -k DIRECTORY | TYPE NAME) [options]

-f, --filename stringArray
    Path to one or more files, directories, or URLs containing the configuration to diff.

-k, --kustomize string
    Path to a Kustomize directory containing the configuration to diff.

TYPE NAME
    The type and name of a resource to diff (e.g., deployment my-app). Used to diff a live resource against a default/template.

--server-side
    If true, the diff computation is performed server-side, providing a more accurate preview. This is the default behavior for `kubectl diff`.

--local
    If true, perform a diff without contacting the cluster. This compares the local input files against a blank (empty) object in memory.

-n, --namespace string
    If present, the namespace scope for this CLI request.

--context string
    The name of the kubeconfig context to use.

--kubeconfig string
    Path to the kubeconfig file to use for CLI requests.

--dry-run string
    Must be 'server' or 'client'. For `diff`, it defaults to 'server', submitting a dry-run request to the API server for comparison.

--field-manager string
    Name of the field manager to use for the server-side apply dry-run during diff operation.

--recursive
    If true and a directory is specified with -f, process the directory recursively.

--validate string
    Validate the input against a schema. Possible values: 'strict', 'warn', 'ignore'.

--timeout duration
    The length of time to wait for a server response (e.g., 5s, 1m).

-l, --selector string
    Selector (label query) to filter resources for the diff operation.

--all-namespaces
    If present, list resources across all namespaces (for TYPE NAME usage).

The `kubectl diff` command provides a powerful mechanism to safely preview the changes that would occur if a `kubectl apply` operation were executed. It compares the current live state of one or more Kubernetes resources within a cluster with a desired state defined in local configuration files, Kustomize directories, or standard input. By performing a dry-run against the Kubernetes API server, `kubectl diff` computes the potential resulting object and then presents a standard `diff` output, highlighting additions, deletions, and modifications. This allows users to meticulously review and confirm intended changes before they are actually applied to the cluster, significantly reducing the risk of unintended modifications, misconfigurations, or service disruptions.

kubectl diff performs a dry-run and relies on the API server's interpretation. While highly accurate, it may not perfectly reflect all possible mutations by admission controllers or webhooks that could occur during an actual apply operation. The --local option compares against a blank object, which is useful for validating syntax but does not reflect the current live state without cluster contact.

Internally, kubectl diff sends a dry-run 'apply' request to the Kubernetes API server with the desired configuration. The API server then processes this request as if it were a real 'apply' but without persisting any changes. It computes the theoretical resulting object, incorporating default values, schema validations, and server-side mutations. This theoretical object is then returned to kubectl, which compares it against the resource's current live state in the cluster and presents the differences using a standard patch-style diff format.

kubectl diff is a cornerstone tool in GitOps workflows. It enables automated CI/CD pipelines and developers to verify that the configuration defined in a Git repository (the desired state) accurately reflects the changes that would be made to the live Kubernetes cluster (the actual state) before any deployment takes place. This pre-flight check ensures consistency, minimizes surprises, and maintains a verifiable audit trail of changes.

The kubectl diff command was introduced into kubectl to address the critical need for pre-deployment validation and to enhance the safety of kubectl apply operations. Its development paralleled the evolution of server-side apply capabilities in Kubernetes, allowing it to leverage the API server for more authoritative and accurate dry-run comparisons. This integration has solidified its role as an indispensable tool for safe and predictable resource management in Kubernetes environments.

kubectl apply(1), kubectl get(1), diff(1), git diff