Add documentation for cmd in book

- Fixes PR feedback

cmd/clusterctl/client/client.go

@@ -56,8 +56,8 @@ type Client interface {
 	// ApplyUpgrade executes an upgrade plan.
 	ApplyUpgrade(options ApplyUpgradeOptions) error
 
-	// ProcessYAML provides a direct way to process a yaml and inspect it's
-	// variables
+	// ProcessYAML provides a direct way to process a yaml and inspect its
+	// variables.
 	ProcessYAML(options ProcessYAMLOptions) (YamlPrinter, error)
 }
 

cmd/clusterctl/client/config.go

@@ -58,6 +58,7 @@ func (c *clusterctlClient) GetProviderComponents(provider string, providerType c
 	return components, nil
 }
 
+// ProcessYAMLOptions are the options supported by ProcessYAML.
 type ProcessYAMLOptions struct {
 	// URLSource to be used for reading the template
 	URLSource *URLSourceOptions
@@ -68,7 +69,6 @@ type ProcessYAMLOptions struct {
 }
 
 func (c *clusterctlClient) ProcessYAML(options ProcessYAMLOptions) (YamlPrinter, error) {
-
 	// Technically we do not need to connect to the cluster. However, we are
 	// leveraging the template client which exposes GetFromURL() is available
 	// on the cluster client so we create a cluster client with default
@@ -83,11 +83,11 @@ func (c *clusterctlClient) ProcessYAML(options ProcessYAMLOptions) (YamlPrinter,
 		return nil, err
 	}
 
-	if options.URLSource != nil {
-		return c.getTemplateFromURL(cluster, *options.URLSource, "", options.ListVariablesOnly)
+	if options.URLSource == nil {
+		return nil, errors.New("unable to read custom template. Please specify a template source")
 	}
 
-	return nil, errors.New("unable to read custom template. Please specify a template source")
+	return c.getTemplateFromURL(cluster, *options.URLSource, "", options.ListVariablesOnly)
 }
 
 // GetClusterTemplateOptions carries the options supported by GetClusterTemplate.

cmd/clusterctl/client/config_test.go

@@ -624,13 +624,26 @@ v3: ${VAR3:-default3}`
 				URLSource: &URLSourceOptions{
 					URL: templateFile,
 				},
+				ListVariablesOnly: false,
 			},
 			expectErr: false,
 			expectedYaml: `v1: default1
 v2: default2
 v3: default3`,
 			expectedVars: []string{"VAR1", "VAR2", "VAR3"},
 		},
+		{
+			name: "returns the expected variables only if ListVariablesOnly is set",
+			options: ProcessYAMLOptions{
+				URLSource: &URLSourceOptions{
+					URL: templateFile,
+				},
+				ListVariablesOnly: true,
+			},
+			expectErr:    false,
+			expectedYaml: ``,
+			expectedVars: []string{"VAR1", "VAR2", "VAR3"},
+		},
 		{
 			name:      "returns error if no source was specified",
 			options:   ProcessYAMLOptions{},

docs/book/src/SUMMARY.md

@@ -16,6 +16,7 @@
     - [clusterctl Commands](clusterctl/commands/commands.md)
         - [init](clusterctl/commands/init.md)
         - [config cluster](clusterctl/commands/config-cluster.md)
+        - [generate yaml](clusterctl/commands/generate-yaml.md)
         - [move](./clusterctl/commands/move.md)
         - [upgrade](clusterctl/commands/upgrade.md)
         - [delete](clusterctl/commands/delete.md)

docs/book/src/clusterctl/commands/commands.md

@@ -2,9 +2,7 @@
 
 * [`clusterctl init`](init.md)
 * [`clusterctl config cluster`](config-cluster.md)
+* [`clusterctl generate yaml`](generate-yaml.md)
 * [`clusterctl move`](move.md)
 * [`clusterctl upgrade`](upgrade.md)
 * [`clusterctl delete`](delete.md)
-
-
-

docs/book/src/clusterctl/commands/generate-yaml.md

@@ -0,0 +1,29 @@
+# clusterctl generate yaml
+
+The `clusterctl generate yaml` command processes yaml using clusterct's yaml
+processor.
+
+clusterctl ships with a simple yaml processor that performs variable
+substitution that takes into account of default values.
+
+Variable values are either sourced from the clusterctl config file or
+from environment variables.
+
+Under the hood, clusterctl's yaml processor uses
+[drone/envsubst][drone-envsusbt] to replace variables and uses the defaults if
+necessary.
+
+Current usage of the command is as follows:
+```bash
+# Generates a configuration file with variable values using a template from a
+# specific URL.
+clusterctl generate yaml --from https://github.com/foo-org/foo-repository/blob/master/cluster-template.yaml
+
+# Generates a configuration file with variable values using
+# a template stored locally.
+clusterctl generate yaml  --from ~/workspace/cluster-template.yaml
+```
+
+
+<!-- Links -->
+[drone-envsusbt]: https://github.com/drone/envsusbt

docs/book/src/clusterctl/overview.md

@@ -5,14 +5,16 @@ The `clusterctl` CLI tool handles the lifecycle of a Cluster API [management clu
 The `clusterctl` command line interface is specifically designed for providing a simple "day 1 experience" and a
 quick start with Cluster API; it automates fetching the YAML files defining [provider components] and installing them.
 
-Additionally it encodes a set of best practices in managing providers, that helps the user in avoiding 
+Additionally it encodes a set of best practices in managing providers, that helps the user in avoiding
 mis-configurations or in managing day 2 operations such as upgrades.
 
 * use [`clusterctl init`](commands/init.md) to install Cluster API providers
 * use [`clusterctl upgrade`](commands/upgrade.md) to upgrade Cluster API providers
 * use [`clusterctl delete`](commands/delete.md) to delete Cluster API providers
 
 * use [`clusterctl config cluster`](commands/config-cluster.md) to spec out workload clusters
+* use [`clusterctl generate yaml`](commands/generate-yaml.md) to process yaml
+  using clusterctl's internal yaml processor.
 * use [`clusterctl move`](commands/move.md) to migrate objects defining a workload clusters (e.g. Cluster, Machines) from a management cluster to another management cluster
 
 <!-- links -->