databus23/helm-diff: previewing a Helm upgrade before it touches the cluster

The gap helm-diff fills between helm template and helm upgrade

Helm has two ways to look at a release before you change it, and neither answers the question people actually ask. helm template renders a chart locally, but it renders from your working tree, not from what the cluster is running, so it tells you nothing about the delta. helm upgrade --dry-run renders against the live release, but it prints the whole manifest, and a chart with a few hundred lines of ConfigMap makes the one changed field impossible to find. The plugin's answer is to compute both sides and show only the difference: according to the README, it "generates a diff between the latest deployed version of a release and a helm template-rendered manifest." The audience is anyone who runs helm upgrade against a cluster other people depend on, which in practice means platform teams, release engineers, and CI pipelines that want a human or a policy check before apply. The README also notes the plugin can compare two revisions or versions of a release, which turns it into a review tool for a change that already shipped.

How the diff is computed, and why the dry-run flag matters

The mechanism is a comparison of two rendered documents. One side is the manifest of the currently deployed release, read from the cluster. The other side is what the release would look like after the upgrade, and here the plugin offers a choice. By default it renders the chart the way helm template does, from the chart source and the values you pass. When HELM_DIFF_USE_UPGRADE_DRY_RUN is set to true, it instead uses helm upgrade --dry-run output. That distinction is not cosmetic. helm template cannot run cluster lookups the way a real upgrade can, so charts that call .Capabilities or look up existing resources can render differently on the two paths. The rendering and structural comparison work is delegated to libraries rather than hand-rolled: go.mod lists homeport/dyff, gonvenience/ytbx, evanphx/json-patch/v5, aryann/difflib, and google/go-cmp, which suggests YAML-aware comparison and JSON patch handling rather than line-by-line text diffing. The result is the familiar colored output: added lines, removed lines, and context, with the plugin's own binary (cmd/, built to bin/diff by the Makefile) driving it.

Installing the helm-diff plugin and running a first diff

The documented install path is the Helm plugin manager, which the README says requires helm 3.18 or later. One command fetches the plugin and puts the diff binary on Helm's plugin path.

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

After that, helm diff becomes a subcommand. The README describes the core use as generating a diff between the latest deployed version of a release and a helm template-rendered manifest, so the invocation takes the release name and the chart path the same way helm upgrade does, and the plugin prints the comparison of the deployed manifest against the would-be manifest.

For an airgapped environment, the README documents a second path: download the platform-specific archive (for example helm-diff-linux-amd64.tgz) from the releases page, extract it, and install from the extracted directory. The install script detects the bundled binary and skips the GitHub download.

tar xzf helm-diff-linux-amd64.tgz
helm plugin install ./helm-diff-linux-amd64

The README notes the archive wraps its content in a directory named after the archive itself, which is what Helm 4 expects when installing from a tarball.

Helm 4 provenance verification changes the install story

With Helm 4, plugin provenance is verified by default, and that has a concrete consequence for how you install helm-diff. The README states that git repo URLs do not support provenance verification, so the one-line install from the repository URL is not the path to use under Helm 4. Instead the project publishes GPG-signed .prov artifacts next to release tarballs, and you install from a direct tarball URL after importing the maintainer's public key. The README gives the expected fingerprint as C5645EF4 7482257A 1F806D2B EA17A2A2 06AFF8CD and notes that the fingerprint is published in the notes for each release. For offline installs under Helm 4, the tarball and its .prov file must be transferred together and the original tarball file name must be kept, because verification matches the file name against checksums recorded in the .prov file. This is a real operational constraint: the archive name is part of the verification input, so renaming the file during transfer breaks the install. The README also points to HIP-0026 for the underlying plugin provenance design.

Where helm-diff stops being the right tool

The plugin answers one question, and it is worth being clear about what it does not do. It does not validate that the resulting objects are acceptable to the API server. A diff can be clean and the apply can still fail on a webhook, an immutable field, or a resource that already exists. It does not tell you whether the change is safe, only what the change is. It also inherits the rendering caveats of whichever path it takes: if your chart depends on cluster state that only a real upgrade can see, the template-based default may show you a manifest that differs from what the upgrade would actually submit, and the README's own escape hatch (HELM_DIFF_USE_UPGRADE_DRY_RUN) exists precisely because that mismatch is possible. Finally, if your deployments are driven by a controller that reconciles continuously rather than by discrete helm upgrade commands, there is no single upgrade to preview, and the plugin has nothing to compare against. The repository's README does not document rollback behavior, so do not read the diff output as a rollback plan.

How helm-diff differs from helm template plus a text diff

The obvious alternative is to render the chart yourself and diff the output against a stored copy of the deployed manifest. That works, and it is what many teams do before they find this plugin. The difference is in what gets compared. A text diff of two rendered YAML files is sensitive to key ordering and whitespace, so a reordered map or a changed indentation shows up as a large change even when the semantic content is identical. helm-diff's dependency set points the other way: dyff and ytbx are YAML-aware comparison libraries, and json-patch is present for structural patching, which is the machinery you need to report a changed value rather than a changed line. The second difference is where the deployed side comes from. A hand-rolled pipeline has to fetch and store the live manifest itself; the plugin reads the deployed release directly, which removes a synchronization step that is easy to get wrong. The trade-off is that you are adding a plugin binary to every machine or CI image that runs helm upgrade, and under Helm 4 that binary now carries a provenance verification requirement.

Maintenance, upgrade cost, and licence

The repository is not archived, and the last push was on 2026-09-17, with releases v3.15.13 on 2026-09-11, v3.15.12 on 2026-08-30, and v3.15.11 on 2026-08-01. That is a steady release cadence, and the version numbers suggest patch-level fixes rather than large feature drops. The upgrade cost is low in the normal case: helm plugin install fetches the current release, and there is no server component to migrate. The cost that is not zero is the Helm major-version boundary. go.mod declares helm.sh/helm/v4 v4.3.0, so the plugin tracks Helm 4, and the README's install instructions split between the Helm 3 path (extract the archive, install from the extracted directory) and the Helm 4 path (tarball URL with provenance, or tarball plus .prov offline). Teams pinned to an older Helm should check the plugin version they install rather than assuming the latest works. The project is Apache-2.0 licensed, which permits commercial and closed-source use and requires preserving the licence and notices; the LICENSE file at the repository root is the authoritative text, and this is a description of the terms, not legal advice.

Editorial conclusion

Adopt helm-diff if you run Helm upgrades against shared clusters and want the rendered change visible before apply, especially in CI where a diff can gate a pull request. Skip it if your releases are entirely generated by a controller that reconciles continuously, since there is no single upgrade moment to preview. Verify first that your Helm version satisfies the plugin's requirement (helm 3.18+ for the plugin-manager install path) and that the dry-run mode you intend to use (HELM_DIFF_USE_UPGRADE_DRY_RUN) behaves the way your chart's lookups expect, because the two render paths do not produce identical output for every chart.

Frequently asked questions

Official sources

1. databus23/helm-diff on GitHub
2. Issues
3. License: Apache-2.0
4. README
5. Releases