Skip to content

feat: add structured output mode for helm-diff #899

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
madhunzv wants to merge 4 commits into
base: master
Choose a base branch
from
Open

feat: add structured output mode for helm-diff #899

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
3dec2e2
feat: add structured output mode for helm-diff
madhunzv Dec 12, 2025
853e6c1
fix lint errors
madhunzv Dec 30, 2025
fe2a468
fix: log panic msg and add tests for error paths
madhunzv Jan 3, 2026
a8e802e
refactor: improve error handling in structured entry creation and upd…
madhunzv Jan 5, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
37 changes: 32 additions & 5 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -115,7 +115,7 @@ Flags:
--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, dyff. When set to "template", use the env var HELM_DIFF_TPL to specify the template. (default "diff")
--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
Expand Down Expand Up @@ -145,6 +145,33 @@ Additional help topcis:
Use "diff [command] --help" for more information about a command.
```

### Structured JSON output

Set `--output structured` (or `HELM_DIFF_OUTPUT=structured`) to emit machine-readable JSON. Each entry reports the Kubernetes object metadata, resource existence, and per-field changes using JSON Pointer paths:

```shell
helm diff upgrade prod api ./charts/api --output structured
```

```json
[
{
"apiVersion": "apps/v1",
"kind": "Deployment",
"namespace": "prod",
"name": "api",
"changeType": "MODIFY",
"resourceStatus": {"oldExists": true, "newExists": true},
"changes": [
{"path": "spec", "field": "replicas", "change": "replace", "oldValue": 2, "newValue": 3},
{"path": "spec.template.spec.containers[0]", "field": "image", "change": "replace", "oldValue": "api:v1", "newValue": "api:v2"}
]
}
]
```

When a kind is suppressed via `--suppress`, `changesSuppressed` is set to `true` and field details are omitted. Nested metadata such as labels show the container path (`metadata.labels`) and expose the label key through the `field` property (for example `app.kubernetes.io/version`).

## Commands:

### upgrade:
Expand Down Expand Up @@ -211,7 +238,7 @@ Flags:
--kubeconfig string This flag is ignored, to allow passing of this top level flag to helm
--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, dyff. When set to "template", use the env var HELM_DIFF_TPL to specify the template. (default "diff")
--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
Expand Down Expand Up @@ -266,7 +293,7 @@ Flags:
-h, --help help for release
--include-tests enable the diffing of the helm test hooks
--normalize-manifests normalize manifests before running diff to exclude style differences from the output
--output string Possible values: diff, simple, template, dyff. When set to "template", use the env var HELM_DIFF_TPL to specify the template. (default "diff")
--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")
--show-secrets do not redact secret values in the output
--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')
Expand Down Expand Up @@ -308,7 +335,7 @@ Flags:
-h, --help help for revision
--include-tests enable the diffing of the helm test hooks
--normalize-manifests normalize manifests before running diff to exclude style differences from the output
--output string Possible values: diff, simple, template, dyff. When set to "template", use the env var HELM_DIFF_TPL to specify the template. (default "diff")
--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")
--show-secrets do not redact secret values in the output
--show-secrets-decoded decode secret values in the output
--strip-trailing-cr strip trailing carriage return on input
Expand Down Expand Up @@ -344,7 +371,7 @@ Flags:
-h, --help help for rollback
--include-tests enable the diffing of the helm test hooks
--normalize-manifests normalize manifests before running diff to exclude style differences from the output
--output string Possible values: diff, simple, template, dyff. When set to "template", use the env var HELM_DIFF_TPL to specify the template. (default "diff")
--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")
--show-secrets do not redact secret values in the output
--show-secrets-decoded decode secret values in the output
--strip-trailing-cr strip trailing carriage return on input
Expand Down
2 changes: 1 addition & 1 deletion cmd/options.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,7 @@ func AddDiffOptions(f *pflag.FlagSet, o *diff.Options) {
f.BoolVar(&o.ShowSecretsDecoded, "show-secrets-decoded", false, "decode secret values in the output")
f.StringArrayVar(&o.SuppressedKinds, "suppress", []string{}, "allows suppression of the kinds listed in the diff output (can specify multiple, like '--suppress Deployment --suppress Service')")
f.IntVarP(&o.OutputContext, "context", "C", -1, "output NUM lines of context around changes")
f.StringVar(&o.OutputFormat, "output", "diff", "Possible values: diff, simple, template, dyff. When set to \"template\", use the env var HELM_DIFF_TPL to specify the template.")
f.StringVar(&o.OutputFormat, "output", "diff", "Possible values: diff, simple, template, json, structured, dyff. When set to \"template\", use the env var HELM_DIFF_TPL to specify the template.")
f.BoolVar(&o.StripTrailingCR, "strip-trailing-cr", false, "strip trailing carriage return on input")
f.Float32VarP(&o.FindRenames, "find-renames", "D", 0, "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")
f.StringArrayVar(&o.SuppressedOutputLineRegex, "suppress-output-line-regex", []string{}, "a regex to suppress diff output lines that match")
Expand Down
70 changes: 56 additions & 14 deletions diff/diff.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,7 @@ import (
"fmt"
"io"
"math"
"os"
"regexp"
"sort"
"strings"
Expand All @@ -31,6 +32,11 @@ type Options struct {
SuppressedOutputLineRegex []string
}

// StructuredOutput returns true when the structured JSON output is requested.
func (o *Options) StructuredOutput() bool {
return o != nil && o.OutputFormat == "structured"
}

type OwnershipDiff struct {
OldRelease string
NewRelease string
Expand Down Expand Up @@ -65,7 +71,7 @@ func generateReport(oldIndex, newIndex map[string]*manifest.MappingResult, newOw

for name, diff := range newOwnedReleases {
diff := diffStrings(diff.OldRelease, diff.NewRelease, true)
report.addEntry(name, options.SuppressedKinds, "", 0, diff, "OWNERSHIP")
report.addEntry(name, options.SuppressedKinds, "", 0, diff, "OWNERSHIP", nil)
}

for _, key := range sortedKeys(oldIndex) {
Expand Down Expand Up @@ -159,7 +165,7 @@ func doSuppress(report Report, suppressedOutputLineRegex []string) (Report, erro
entry.ChangeType = "MODIFY_SUPPRESSED"
}

filteredReport.addEntry(entry.Key, entry.SuppressedKinds, entry.Kind, entry.Context, diffRecords, entry.ChangeType)
filteredReport.addEntry(entry.Key, entry.SuppressedKinds, entry.Kind, entry.Context, diffRecords, entry.ChangeType, entry.Structured)
}

return filteredReport, nil
Expand Down Expand Up @@ -235,20 +241,56 @@ func doDiff(report *Report, key string, oldContent *manifest.MappingResult, newC
redactSecrets(oldContent, newContent)
}

if oldContent == nil {
emptyMapping := &manifest.MappingResult{}
diffs := diffMappingResults(emptyMapping, newContent, options.StripTrailingCR)
report.addEntry(key, options.SuppressedKinds, newContent.Kind, options.OutputContext, diffs, "ADD")
} else if newContent == nil {
emptyMapping := &manifest.MappingResult{}
diffs := diffMappingResults(oldContent, emptyMapping, options.StripTrailingCR)
report.addEntry(key, options.SuppressedKinds, oldContent.Kind, options.OutputContext, diffs, "REMOVE")
} else {
diffs := diffMappingResults(oldContent, newContent, options.StripTrailingCR)
if actualChanges(diffs) > 0 {
report.addEntry(key, options.SuppressedKinds, oldContent.Kind, options.OutputContext, diffs, "MODIFY")
var changeType string
var subjectKind string
var diffs []difflib.DiffRecord
switch {
case oldContent == nil:
changeType = "ADD"
if newContent != nil {
subjectKind = newContent.Kind
}
if !options.StructuredOutput() && newContent != nil {
emptyMapping := &manifest.MappingResult{}
diffs = diffMappingResults(emptyMapping, newContent, options.StripTrailingCR)
}
case newContent == nil:
changeType = "REMOVE"
if oldContent != nil {
subjectKind = oldContent.Kind
}
if !options.StructuredOutput() && oldContent != nil {
emptyMapping := &manifest.MappingResult{}
diffs = diffMappingResults(oldContent, emptyMapping, options.StripTrailingCR)
}
default:
changeType = "MODIFY"
subjectKind = oldContent.Kind
if !options.StructuredOutput() {
diffs = diffMappingResults(oldContent, newContent, options.StripTrailingCR)
if actualChanges(diffs) == 0 {
return
}
}
}

var structured *StructuredEntry
if options.StructuredOutput() {
entry, err := buildStructuredEntry(key, changeType, subjectKind, options.SuppressedKinds, oldContent, newContent)
if err != nil {
// Log warning and omit field-level changes for this entry
// printStructuredReport() will still output a basic entry with name and changeType
fmt.Fprintf(os.Stderr, "Warning: failed to build structured entry for %s (kind: %s, changeType: %s): %v\n",
Copy link
Collaborator

@yxxhero yxxhero Jan 24, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

could we ignore this error?

Copy link
Author

@madhunzv madhunzv Jan 24, 2026 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Quick clarification: the warning goes to stderr (not stdout), so it doesn't affect the JSON output.
I kept it to help users understand why field-level changes might be missing when YAML parsing fails.

Would you prefer I keep it or remove it entirely?

key, subjectKind, changeType, err)
} else {
if changeType == "MODIFY" && !entry.ChangesSuppressed && len(entry.Changes) == 0 {
return
}
structured = entry
}
}

report.addEntry(key, options.SuppressedKinds, subjectKind, options.OutputContext, diffs, changeType, structured)
}

func preHandleSecrets(old, new *manifest.MappingResult) (v1.Secret, v1.Secret, error, error) {
Expand Down
Loading
Loading