Check and generate docs for updated provision command (kyma-project#298)

* Check and generate docs for updated provision command

README.md

@@ -53,13 +53,15 @@ To install Kyma CLI on Windows, download and unzip the [artifact](https://github
 
 Kyma CLI comes with a set of commands:
 
-- `version` shows the Kyma cluster version and the Kyma CLI version.
-- `provision minikube` initializes Minikube on a new cluster. It replaces the `minikube.sh` script. 
-- `install` installs Kyma to a cluster based on the current release. It replaces the `ìnstaller.sh` and `is-installed.sh` script. 
-- `uninstall` uninstalls all Kyma-related resources from a cluster.
-- `test` runs tests on a provisioned Kyma cluster.
-- `completion` generates and shows the bash completion script.
-- `help` displays and explains the usage of a given command.
+|     Command        | Child commands   |  Description  | Example |
+|--------------------|----------------|---------------|---------|
+| `completion`| None| Generates and displays the bash or zsh completion script. | `kyma completion`|
+| `console`| None|  Launches Kyma Console in a browser window. | `kyma console`  |
+| `install`| None| Installs Kyma on a cluster based on the current or specified release. | `kyma install`|
+| `provision`| `provision minikube`<br> `provision gardener` <br> `provision gcp`| Provisions a new cluster on a platform of your choice. Currently, this command supports cluster provisioning on GCP, Gardener, and Minikube. | `kyma provision minikube`|
+| `test`|`test definitions`<br> `test delete` <br> `test list` <br> `test run` <br> `test status`<br> | Runs and manages tests on a provisioned Kyma cluster. Using child commands, you can run tests, view test definitions, list and delete test suites, and display test status.| `kyma test run`  |
+| `uninstall`|None| Uninstalls all Kyma-related resources from a cluster. | `kyma uninstall`  |
+| `version`|None| Shows the cluster version and the Kyma CLI version.|`kyma version`|
 
 For details on particular commands and options, see [this](https://github.com/kyma-project/cli/tree/master/docs/gen-docs) list.
 
@@ -108,7 +110,7 @@ Further usage examples include:
 
 ### Kyma CLI as a kubectl plugin
 
-> **NOTE**: To use Kyma CLI as a kubectl plugin, use Kubernetes version 1.12.0 or higher.
+>**NOTE**: To use Kyma CLI as a kubectl plugin, use Kubernetes version 1.12.0 or higher.
 
 A plugin is a standalone executable file with a name prefixed with `kubectl-` .To use the plugin, perform the following steps:
 

cmd/kyma/completion/completion.go

@@ -21,7 +21,6 @@ To configure your shell to load completions, add ` + "`. <(kyma completion bash)
 		RunE:    completion,
 		Aliases: []string{},
 	}
-	completionCmd.Flags().Bool("help", false, "Displays help for the command.")
 	return completionCmd
 }
 

cmd/kyma/console/cmd.go

@@ -27,15 +27,14 @@ func NewCmd(o *Options) *cobra.Command {
 
 	cmd := &cobra.Command{
 		Use:     "console",
-		Short:   "Open the Kyma Console in a web browser.",
+		Short:   "Opens the Kyma Console in a web browser.",
 		Long: `Use this command to open the Kyma Console in a web browser.
 
 `,
 
 		RunE:    func(_ *cobra.Command, _ []string) error { return c.Run() },
 		Aliases: []string{"c"},
 	}
-    cmd.Flags().Bool("help", false, "Displays help for the command.")
 	return cmd
 }
 

cmd/kyma/install/cmd.go

@@ -93,16 +93,19 @@ The standard installation uses the minimal configuration. The system performs th
 		Aliases: []string{"i"},
 	}
 
