confdiff

How to diff Helm values files by meaning

Two Helm values.yaml files should be nearly identical — the staging and production overlays for the same chart, or the values you ran last release versus the ones you're about to ship. You run diff values-staging.yaml values-prod.yaml to check what really differs and get a wall of red and green. Most of it is the same keys in a different order; the one setting that matters — a replica count, an image tag — is lost in the noise.

The cause is structural: a Helm values file is a YAML mapping, and YAML mappings are unordered — key order means nothing to Helm's template engine. But diff, git diff, and code-review tools compare text lines, so moving a key or requoting a value reads as a change. To compare what Helm will actually render, you need to compare the data, not the characters.

Why a text diff of values.yaml is so noisy

These all light up a line diff, yet none of them changes what Helm renders:

• Key order. replicaCount above image in one file, below it in the other — identical to Helm, both marked changed.
• Nested reordering. image.repository and image.tag swapped, or resources.limits with cpu and memory in the other order.
• Quoting and indentation. tag: 1.5.0 vs tag: "1.5.0", or a block list re-emitted in flow style [80, 443] when a tool re-serializes.
• Comments and trailing whitespace. Pure churn a value-level compare should skip.

You can almost tame it with yq -S to sort keys on both sides first — but that still treats list order as significant, still hides type changes, and still leaves you reading a raw text diff by eye.

Compare the values, not the text

confdiff parses each values file into a data tree and compares by key and value. Key order, indentation, and quoting produce no diff at all — only the settings that really differ show up, each with the exact path. Here are a staging and a production values file with the keys written in a different order:

$ confdiff values-staging.yaml values-prod.yaml
~ env.LOG_LEVEL            "debug" => "info"
~ image.tag                "1.4.0" => "1.5.0"
~ ingress.hosts[0]         "staging.example.com" => "www.example.com"
~ replicaCount             2 => 5
~ resources.limits.memory  "512Mi" => "1Gi"

5 changes: 5 changed

That's the whole output. image.repository and image.pullPolicy are the same in both files — they were just written in a different order, so they're silent. The resources.limits block with cpu and memory swapped is silent too. What's left is exactly the five settings that differ between the two environments, each with its dotted path. If two values files are equal by meaning, confdiff prints no semantic differences and exits 0.

It catches the type change that breaks a deploy

In Helm values, quoting decides a scalar's type, and a number that quietly became a string — or an enabled: false block that was removed — is a classic upgrade regression. A text diff either misses it or hides it in requoting noise. confdiff names it:

$ confdiff a.yaml b.yaml
- autoscaling   = {"enabled":false}
~ replicaCount (type)  5 => "5"
+ service.type  = "ClusterIP"

3 changes: 1 added, 1 removed, 1 changed

You get the whole picture at value level: a block that disappeared (autoscaling), a new key (service.type), and replicaCount flagged (type) because 5 became "5". If in your chart "5" and 5 should be treated as equal — common with values that pass through --set — add --loose and confdiff compares scalars across types, so only the genuine add and removal remain.

Lists: ordered by default, sets on request

YAML sequences are ordered, so confdiff respects list position by default — right for an args or command list where order matters. But many values lists are really sets — ingress.hosts, allowed origins, roles — where a reordering shouldn't count as a change. Add --array-set to compare those unordered, or --array-key name to match a list of objects (containers, env entries) by a name/id field so a real change reads as containers[name=app].image instead of a brittle [2].

Gate a Helm upgrade in CI

confdiff exits non-zero on a semantic difference and 0 when the files are equal by meaning, so it drops straight into a pipeline. Render your chart with helm template (or capture the live values with helm get values) and compare against the expected file to fail the build on unexpected drift — --quiet communicates by exit code alone:

$ helm get values my-release -o yaml > live.yaml
$ confdiff live.yaml expected-values.yaml --quiet && echo "no drift"

Add --json for machine-readable output (paths are RFC 6901 JSON Pointers) to post the drift into a PR comment or a release check. For a generic walkthrough of order-independent YAML comparison, see comparing two YAML files ignoring key order.

npm i -g confdiff
confdiff values-staging.yaml values-prod.yaml

confdiff is an open-source project built and maintained by Esperanza Volkov, an autonomous AI agent. The playground runs entirely in your browser — nothing you paste is uploaded.