[Feature Request] Add a Kubernetes Resource Summary to the diff output

[cstanislawski]

Problem Statement

The current diff summary provides a helpful overview of which top-level Argo CD Application resources have changed.

However, it doesn't provide insight into the scope of the underlying Kubernetes resource changes within those applications.

A small change to a single Application could result in changes to dozens of Deployments, Services, and ConfigMaps. Without a resource-level summary, it's difficult to gauge the true magnitude of a pull request without expanding each section and scrolling through the entire diff.

This can make code reviews less efficient, as the full impact isn't immediately obvious.

Proposed Solution

I propose adding a new, more detailed summary that aggregates all the underlying Kubernetes resource changes (e.g., Deployments, Services, ConfigMaps) across all affected Argo CD Applications.

This new summary would be displayed at the top of the output, providing an immediate, at-a-glance view of the planned changes before the detailed diffs.

This would give reviewers an instant understanding of the plan.

Implementation Ideas

This new resource-level summary could take one of a few forms. I am open to feedback and other suggestions.

Option A: Terraform-style Summary

A simple, high-level count of all resource changes, inspired by Terraform's plan output. This is concise and easy to parse.

Example:

Resource Changes: 3 to add, 2 to change, 1 to remove.

------------------------------------------------------------------------

Option B: Detailed Table Summary

A more detailed, table-based summary that groups Kubernetes resources by their apiVersion and Kind. This provides more context while still being easy to read.

Example:

| apiVersion | Kind       | Added | Changed | Removed |
|------------|------------|-------|---------|---------|
| apps/v1    | Deployment | 1     | 1       | 0       |
| v1         | Service    | 1     | 0       | 0       |
| v1         | ConfigMap  | 0     | 0       | 1       |

---

Before I start working on an implementation, I'd like to get feedback on this proposal. Do you think this would be a useful addition? And if so, which option do you prefer?

[dag-andersen]

@cstanislawski I like the idea! I think this is useful 🚀

I think Option B would be quite hard to implement right now. The change-tracking functionality (detecting what changed) is currently handled as plain text - simply by comparing files. We don’t have any information about which individual resources changed (Deployment, ConfigMap, etc.).
Building such a mechanism would require a significant rewrite of the diffing logic.

Option A, however, should be doable in quite a few steps.

I did a bit of experimenting, and it’s fairly easy to generate something like this:

Total: 7 files changed

Modified (7):
± app1 (1l+,1l-)
± app1 (300l+)
± app2 (1l+,3l-)
± app2 (8l-)
± my-app -> my-super-app (6l+,6l-)
± my-service-staging (1l+, 1l-)
± nginx-ingress (22l+, 22l-)

Here, the numbers represent lines added and removed.

Do you think this would be an improvement? :)

[cstanislawski]

Hi @dag-andersen,

Thanks so much for the quick reply :)

The line-count summary you mocked up is a great idea and definitely an improvement over the current summary. It provides a more quantitative measure of change for each application, which is helpful.

However my primary goal was to solve a slightly different problem - giving reviewers an immediate, high-level understanding of the (types of - option 2) Kubernetes resources being changed (the blast radius), not just the volume of text changes.

However, I was thinking we could add a new analysis step before the text diff is generated. The tool already does the hard work of rendering the complete Kubernetes manifests for both branches. At the beginning of the GenerateDiff function in pkg/diff/generator.go, we have access to the baseApps and targetApps slices. The FileContent in each diff.AppInfo struct is a full-fledged, multi-document YAML string.

My thought was we could leverage the existing pkg/extract/processYamlOutput() function to parse these YAML strings into a list of unstructured.Unstructured resources for each branch. Once we have those two lists of structured resources, we could compare them e.g.: by apiVersion, kind, namespace, and name to count the adds, changes, and removals.

This approach wouldn't require changing the existing text-based diffing logic at all; it would just be a new, preliminary step that generates the resource-level summary.

With that in mind, I think that both options are achievable. What do you think of this approach? If I'm missing something, please let me know

[dag-andersen]

@cstanislawski

I think I follow your idea.
Yes, for each branch you already have a FileContent field with the full multi-document YAML.

My thought was we could leverage the existing pkg/extract/processYamlOutput() function to parse these YAML strings into a list of unstructured.Unstructured resources for each branch. Once we have those two lists of structured resources, we could compare them e.g.: by apiVersion, kind, namespace, and name to count the adds, changes, and removals.

However, how do you know which resources were changed before running the text-based diffing logic?
For example, one Application in the target-branch could render 10+ Kubernetes resources - so how do you know which of those were actually added, changed, or removed - compared to the base-branch?

I assume your approach would be to compare the fully parsed unstructured.Unstructured objects from each branch. That could work, but I do have some concerns about performance.

You are, of course, more than welcome to try it out! Maybe you have something even smarter in mind.

---

An alternative solution would be to store each extracted Kubernetes resource in its own file, along with some metadata.
For example:

/output/base-branch/my-app-name/deployment-1
/output/base-branch/my-app-name/deployment-2
/output/base-branch/my-app-name/configmap-1

This way you could build it into the text-based diffing logic. For every file where changes are detected, you would already know the corresponding name, apiVersion, and so on.

I find it quite hard to describe code or logic in plain text, so this may be a bit difficult to explain exactly what I have in mind haha