-	cobraCmd.Flags().BoolVarP(&o.NoWait, "noWait", "n", false, "Determines if the command should wait for the Kyma installation to complete.")
+	cobraCmd.Flags().BoolVarP(&o.NoWait, "noWait", "n", false, "Determines if the command should wait for Kyma installation to complete.")
 	cobraCmd.Flags().StringVarP(&o.Domain, "domain", "d", localDomain, "Specifies the domain used for installation.")
 	cobraCmd.Flags().StringVarP(&o.TLSCert, "tlsCert", "", "", "Specifies the TLS certificate for the domain used for installation.")
 	cobraCmd.Flags().StringVarP(&o.TLSKey, "tlsKey", "", "", "Specifies the TLS key for the domain used for installation.")
-	cobraCmd.Flags().StringVarP(&o.Source, "source", "s", DefaultKymaVersion, "Specifies the installation source. To use the specific release, write kyma install --source=1.3.0. To use the latest master, write kyma install --source=latest. To use the local sources, write kyma install --source=local. To use the remote image, write kyma install --source=user/my-kyma-installer:v1.4.0.")
+	cobraCmd.Flags().StringVarP(&o.Source, "source", "s", DefaultKymaVersion, `Specifies the installation source. 
+	- To use the specific release, write "kyma install --source=1.3.0".
+	- To use the latest master, write "kyma install --source=latest".
+	- To use the local sources, write "kyma install --source=local". 
+	- To use a custom installer image, write kyma "install --source=user/my-kyma-installer:v1.4.0".`)
 	cobraCmd.Flags().StringVarP(&o.LocalSrcPath, "src-path", "", "", "Specifies the absolute path to local sources.")
 	cobraCmd.Flags().DurationVarP(&o.Timeout, "timeout", "", 1*time.Hour, "Time-out after which CLI stops watching the installation progress.")
 	cobraCmd.Flags().StringVarP(&o.Password, "password", "p", "", "Specifies the predefined cluster password.")
-	cobraCmd.Flags().StringArrayVarP(&o.OverrideConfigs, "override", "o", nil, "Specifies the path to a yaml file with parameters to override.")
-	cobraCmd.Flags().Bool("help", false, "Displays help for the command.")
+	cobraCmd.Flags().StringArrayVarP(&o.OverrideConfigs, "override", "o", nil, "Specifies the path to a YAML file with parameters to override.")
 
 	return cobraCmd
 }

cmd/kyma/kyma.go

@@ -39,9 +39,9 @@ For more information, see: https://github.com/kyma-project/cli
 	cmd.PersistentFlags().BoolVarP(&o.Verbose, "verbose", "v", false, "Displays details of actions triggered by the command.")
 	cmd.PersistentFlags().BoolVar(&o.NonInteractive, "non-interactive", false, "Enables the non-interactive shell mode.")
 	// Kubeconfig env var and defualt paths are resolved by the kyma k8s client using the k8s defined resolution strategy.
-	cmd.PersistentFlags().StringVar(&o.KubeconfigPath, "kubeconfig", "", "Specifies the path to the kubeconfig file. By default, Kyma CLI uses the KUBECONFIG environment variable or /$HOME/.kube/config if the variable is not set.")
-	cmd.Flags().Bool("help", false, "Displays help for the command.")
-
+	cmd.PersistentFlags().StringVar(&o.KubeconfigPath, "kubeconfig", "", `Specifies the path to the kubeconfig file. By default, Kyma CLI uses the KUBECONFIG environment variable or "/$HOME/.kube/config" if the variable is not set.`)
+	cmd.PersistentFlags().BoolP("help", "h", false, "Displays help for the command.")
+	
 	provisionCmd := provision.NewCmd()
 	provisionCmd.AddCommand(minikube.NewCmd(minikube.NewOptions(o)))
 	provisionCmd.AddCommand(gcp.NewCmd(gcp.NewOptions(o)))

cmd/kyma/provision/cmd.go

@@ -10,6 +10,5 @@ func NewCmd() *cobra.Command {
 		Use:   "provision",
 		Short: "Provisions a cluster for Kyma installation.",
 	}
