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.
- chartdelta-0.5.1/.github/workflows/ci.yml +18 -0
- chartdelta-0.5.1/.github/workflows/release.yml +17 -0
- chartdelta-0.5.1/.gitignore +6 -0
- chartdelta-0.5.1/LICENSE +21 -0
- chartdelta-0.5.1/PKG-INFO +214 -0
- chartdelta-0.5.1/README.md +195 -0
- chartdelta-0.5.1/pyproject.toml +38 -0
- chartdelta-0.5.1/skills/helm-chart-diff/SKILL.md +161 -0
- chartdelta-0.5.1/src/chartdelta/__init__.py +3 -0
- chartdelta-0.5.1/src/chartdelta/__main__.py +5 -0
- chartdelta-0.5.1/src/chartdelta/cli.py +307 -0
- chartdelta-0.5.1/src/chartdelta/core.py +683 -0
- chartdelta-0.5.1/src/chartdelta/upgrade.py +272 -0
- chartdelta-0.5.1/src/chartdelta/values_check.py +289 -0
- chartdelta-0.5.1/tests/conftest.py +103 -0
- chartdelta-0.5.1/tests/fake_helm.py +87 -0
- chartdelta-0.5.1/tests/test_chartdelta.py +432 -0
|
@@ -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
|
chartdelta-0.5.1/LICENSE
ADDED
|
@@ -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.
|