Helm Diff Plugin

This is a Helm plugin giving you a preview of what a helm upgrade would change. It basically generates a diff between the latest deployed version of a release and a helm template-rendered manifest (or helm upgrade --dry-run when HELM_DIFF_USE_UPGRADE_DRY_RUN=true is set). This can also be used to compare two revisions/versions of your helm release.

Install

Using Helm plugin manager (> 2.3.x)

requires helm 3.18+

helm plugin install https://github.com/databus23/helm-diff

Installing offline

If installing this in an offline/airgapped environment, download the platform-specific binary archive (e.g., helm-diff-linux-amd64.tgz or helm-diff-windows-amd64.tgz) from releases. Make sure to select the correct .tgz file for your operating system and architecture.

The release archives include everything needed to install the plugin (binary, plugin.yaml, and the install scripts). The simplest way to install offline is to extract the archive and point helm plugin install at the extracted directory:

tar xzf helm-diff-linux-amd64.tgz   # extracts into a ./diff directory
helm plugin install ./diff

The install script detects that the binary is already bundled and skips the GitHub download.

Alternatively, if you keep a separate local checkout of the plugin source, you can point the installer at a downloaded .tgz via the HELM_DIFF_BIN_TGZ environment variable.

Set HELM_DIFF_BIN_TGZ to the absolute path to the downloaded binary archive:

POSIX shell:

export HELM_DIFF_BIN_TGZ=/path/to/helm-diff-linux-amd64.tgz


**PowerShell:**
```powershell
$env:HELM_DIFF_BIN_TGZ = "C:\path\to\helm-diff-bin.tgz"

Now, run helm plugin install /path/to/helm-diff/. Here, /path/to/helm-diff/ must be a local copy of the Helm Diff plugin source directory (including plugin.yaml and the install scripts), for example from a repo you cloned or a source archive you downloaded earlier and transferred into the offline environment. The install script will skip the GitHub download and instead install from the .tgz.

For Helm 4 users:

Helm 4 verifies plugin provenance by default. This project publishes GPG-signed provenance artifacts (.prov) alongside release tarballs. To verify, import the project's public key into your keyring and install from a direct tarball URL (git repo URLs do not support provenance verification):

gpg --keyserver hkps://keys.openpgp.org --recv-keys 6D1B9CFF340869384450267300A28D1CC7CD8D7A
helm plugin install https://github.com/databus23/helm-diff/releases/latest/download/helm-diff-linux-amd64.tgz

For offline/airgapped environments, download the public key from the GitHub release assets on a connected machine, transfer it, and import it locally:

curl -sL https://github.com/databus23/helm-diff/releases/latest/download/pubkey.asc -o pubkey.asc
gpg --import pubkey.asc

The public key fingerprint is published in the notes for each GitHub release.

For more information about Helm 4's plugin verification, see: - Helm 4 Overview - HIP-0026: Plugin Provenance - Helm Provenance Documentation

Pre Helm 2.3.0 Installation

Pick a release tarball from the releases page.

Unpack the tarball in your helm plugins directory ($(helm home)/plugins).

E.g.

curl -L $TARBALL_URL | tar -C $(helm home)/plugins -xzv

From Source

Prerequisites

• GoLang >= 1.21

Make sure you do not have a version of helm-diff installed. You can remove it by running helm plugin uninstall diff

Installation Steps

The first step is to download the repository and enter the directory. You can do this via git clone or downloading and extracting the release. If you clone via git, remember to checkout the latest tag for the latest release.

Next, install the plugin into helm.

make install/helm

Usage

``` The Helm Diff Plugin

• Shows a diff explaining what a helm upgrade would change: This fetches the currently deployed version of a release and compares it to a local chart plus values. This can be used to visualize what changes a helm upgrade will perform.

• Shows a diff explaining what had changed between two revisions: This fetches previously deployed versions of a release and compares them. This can be used to visualize what changes were made during revision change.

• Shows a diff explaining what a helm rollback would change: This fetches the currently deployed version of a release and compares it to the previously deployed version of the release, that you want to rollback. This can be used to visualize what changes a helm rollback will perform.

Usage: diff [flags] diff [command]

Available Commands: completion Generate the autocompletion script for the specified shell local Shows diff between two local chart directories release Shows diff between release's manifests revision Shows diff between revision's manifests rollback Show a diff explaining what a helm rollback could perform upgrade Show a diff explaining what a helm upgrade would change. version Show version of the helm diff plugin

