chartdelta 0.5.1__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,18 @@
1
+ name: ci
2
+ on:
3
+ push: { branches: [main] }
4
+ pull_request:
5
+ jobs:
6
+ test:
7
+ runs-on: ubuntu-latest
8
+ strategy:
9
+ matrix:
10
+ python: ["3.9", "3.13"]
11
+ steps:
12
+ - uses: actions/checkout@v4
13
+ - uses: actions/setup-python@v5
14
+ with: { python-version: "${{ matrix.python }}" }
15
+ - uses: azure/setup-helm@v4
16
+ - run: pip install -e ".[dev]"
17
+ - run: pytest -q
18
+ - run: CHARTDELTA_REAL_HELM=1 pytest -q
@@ -0,0 +1,17 @@
1
+ # Publishes to PyPI when a GitHub release is published.
2
+ # One-time setup: on pypi.org add a "trusted publisher" for this repo,
3
+ # workflow "release.yml", environment "pypi". No API token needed.
4
+ name: release
5
+ on:
6
+ release: { types: [published] }
7
+ jobs:
8
+ publish:
9
+ runs-on: ubuntu-latest
10
+ environment: pypi
11
+ permissions: { id-token: write }
12
+ steps:
13
+ - uses: actions/checkout@v4
14
+ - uses: actions/setup-python@v5
15
+ with: { python-version: "3.13" }
16
+ - run: pip install build && python -m build
17
+ - uses: pypa/gh-action-pypi-publish@release/v1
@@ -0,0 +1,6 @@
1
+ __pycache__/
2
+ *.egg-info/
3
+ dist/
4
+ .venv/
5
+ .pytest_cache/
6
+ .chartdelta/
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Radhana
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,214 @@
1
+ Metadata-Version: 2.5
2
+ Name: chartdelta
3
+ Version: 0.5.1
4
+ Summary: Render a Helm chart with real values and diff the manifests against the original (git ref, another chart, or other values). No cluster needed.
5
+ Project-URL: Homepage, https://github.com/YOUR_GITHUB_USER/chartdelta
6
+ Author: Radhana
7
+ License-Expression: MIT
8
+ License-File: LICENSE
9
+ Keywords: argocd,claude-skill,diff,gitops,helm,kubernetes
10
+ Classifier: Environment :: Console
11
+ Classifier: Intended Audience :: Developers
12
+ Classifier: Programming Language :: Python :: 3
13
+ Classifier: Topic :: System :: Systems Administration
14
+ Requires-Python: >=3.9
15
+ Requires-Dist: pyyaml>=6.0
16
+ Provides-Extra: dev
17
+ Requires-Dist: pytest>=7; extra == 'dev'
18
+ Description-Content-Type: text/markdown
19
+
20
+ # chartdelta
21
+
22
+ See what your Helm chart change **actually renders to**, before you commit it.
23
+
24
+ `chartdelta` renders a chart twice with `helm template` — once as it was (the
25
+ original) and once as it is now (your modifications) — and shows a
26
+ per-resource diff of the manifests. No cluster, no installed release, no Helm
27
+ plugin: just `helm`, `git`, and this CLI.
28
+
29
+ ```console
30
+ $ chartdelta diff charts/app1 -f envs/prod.yaml
31
+ HEAD@3f2a9c1e -> working tree
32
+ 0 added, 0 removed, 1 changed, 7 unchanged
33
+
34
+ ~ Deployment/release-app1 [app1/templates/deployment.yaml]
35
+
36
+ --- HEAD@3f2a9c1e: Deployment/release-app1
37
+ +++ working tree: Deployment/release-app1
38
+ @@ -22,7 +22,7 @@
39
+ resources:
40
+ limits:
41
+ - memory: 512Mi
42
+ + memory: 1Gi
43
+ ```
44
+
45
+ It also ships a [Claude skill](skills/helm-chart-diff/SKILL.md) so Claude can
46
+ read a chart, run the diff, and explain the impact.
47
+
48
+ ## Install
49
+
50
+ ```sh
51
+ pipx install chartdelta # or: uv tool install chartdelta
52
+ uvx chartdelta --help # run without installing
53
+ ```
54
+
55
+ Requires Python 3.9+, `helm` 3 on `PATH`, and `git` for git-based comparisons.
56
+
57
+ ## What is "the original"?
58
+
59
+ | You want to compare… | Command |
60
+ |---|---|
61
+ | uncommitted changes vs. last commit (default) | `chartdelta diff CHART -f values.yaml` |
62
+ | your branch vs. main, like a merge request | `chartdelta diff CHART -f values.yaml --base origin/main --merge-base` |
63
+ | against any tag / commit | `chartdelta diff CHART --base v1.4.0` |
64
+ | two values files on the same chart | `chartdelta diff CHART -f new.yaml --base-values old.yaml` |
65
+ | two chart directories | `chartdelta diff ./new-chart --base-chart ./old-chart -f values.yaml` |
66
+
67
+ In git mode, both the chart **and** the `-f` values files are taken as they
68
+ were at the base ref, so a change to either shows up. A values file that did
69
+ not exist at the base ref (or lives outside the repo) is used on both sides.
70
+
71
+ ## Useful options
72
+
73
+ - `-o text|markdown|json` — `markdown` is made for merge-request comments,
74
+ `json` includes `changedPaths` per resource (e.g.
75
+ `spec.template.spec.containers[name=app].image`) for tooling and AI agents.
76
+ - `--summary` — changed resources and field paths only, no diff bodies.
77
+ - `--exit-code` — exit `2` when there are differences (`0` none, `1` error).
78
+ - `--ignore-version-labels` — hide `helm.sh/chart` / `app.kubernetes.io/version`
79
+ churn after a chart version bump. `--ignore-label KEY` for anything else.
80
+ - `--kind Deployment` — restrict to some kinds.
81
+ - `--set`, `--set-string`, `-r/--release`, `-n/--namespace`, `--kube-version`,
82
+ `--api-versions`, `--include-crds`, `--no-hooks`, `--helm-arg` — forwarded
83
+ to `helm template` on both sides.
84
+ - `--build-deps` — run `helm dependency build` when subcharts are missing.
85
+ If the base side's dependencies are unchanged, your already-downloaded
86
+ `charts/` is reused, with no network access.
87
+ - Secret values are replaced by a short hash by default, so you see *that* a
88
+ secret changed without printing it. `--show-secrets` disables this.
89
+
90
+ `chartdelta inspect CHART [-f values.yaml]` summarises a chart: metadata,
91
+ dependencies, top-level values, templates, and the resources it renders.
92
+
93
+ ## Rendering with your values
94
+
95
+ ```sh
96
+ chartdelta render charts/app1 -f envs/prod.yaml # all manifests
97
+ chartdelta render charts/app1 -f envs/prod.yaml --kind Deployment --name api
98
+ chartdelta render charts/app1 -f envs/prod.yaml --list # just the resource list
99
+ ```
100
+
101
+ This is `helm template` with conveniences: filter by kind and name, keys in a
102
+ stable sorted order, each manifest labelled with its source template, and
103
+ Secret values replaced by hashes unless `--show-secrets` is given. Use
104
+ `-o json` for tooling. The output is normalised YAML (comments from the
105
+ templates are dropped), so use plain `helm template` when you need the raw
106
+ text.
107
+
108
+ ## Reviewing a chart upgrade
109
+
110
+ ```sh
111
+ chartdelta upgrade kyverno/kyverno --from 3.2.6 --to 3.3.4 -f values.yaml
112
+ chartdelta upgrade oci://registry.example.com/charts/app --from 1.4.0 --to 2.0.0 -f values.yaml
113
+ chartdelta upgrade --from ./old-chart --to ./new-chart -f values.yaml # already unpacked
114
+ ```
115
+
116
+ Pulls both versions with `helm pull` (no manual download or unzip), renders
117
+ each with **your** values, and reports:
118
+
119
+ - **Chart metadata**: appVersion, `kubeVersion` constraint, subchart versions.
120
+ - **CRDs**: added / removed / changed, and for each changed CRD the API
121
+ versions added or removed, versions no longer served, storage-version
122
+ changes, and how many schema fields changed. Each is marked `BREAKING`
123
+ (a version clients can use today is removed or no longer served) or
124
+ `CHECK` (storage version moved, or an unserved version was removed). Full CRD diffs only with `--crd-diff`.
125
+ - **Rendered resources**: the per-resource diff, with version-label churn
126
+ hidden by default.
127
+ - **Default values**: defaults that were removed, changed or added.
128
+ - **Your values**: keys in your values files that the new version no longer
129
+ reads (renamed or removed options), separated from keys that were already
130
+ ignored before.
131
+
132
+ `--summary` drops the diff bodies, `-o markdown|json` as usual, `--keep DIR`
133
+ keeps the pulled charts, `--exit-code` exits 2 on a breaking CRD change or a
134
+ values key that stops working.
135
+
136
+ Remember that `helm upgrade` does not update CRDs shipped in a chart's
137
+ `crds/` directory; they must be applied separately (Argo CD applies them on
138
+ sync). This command compares charts, not the cluster: it cannot see which CRD
139
+ versions your existing objects are stored at.
140
+
141
+ ## Catching values that Helm silently ignores
142
+
143
+ Helm accepts any key in a values file. A typo (`replicas` instead of
144
+ `replicaCount`) or a wrongly nested key is merged and never read, unless the
145
+ chart ships a `values.schema.json`.
146
+
147
+ ```console
148
+ $ chartdelta check-values charts/app1 -f envs/prod.yaml
149
+ IGNORED replicas (envs/prod.yaml)
150
+ not in the chart's values.yaml and not referenced by any template; removing it does not change the rendered output
151
+ did you mean 'replicaCount'?
152
+ IGNORED tag (envs/prod.yaml)
153
+ ...
154
+ 'tag' exists at 'image.tag' — wrong nesting?
155
+ ```
156
+
157
+ A key is reported when it is missing from the chart's default values, no
158
+ template references `.Values.<path>`, **and** rendering the chart without it
159
+ gives identical output. Subchart values are checked against the subchart
160
+ (when it is present in `charts/`), `global` is skipped, and maps whose default
161
+ is `{}` (annotations, nodeSelector, …) are treated as free-form. Structural
162
+ type mismatches (map vs. scalar, list, bool) are reported too. Exit code is
163
+ `2` when problems are found, so it works as a CI gate. `chartdelta diff
164
+ --check-values` prints the same warnings alongside a diff.
165
+
166
+ Not covered: keys inside lists (e.g. a typo in an `env` entry), and keys that
167
+ are valid but currently behind a disabled feature are not reported.
168
+
169
+ ## GitLab CI example
170
+
171
+ ```yaml
172
+ helm-diff:
173
+ image: python:3.12
174
+ script:
175
+ - curl -fsSL https://raw.githubusercontent.com/helm/helm/main/scripts/get-helm-3 | bash
176
+ - pip install chartdelta
177
+ - git fetch origin "$CI_MERGE_REQUEST_TARGET_BRANCH_NAME"
178
+ - chartdelta diff charts/app1 -f envs/prod.yaml
179
+ --base "origin/$CI_MERGE_REQUEST_TARGET_BRANCH_NAME" --merge-base -o markdown > helm-diff.md
180
+ artifacts:
181
+ paths: [helm-diff.md]
182
+ rules:
183
+ - if: $CI_PIPELINE_SOURCE == "merge_request_event"
184
+ ```
185
+
186
+ ## How it differs from the helm-diff plugin
187
+
188
+ [helm-diff](https://github.com/databus23/helm-diff) compares a chart against a
189
+ **release installed in a cluster**. `chartdelta` compares two **renderings**
190
+ (git ref, directory, or values), which fits GitOps workflows where Argo CD or
191
+ Flux does the deploy and you want to review the change at merge-request time.
192
+ It does not see live-cluster drift.
193
+
194
+ ## Limitations
195
+
196
+ - Output depends on `helm template`, so `lookup` calls return empty and
197
+ `.Capabilities` come from `--kube-version` / `--api-versions`, not a cluster.
198
+ - Charts are local directories; pull OCI/repo charts first (`helm pull --untar`).
199
+
200
+ ## Using the Claude skill
201
+
202
+ Copy `skills/helm-chart-diff` into your skills folder (for Claude Code:
203
+ `~/.claude/skills/` or a project's `.claude/skills/`), then ask things like
204
+ "what does my change to this chart actually do with prod values?".
205
+
206
+ ## Development
207
+
208
+ ```sh
209
+ pip install -e ".[dev]"
210
+ pytest # uses a small helm stand-in
211
+ CHARTDELTA_REAL_HELM=1 pytest # runs the same suite against real helm
212
+ ```
213
+
214
+ MIT licensed.
@@ -0,0 +1,195 @@
1
+ # chartdelta
2
+
3
+ See what your Helm chart change **actually renders to**, before you commit it.
4
+
5
+ `chartdelta` renders a chart twice with `helm template` — once as it was (the
6
+ original) and once as it is now (your modifications) — and shows a
7
+ per-resource diff of the manifests. No cluster, no installed release, no Helm
8
+ plugin: just `helm`, `git`, and this CLI.
9
+
10
+ ```console
11
+ $ chartdelta diff charts/app1 -f envs/prod.yaml
12
+ HEAD@3f2a9c1e -> working tree
13
+ 0 added, 0 removed, 1 changed, 7 unchanged
14
+
15
+ ~ Deployment/release-app1 [app1/templates/deployment.yaml]
16
+
17
+ --- HEAD@3f2a9c1e: Deployment/release-app1
18
+ +++ working tree: Deployment/release-app1
19
+ @@ -22,7 +22,7 @@
20
+ resources:
21
+ limits:
22
+ - memory: 512Mi
23
+ + memory: 1Gi
24
+ ```
25
+
26
+ It also ships a [Claude skill](skills/helm-chart-diff/SKILL.md) so Claude can
27
+ read a chart, run the diff, and explain the impact.
28
+
29
+ ## Install
30
+
31
+ ```sh
32
+ pipx install chartdelta # or: uv tool install chartdelta
33
+ uvx chartdelta --help # run without installing
34
+ ```
35
+
36
+ Requires Python 3.9+, `helm` 3 on `PATH`, and `git` for git-based comparisons.
37
+
38
+ ## What is "the original"?
39
+
40
+ | You want to compare… | Command |
41
+ |---|---|
42
+ | uncommitted changes vs. last commit (default) | `chartdelta diff CHART -f values.yaml` |
43
+ | your branch vs. main, like a merge request | `chartdelta diff CHART -f values.yaml --base origin/main --merge-base` |
44
+ | against any tag / commit | `chartdelta diff CHART --base v1.4.0` |
45
+ | two values files on the same chart | `chartdelta diff CHART -f new.yaml --base-values old.yaml` |
46
+ | two chart directories | `chartdelta diff ./new-chart --base-chart ./old-chart -f values.yaml` |
47
+
48
+ In git mode, both the chart **and** the `-f` values files are taken as they
49
+ were at the base ref, so a change to either shows up. A values file that did
50
+ not exist at the base ref (or lives outside the repo) is used on both sides.
51
+
52
+ ## Useful options
53
+
54
+ - `-o text|markdown|json` — `markdown` is made for merge-request comments,
55
+ `json` includes `changedPaths` per resource (e.g.
56
+ `spec.template.spec.containers[name=app].image`) for tooling and AI agents.
57
+ - `--summary` — changed resources and field paths only, no diff bodies.
58
+ - `--exit-code` — exit `2` when there are differences (`0` none, `1` error).
59
+ - `--ignore-version-labels` — hide `helm.sh/chart` / `app.kubernetes.io/version`
60
+ churn after a chart version bump. `--ignore-label KEY` for anything else.
61
+ - `--kind Deployment` — restrict to some kinds.
62
+ - `--set`, `--set-string`, `-r/--release`, `-n/--namespace`, `--kube-version`,
63
+ `--api-versions`, `--include-crds`, `--no-hooks`, `--helm-arg` — forwarded
64
+ to `helm template` on both sides.
65
+ - `--build-deps` — run `helm dependency build` when subcharts are missing.
66
+ If the base side's dependencies are unchanged, your already-downloaded
67
+ `charts/` is reused, with no network access.
68
+ - Secret values are replaced by a short hash by default, so you see *that* a
69
+ secret changed without printing it. `--show-secrets` disables this.
70
+
71
+ `chartdelta inspect CHART [-f values.yaml]` summarises a chart: metadata,
72
+ dependencies, top-level values, templates, and the resources it renders.
73
+
74
+ ## Rendering with your values
75
+
76
+ ```sh
77
+ chartdelta render charts/app1 -f envs/prod.yaml # all manifests
78
+ chartdelta render charts/app1 -f envs/prod.yaml --kind Deployment --name api
79
+ chartdelta render charts/app1 -f envs/prod.yaml --list # just the resource list
80
+ ```
81
+
82
+ This is `helm template` with conveniences: filter by kind and name, keys in a
83
+ stable sorted order, each manifest labelled with its source template, and
84
+ Secret values replaced by hashes unless `--show-secrets` is given. Use
85
+ `-o json` for tooling. The output is normalised YAML (comments from the
86
+ templates are dropped), so use plain `helm template` when you need the raw
87
+ text.
88
+
89
+ ## Reviewing a chart upgrade
90
+
91
+ ```sh
92
+ chartdelta upgrade kyverno/kyverno --from 3.2.6 --to 3.3.4 -f values.yaml
93
+ chartdelta upgrade oci://registry.example.com/charts/app --from 1.4.0 --to 2.0.0 -f values.yaml
94
+ chartdelta upgrade --from ./old-chart --to ./new-chart -f values.yaml # already unpacked
95
+ ```
96
+
97
+ Pulls both versions with `helm pull` (no manual download or unzip), renders
98
+ each with **your** values, and reports:
99
+
100
+ - **Chart metadata**: appVersion, `kubeVersion` constraint, subchart versions.
101
+ - **CRDs**: added / removed / changed, and for each changed CRD the API
102
+ versions added or removed, versions no longer served, storage-version
103
+ changes, and how many schema fields changed. Each is marked `BREAKING`
104
+ (a version clients can use today is removed or no longer served) or
105
+ `CHECK` (storage version moved, or an unserved version was removed). Full CRD diffs only with `--crd-diff`.
106
+ - **Rendered resources**: the per-resource diff, with version-label churn
107
+ hidden by default.
108
+ - **Default values**: defaults that were removed, changed or added.
109
+ - **Your values**: keys in your values files that the new version no longer
110
+ reads (renamed or removed options), separated from keys that were already
111
+ ignored before.
112
+
113
+ `--summary` drops the diff bodies, `-o markdown|json` as usual, `--keep DIR`
114
+ keeps the pulled charts, `--exit-code` exits 2 on a breaking CRD change or a
115
+ values key that stops working.
116
+
117
+ Remember that `helm upgrade` does not update CRDs shipped in a chart's
118
+ `crds/` directory; they must be applied separately (Argo CD applies them on
119
+ sync). This command compares charts, not the cluster: it cannot see which CRD
120
+ versions your existing objects are stored at.
121
+
122
+ ## Catching values that Helm silently ignores
123
+
124
+ Helm accepts any key in a values file. A typo (`replicas` instead of
125
+ `replicaCount`) or a wrongly nested key is merged and never read, unless the
126
+ chart ships a `values.schema.json`.
127
+
128
+ ```console
129
+ $ chartdelta check-values charts/app1 -f envs/prod.yaml
130
+ IGNORED replicas (envs/prod.yaml)
131
+ not in the chart's values.yaml and not referenced by any template; removing it does not change the rendered output
132
+ did you mean 'replicaCount'?
133
+ IGNORED tag (envs/prod.yaml)
134
+ ...
135
+ 'tag' exists at 'image.tag' — wrong nesting?
136
+ ```
137
+
138
+ A key is reported when it is missing from the chart's default values, no
139
+ template references `.Values.<path>`, **and** rendering the chart without it
140
+ gives identical output. Subchart values are checked against the subchart
141
+ (when it is present in `charts/`), `global` is skipped, and maps whose default
142
+ is `{}` (annotations, nodeSelector, …) are treated as free-form. Structural
143
+ type mismatches (map vs. scalar, list, bool) are reported too. Exit code is
144
+ `2` when problems are found, so it works as a CI gate. `chartdelta diff
145
+ --check-values` prints the same warnings alongside a diff.
146
+
147
+ Not covered: keys inside lists (e.g. a typo in an `env` entry), and keys that
148
+ are valid but currently behind a disabled feature are not reported.
149
+
150
+ ## GitLab CI example
151
+
152
+ ```yaml
153
+ helm-diff:
154
+ image: python:3.12
155
+ script:
156
+ - curl -fsSL https://raw.githubusercontent.com/helm/helm/main/scripts/get-helm-3 | bash
157
+ - pip install chartdelta
158
+ - git fetch origin "$CI_MERGE_REQUEST_TARGET_BRANCH_NAME"
159
+ - chartdelta diff charts/app1 -f envs/prod.yaml
160
+ --base "origin/$CI_MERGE_REQUEST_TARGET_BRANCH_NAME" --merge-base -o markdown > helm-diff.md
161
+ artifacts:
162
+ paths: [helm-diff.md]
163
+ rules:
164
+ - if: $CI_PIPELINE_SOURCE == "merge_request_event"
165
+ ```
166
+
167
+ ## How it differs from the helm-diff plugin
168
+
169
+ [helm-diff](https://github.com/databus23/helm-diff) compares a chart against a
170
+ **release installed in a cluster**. `chartdelta` compares two **renderings**
171
+ (git ref, directory, or values), which fits GitOps workflows where Argo CD or
172
+ Flux does the deploy and you want to review the change at merge-request time.
173
+ It does not see live-cluster drift.
174
+
175
+ ## Limitations
176
+
177
+ - Output depends on `helm template`, so `lookup` calls return empty and
178
+ `.Capabilities` come from `--kube-version` / `--api-versions`, not a cluster.
179
+ - Charts are local directories; pull OCI/repo charts first (`helm pull --untar`).
180
+
181
+ ## Using the Claude skill
182
+
183
+ Copy `skills/helm-chart-diff` into your skills folder (for Claude Code:
184
+ `~/.claude/skills/` or a project's `.claude/skills/`), then ask things like
185
+ "what does my change to this chart actually do with prod values?".
186
+
187
+ ## Development
188
+
189
+ ```sh
190
+ pip install -e ".[dev]"
191
+ pytest # uses a small helm stand-in
192
+ CHARTDELTA_REAL_HELM=1 pytest # runs the same suite against real helm
193
+ ```
194
+
195
+ MIT licensed.
@@ -0,0 +1,38 @@
1
+ [build-system]
2
+ requires = ["hatchling"]
3
+ build-backend = "hatchling.build"
4
+
5
+ [project]
6
+ name = "chartdelta"
7
+ dynamic = ["version"]
8
+ description = "Render a Helm chart with real values and diff the manifests against the original (git ref, another chart, or other values). No cluster needed."
9
+ readme = "README.md"
10
+ license = "MIT"
11
+ requires-python = ">=3.9"
12
+ authors = [{ name = "Radhana" }]
13
+ keywords = ["helm", "kubernetes", "diff", "gitops", "argocd", "claude-skill"]
14
+ classifiers = [
15
+ "Environment :: Console",
16
+ "Intended Audience :: Developers",
17
+ "Topic :: System :: Systems Administration",
18
+ "Programming Language :: Python :: 3",
19
+ ]
20
+ dependencies = ["PyYAML>=6.0"]
21
+
22
+ [project.optional-dependencies]
23
+ dev = ["pytest>=7"]
24
+
25
+ [project.scripts]
26
+ chartdelta = "chartdelta.cli:main"
27
+
28
+ [project.urls]
29
+ Homepage = "https://github.com/YOUR_GITHUB_USER/chartdelta"
30
+
31
+ [tool.hatch.version]
32
+ path = "src/chartdelta/__init__.py"
33
+
34
+ [tool.hatch.build.targets.wheel]
35
+ packages = ["src/chartdelta"]
36
+
37
+ [tool.pytest.ini_options]
38
+ testpaths = ["tests"]
@@ -0,0 +1,161 @@
1
+ ---
2
+ name: helm-chart-diff
3
+ description: Read a Helm chart, render it with the real values files (helm template), and diff the rendered Kubernetes manifests between the user's modifications and the original (git ref, other values file, or other chart directory). Use whenever the user changes a Helm chart or values file and asks what the change does, wants a helm diff without a cluster, wants a chart or merge request reviewed, or asks "what will this render to" for a given environment.
4
+ ---
5
+
6
+ # Helm chart diff
7
+
8
+ Answer "what does this chart change actually do?" from rendered manifests, not
9
+ from reading templates. Uses the `chartdelta` CLI, which runs `helm template`
10
+ for both sides and diffs per resource. No cluster access is needed or used.
11
+
12
+ ## 1. Check prerequisites
13
+
14
+ ```sh
15
+ helm version --short && chartdelta --version
16
+ ```
17
+
18
+ - `chartdelta` missing: use `uvx chartdelta ...` if `uv` exists, otherwise
19
+ `pipx install chartdelta` (or `pip install chartdelta`).
20
+ - `helm` missing: tell the user; do not try to emulate templating by hand.
21
+
22
+ ## 2. Find the chart and the values
23
+
24
+ - The chart is the directory containing `Chart.yaml`. If several exist, pick
25
+ the one the user named or whose files changed (`git status --short`).
26
+ - Use the values files the user actually deploys with. Look for
27
+ `values-<env>.yaml`, an `envs/` folder, or Argo CD `Application` manifests
28
+ (`spec.source.helm.valueFiles`, `releaseName`, `parameters`). Pass them with
29
+ `-f` in the same order. If it is unclear which environment matters, ask once,
30
+ or run each environment separately.
31
+ - Match release name and namespace when known (`-r`, `-n`), since both appear
32
+ in rendered names.
33
+
34
+ ## 3. Read the chart
35
+
36
+ ```sh
37
+ chartdelta inspect <chart> -f <values> -o json
38
+ ```
39
+
40
+ Gives metadata, dependencies, top-level values, templates and the rendered
41
+ resource list. Open individual templates only where the diff needs explaining.
42
+
43
+ ## 4. Render the manifests when asked
44
+
45
+ When the user wants to see what the chart renders to with their values (not a
46
+ comparison), or you need the full manifest to explain a diff:
47
+
48
+ ```sh
49
+ chartdelta render <chart> -f <values> --list # what gets created
50
+ chartdelta render <chart> -f <values> --kind Deployment --name <text>
51
+ chartdelta render <chart> -f <values> # everything
52
+ ```
53
+
54
+ - Start with `--list`, then print only the resources that matter; a full
55
+ render of a large chart is long. To hand over the full output, redirect it
56
+ to a file (`> rendered.yaml`) and give the user the file.
57
+ - Secret values are shown as hashes. Do not add `--show-secrets` unless asked.
58
+ - A render error is the answer: show helm's message, the template and line it
59
+ names, and the value that caused it.
60
+ - Output is normalised (sorted keys, no comments). If the user needs helm's
61
+ raw output, run `helm template <release> <chart> -f <values>` directly.
62
+
63
+ ## 5. Check the values files for ignored keys
64
+
65
+ ```sh
66
+ chartdelta check-values <chart> -f <values> -o json
67
+ ```
68
+
69
+ Helm silently accepts unknown keys, so run this whenever the user edited a
70
+ values file, and always when a diff comes back empty or smaller than expected.
71
+ Exit code 2 means findings:
72
+
73
+ - `unknown-key` with `noEffect: true`: the key is not read by the chart and
74
+ removing it changes nothing. Report it as ignored and pass on `suggestion`
75
+ (typo or wrong nesting).
76
+ - `unknown-key` with `noEffect: null`: static result only (the chart did not
77
+ render, or `--no-render`). Say it is likely ignored, not certain.
78
+ - `type-mismatch`: the value has a different shape than the chart default.
79
+
80
+ Keys inside lists are not checked; read the template if one is in doubt.
81
+
82
+ ## 6. Run the diff
83
+
84
+ Choose the base to match what the user means by "original":
85
+
86
+ | Situation | Command |
87
+ |---|---|
88
+ | Uncommitted edits vs. last commit | `chartdelta diff <chart> -f <values> -o json` |
89
+ | Branch vs. main (merge request review) | add `--base origin/main --merge-base` |
90
+ | Against a tag or commit | add `--base <ref>` |
91
+ | Two values files, same chart | `chartdelta diff <chart> -f new.yaml --base-values old.yaml -o json` |
92
+ | Two chart directories | `chartdelta diff <new> --base-chart <old> -f <values> -o json` |
93
+
94
+ Notes:
95
+ - Start with `-o json --summary` on large charts, then fetch full diffs for
96
+ the interesting kinds with `--kind`.
97
+ - After a chart version bump, add `--ignore-version-labels`.
98
+ - "declares dependencies but charts/ is empty": re-run with `--build-deps`.
99
+ - Exit code 1 means a render or git error. Show the helm error and which side
100
+ (base or target) failed; a base-side failure means the original was already
101
+ broken with these values.
102
+ - Never pass `--show-secrets` unless the user asks.
103
+
104
+ ## 7. Chart version upgrades
105
+
106
+ When the user is moving a third-party chart from one version to another, do
107
+ not pull and unpack by hand. One command pulls both versions and compares
108
+ them with the user's values:
109
+
110
+ ```sh
111
+ chartdelta upgrade <repo/chart | oci://...> --from <current> --to <target> -f <values> -o json --summary
112
+ ```
113
+
114
+ - Find the current version in the Argo CD `Application` (`targetRevision`),
115
+ `Chart.yaml` dependencies, or `helm list`. Add `--repo <url>` when the repo
116
+ is not added locally. Local directories also work: `--from ./old --to ./new`.
117
+ - Then report in this order:
118
+ 1. `crds` by `severity`. `breaking`: an API version in use today is removed
119
+ or no longer served, or the CRD is removed; manifests and objects must
120
+ move to a served version before the upgrade, and an intermediate chart
121
+ version that serves both is usually the way. `check`: the storage
122
+ version moved or an unserved version was removed; safe unless
123
+ `kubectl get crd <name> -o jsonpath='{.status.storedVersions}'` still
124
+ lists a removed version. Do not call a `check` item breaking.
125
+ 2. `valuesFindings` with `newInThisUpgrade: true`: the user's overrides that
126
+ the new version ignores. These are the renamed options; give the
127
+ suggested new key.
128
+ 3. `resources`: what changes in the cluster, as in the Report step.
129
+ 4. `defaults.changed` / `removed` that the user does not override, since
130
+ these change behaviour without any edit on their side.
131
+ 5. `metadataChanges.kubeVersion` and subchart bumps.
132
+ - CRDs in a chart's `crds/` directory are not touched by `helm upgrade`. With
133
+ Argo CD they are applied on sync; large CRDs may need server-side apply.
134
+ - Fetch full text only where needed: re-run without `--summary`, or with
135
+ `--crd-diff` for one CRD.
136
+ - This compares charts only. Always recommend reading the chart's upgrade
137
+ notes or changelog for manual steps the manifests cannot show.
138
+
139
+ ## 8. Report
140
+
141
+ Lead with the outcome, then the evidence:
142
+
143
+ 1. One line: N added / removed / changed, and against which base.
144
+ 2. Per changed resource: what changed in plain terms, using `changedPaths`
145
+ (e.g. "Deployment/app: memory limit 512Mi → 1Gi").
146
+ 3. Call out operational impact when it applies:
147
+ - a change under `spec.template` of a Deployment/StatefulSet/DaemonSet
148
+ rolls the pods; a ConfigMap/Secret change does not, unless a checksum
149
+ annotation changed too
150
+ - removed resources will be deleted (pruned, if GitOps pruning is on)
151
+ - changes to immutable fields (`spec.selector`, Service `clusterIP`,
152
+ StatefulSet `volumeClaimTemplates`, Job spec) need a recreate
153
+ - changes to replicas, resources, probes, PDBs, affinity, HPA bounds
154
+ - new or changed RBAC, hostPath, privileged or host-network settings
155
+ 4. Unexpected changes: anything in the diff the user's edit does not explain.
156
+ 5. If there are no differences, say so and name the likely reason (the value
157
+ is unused by any template, overridden by a later values file, or behind a
158
+ disabled condition).
159
+
160
+ Show raw diff hunks only for the parts that matter; offer `-o markdown` output
161
+ if the user wants something to paste into a merge request.
@@ -0,0 +1,3 @@
1
+ """chartdelta: diff what your Helm chart changes actually render to."""
2
+
3
+ __version__ = "0.5.1"