kube-diff

kube-diff

A CLI tool that compares local Kubernetes manifests (plain YAML, Helm charts, Kustomize overlays) against the actual state in your cluster, providing clear, colorized diffs with a summary report.

For detailed documentation, see the docs/ folder:

Usage | Configuration | Examples | Deployment | Development | Use Cases

Why kube-diff?

Quick Start

Install

# Homebrew
brew install somaz94/tap/kube-diff

# Scoop (Windows)
scoop bucket add somaz94 https://github.com/somaz94/scoop-bucket
scoop install kube-diff

# Krew (kubectl plugin)
kubectl krew install diff2

# Binary (latest)
curl -sL https://github.com/somaz94/kube-diff/releases/latest/download/kube-diff_linux_amd64.tar.gz | tar xz
sudo mv kube-diff /usr/local/bin/

# Binary (specific version)
curl -sL https://github.com/somaz94/kube-diff/releases/download/v0.1.0/kube-diff_0.1.0_linux_amd64.tar.gz | tar xz
sudo mv kube-diff /usr/local/bin/

# From source
go install github.com/somaz94/kube-diff/cmd@latest

Upgrade

# Homebrew
brew update && brew upgrade kube-diff

# Scoop
scoop update kube-diff

# Krew
kubectl krew upgrade diff2

# From source
go install github.com/somaz94/kube-diff/cmd@latest

Uninstall

# Homebrew
brew uninstall kube-diff

# Scoop
scoop uninstall kube-diff

# Krew
kubectl krew uninstall diff2

# Manual
sudo rm /usr/local/bin/kube-diff

Basic Usage

# Compare YAML manifests against cluster
kube-diff file ./manifests/

# Compare Helm chart
kube-diff helm ./my-chart --values values-prod.yaml --release my-release

# Compare Kustomize overlay
kube-diff kustomize ./overlays/production

# Ignore specific fields in diff
kube-diff file ./manifests/ --ignore-field metadata.annotations.checksum

# Table output with custom context lines
kube-diff file ./manifests/ -o table -C 5

# Don't fail CI on changes
kube-diff file ./manifests/ --exit-code

# Compare against last-applied-configuration instead of live state
kube-diff file ./manifests/ --diff-strategy last-applied

# Watch mode — auto re-run on file changes
kube-diff watch file ./manifests/
kube-diff watch helm ./my-chart/ -f values.yaml

Example Output

★ NEW    ConfigMap/app-config (namespace: production)
~ CHANGED Deployment/web-app (namespace: production)
--- cluster
+++ local
@@ -1,5 +1,5 @@
 spec:
-  replicas: 2
+  replicas: 3
✓ OK     Service/web-svc (namespace: production)

Summary: 3 resources — 1 changed, 1 new, 1 unchanged

Exit Codes

Project Structure

cmd/                    # CLI entry point & Cobra commands
internal/
  source/               # Manifest loaders (file, helm, kustomize)
  cluster/              # K8s dynamic client fetcher
  diff/                 # Normalization & unified diff
  report/               # Color/JSON/Markdown output

Contributing

Contributions are welcome! See CONTRIBUTING.md for details.

License

This project is licensed under the Apache License 2.0 — see the LICENSE file for details.