-	cmd.Flags().Bool("help", false, "Displays help for the command.")
 	return cmd
 }

cmd/kyma/provision/gardener/cmd.go

@@ -30,29 +30,35 @@ func NewCmd(o *Options) *cobra.Command {
 
 	cmd := &cobra.Command{
 		Use:   "gardener",
-		Short: "Provisions a Gardener cluster.",
-		Long:  `Use this command to provision a Gardener cluster for Kyma installation.`,
+		Short: "Provisions a Kubernetes cluster using Gardener.",
+		Long:  `Use this command to provision Kubernetes clusters with Gardener for Kyma installation. 
+To successfully provision a cluster on a cloud provider of your choice, you must first create a service account to pass its details as one of the command parameters. 
+Use the following instructions to create a service account for a selected provider:
+- GCP: Check the roles and create a service account using instructions at https://gardener.cloud/050-tutorials/content/howto/gardener_gcp/
+- AWS: Check the roles and create a service account using instructions at https://gardener.cloud/050-tutorials/content/howto/gardener_aws/ 
+- Azure: Create a service account with the `+ "`contributor`" +` role. Use service account details to create a Secret and store it in Gardener.`,
+
 		RunE:  func(_ *cobra.Command, _ []string) error { return c.Run() },
 	}
 
-	cmd.Flags().StringVarP(&o.Name, "name", "n", "", "Name of the cluster to provision. (required)")
-	cmd.Flags().StringVarP(&o.Project, "project", "p", "", "Name of the Gardener Project where to provision the cluster in. (required)")
-	cmd.Flags().StringVarP(&o.CredentialsFile, "credentials", "c", "", "Path to the Gardener service account kubeconfig file. (required)")
-	cmd.Flags().StringVar(&o.TargetProvider, "target-provider", "gcp", "Specify the cloud provider that Gardener should use to create the cluster.")
-	cmd.Flags().StringVarP(&o.Secret, "secret", "s", "", "Name of the Gardener secret to access the target provider. (required)")
-	cmd.Flags().StringVarP(&o.KubernetesVersion, "kube-version", "k", "1.15.4", "Kubernetes version of the cluster to provision.")
-	cmd.Flags().StringVarP(&o.Region, "region", "r", "europe-west3", "Region of the cluster to provision.")
-	cmd.Flags().StringVarP(&o.Zone, "zone", "z", "europe-west3-a", "Zone of the cluster to provision.")
-	cmd.Flags().StringVarP(&o.MachineType, "type", "t", "n1-standard-4", "Type of machine of the cluster to provision.")
-	cmd.Flags().StringVar(&o.CIDR, "cidr", "10.250.0.0/19", "Gardener CIDR of the cluster to provision.")
-	cmd.Flags().StringVar(&o.DiskType, "disk-type", "pd-standard", "Type of disk to use on the target provider.")
-	cmd.Flags().IntVar(&o.DiskSizeGB, "disk-size", 30, "Specifies the disk size in GB of the cluster to provision.")
-	cmd.Flags().IntVar(&o.NodeCount, "nodes", 3, "Specifies the number of nodes of the cluster to provision.")
-	cmd.Flags().IntVar(&o.ScalerMin, "scaler-min", 2, "Specifies the minimum autoscale of the cluster to provision.")
-	cmd.Flags().IntVar(&o.ScalerMax, "scaler-max", 4, "Specifies the maximum autoscale of the cluster to provision.")
-	cmd.Flags().IntVar(&o.Surge, "surge", 4, "Specifies maximum surge of the cluster to provision.")
-	cmd.Flags().IntVarP(&o.Unavailable, "unavailable", "u", 1, "Specifies the maximum number of unavailable nodes allowed.")
-	cmd.Flags().StringSliceVarP(&o.Extra, "extra", "e", nil, "Provide one or more arguments of the form NAME=VALUE to add extra configurations.")
+	cmd.Flags().StringVarP(&o.Name, "name", "n", "", "Specifies the name of the cluster to provision. (required)")
+	cmd.Flags().StringVarP(&o.Project, "project", "p", "", "Specifies the name of the Gardener project where you provision the cluster. (required)")
+	cmd.Flags().StringVarP(&o.CredentialsFile, "credentials", "c", "", "Specifies the path to the kubeconfig file of the Gardener service account for a target provider. (required)")
+	cmd.Flags().StringVar(&o.TargetProvider, "target-provider", "gcp", "Specifies the cloud provider that Gardener should use to create the cluster.")
+	cmd.Flags().StringVarP(&o.Secret, "secret", "s", "", "Specifies the name of the Gardener secret used to access the target provider. (required)")
+	cmd.Flags().StringVarP(&o.KubernetesVersion, "kube-version", "k", "1.15.4", "Specifies the Kubernetes version of the cluster.")
+	cmd.Flags().StringVarP(&o.Region, "region", "r", "europe-west3", "Specifies the region of the cluster.")
+	cmd.Flags().StringVarP(&o.Zone, "zone", "z", "europe-west3-a", "Specifies the zone of the cluster.")
+	cmd.Flags().StringVarP(&o.MachineType, "type", "t", "n1-standard-4", "Specifies the machine type used for the cluster.")
+	cmd.Flags().StringVar(&o.CIDR, "cidr", "10.250.0.0/19", "Specifies Gardener Classless Inter-Domain Routing (CIDR) of the cluster.")
+	cmd.Flags().StringVar(&o.DiskType, "disk-type", "pd-standard", "Specifies the type of disk to use on the target provider.")
+	cmd.Flags().IntVar(&o.DiskSizeGB, "disk-size", 30, "Specifies the disk size (in GB) of the cluster.")
+	cmd.Flags().IntVar(&o.NodeCount, "nodes", 3, "Specifies the number of cluster nodes.")
+	cmd.Flags().IntVar(&o.ScalerMin, "scaler-min", 2, "Specifies the minimum autoscale value of the cluster.")
+	cmd.Flags().IntVar(&o.ScalerMax, "scaler-max", 4, "Specifies the maximum autoscale value of the cluster.")
+	cmd.Flags().IntVar(&o.Surge, "surge", 4, "Specifies the maximum surge of the cluster.")
+	cmd.Flags().IntVarP(&o.Unavailable, "unavailable", "u", 1, "Specifies the maximum allowed number of unavailable nodes.")
+	cmd.Flags().StringSliceVarP(&o.Extra, "extra", "e", nil, `Specifies one or more arguments as "NAME=VALUE" key-value pairs to configure additional cluster settings. You can use this flag multiple times or enter the key-value pairs as a comma-separated list.`)
 
 	return cmd
 }

