-
Notifications
You must be signed in to change notification settings - Fork 279
/
README.md
365 lines (289 loc) · 21 KB
/
README.md
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
# Helm Diff Plugin
[](https://goreportcard.com/report/github.com/databus23/helm-diff)
[](https://godoc.org/github.com/databus23/helm-diff)
[](https://github.com/databus23/helm-diff/blob/master/LICENSE)
This is a Helm plugin giving you a preview of what a `helm upgrade` would change.
It basically generates a diff between the latest deployed version of a release
and a `helm upgrade --debug --dry-run`. This can also be used to compare two
revisions/versions of your helm release.
<a href="https://asciinema.org/a/105326" target="_blank"><img src="https://asciinema.org/a/105326.png" /></a>
## Install
### Using Helm plugin manager (> 2.3.x)
```shell
helm plugin install https://github.com/databus23/helm-diff
```
### Pre Helm 2.3.0 Installation
Pick a release tarball from the [releases](https://github.com/databus23/helm-diff/releases) page.
Unpack the tarball in your helm plugins directory (`$(helm home)/plugins`).
E.g.
```
curl -L $TARBALL_URL | tar -C $(helm home)/plugins -xzv
```
### From Source
#### Prerequisites
- GoLang `>= 1.21`
Make sure you do not have a version of `helm-diff` installed. You can remove it by running `helm plugin uninstall diff`
#### Installation Steps
The first step is to download the repository and enter the directory. You can do this via `git clone` or downloading and extracting the release. If you clone via git, remember to checkout the latest tag for the latest release.
Next, install the plugin into helm.
```bash
make install/helm3
```
## Usage
```
The Helm Diff Plugin
* Shows a diff explaining what a helm upgrade would change:
This fetches the currently deployed version of a release
and compares it to a local chart plus values. This can be
used to visualize what changes a helm upgrade will perform.
* Shows a diff explaining what had changed between the two revisions:
This fetches previously deployed versions of a release
and compares them. This can be used to visualize what changes
were made during revision change.
* Shows a diff explaining what a helm rollback would change:
This fetches the currently deployed version of a release
and compares it to the previously deployed version of the release that you
want to rollback. This can be used to visualize what changes a
helm rollback will perform.
Usage:
diff [flags]
diff [command]
Available Commands:
completion Generate the autocompletion script for the specified shell
release Shows diff between release's manifests
revision Shows diff between revision's manifests
rollback Show a diff explaining what a helm rollback could perform
upgrade Show a diff explaining what a helm upgrade would change.
version Show version of the helm diff plugin
Flags:
--allow-unreleased enables diffing of releases that are not yet deployed via Helm
-a, --api-versions stringArray Kubernetes api versions used for Capabilities.APIVersions
--color color output. You can control the value for this flag via HELM_DIFF_COLOR=[true|false]. If both --no-color and --color are unspecified, coloring enabled only when the stdout is a term and TERM is not "dumb"
-C, --context int output NUM lines of context around changes (default -1)
--detailed-exitcode return a non-zero exit code when there are changes
--devel use development versions, too. Equivalent to version '>0.0.0-0'. If --version is set, this is ignored.
--disable-openapi-validation disables rendered templates validation against the Kubernetes OpenAPI Schema
--disable-validation disables rendered templates validation against the Kubernetes cluster you are currently pointing to. This is the same validation performed on an install
--dry-run disables cluster access and show diff as if it was install. Implies --install, --reset-values, and --disable-validation
--enable-dns enable DNS lookups when rendering templates
-D, --find-renames float32 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
-h, --help help for diff
--include-tests enable the diffing of the helm test hooks
--install enables diffing of releases that are not yet deployed via Helm (equivalent to --allow-unreleased, added to match "helm upgrade --install" command
--kube-version string Kubernetes version used for Capabilities.KubeVersion
--kubeconfig string This flag is ignored, to allow passing of this top level flag to helm
--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")
--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
--reset-values reset the values to the ones built into the chart and merge in any new values
--reuse-values reuse the last release's values and merge in any new values. If '--reset-values' is specified, this is ignored
--set stringArray set values on the command line (can specify multiple or separate values with commas: key1=val1,key2=val2)
--set-file stringArray set values from respective files specified via the command line (can specify multiple or separate values with commas: key1=path1,key2=path2)
--set-string stringArray set STRING values on the command line (can specify multiple or separate values with commas: key1=val1,key2=val2)
--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')
-q, --suppress-secrets suppress secrets in the output
--three-way-merge use three-way-merge to compute patch and generate diff output
-f, --values valueFiles specify values in a YAML file (can specify multiple) (default [])
--version string specify the exact chart version to use. If this is not specified, the latest version is used
Additional help topics:
diff
Use "diff [command] --help" for more information about a command.
```
## Commands:
### upgrade:
```
$ helm diff upgrade -h
Show a diff explaining what a helm upgrade would change.
This fetches the currently deployed version of a release
and compares it to a chart plus values.
This can be used to visualize what changes a helm upgrade will
perform.
Usage:
diff upgrade [flags] [RELEASE] [CHART]
Examples:
helm diff upgrade my-release stable/postgresql --values values.yaml
# Set HELM_DIFF_IGNORE_UNKNOWN_FLAGS=true to ignore unknown flags
# It's useful when you're using `helm-diff` in a `helm upgrade` wrapper.
# See https://github.com/databus23/helm-diff/issues/278 for more information.
HELM_DIFF_IGNORE_UNKNOWN_FLAGS=true helm diff upgrade my-release stable/postgres --wait
# helm-diff disallows the use of the `lookup` function by default.
# To enable it, you must set HELM_DIFF_USE_INSECURE_SERVER_SIDE_DRY_RUN=true to
# use `helm template --dry-run=server` or
# `helm upgrade --dry-run=server` (in case you also set `HELM_DIFF_USE_UPGRADE_DRY_RUN`)
# See https://github.com/databus23/helm-diff/pull/458
# for more information.
HELM_DIFF_USE_INSECURE_SERVER_SIDE_DRY_RUN=true helm diff upgrade my-release datadog/datadog
# Set HELM_DIFF_USE_UPGRADE_DRY_RUN=true to
# use `helm upgrade --dry-run` instead of `helm template` to render manifests from the chart.
# See https://github.com/databus23/helm-diff/issues/253 for more information.
HELM_DIFF_USE_UPGRADE_DRY_RUN=true helm diff upgrade my-release datadog/datadog
# Set HELM_DIFF_THREE_WAY_MERGE=true to
# enable the three-way-merge on diff.
# This is equivalent to specifying the --three-way-merge flag.
# Read the flag usage below for more information on --three-way-merge.
HELM_DIFF_THREE_WAY_MERGE=true helm diff upgrade my-release datadog/datadog
# Set HELM_DIFF_NORMALIZE_MANIFESTS=true to
# normalize the yaml file content when using helm diff.
# This is equivalent to specifying the --normalize-manifests flag.
# Read the flag usage below for more information on --normalize-manifests.
HELM_DIFF_NORMALIZE_MANIFESTS=true helm diff upgrade my-release datadog/datadog
# Set HELM_DIFF_OUTPUT_CONTEXT=n to configure the output context to n lines.
# This is equivalent to specifying the --context flag.
# Read the flag usage below for more information on --context.
HELM_DIFF_OUTPUT_CONTEXT=5 helm diff upgrade my-release datadog/datadog
Flags:
--allow-unreleased enables diffing of releases that are not yet deployed via Helm
-a, --api-versions stringArray Kubernetes api versions used for Capabilities.APIVersions
-C, --context int output NUM lines of context around changes (default -1)
--detailed-exitcode return a non-zero exit code when there are changes
--devel use development versions, too. Equivalent to version '>0.0.0-0'. If --version is set, this is ignored.
--disable-openapi-validation disables rendered templates validation against the Kubernetes OpenAPI Schema
--disable-validation disables rendered templates validation against the Kubernetes cluster you are currently pointing to. This is the same validation performed on an install
--dry-run disables cluster access and show diff as if it was install. Implies --install, --reset-values, and --disable-validation
--enable-dns enable DNS lookups when rendering templates
-D, --find-renames float32 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
-h, --help help for upgrade
--include-tests enable the diffing of the helm test hooks
--install enables diffing of releases that are not yet deployed via Helm (equivalent to --allow-unreleased, added to match "helm upgrade --install" command
--kube-version string Kubernetes version used for Capabilities.KubeVersion
--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")
--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
--reset-values reset the values to the ones built into the chart and merge in any new values
--reuse-values reuse the last release's values and merge in any new values. If '--reset-values' is specified, this is ignored
--set stringArray set values on the command line (can specify multiple or separate values with commas: key1=val1,key2=val2)
--set-file stringArray set values from respective files specified via the command line (can specify multiple or separate values with commas: key1=path1,key2=path2)
--set-string stringArray set STRING values on the command line (can specify multiple or separate values with commas: key1=val1,key2=val2)
--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 values listed in the diff output
-q, --suppress-secrets suppress secrets in the output
--three-way-merge use three-way-merge to compute patch and generate diff output
-f, --values valueFiles specify values in a YAML file (can specify multiple) (default [])
--version string specify the exact chart version to use. If this is not specified, the latest version is used
Global Flags:
--color color output. You can control the value for this flag via HELM_DIFF_COLOR=[true|false]. If both --no-color and --color are unspecified, coloring enabled only when the stdout is a term and TERM is not "dumb"
--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"
```
### release:
```
$ helm diff release -h
This command compares the manifests details of a different releases created from the same chart
It can be used to compare the manifests of
- release1 with release2
$ helm diff release [flags] release1 release2
Example:
$ helm diff release my-prod my-stage
Usage:
diff release [flags] RELEASE release1 [release2]
Flags:
-C, --context int output NUM lines of context around changes (default -1)
--detailed-exitcode return a non-zero exit code when there are changes
-D, --find-renames float32 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
-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")
--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 values listed in the diff output
-q, --suppress-secrets suppress secrets in the output
Global Flags:
--color color output. You can control the value for this flag via HELM_DIFF_COLOR=[true|false]. If both --no-color and --color are unspecified, coloring enabled only when the stdout is a term and TERM is not "dumb"
--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"
```
### revision:
```
$ helm diff revision -h
This command compares the manifests details of a named release.
It can be used to compare the manifests of
- latest REVISION with specified REVISION
$ helm diff revision [flags] RELEASE REVISION1
Example:
$ helm diff revision my-release 2
- REVISION1 with REVISION2
$ helm diff revision [flags] RELEASE REVISION1 REVISION2
Example:
$ helm diff revision my-release 2 3
Usage:
diff revision [flags] RELEASE REVISION1 [REVISION2]
Flags:
-C, --context int output NUM lines of context around changes (default -1)
--detailed-exitcode return a non-zero exit code when there are changes
-D, --find-renames float32 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
-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")
--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 values listed in the diff output
-q, --suppress-secrets suppress secrets in the output
Global Flags:
--color color output. You can control the value for this flag via HELM_DIFF_COLOR=[true|false]. If both --no-color and --color are unspecified, coloring enabled only when the stdout is a term and TERM is not "dumb"
--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"
```
### rollback:
```
$ helm diff rollback -h
This command compares the latest manifest details of a named release
with specific revision values to rollback.
It forecasts/visualizes changes, that a helm rollback could perform.
Usage:
diff rollback [flags] [RELEASE] [REVISION]
Examples:
helm diff rollback my-release 2
Flags:
-C, --context int output NUM lines of context around changes (default -1)
--detailed-exitcode return a non-zero exit code when there are changes
-D, --find-renames float32 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
-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")
--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 values listed in the diff output
-q, --suppress-secrets suppress secrets in the output
Global Flags:
--color color output. You can control the value for this flag via HELM_DIFF_COLOR=[true|false]. If both --no-color and --color are unspecified, coloring enabled only when the stdout is a term and TERM is not "dumb"
--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"
```
## Build
Clone the repository into your `$GOPATH` and then build it.
```
$ mkdir -p $GOPATH/src/github.com/databus23/
$ cd $GOPATH/src/github.com/databus23/
$ git clone https://github.com/databus23/helm-diff.git
$ cd helm-diff
$ make install
```
The above will install this plugin into your `$HELM_HOME/plugins` directory.
### Prerequisites
- You need to have [Go](http://golang.org) installed. Make sure to set `$GOPATH`
### Running Tests
Automated tests are implemented with [*testing*](https://golang.org/pkg/testing/).
To run all tests:
```
go test -v ./...
```
## Release
Bump `version` in `plugin.yaml`:
```
$ code plugin.yaml
$ git commit -m 'Bump helm-diff version to 3.x.y'
```
Set `GITHUB_TOKEN` and run:
```
$ make docker-run-release
```