msb-public
/
helm
mirror of https://github.com/helm/helm
1
0
Code Issues Projects Releases Wiki Activity

Improve documentation for helm upgrade (#4030)

Browse Source 
Expand and clarify documentation for `helm upgrade` to include nuances
of command line values setting.

Fixes issue #4030
pull/4486/head
smurfralf 6 years ago
parent dee4bfb226
commit eeb3a1454a
3 changed files with 189 additions and 61 deletions
Show Stats Download Patch File Download Diff File

61
cmd/helm/upgrade.go
Unescape View File

@ -29,30 +29,57 @@ import (
) )
const upgradeDesc = ` const upgradeDesc = `
This command upgrades a release to a new version of a chart. This command upgrades a release to a specified version of a chart and/or updates chart values.
The upgrade arguments must be a release and chart. The chart Required arguments are release and chart. The chart argument can be one of:
argument can be either: a chart reference('stable/mariadb'), a path to a chart directory, - a chart reference('stable/mariadb'); use '--version' and '--devel' flags for versions other than latest,
a packaged chart, or a fully qualified URL. For chart references, the latest - a path to a chart directory,
version will be specified unless the '--version' flag is set. - a packaged chart,
- a fully qualified URL.
To override values in a chart, use either the '--values' flag and pass in a file To customize the chart values use any of
or use the '--set' flag and pass configuration from the command line. To force string - '--values'/'-f' to pass in a yaml file holding settings,
values in '--set', use '--set-string' instead. In case a value is large and therefore - '--set' to provide one or more key=val pairs directly,
you want not to use neither '--values' nor '--set', use '--set-file' to read the - '--set-string' to provide key=val forcing val to be stored as a string,
single large value from file. - '--set-file' to provide key=path to read a single large value from a file at path.
You can specify the '--values'/'-f' flag multiple times. The priority will be given to the To edit or append to the existing customized values add the
last (right-most) file specified. For example, if both myvalues.yaml and override.yaml '--reuse-values' flag, otherwise any existing customized values are ignored.
contained a key called 'Test', the value set in override.yaml would take precedence:
If no chart value arguments are provided on the command line, any existing customized values are carried
forward. To revert to use only values provided in the chart, use the '--reset-values' flag.
You can specify any of the chart value flags multiple times. The priority will be given to the last
(right-most) value specified. For example, if both myvalues.yaml and override.yaml contained a key
called 'Test', the value set in override.yaml would take precedence:
$ helm upgrade -f myvalues.yaml -f override.yaml redis ./redis $ helm upgrade -f myvalues.yaml -f override.yaml redis ./redis
You can specify the '--set' flag multiple times. The priority will be given to the Note that the key name provided to the '--set', '--set-string' and '--set-file' flags can reference
last (right-most) set specified. For example, if both 'bar' and 'newbar' values are structure elements. Examples:
set for a key called 'foo', the 'newbar' value would take precedence: - mybool=TRUE
- livenessProbe.timeoutSeconds=10
- metrics.annotations[0]=hey,metrics.annotations[1]=ho
which sets the top level key mybool to true, the nested timeoutSeconds to 10 and two array values respectively.
Note that the value side of the key=val provided to '--set' and '--set-string' flags will pass through
shell evaluation followed by yaml type parsing to produce the final value. This may alter inputs with
special characters in unexpected ways, for example
$ helm upgrade --set pwd=3jk$o2,z=f\30.e redis ./redis
results in "pwd: 3jk" and "z: f30.e". Use single quotes to avoid shell evaluation and argument delimiters,
and use backslash to escape yaml special characters:
$ helm upgrade --set pwd='3jk$o2z=f\\30.e' redis ./redis
which results in the expected "pwd: 3jk$o2z=f\30.e". If a single quote occurs in your value then follow
your shell convention for escaping it; for example in bash:
$ helm upgrade --set pwd='3jk$o2z=f\\30with'\''quote'
$ helm upgrade --set foo=bar --set foo=newbar redis ./redis which results in "pwd: 3jk$o2z=f\30with'quote".
` `
type upgradeCmd struct { type upgradeCmd struct {

63
docs/helm/helm_upgrade.md
Unescape View File

@ -5,30 +5,57 @@ upgrade a release
### Synopsis ### Synopsis
This command upgrades a release to a new version of a chart. This command upgrades a release to a specified version of a chart and/or updates chart values.
The upgrade arguments must be a release and chart. The chart Required arguments are release and chart. The chart argument can be one of:
argument can be either: a chart reference('stable/mariadb'), a path to a chart directory, - a chart reference('stable/mariadb'); use '--version' and '--devel' flags for versions other than latest,
a packaged chart, or a fully qualified URL. For chart references, the latest - a path to a chart directory,
version will be specified unless the '--version' flag is set. - a packaged chart,
- a fully qualified URL.
To override values in a chart, use either the '--values' flag and pass in a file To customize the chart values use any of
or use the '--set' flag and pass configuration from the command line. To force string - '--values'/'-f' to pass in a yaml file holding settings,
values in '--set', use '--set-string' instead. In case a value is large and therefore - '--set' to provide one or more key=val pairs directly,
you want not to use neither '--values' nor '--set', use '--set-file' to read the - '--set-string' to provide key=val forcing val to be stored as a string,
single large value from file. - '--set-file' to provide key=path to read a single large value from a file at path.
You can specify the '--values'/'-f' flag multiple times. The priority will be given to the To edit or append to the existing customized values add the
last (right-most) file specified. For example, if both myvalues.yaml and override.yaml '--reuse-values' flag, otherwise any existing customized values are ignored.
contained a key called 'Test', the value set in override.yaml would take precedence:
If no chart value arguments are provided on the command line, any existing customized values are carried
forward. To revert to use only values provided in the chart, use the '--reset-values' flag.
You can specify any of the chart value flags multiple times. The priority will be given to the last
(right-most) value specified. For example, if both myvalues.yaml and override.yaml contained a key
called 'Test', the value set in override.yaml would take precedence:
$ helm upgrade -f myvalues.yaml -f override.yaml redis ./redis $ helm upgrade -f myvalues.yaml -f override.yaml redis ./redis
You can specify the '--set' flag multiple times. The priority will be given to the Note that the key name provided to the '--set', '--set-string' and '--set-file' flags can reference
last (right-most) set specified. For example, if both 'bar' and 'newbar' values are structure elements. Examples:
set for a key called 'foo', the 'newbar' value would take precedence: - mybool=TRUE
- livenessProbe.timeoutSeconds=10
- metrics.annotations[0]=hey,metrics.annotations[1]=ho
which sets the top level key mybool to true, the nested timeoutSeconds to 10 and two array values respectively.
Note that the value side of the key=val provided to '--set' and '--set-string' flags will pass through
shell evaluation followed by yaml type parsing to produce the final value. This may alter inputs with
special characters in unexpected ways, for example
$ helm upgrade --set pwd=3jk$o2,z=f\30.e redis ./redis
results in "pwd: 3jk" and "z: f30.e". Use single quotes to avoid shell evaluation and argument delimiters,
and use backslash to escape yaml special characters:
$ helm upgrade --set pwd='3jk$o2z=f\\30.e' redis ./redis
which results in the expected "pwd: 3jk$o2z=f\30.e". If a single quote occurs in your value then follow
your shell convention for escaping it; for example in bash:
$ helm upgrade --set pwd='3jk$o2z=f\\30with'\''quote'
$ helm upgrade --set foo=bar --set foo=newbar redis ./redis which results in "pwd: 3jk$o2z=f\30with'quote".
``` ```
@ -88,4 +115,4 @@ helm upgrade [RELEASE] [CHART] [flags]
* [helm](helm.md) - The Helm package manager for Kubernetes. * [helm](helm.md) - The Helm package manager for Kubernetes.
###### Auto generated by spf13/cobra on 10-Aug-2018 ###### Auto generated by spf13/cobra on 17-Aug-2018

126
docs/man/man1/helm_upgrade.1
Unescape View File

@ -1,6 +1,4 @@
.TH "HELM" "1" "May 2017" "Auto generated by spf13/cobra" "" .TH "HELM" "1" "Aug 2018" "Auto generated by spf13/cobra" "" ""
.nh
.ad l
.SH NAME .SH NAME
@ -15,22 +13,32 @@ helm\-upgrade \- upgrade a release
.SH DESCRIPTION .SH DESCRIPTION
.PP .PP
This command upgrades a release to a new version of a chart. This command upgrades a release to a specified version of a chart
and/or updates chart values.
.PP .PP
The upgrade arguments must be a release and chart. The chart Required arguments are release and chart. The chart argument can be one of:
argument can be either: a chart reference('stable/mariadb'), a path to a chart directory, \- a chart reference('stable/mariadb'); use '\-\-version' and '\-\-devel' flags for versions other than latest,
a packaged chart, or a fully qualified URL. For chart references, the latest \- a path to a chart directory,
version will be specified unless the '\-\-version' flag is set. \- a packaged chart,
\- a fully qualified URL.
.PP .PP
To override values in a chart, use either the '\-\-values' flag and pass in a file To customize the chart values use any of
or use the '\-\-set' flag and pass configuration from the command line. \- '\-\-values'/'\-f' to pass in a yaml file holding settings,
\- '\-\-set' to provide one or more key=val pairs directly,
\- '\-\-set\-string' to provide key=val forcing val to be stored as a string,
\- '\-\-set\-file' to provide key=path to read a single large value from a file at path.
.PP .PP
You can specify the '\-\-values'/'\-f' flag multiple times. The priority will be given to the To edit or append to the existing customized values add the
last (right\-most) file specified. For example, if both myvalues.yaml and override.yaml '\-\-reuse\-values' flag, otherwise any existing customized values are ignored.
contained a key called 'Test', the value set in override.yaml would take precedence:
.PP
If no chart value arguments are provided on the command line, any existing customized values are carried forward. To revert to use only values provided in the chart, use the '\-\-reset\-values' flag.
.PP
You can specify any of the chart value flags multiple times. The priority will be given to the last (right\-most) value specified. For example, if both myvalues.yaml and override.yaml contained a key called 'Test', the value set in override.yaml would take precedence:
.PP .PP
.RS .RS
@ -42,19 +50,53 @@ $ helm upgrade \-f myvalues.yaml \-f override.yaml redis ./redis
.RE .RE
.PP .PP
You can specify the '\-\-set' flag multiple times. The priority will be given to the Note that the key name provided to the '\-\-set', '\-\-set\-string' and '\-\-set\-file' flags can reference structure elements. Examples:
last (right\-most) set specified. For example, if both 'bar' and 'newbar' values are \- mybool=TRUE
set for a key called 'foo', the 'newbar' value would take precedence: \- livenessProbe.timeoutSeconds=10
\- metrics.annotations[0]=hey,metrics.annotations[1]=ho
.PP
which sets the top level key mybool to true, the nested timeoutSeconds to 10 and two array values respectively.
.PP
Note that the value side of the key=val provided to '\-\-set' and '\-\-set\-string' flags will pass through shell evaluation followed by yaml type parsing to produce the final value. This may alter inputs with special characters in unexpected ways, for example
.PP
.RS
.nf
$ helm upgrade \-\-set pwd=3jk$o2,z=f\\30.e redis ./redis
.fi
.RE
.PP
results in "pwd: 3jk" and "z: f30.e". Use single quotes to avoid shell evaulation and argument delimiters, and use backslash to escape yaml special characters:
.PP
.RS
.nf
$ helm upgrade \-\-set pwd='3jk$o2z=f\\\\30.e' redis ./redis
.fi
.RE
.PP
which results in the expected "pwd: 3jk$o2z=f\\30.e". If a single quote occurs in your value then follow your shell convention for escaping it; for example in bash:
.PP .PP
.RS .RS
.nf .nf
$ helm upgrade \-\-set foo=bar \-\-set foo=newbar redis ./redis $ helm upgrade \-\-set pwd='3jk$o2z=f\\\\30with'\\''quote'
.fi .fi
.RE .RE
.PP
which results in "pwd: 3jk$o2z=f\\30with'quote".
.SH OPTIONS .SH OPTIONS
.PP .PP
@ -65,9 +107,13 @@ $ helm upgrade \-\-set foo=bar \-\-set foo=newbar redis ./redis
\fB\-\-cert\-file\fP="" \fB\-\-cert\-file\fP=""
identify HTTPS client using this SSL certificate file identify HTTPS client using this SSL certificate file
.PP
\fB\-\-description\fP=""
specify the description to use for the upgrade, rather than the default
.PP .PP
\fB\-\-devel\fP[=false] \fB\-\-devel\fP[=false]
use development versions, too. Equivalent to version '>0.0.0\-a'. If \-\-version is set, this is ignored. use development versions, too. Equivalent to version '>0.0.0\-0'. If \-\-version is set, this is ignored.
.PP .PP
\fB\-\-dry\-run\fP[=false] \fB\-\-dry\-run\fP[=false]
@ -90,13 +136,17 @@ $ helm upgrade \-\-set foo=bar \-\-set foo=newbar redis ./redis
path to the keyring that contains public signing keys path to the keyring that contains public signing keys
.PP .PP
\fB\-\-namespace\fP="default" \fB\-\-namespace\fP=""
namespace to install the release into (only used if \-\-install is set) namespace to install the release into (only used if \-\-install is set). Defaults to the current kube config namespace
.PP .PP
\fB\-\-no\-hooks\fP[=false] \fB\-\-no\-hooks\fP[=false]
disable pre/post upgrade hooks disable pre/post upgrade hooks
.PP
\fB\-\-password\fP=""
chart repository password where to locate the requested chart
.PP .PP
\fB\-\-recreate\-pods\fP[=false] \fB\-\-recreate\-pods\fP[=false]
performs pods restart for the resource if applicable performs pods restart for the resource if applicable
@ -111,15 +161,23 @@ $ helm upgrade \-\-set foo=bar \-\-set foo=newbar redis ./redis
.PP .PP
\fB\-\-reuse\-values\fP[=false] \fB\-\-reuse\-values\fP[=false]
when upgrading, reuse the last release's values, and merge in any new values. If '\-\-reset\-values' is specified, this is ignored. when upgrading, reuse the last release's values and merge in any overrides from the command line via \-\-set and \-f. If '\-\-reset\-values' is specified, this is ignored.
.PP .PP
\fB\-\-set\fP=[] \fB\-\-set\fP=[]
set values on the command line (can specify multiple or separate values with commas: key1=val1,key2=val2) set values on the command line (can specify multiple or separate values with commas: key1=val1,key2=val2)
.PP
\fB\-\-set\-file\fP=[]
set values from respective files specified via the command line (can specify multiple or separate values with commas: key1=path1,key2=path2)
.PP
\fB\-\-set\-string\fP=[]
set STRING values on the command line (can specify multiple or separate values with commas: key1=val1,key2=val2)
.PP .PP
\fB\-\-timeout\fP=300 \fB\-\-timeout\fP=300
time in seconds to wait for any individual kubernetes operation (like Jobs for hooks) time in seconds to wait for any individual Kubernetes operation (like Jobs for hooks)
.PP .PP
\fB\-\-tls\fP[=false] \fB\-\-tls\fP[=false]
@ -133,6 +191,10 @@ $ helm upgrade \-\-set foo=bar \-\-set foo=newbar redis ./redis
\fB\-\-tls\-cert\fP="$HELM\_HOME/cert.pem" \fB\-\-tls\-cert\fP="$HELM\_HOME/cert.pem"
path to TLS certificate file path to TLS certificate file
.PP
\fB\-\-tls\-hostname\fP=""
the server name used to verify the hostname on the returned certificates from the server
.PP .PP
\fB\-\-tls\-key\fP="$HELM\_HOME/key.pem" \fB\-\-tls\-key\fP="$HELM\_HOME/key.pem"
path to TLS key file path to TLS key file
@ -141,6 +203,10 @@ $ helm upgrade \-\-set foo=bar \-\-set foo=newbar redis ./redis
\fB\-\-tls\-verify\fP[=false] \fB\-\-tls\-verify\fP[=false]
enable TLS for request and verify remote enable TLS for request and verify remote
.PP
\fB\-\-username\fP=""
chart repository username where to locate the requested chart
.PP .PP
\fB\-f\fP, \fB\-\-values\fP=[] \fB\-f\fP, \fB\-\-values\fP=[]
specify values in a YAML file or a URL(can specify multiple) specify values in a YAML file or a URL(can specify multiple)
@ -168,16 +234,24 @@ $ helm upgrade \-\-set foo=bar \-\-set foo=newbar redis ./redis
location of your Helm config. Overrides $HELM\_HOME location of your Helm config. Overrides $HELM\_HOME
.PP .PP
\fB\-\-host\fP="localhost:44134" \fB\-\-host\fP=""
address of tiller. Overrides $HELM\_HOST address of Tiller. Overrides $HELM\_HOST
.PP .PP
\fB\-\-kube\-context\fP="" \fB\-\-kube\-context\fP=""
name of the kubeconfig context to use name of the kubeconfig context to use
.PP
\fB\-\-kubeconfig\fP=""
absolute path to the kubeconfig file to use
.PP
\fB\-\-tiller\-connection\-timeout\fP=300
the duration (in seconds) Helm will wait to establish a connection to tiller
.PP .PP
\fB\-\-tiller\-namespace\fP="kube\-system" \fB\-\-tiller\-namespace\fP="kube\-system"
namespace of tiller namespace of Tiller
.SH SEE ALSO .SH SEE ALSO
@ -187,4 +261,4 @@ $ helm upgrade \-\-set foo=bar \-\-set foo=newbar redis ./redis
.SH HISTORY .SH HISTORY
.PP .PP
19\-May\-2017 Auto generated by spf13/cobra 17\-Aug\-2018 Auto generated by spf13/cobra

Write Preview
Loading…
Cancel
Save