cmd/kyma/provision/gcp/cmd.go

@@ -30,19 +30,21 @@ func NewCmd(o *Options) *cobra.Command {
 
 	cmd := &cobra.Command{
 		Use:   "gcp",
-		Short: "Provisions a GCP cluster.",
-		Long:  `Use this command to provision a GCP cluster for Kyma installation.`,
+		Short: "Provisions a Google Kubernetes Engine (GKE) cluster on Google Cloud Platform (GCP).",
+		Long:  `Use this command to provision a Kubernetes cluster on GCP for Kyma installation. Use the flags to specify cluster details.
+NOTE: To access the provisioned cluster, make sure you get authenticated by Google Cloud SDK. To do so,run `+ "`gcloud auth application-default login`" + ` and log in with your Google Cloud credentials.`,
+
 		RunE:  func(_ *cobra.Command, _ []string) error { return c.Run() },
 	}
 
-	cmd.Flags().StringVarP(&o.Name, "name", "n", "", "Name of the cluster to provision. (required)")
-	cmd.Flags().StringVarP(&o.Project, "project", "p", "", "Name of the GCP Project where to provision the cluster in. (required)")
-	cmd.Flags().StringVarP(&o.CredentialsFile, "credentials", "c", "", "Path to the GCP service account key file. (required)")
-	cmd.Flags().StringVarP(&o.KubernetesVersion, "kube-version", "k", "1.14", "Kubernetes version of the cluster to provision.")
-	cmd.Flags().StringVarP(&o.Location, "location", "l", "europe-west3-a", "Location of the cluster to provision.")
-	cmd.Flags().StringVarP(&o.MachineType, "type", "t", "n1-standard-4", "Type of machine of the cluster to provision.")
-	cmd.Flags().IntVar(&o.DiskSizeGB, "disk-size", 30, "Specifies the disk size in GB of the cluster to provision.")
-	cmd.Flags().IntVar(&o.NodeCount, "nodes", 3, "Specifies the number of nodes of the cluster to provision.")
+	cmd.Flags().StringVarP(&o.Name, "name", "n", "", "Specifies the name of the GKE cluster to provision. (required)")
+	cmd.Flags().StringVarP(&o.Project, "project", "p", "", "Specifies the name of the GCP Project where you provision the GKE cluster. (required)")
+	cmd.Flags().StringVarP(&o.CredentialsFile, "credentials", "c", "", "Specifies the path to the GCP service account key file. (required)")
+	cmd.Flags().StringVarP(&o.KubernetesVersion, "kube-version", "k", "1.14", "Specifies the Kubernetes version of the cluster.")
+	cmd.Flags().StringVarP(&o.Location, "location", "l", "europe-west3-a", "Specifies the location of the cluster.")
+	cmd.Flags().StringVarP(&o.MachineType, "type", "t", "n1-standard-4", "Specifies the machine type used for the cluster.")
+	cmd.Flags().IntVar(&o.DiskSizeGB, "disk-size", 30, "Specifies the disk size (in GB) of the cluster.")
+	cmd.Flags().IntVar(&o.NodeCount, "nodes", 3, "Specifies the number of cluster nodes.")
 	// Temporary disabled flag. To be enabled when hydroform supports TF modules
 	//cmd.Flags().StringSliceVarP(&o.Extra, "extra", "e", nil, "Provide one or more arguments of the form NAME=VALUE to add extra configurations.")
 

cmd/kyma/provision/minikube/cmd.go

@@ -69,7 +69,6 @@ func NewCmd(o *Options) *cobra.Command {
 	cmd.Flags().StringVar(&o.Memory, "memory", "8192", "Specifies RAM reserved for installation.")
 	cmd.Flags().StringVar(&o.CPUS, "cpus", "4", "Specifies the number of CPUs used for installation.")
 	cmd.Flags().StringVar(&o.Profile, "profile", "", "Specifies the Minikube profile.")
-	cmd.Flags().Bool("help", false, "Displays help for the command.")
 	return cmd
 }
 

cmd/kyma/test/cmd.go

@@ -7,9 +7,8 @@ import (
 func NewCmd() *cobra.Command {
 	cmd := &cobra.Command{
 		Use:   "test",
-		Short: "Run tests on a provisioned Kyma cluster.",
+		Short: "Runs tests on a provisioned Kyma cluster.",
 		Long: "Use this command to run tests on a provisioned Kyma cluster.",
 	}
-	cmd.Flags().Bool("help", false, "Displays help for the command.")
 	return cmd
 }

cmd/kyma/test/definitions/cmd.go

@@ -29,7 +29,6 @@ func NewCmd(o *options) *cobra.Command {
 		RunE:    func(_ *cobra.Command, _ []string) error { return cmd.Run() },
 		Aliases: []string{"def"},
 	}
-    cobraCmd.Flags().Bool("help", false, "Displays help for the command.")
 	return cobraCmd
 }
 

cmd/kyma/test/delete/cmd.go

@@ -33,7 +33,6 @@ Provide at least one test suite name.`,
 		RunE:    func(_ *cobra.Command, args []string) error { return cmd.Run(args) },
 		Aliases: []string{"d"},
 	}
-	cobraCmd.Flags().Bool("help", false, "Displays help for the command.")
 	return cobraCmd
 }
 

cmd/kyma/test/list/cmd.go

@@ -30,7 +30,6 @@ func NewCmd(o *options) *cobra.Command {
 		RunE:    func(_ *cobra.Command, _ []string) error { return cmd.Run() },
 		Aliases: []string{"l"},
 	}
-	cobraCmd.Flags().Bool("help", false, "Displays help for the command.")
 	return cobraCmd
 }
 

cmd/kyma/test/run/cmd.go

@@ -41,11 +41,10 @@ To execute all test defintions, run ` + "`kyma test run -n example-test`" + `.
 		Aliases: []string{"r"},
 	}
 
-	cobraCmd.Flags().StringVarP(&o.Name, "name", "n", "", "Specifies the name of the new test suite. If you don't specify the value for the `-n` flag, the name of the test suite will be autogenerated.")
-	cobraCmd.Flags().Int64VarP(&o.ExecutionCount, "count", "c", 1, "Defines how many times every test should be executed. \"count\" and \"max-retries\" flags are mutually exclusive.")
-	cobraCmd.Flags().Int64VarP(&o.MaxRetries, "max-retries", "", 0, "Defines how many times a given test is retried when it fails. A suite is marked with a \"succeeded\" status even if some tests failed at first and then finally succeeded. The default value of 0 means that there are no retries of a given test.")
+	cobraCmd.Flags().StringVarP(&o.Name, "name", "n", "", `Specifies the name of the new test suite. If you don't specify the value for the "-n" flag, the name of the test suite will be autogenerated.`)
+	cobraCmd.Flags().Int64VarP(&o.ExecutionCount, "count", "c", 1, `Defines how many times every test should be executed. "count" and "max-retries" flags are mutually exclusive.`)
+	cobraCmd.Flags().Int64VarP(&o.MaxRetries, "max-retries", "", 0, `Defines how many times a given test is retried when it fails. A suite is marked with a "succeeded" status even if some tests failed at first and then finally succeeded. The default value of 0 means that there are no retries of a given test.`)
 	cobraCmd.Flags().Int64VarP(&o.Concurrency, "concurrency", "", 1, "Specifies the number of tests to be executed in parallel.")
-	cobraCmd.Flags().Bool("help", false, "Displays help for the command.")
 	return cobraCmd
 }
 

cmd/kyma/test/status/cmd.go

@@ -46,7 +46,6 @@ To print the status of specific test cases, `+"`run kyma test status testSuiteOn
 
 	cobraCmd.Flags().StringVarP(&o.OutputFormat, "output", "o", "",
 		"Output format. One of: json|yaml|wide")
-	cobraCmd.Flags().Bool("help", false, "Displays help for the command.")
 	return cobraCmd
 }
 

cmd/kyma/uninstall/cmd.go

@@ -58,7 +58,6 @@ This command:
 	}
 
 	cobraCmd.Flags().DurationVarP(&o.Timeout, "timeout", "", 30*time.Minute, "Time-out after which Kyma CLI stops watching the the process of unstalling Kyma.")
-	cobraCmd.Flags().Bool("help", false, "Displays help for the command.")
 	return cobraCmd
 }
 

cmd/kyma/version/version.go

@@ -33,7 +33,6 @@ func NewCmd(o *Options) *cobra.Command {
 		RunE: func(_ *cobra.Command, _ []string) error { return c.Run() },
 	}
 	cmd.Flags().BoolVarP(&o.Client, "client", "c", false, "Client version only (no server required)")
-    cmd.Flags().Bool("help", false, "Displays help for the command.")
 	return cmd
 }