From eeb3a1454a54194bada37661dab57d397c3e899b Mon Sep 17 00:00:00 2001
From: smurfralf <robert.r.allen@ericsson.com>
Date: Fri, 17 Aug 2018 17:45:36 -0400
Subject: [PATCH] Improve documentation for helm upgrade (#4030)

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

Fixes issue #4030
---
 cmd/helm/upgrade.go          |  61 ++++++++++++-----
 docs/helm/helm_upgrade.md    |  63 +++++++++++++-----
 docs/man/man1/helm_upgrade.1 | 126 +++++++++++++++++++++++++++--------
 3 files changed, 189 insertions(+), 61 deletions(-)

diff --git a/cmd/helm/upgrade.go b/cmd/helm/upgrade.go
index ba0649e39..55ed63c13 100644
--- a/cmd/helm/upgrade.go
+++ b/cmd/helm/upgrade.go
@@ -29,30 +29,57 @@ import (
 )
 
 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
-argument can be either: a chart reference('stable/mariadb'), a path to a chart directory,
-a packaged chart, or a fully qualified URL. For chart references, the latest
-version will be specified unless the '--version' flag is set.
+Required arguments are release and chart. The chart argument can be one of:
+ - a chart reference('stable/mariadb'); use '--version' and '--devel' flags for versions other than latest,
+ - a path to a chart directory,
+ - a packaged chart,
+ - a fully qualified URL.
 
-To override values in a chart, use either the '--values' flag and pass in a file
-or use the '--set' flag and pass configuration from the command line. To force string
-values in '--set', use '--set-string' instead. In case a value is large and therefore
-you want not to use neither '--values' nor '--set', use '--set-file' to read the
-single large value from file.
+To customize the chart values use any of
+ - '--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.
 
-You can specify the '--values'/'-f' flag multiple times. The priority will be given to the
-last (right-most) file specified. For example, if both myvalues.yaml and override.yaml
-contained a key called 'Test', the value set in override.yaml would take precedence:
+To edit or append to the existing customized values add the 
+ '--reuse-values' flag, otherwise any existing customized values are ignored.
+
+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
 
-You can specify the '--set' flag multiple times. The priority will be given to the
-last (right-most) set specified. For example, if both 'bar' and 'newbar' values are
-set for a key called 'foo', the 'newbar' value would take precedence:
+Note that the key name provided to the '--set', '--set-string' and '--set-file' flags can reference
+structure elements. Examples:
+  - 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 {
diff --git a/docs/helm/helm_upgrade.md b/docs/helm/helm_upgrade.md
index 522464c6b..6dcb25387 100644
--- a/docs/helm/helm_upgrade.md
+++ b/docs/helm/helm_upgrade.md
@@ -5,30 +5,57 @@ upgrade a release
 ### 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
-argument can be either: a chart reference('stable/mariadb'), a path to a chart directory,
-a packaged chart, or a fully qualified URL. For chart references, the latest
-version will be specified unless the '--version' flag is set.
+Required arguments are release and chart. The chart argument can be one of:
+ - a chart reference('stable/mariadb'); use '--version' and '--devel' flags for versions other than latest,
+ - a path to a chart directory,
+ - a packaged chart,
+ - a fully qualified URL.
 
-To override values in a chart, use either the '--values' flag and pass in a file
-or use the '--set' flag and pass configuration from the command line. To force string
-values in '--set', use '--set-string' instead. In case a value is large and therefore
-you want not to use neither '--values' nor '--set', use '--set-file' to read the
-single large value from file.
+To customize the chart values use any of
+ - '--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.
 
-You can specify the '--values'/'-f' flag multiple times. The priority will be given to the
-last (right-most) file specified. For example, if both myvalues.yaml and override.yaml
-contained a key called 'Test', the value set in override.yaml would take precedence:
+To edit or append to the existing customized values add the 
+ '--reuse-values' flag, otherwise any existing customized values are ignored.
+
+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
 
-You can specify the '--set' flag multiple times. The priority will be given to the
-last (right-most) set specified. For example, if both 'bar' and 'newbar' values are
-set for a key called 'foo', the 'newbar' value would take precedence:
+Note that the key name provided to the '--set', '--set-string' and '--set-file' flags can reference
+structure elements. Examples:
+  - 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.
 
-###### Auto generated by spf13/cobra on 10-Aug-2018
+###### Auto generated by spf13/cobra on 17-Aug-2018
diff --git a/docs/man/man1/helm_upgrade.1 b/docs/man/man1/helm_upgrade.1
index 24bba7c85..202f3d8c1 100644
--- a/docs/man/man1/helm_upgrade.1
+++ b/docs/man/man1/helm_upgrade.1
@@ -1,6 +1,4 @@
-.TH "HELM" "1" "May 2017" "Auto generated by spf13/cobra" "" 
-.nh
-.ad l
+.TH "HELM" "1" "Aug 2018" "Auto generated by spf13/cobra" ""  ""
 
 
 .SH NAME
@@ -15,22 +13,32 @@ helm\-upgrade \- upgrade a release
 
 .SH DESCRIPTION
 .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
-The upgrade arguments must be a release and chart. The chart
-argument can be either: a chart reference('stable/mariadb'), a path to a chart directory,
-a packaged chart, or a fully qualified URL. For chart references, the latest
-version will be specified unless the '\-\-version' flag is set.
+Required arguments are release and chart. The chart argument can be one of:
+ \- a chart reference('stable/mariadb'); use '\-\-version' and '\-\-devel' flags for versions other than latest,
+ \- a path to a chart directory,
+ \- a packaged chart,
+ \- a fully qualified URL.
 
 .PP
-To override values in a chart, use either the '\-\-values' flag and pass in a file
-or use the '\-\-set' flag and pass configuration from the command line.
+To customize the chart values use any of
+ \- '\-\-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
-You can specify the '\-\-values'/'\-f' flag multiple times. The priority will be given to the
-last (right\-most) file specified. For example, if both myvalues.yaml and override.yaml
-contained a key called 'Test', the value set in override.yaml would take precedence:
+To edit or append to the existing customized values add the
+ '\-\-reuse\-values' flag, otherwise any existing customized values are ignored.
+
+.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
 .RS
@@ -42,19 +50,53 @@ $ helm upgrade \-f myvalues.yaml \-f override.yaml redis ./redis
 .RE
 
 .PP
-You can specify the '\-\-set' flag multiple times. The priority will be given to the
-last (right\-most) set specified. For example, if both 'bar' and 'newbar' values are
-set for a key called 'foo', the 'newbar' value would take precedence:
+Note that the key name provided to the '\-\-set', '\-\-set\-string' and '\-\-set\-file' flags can reference structure elements. Examples:
+  \- mybool=TRUE
+  \- 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
 .RS
 
 .nf
-$ helm upgrade \-\-set foo=bar \-\-set foo=newbar redis ./redis
+$ helm upgrade \-\-set pwd='3jk$o2z=f\\\\30with'\\''quote'
 
 .fi
 .RE
 
+.PP
+which results in "pwd: 3jk$o2z=f\\30with'quote".
+
 
 .SH OPTIONS
 .PP
@@ -65,9 +107,13 @@ $ helm upgrade \-\-set foo=bar \-\-set foo=newbar redis ./redis
 \fB\-\-cert\-file\fP=""
     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
 \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
 \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
 
 .PP
-\fB\-\-namespace\fP="default"
-    namespace to install the release into (only used if \-\-install is set)
+\fB\-\-namespace\fP=""
+    namespace to install the release into (only used if \-\-install is set). Defaults to the current kube config namespace
 
 .PP
 \fB\-\-no\-hooks\fP[=false]
     disable pre/post upgrade hooks
 
+.PP
+\fB\-\-password\fP=""
+    chart repository password where to locate the requested chart
+
 .PP
 \fB\-\-recreate\-pods\fP[=false]
     performs pods restart for the resource if applicable
@@ -111,15 +161,23 @@ $ helm upgrade \-\-set foo=bar \-\-set foo=newbar redis ./redis
 
 .PP
 \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
 \fB\-\-set\fP=[]
     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
 \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
 \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"
     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
 \fB\-\-tls\-key\fP="$HELM\_HOME/key.pem"
     path to TLS key file
@@ -141,6 +203,10 @@ $ helm upgrade \-\-set foo=bar \-\-set foo=newbar redis ./redis
 \fB\-\-tls\-verify\fP[=false]
     enable TLS for request and verify remote
 
+.PP
+\fB\-\-username\fP=""
+    chart repository username where to locate the requested chart
+
 .PP
 \fB\-f\fP, \fB\-\-values\fP=[]
     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
 
 .PP
-\fB\-\-host\fP="localhost:44134"
-    address of tiller. Overrides $HELM\_HOST
+\fB\-\-host\fP=""
+    address of Tiller. Overrides $HELM\_HOST
 
 .PP
 \fB\-\-kube\-context\fP=""
     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
 \fB\-\-tiller\-namespace\fP="kube\-system"
-    namespace of tiller
+    namespace of Tiller
 
 
 .SH SEE ALSO
@@ -187,4 +261,4 @@ $ helm upgrade \-\-set foo=bar \-\-set foo=newbar redis ./redis
 
 .SH HISTORY
 .PP
-19\-May\-2017 Auto generated by spf13/cobra
+17\-Aug\-2018 Auto generated by spf13/cobra