Flags: --allow-unreleased enables diffing of releases that are not yet deployed via Helm -a, --api-versions stringArray Kubernetes api versions used for Capabilities.APIVersions --color color output. You can control the value for this flag via HELM_DIFF_COLOR=[true|false]. If both --no-color and --color are unspecified, coloring enabled only when the stdout is a term and TERM is not "dumb" -C, --context int output NUM lines of context around changes (default -1) --detailed-exitcode return a non-zero exit code when there are changes --devel use development versions, too. Equivalent to version '>0.0.0-0'. If --version is set, this is ignored. --disable-openapi-validation disables rendered templates validation against the Kubernetes OpenAPI Schema --disable-validation disables rendered templates validation against the Kubernetes cluster you are currently pointing to. This is the same validation performed on an install --dry-run string[="client"] --dry-run, --dry-run=client, or --dry-run=true disables cluster access and show diff as if it was install. Implies --install, --reset-values, and --disable-validation. --dry-run=server enables the cluster access with helm-get and the lookup template function. --enable-dns enable DNS lookups when rendering templates -D, --find-renames float32 Enable rename detection if set to any value greater than 0. If specified, the value denotes the maximum fraction of changed content as lines added + removed compared to total lines in a diff for considering it a rename. Only objects of the same Kind are attempted to be matched -h, --help help for diff --include-crds include CRDs in the diffing --include-tests enable the diffing of the helm test hooks --insecure-skip-tls-verify skip tls certificate checks for the chart download --install enables diffing of releases that are not yet deployed via Helm (equivalent to --allow-unreleased, added to match "helm upgrade --install" command --kube-version string Kubernetes version used for Capabilities.KubeVersion --kubeconfig string This flag is ignored, to allow passing of this top level flag to helm --no-color remove colors from the output. If both --no-color and --color are unspecified, coloring enabled only when the stdout is a term and TERM is not "dumb" --no-hooks disable diffing of hooks --normalize-manifests normalize manifests before running diff to exclude style differences from the output --output string Possible values: diff, simple, template, json, structured, dyff. When set to "template", use the env var HELM_DIFF_TPL to specify the template. (default "diff") --post-renderer string the path to an executable to be used for post rendering. If it exists in $PATH, the binary will be used, otherwise it will try to look for the executable at the given path --post-renderer-args stringArray an argument to the post-renderer (can specify multiple) --repo string specify the chart repository url to locate the requested chart --reset-then-reuse-values reset the values to the ones built into the chart, apply the last release's values and merge in any new values. If '--reset-values' or '--reuse-values' is specified, this is ignored --reset-values reset the values to the ones built into the chart and merge in any new values --reuse-values reuse the last release's values and merge in any new values. If '--reset-values' is specified, this is ignored --server-side string must be "true", "false" or "auto". Object updates run in the server instead of the client ("auto" defaults the value from the previous chart release's method) (default "auto") --set stringArray set values on the command line (can specify multiple or separate values with commas: key1=val1,key2=val2) --set-file stringArray set values from respective files specified via the command line (can specify multiple or separate values with commas: key1=path1,key2=path2) --set-json stringArray set JSON values on the command line (can specify multiple or separate values with commas: key1=jsonval1,key2=jsonval2) --set-literal stringArray set STRING literal values on the command line --set-string stringArray set STRING values on the command line (can specify multiple or separate values with commas: key1=val1,key2=val2) --show-secrets do not redact secret values in the output --show-secrets-decoded decode secret values in the output --skip-schema-validation skip validation of the rendered manifests against the Kubernetes OpenAPI schema --strip-trailing-cr strip trailing carriage return on input --suppress stringArray allows suppression of the kinds listed in the diff output (can specify multiple, like '--suppress Deployment --suppress Service') --suppress-output-line-regex stringArray a regex to suppress diff output lines that match -q, --suppress-secrets suppress secrets in the output --take-ownership if set, upgrade will ignore the check for helm annotations and take ownership of the existing resources --three-way-merge use three-way-merge to compute patch and generate diff output -f, --values valueFiles specify values in a YAML file (can specify multiple) (default []) --version string specify the exact chart version to use. If this is not specified, the latest version is used

Additional help topcis: diff

Use "diff [command] --help"