kdiff

kdiff lets you conveniently integrate YAML cleaning and comparison logic with kubectl diff.

Specify how your manifests should be filtered (i.e. “cleaned”, or narrowed down in scope), and how they shoud be compared, directly on the command line:

# Arguments after -- are passed to kubectl by default
kdiff --transform 'yq .spec' --compare 'diff -u --color' -- -f mypod.yaml

# A --yq shorthand is provided for convenience,
# and KUBECTL_EXRTERNAL_DIFF is honored.
# Thus, the following call is equivalent
KUBECTL_EXTERNAL_DIFF='diff -u --color'
kdiff --yq=.spec  -- -f mypod.yaml

A --yq shorthand can be used.

# Limit the diff to the configmap data
kdiff --yq=.data  -- -f myconfig.yaml

If omitted, --compare defaults to KUBECTL_EXTERNAL_DIFF

KUBECTL_EXTERNAL_DIFF='dyff between -b'
# Compare metadata, ignoring labels
kdiff --yq='.metadata | del(.labels)' -- mypod.yaml

Presets

Frequently used transform and compare combinations can be saved as *presets’ in "${KDIFF_CONFIG_DIR}" (${HOME}/.config/kdiff by default).

Consider the following configuration layout:

~/.config/kdiff
├── compare
│   ├── diff
│   └── dyff
└── transform
    └── clean

Use the executable clean in combination with the comparison program dyff by calling:

kdiff --preset clean:dyff -- -f mypod.yaml

Presets can be aliased:

echo "clean:dyff" >> "${KDIFF_CONFIG_DIR}/cleany"
# Use 'cleany' or 'clean:diff' interchangeably
kdiff --preset cleany -- -f mypod.yaml

Aliasing is mainly useful when using kdiff as KUBECTL_EXTERNAL_DIFF, because arguments not matching ^[a-zA-Z0-9-=]+$ are stripped by kubectl. An alias can be a simple alphanumeric string.

# Neither of the following would work:
KUBECTL_EXTERNAL_DIFF='kdiff --yq=.data'
KUBECTL_EXTERNAL_DIFF='kdiff --preset clean:dyff'
# Use aliases instead
KUBECTL_EXTERNAL_DIFF='kdiff --preset data-only'
KUBECTL_EXTERNAL_DIFF='kdiff --preset cleany'

Happy diffing :)

Installation

kdiff depends on yq for YAML processing. If you haven’t already, I encourage you to install it!

Clone the repository and use the make install command to install the kdiff script. By default, this will install kdiff to $HOME/.local/bin, which should be in your PATH.

git clone https://your-repo-url/kdiff.git
cd kdiff
make install

You can customize the installation path using the PREFIX variable, for example for a system-wide installation (this may require sudo):

# Install to /usr/local/bin
make install PREFIX=/usr/local

An uninstall target is also available to remove the script.

Presets

The included presets are optional and can be installed with a separate command:

make install-presets

This will copy the default presets to $XDG_CONFIG_HOME/kdiff (or ~/.config/kdiff).

Note that some presets have external dependencies, such as kubectl-neat and dyff. You will need to install them separately for the corresponding presets to work.

You can remove the presets with make uninstall-presets.