Fix up gke-deploy docs. (#519)

* Fix tables in docs.

* Add cobra-generated docs and update README.md.

* Fix go.mod.

gke-deploy/README.md

@@ -1,9 +1,9 @@
 # GKE Deploy
 
-** Warning: This builder is experimental and is very likely to change in
+** Warning: This cloud builder is experimental and will very likely to change in
 breaking ways at this time. **
 
-This tool deploys an application to a GKE cluster in a way that follows Google's
+This tool deploys an application to a GKE cluster, following Google's
 recommended best practices.
 
 ## gke-deploy vs kubectl
@@ -14,35 +14,39 @@ the following:
 
 ### Prepare Step
 
-1.  `gke-deploy` modifies a set of Kubernetes resource YAML configs to use a
-    container image's digest instead of a tag and adds
+*   The `gke-deploy` builder modifies a set of Kubernetes resource YAML configs
+    to use a container image's digest instead of a tag.
+
+*   The builder adds
     [recommended labels](https://kubernetes.io/docs/concepts/overview/working-with-objects/common-labels/#applications-and-instances-of-applications).
 
 ### Apply Step
 
-1.  `gke-deploy` gets authorized to access a GKE cluster.
+The `gke-deploy` does the following:
+
+1.  Gets authorized to access a GKE cluster
 
-2.  `gke-deploy` applies (using `kubectl`) the set of Kubernetes resource YAML configs that were
-    modified in the prepare step.
+2.  Applies (using `kubectl`) the set of Kubernetes resource YAML configs that were
+    modified in the prepare step
 
-3.  `gke-deploy` waits for applied Kubernetes resources to be ready.
+3.  Waits for applied Kubernetes resources to be ready
 
 ## Usage
 
-### [gke-deploy run [flags]](docs/run.md)
+[`gke-deploy run [flags]`](doc/gke-deploy_run.md)
 
 This command will execute both the [Prepare](#prepare-step) and
 [Apply](#apply-step) phases mentioned above.
 
-### [gke-deploy prepare [flags]](docs/prepare.md)
+[`gke-deploy prepare [flags]`](doc/gke-deploy_prepare.md)
 
 This command will execute only the [Prepare](#prepare-step) phase mentioned
 above.
 
-### [gke-deploy apply [flags]](docs/apply.md)
+[`gke-deploy apply [flags]`](doc/gke-deploy_apply.md)
 
 This command will execute only the [Apply](#apply-step) phase mentioned above.
 
-### [Automated Deployments with GCB](docs/automated-deployments.md)
+## [Automated Deployments with GCB](doc/automated-deployments.md)
 
-Follow these instructions to set up continuous deployment.
+Follow [these instructions](doc/automated-deployments.md) to set up continuous deployment.

gke-deploy/cmd/apply/apply.go

@@ -28,16 +28,14 @@ const (
 
 - Apply Kubernetes config YAMLs to the target cluster with the provided namespace.
 - Wait for deployed resources to be ready before exiting.
-
-Examples:
-  # Apply only.
+`
+	example = `  # Apply only.
   gke-deploy apply -f configs -c my-cluster -n my-namespace -c my-cluster -l us-east1-b
 
   # Execute prepare and apply, with an intermediary step in between (e.g., manually check modified YAMLs)
   gke-deploy prepare -f configs -i gcr.io/my-project/my-app:1.0.0 -a my-app -v 1.0.0 -o modified -n my-namespace
   cat modified/*
-  gke-deploy apply -f modified -c my-cluster -n my-namespace -c my-cluster -l us-east1-b  # Pass modified directory to -f
-`
+  gke-deploy apply -f modified -c my-cluster -n my-namespace -c my-cluster -l us-east1-b  # Pass modified directory to -f`
 )
 
 type options struct {
@@ -58,6 +56,7 @@ func NewApplyCommand() *cobra.Command {
 		Aliases: []string{"a"},
 		Short:   short,
 		Long:    long,
+		Example: example,
 		RunE: func(cmd *cobra.Command, _ []string) error {
 			return apply(cmd, options)
 		},

gke-deploy/cmd/prepare/prepare.go

@@ -30,16 +30,14 @@ const (
   - Set the digest of images that match the [--image|-i] flag, if provided.
   - Add app.kubernetes.io/name=[--app|-a] label, if provided.
   - Add app.kubernetes.io/version=[--version|-v] label, if provided.
-
-Examples:
-  # Prepare only.
+`
+	example = `  # Prepare only.
   gke-deploy prepare -f configs -i gcr.io/my-project/my-app:1.0.0 -a my-app -v 1.0.0 -o modified -n my-namespace
 
   # Execute prepare and apply, with an intermediary step in between (e.g., manually check modified YAMLs)
   gke-deploy prepare -f configs -i gcr.io/my-project/my-app:1.0.0 -a my-app -v 1.0.0 -o modified -n my-namespace
   cat modified/*
-  gke-deploy apply -f modified -c my-cluster -n my-namespace -c my-cluster -l us-east1-b  # Pass modified directory to -f
-`
+  gke-deploy apply -f modified -c my-cluster -n my-namespace -c my-cluster -l us-east1-b  # Pass modified directory to -f`
 )
 
 type options struct {
@@ -61,6 +59,7 @@ func NewPrepareCommand() *cobra.Command {
 		Aliases: []string{"p"},
 		Short:   short,
 		Long:    long,
+		Example: example,
 		RunE: func(cmd *cobra.Command, _ []string) error {
 			return prepare(cmd, options)
 		},
@@ -97,9 +96,6 @@ func prepare(cmd *cobra.Command, options *options) error {
 	if options.output == "" {
 		return fmt.Errorf("value of -o|--output cannot be empty")
 	}
-	if options.namespace == "" {
-		return fmt.Errorf("value of -n|--namespace cannot be empty")
-	}
 
 	labelsMap, err := common.CreateLabelsMap(options.labels)
 	if err != nil {

gke-deploy/cmd/root.go

@@ -33,9 +33,8 @@ Prepare Phase:
 Apply Phase:
   - Apply Kubernetes config YAMLs to the target cluster with the provided namespace.
   - Wait for deployed resources to be ready before exiting.
-
-Examples:
-  # Modify configs and deploy to GKE cluster.
+`
+	example = `  # Modify configs and deploy to GKE cluster.
   gke-deploy run -f configs -i gcr.io/my-project/my-app:1.0.0 -a my-app -v 1.0.0 -o modified -n my-namespace -c my-cluster -l us-east1-b
 
   # Deploy to GKE cluster that kubectl is currently targeting.
@@ -50,8 +49,7 @@ Examples:
   # Execute prepare and apply, with an intermediary step in between (e.g., manually check modified YAMLs)
   gke-deploy prepare -f configs -i gcr.io/my-project/my-app:1.0.0 -a my-app -v 1.0.0 -o modified -n my-namespace
   cat modified/*
-  gke-deploy apply -f modified -c my-cluster -n my-namespace -c my-cluster -l us-east1-b  # Pass modified directory to -f
-`
+  gke-deploy apply -f modified -c my-cluster -n my-namespace -c my-cluster -l us-east1-b  # Pass modified directory to -f`
 	version = "" // TODO(joonlim): Create plan for versioning.
 )
 
@@ -60,6 +58,7 @@ func NewCommand() *cobra.Command {
 		Use:     "gke-deploy",
 		Short:   short,
 		Long:    long,
+		Example: example,
 		Version: version,
 	}
 

gke-deploy/cmd/run/run.go

@@ -36,14 +36,12 @@ Prepare Phase:
 Apply Phase:
   - Apply Kubernetes config YAMLs to the target cluster with the provided namespace.
   - Wait for deployed resources to be ready before exiting.
-
-Examples:
-  # Modify configs and deploy to GKE cluster.
+`
+	example = `  # Modify configs and deploy to GKE cluster.
   gke-deploy run -f configs -i gcr.io/my-project/my-app:1.0.0 -a my-app -v 1.0.0 -o modified -n my-namespace -c my-cluster -l us-east1-b
 
   # Deploy to GKE cluster that kubectl is currently targeting.
-  gke-deploy run -f configs
-`
+  gke-deploy run -f configs`
 )
 
 type options struct {
@@ -69,6 +67,7 @@ func NewRunCommand() *cobra.Command {
 		Aliases: []string{"r", "deploy", "d"},
 		Short:   short,
 		Long:    long,
+		Example: example,
 		RunE: func(cmd *cobra.Command, _ []string) error {
 			return run(cmd, options)
 		},

gke-deploy/doc/gke-deploy.md

@@ -0,0 +1,53 @@
+## gke-deploy
+
+Deploy to GKE
+
+### Synopsis
+
+Deploy to GKE in two phases, which will do the following:
+
+Prepare Phase:
+  - Modify Kubernetes config YAMLs:
+    - Set the digest of images that match the [--image|-i] flag, if provided.
+    - Add app.kubernetes.io/name=[--name|-a] label, if provided.
+    - Add app.kubernetes.io/version=[--version|-v] label, if provided.
+
+Apply Phase:
+  - Apply Kubernetes config YAMLs to the target cluster with the provided namespace.
+  - Wait for deployed resources to be ready before exiting.
+
+
+### Examples
+
+```
+  # Modify configs and deploy to GKE cluster.
+  gke-deploy run -f configs -i gcr.io/my-project/my-app:1.0.0 -a my-app -v 1.0.0 -o modified -n my-namespace -c my-cluster -l us-east1-b
+
+  # Deploy to GKE cluster that kubectl is currently targeting.
+  gke-deploy run -f configs
+
+  # Prepare only.
+  gke-deploy prepare -f configs -i gcr.io/my-project/my-app:1.0.0 -a my-app -v 1.0.0 -o modified -n my-namespace
+
+  # Apply only.
+  gke-deploy apply -f configs -c my-cluster -n my-namespace -c my-cluster -l us-east1-b
+
+  # Execute prepare and apply, with an intermediary step in between (e.g., manually check modified YAMLs)
+  gke-deploy prepare -f configs -i gcr.io/my-project/my-app:1.0.0 -a my-app -v 1.0.0 -o modified -n my-namespace
+  cat modified/*
+  gke-deploy apply -f modified -c my-cluster -n my-namespace -c my-cluster -l us-east1-b  # Pass modified directory to -f
+```
+
+### Options
+
+```
+  -h, --help   help for gke-deploy
+```
+
+### SEE ALSO
+
+* [gke-deploy apply](gke-deploy_apply.md)	 - Skip prepare phase and execute apply phase
+* [gke-deploy prepare](gke-deploy_prepare.md)	 - Execute prepare phase and skip apply phase
+* [gke-deploy run](gke-deploy_run.md)	 - Execute both prepare and apply phase
+
+###### Auto generated by spf13/cobra on 12-Jul-2019

gke-deploy/doc/gke-deploy_apply.md

@@ -0,0 +1,46 @@
+## gke-deploy apply
+
+Skip prepare phase and execute apply phase
+
+### Synopsis
+
+Apply unmodified Kubernetes resource configs. Skip prepare.
+
+- Apply Kubernetes config YAMLs to the target cluster with the provided namespace.
+- Wait for deployed resources to be ready before exiting.
+
+
+```
+gke-deploy apply [flags]
+```
+
+### Examples
+
+```
+  # Apply only.
+  gke-deploy apply -f configs -c my-cluster -n my-namespace -c my-cluster -l us-east1-b
+
+  # Execute prepare and apply, with an intermediary step in between (e.g., manually check modified YAMLs)
+  gke-deploy prepare -f configs -i gcr.io/my-project/my-app:1.0.0 -a my-app -v 1.0.0 -o modified -n my-namespace
+  cat modified/*
+  gke-deploy apply -f modified -c my-cluster -n my-namespace -c my-cluster -l us-east1-b  # Pass modified directory to -f
+```
+
+### Options
+
+```
+  -c, --cluster string     Name of GKE cluster to deploy to.
+  -f, --filename string    Config file or directory of config files to use to create the Kubernetes resources (file or files in directory must end with ".yml" or ".yaml").
+  -h, --help               help for apply
+  -l, --location string    Region/zone of GKE cluster to deploy to.
+  -n, --namespace string   Name of GKE cluster to deploy to. (default "default")
+  -p, --project string     Project of GKE cluster to deploy to. If this field is not provided, the current set GCP project is used.
+  -t, --timeout duration   Timeout limit for waiting for resources to finish applying. (default 5m0s)
+  -V, --verbose            Prints underlying commands being called to stdout.
+```
+
+### SEE ALSO
+
+* [gke-deploy](gke-deploy.md)	 - Deploy to GKE
+
+###### Auto generated by spf13/cobra on 12-Jul-2019

gke-deploy/doc/gke-deploy_prepare.md

@@ -0,0 +1,49 @@
+## gke-deploy prepare
+
+Execute prepare phase and skip apply phase
+
+### Synopsis
+
+Prepare to deploy to GKE by generating modified Kubernetes resource configs. Skip apply.
+
+- Modify Kubernetes config YAMLs to:
+  - Set the digest of images that match the [--image|-i] flag, if provided.
+  - Add app.kubernetes.io/name=[--app|-a] label, if provided.
+  - Add app.kubernetes.io/version=[--version|-v] label, if provided.
+
+
+```
+gke-deploy prepare [flags]
+```
+
+### Examples
+
+```
+  # Prepare only.
+  gke-deploy prepare -f configs -i gcr.io/my-project/my-app:1.0.0 -a my-app -v 1.0.0 -o modified -n my-namespace
+
+  # Execute prepare and apply, with an intermediary step in between (e.g., manually check modified YAMLs)
+  gke-deploy prepare -f configs -i gcr.io/my-project/my-app:1.0.0 -a my-app -v 1.0.0 -o modified -n my-namespace
+  cat modified/*
+  gke-deploy apply -f modified -c my-cluster -n my-namespace -c my-cluster -l us-east1-b  # Pass modified directory to -f
+```
+
+### Options
+
+```
+  -a, --app string         Application name of the Kubernetes deployment.
+  -f, --filename string    Config file or directory of config files to use to create the Kubernetes resources (file or files in directory must end with ".yml" or ".yaml").
+  -h, --help               help for prepare
+  -i, --image strings      Image(s) to be deployed. Images can be set comma-delimited or as separate flags.
+  -L, --label strings      Label(s) to add to Kubernetes resources (k1=v1). Labels can be set comma-delimited or as separate flags. If two or more labels with the same key are listed, the last one is used.
+  -n, --namespace string   Name of GKE cluster to deploy to. (default "default")
+  -o, --output string      Target directory to store modified Kubernetes resource configs. (default "./output")
+  -V, --verbose            Prints underlying commands being called to stdout.
+  -v, --version string     Version of the Kubernetes deployment.
+```
+
+### SEE ALSO
+
+* [gke-deploy](gke-deploy.md)	 - Deploy to GKE
+
+###### Auto generated by spf13/cobra on 12-Jul-2019

gke-deploy/doc/gke-deploy_run.md

@@ -0,0 +1,56 @@
+## gke-deploy run
+
+Execute both prepare and apply phase
+
+### Synopsis
+
+Deploy to GKE in two phases, which will do the following:
+
+Prepare Phase:
+  - Modify Kubernetes config YAMLs:
+    - Set the digest of images that match the [--image|-i] flag, if provided.
+    - Add app.kubernetes.io/name=[--app|-a] label, if provided.
+    - Add app.kubernetes.io/version=[--version|-v] label, if provided.
+
+Apply Phase:
+  - Apply Kubernetes config YAMLs to the target cluster with the provided namespace.
+  - Wait for deployed resources to be ready before exiting.
+
+
+```
+gke-deploy run [flags]
+```
+
+### Examples
+
+```
+  # Modify configs and deploy to GKE cluster.
+  gke-deploy run -f configs -i gcr.io/my-project/my-app:1.0.0 -a my-app -v 1.0.0 -o modified -n my-namespace -c my-cluster -l us-east1-b
+
+  # Deploy to GKE cluster that kubectl is currently targeting.
+  gke-deploy run -f configs
+```
+
+### Options
+
+```
+  -a, --app string         Application name of the Kubernetes deployment.
+  -c, --cluster string     Name of GKE cluster to deploy to.
+  -f, --filename string    Config file or directory of config files to use to create the Kubernetes resources (file or files in directory must end with ".yml" or ".yaml").
+  -h, --help               help for run
+  -i, --image strings      Image(s) to be deployed. Images can be set comma-delimited or as separate flags.
+  -L, --label strings      Label(s) to add to Kubernetes resources (k1=v1). Labels can be set comma-delimited or as separate flags. If two or more labels with the same key are listed, the last one is used.
+  -l, --location string    Region/zone of GKE cluster to deploy to.
+  -n, --namespace string   Name of GKE cluster to deploy to. (default "default")
+  -o, --output string      Target directory to store modified Kubernetes resource configs. (default "./output")
+  -p, --project string     Project of GKE cluster to deploy to. If this field is not provided, the current set GCP project is used.
+  -t, --timeout duration   Timeout limit for waiting for resources to finish applying. (default 5m0s)
+  -V, --verbose            Prints underlying commands being called to stdout.
+  -v, --version string     Version of the Kubernetes deployment.
+```
+
+### SEE ALSO
+
+* [gke-deploy](gke-deploy.md)	 - Deploy to GKE
+
+###### Auto generated by spf13/cobra on 12-Jul-2019