Merge pull request #4778 from fabriziopandini/update-book-for-clusterctl-generate-cluster

📖 update book for using clusterctl generate cluster

Author: k8s-ci-robot

cmd/clusterctl/client/init.go

@@ -121,7 +121,7 @@ func (c *clusterctlClient) Init(options InitOptions) ([]Components, error) {
 		log.Info("")
 		log.Info("You can now create your first workload cluster by running the following:")
 		log.Info("")
-		log.Info("  clusterctl config cluster [name] --kubernetes-version [version] | kubectl apply -f -")
+		log.Info("  clusterctl generate cluster [name] --kubernetes-version [version] | kubectl apply -f -")
 		log.Info("")
 	}
 

docs/book/src/SUMMARY.md

@@ -21,7 +21,7 @@
 - [clusterctl CLI](./clusterctl/overview.md)
     - [clusterctl Commands](clusterctl/commands/commands.md)
         - [init](clusterctl/commands/init.md)
-        - [config cluster](clusterctl/commands/config-cluster.md)
+        - [generate cluster](clusterctl/commands/generate-cluster.md)
         - [generate yaml](clusterctl/commands/generate-yaml.md)
         - [get kubeconfig](clusterctl/commands/get-kubeconfig.md)
         - [describe cluster](clusterctl/commands/describe-cluster.md)

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

@@ -1,7 +1,7 @@
 # clusterctl Commands
 
 * [`clusterctl init`](init.md)
-* [`clusterctl config cluster`](config-cluster.md)
+* [`clusterctl generate cluster`](generate-cluster.md)
 * [`clusterctl generate yaml`](generate-yaml.md)
 * [`clusterctl get kubeconfig`](get-kubeconfig.md)
 * [`clusterctl describe cluster`](describe-cluster.md)
@@ -10,3 +10,4 @@
 * [`clusterctl delete`](delete.md)
 * [`clusterctl completion`](completion.md)
 * [`clusterctl alpha rollout`](alpha-rollout.md)
+* [`clusterctl config cluster` (deprecated)](config-cluster.md)

docs/book/src/clusterctl/commands/config-cluster.md

@@ -1,5 +1,14 @@
 # clusterctl config cluster
 
+<aside class="note warning">
+
+<h1> Warning! </h1>
+
+This command has been deprecated and it will be removed in future releases.
+Use [`clusterctl generate cluster`](generate-cluster.md).
+
+</aside>
+
 The `clusterctl config cluster` command returns a YAML template for creating a workload cluster.
 
 For example

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

@@ -0,0 +1,98 @@
+# clusterctl generate cluster
+
+The `clusterctl generate cluster` command returns a YAML template for creating a workload cluster.
+
+For example
+
+```
+clusterctl generate cluster my-cluster --kubernetes-version v1.16.3 --control-plane-machine-count=3 --worker-machine-count=3 > my-cluster.yaml
+```
+
+Geenerates a YAML file named `my-cluster.yaml` with a predefined list of Cluster API objects; Cluster, Machines,
+Machine Deployments, etc. to be deployed in the current namespace (in case, use the `--target-namespace` flag to
+specify a different target namespace).
+
+Then, the file can be modified using your editor of choice; when ready, run the following command
+to apply the cluster manifest.
+
+```
+kubectl apply -f my-cluster.yaml
+```
+
+### Selecting the infrastructure provider to use
+
+The `clusterctl generate cluster` command uses smart defaults in order to simplify the user experience; in the example above,
+it detects that there is only an `aws` infrastructure provider in the current management cluster and so it automatically
+selects a cluster template from the `aws` provider's repository.
+
+In case there is more than one infrastructure provider, the following syntax can be used to select which infrastructure
+provider to use for the workload cluster:
+
+```
+clusterctl generate cluster my-cluster --kubernetes-version v1.16.3 \
+    --infrastructure aws > my-cluster.yaml
+```
+
+or
+
+```
+clusterctl generate cluster my-cluster --kubernetes-version v1.16.3 \
+    --infrastructure aws:v0.4.1 > my-cluster.yaml
+```
+
+### Flavors
+
+The infrastructure provider authors can provide different types of cluster templates, or flavors; use the `--flavor` flag
+to specify which flavor to use; e.g.
+
+```
+clusterctl generate cluster my-cluster --kubernetes-version v1.16.3 \
+    --flavor high-availability > my-cluster.yaml
+```
+
+Please refer to the providers documentation for more info about available flavors.
+
+### Alternative source for cluster templates
+
+clusterctl uses the provider's repository as a primary source for cluster templates; the following alternative sources
+for cluster templates can be used as well:
+
+#### ConfigMaps
+
+Use the `--from-config-map` flag to read cluster templates stored in a Kubernetes ConfigMap; e.g.
+
+```
+clusterctl generate cluster my-cluster --kubernetes-version v1.16.3 \
+    --from-config-map my-templates > my-cluster.yaml
+```
+
+Also following flags are available `--from-config-map-namespace` (defaults to current namespace) and `--from-config-map-key`
+(defaults to `template`).
+
+#### GitHub or local file system folder
+
+Use the `--from` flag to read cluster templates stored in a GitHub repository or in a local file system folder; e.g.
+
+```
+clusterctl generate cluster my-cluster --kubernetes-version v1.16.3 \
+   --from https://github.com/my-org/my-repository/blob/master/my-template.yaml > my-cluster.yaml
+```
+
+or
+
+```
+clusterctl generate cluster my-cluster --kubernetes-version v1.16.3 \
+   --from ~/my-template.yaml > my-cluster.yaml
+```
+
+### Variables
+
+If the selected cluster template expects some environment variables, the user should ensure those variables are set in advance.
+
+E.g. if the `AWS_CREDENTIALS` variable is expected for a cluster template targeting the `aws` infrastructure, you
+should ensure the corresponding environment variable to be set before executing `clusterctl generate cluster`.
+
+Please refer to the providers documentation for more info about the required variables or use the
+`clusterctl generate cluster --list-variables` flag to get a list of variables names required by a cluster template.
+
+The [clusterctl configuration](./../configuration.md) file can be used as alternative to environment variables.

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

@@ -142,7 +142,7 @@ The user should ensure the variables required by a provider are set in advance.
 <h1> How can I known which variables a provider requires? </h1>
 
 Users can refer to the provider documentation for the list of variables to be set or use the
-`clusterctl config provider <provider-name>` command to get a list of expected variable names.
+`clusterctl generate provider <provider-name> --describe` command to get a list of expected variable names.
 
 </aside>
 

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

@@ -55,7 +55,7 @@ This can now be achieved with the following procedure:
 
 1. Create a temporary bootstrap cluster, e.g. using Kind or Minikube
 2. Use `clusterctl init` to install the provider components
-3. Use `clusterctl config cluster ... | kubectl apply -f -` to provision a target management cluster
+3. Use `clusterctl generate cluster ... | kubectl apply -f -` to provision a target management cluster
 4. Wait for the target management cluster to be up and running
 5. Get the kubeconfig for the new target management cluster
 6. Use `clusterctl init` with the new cluster's kubeconfig to install the provider components

docs/book/src/clusterctl/configuration.md

@@ -132,7 +132,7 @@ provider repositories.
 For example, you can now do:
 
 ```bash
-clusterctl config cluster mycluster --flavor dev --infrastructure aws:v0.5.0 -v5
+clusterctl generate cluster mycluster --flavor dev --infrastructure aws:v0.5.0 -v5
 ```
 
 The `-v5` provides verbose logging which will confirm the usage of the

docs/book/src/clusterctl/developers.md

@@ -106,7 +106,7 @@ The above config file changes the location of the [overrides layer] folder thus
 you dev session isn't hijacked by other local artifacts.
 
 With the only exception of the docker provider, the local repository folder does not contain cluster templates,
-so the `clusterctl config cluster` command will fail.
+so the `clusterctl generate cluster` command will fail.
 
 </aside>
 

docs/book/src/clusterctl/overview.md

@@ -12,7 +12,7 @@ mis-configurations or in managing day 2 operations such as upgrades.
 * 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 cluster`](commands/config-cluster.md) to spec out workload clusters
 * use [`clusterctl generate yaml`](commands/generate-yaml.md) to process yaml
 * use [`clusterctl get kubeconfig`](commands/get-kubeconfig.md) to get the kubeconfig of an existing workload cluster.
   using clusterctl's internal yaml processor.

docs/book/src/clusterctl/provider-contract.md

@@ -194,7 +194,7 @@ providers.
 
 ### Workload cluster templates
 
-An infrastructure provider could publish a **cluster templates** file to be used by `clusterctl config cluster`.
+An infrastructure provider could publish a **cluster templates** file to be used by `clusterctl generate cluster`.
 This is single YAML with _all_ the objects required to create a new workload cluster.
 
 The following rules apply:
@@ -205,7 +205,7 @@ Cluster templates MUST be stored in the same folder as the component YAML and fo
 1. The default cluster template should be named `cluster-template.yaml`.
 2. Additional cluster template should be named `cluster-template-{flavor}.yaml`. e.g `cluster-template-prod.yaml`
 
-`{flavor}` is the name the user can pass to the `clusterctl config cluster --flavor` flag to identify the specific template to use.
+`{flavor}` is the name the user can pass to the `clusterctl generate cluster --flavor` flag to identify the specific template to use.
 
 Each provider SHOULD create user facing documentation with the list of available cluster templates.
 
@@ -224,7 +224,7 @@ notes that are required to assist the user in defining the value for each variab
 
 ##### Common variables
 
-The `clusterctl config cluster` command allows user to set a small set of common variables via CLI flags or command arguments.
+The `clusterctl generate cluster` command allows user to set a small set of common variables via CLI flags or command arguments.
 
 Templates writers should use the common variables to ensure consistency across providers and a simpler user experience
 (if compared to the usage of OS environment variables or the `clusterctl` config file).
@@ -236,7 +236,7 @@ Templates writers should use the common variables to ensure consistency across p
 |`--controlplane-machine-count`| `${CONTROL_PLANE_MACHINE_COUNT}` | The number of control plane machines to be added to the workload cluster |
 |`--worker-machine-count`| `${WORKER_MACHINE_COUNT}` | The number of worker machines to be added to the workload cluster |
 
-Additionally, the value of the command argument to `clusterctl config cluster <cluster-name>` (`<cluster-name>` in this case), will
+Additionally, the value of the command argument to `clusterctl generate cluster <cluster-name>` (`<cluster-name>` in this case), will
 be applied to every occurrence of the `${ CLUSTER_NAME }` variable.
 
 ## OwnerReferences chain

docs/book/src/developer/e2e.md

@@ -55,7 +55,7 @@ Using the config file it is possible to:
   - A list of additional files to be added to the provider repository, to be used e.g.
     to provide `cluster-templates.yaml` files.
 - Define the list of variables to be used when doing `clusterctl init` or
-  `clusterctl config cluster`.
+  `clusterctl generate cluster`.
 - Define a list of intervals to be used in the test specs for defining timeouts for the
   wait and `Eventually` methods.
 - Define the list of images to be loaded in the management cluster (this is specific to

docs/book/src/tasks/using-kustomize.md

@@ -1,8 +1,8 @@
 # Using Kustomize with Workload Cluster Manifests
 
-Although the `clusterctl config cluster` command exposes a number of different configuration values 
+Although the `clusterctl generate cluster` command exposes a number of different configuration values 
 for customizing workload cluster YAML manifests, some users may need additional flexibility above 
-and beyond what `clusterctl config cluster` or the example "flavor" templates that some CAPI providers 
+and beyond what `clusterctl generate cluster` or the example "flavor" templates that some CAPI providers 
 supply (as an example, see [these flavor templates](https://github.com/kubernetes-sigs/cluster-api-provider-azure/tree/master/templates/flavors) 
 for the Cluster API Provider for Azure). In the future, a [templating solution](https://github.com/kubernetes-sigs/cluster-api/issues/3252) 
 may be integrated into `clusterctl` to help address this need, but in the meantime users can use 
@@ -26,7 +26,7 @@ assume that you are using a directory structure that looks something like this:
 ```
 
 In the overlay directories, the "base" (unmodified) Cluster API configuration (perhaps generated using 
-`clusterctl config cluster`) would be referenced as a resource in `kustomization.yaml` using `../../base`.
+`clusterctl generate cluster`) would be referenced as a resource in `kustomization.yaml` using `../../base`.
 
 ## Example: Using Kustomize to Specify Custom Images
 

docs/book/src/user/quick-start.md

@@ -321,7 +321,7 @@ Your management cluster has been initialized successfully!
 
 You can now create your first workload cluster by running the following:
 
-  clusterctl config cluster [name] --kubernetes-version [version] | kubectl apply -f -
+  clusterctl generate cluster [name] --kubernetes-version [version] | kubectl apply -f -
 ```
 
 <aside class="note">
@@ -341,13 +341,13 @@ Once the management cluster is ready, you can create your first workload cluster
 
 #### Preparing the workload cluster configuration
 
-The `clusterctl config cluster` command returns a YAML template for creating a [workload cluster].
+The `clusterctl generate cluster` command returns a YAML template for creating a [workload cluster].
 
 <aside class="note">
 
 <h1> Which provider will be used for my cluster? </h1>
 
-The `clusterctl config cluster` command uses smart defaults in order to simplify the user experience; in this example,
+The `clusterctl generate cluster` command uses smart defaults in order to simplify the user experience; in this example,
 it detects that there is only an `aws` infrastructure provider and so it uses that when creating the cluster.
 
 </aside>
@@ -356,10 +356,10 @@ it detects that there is only an `aws` infrastructure provider and so it uses th
 
 <h1> What topology will be used for my cluster? </h1>
 
-The `clusterctl config cluster` command by default uses cluster templates which are provided by the infrastructure
+The `clusterctl generate cluster` command by default uses cluster templates which are provided by the infrastructure
 providers. See the provider's documentation for more information.
 
-See the `clusterctl config cluster` [command][clusterctl config cluster] documentation for
+See the `clusterctl generate cluster` [command][clusterctl generate cluster] documentation for
 details about how to use alternative sources. for cluster templates.
 
 </aside>
@@ -369,7 +369,7 @@ details about how to use alternative sources. for cluster templates.
 Depending on the infrastructure provider you are planning to use, some additional prerequisites should be satisfied
 before configuring a cluster with Cluster API. Instructions are provided for common providers below.
 
-Otherwise, you can look at the `clusterctl config cluster` [command][clusterctl config cluster] documentation for details about how to
+Otherwise, you can look at the `clusterctl generate cluster` [command][clusterctl generate cluster] documentation for details about how to
 discover the list of variables required by a cluster templates.
 
 {{#tabs name:"tab-configuration-infrastructure" tabs:"AWS,Azure,DigitalOcean,Docker,GCP,vSphere,OpenStack,Metal3,Packet"}}
@@ -492,7 +492,7 @@ Depending on your OpenStack and underlying hypervisor the following options migh
 
 To see all required OpenStack environment variables execute:
 ```bash
-clusterctl config cluster --infrastructure openstack --list-variables capi-quickstart
+clusterctl generate cluster --infrastructure openstack --list-variables capi-quickstart
 ```
 
 The following script can be used to export some of them:
@@ -578,7 +578,7 @@ For the purpose of this tutorial, we'll name our cluster capi-quickstart.
 {{#tab Azure|AWS|DigitalOcean|GCP|vSphere|OpenStack|Metal3|Packet}}
 
 ```bash
-clusterctl config cluster capi-quickstart \
+clusterctl generate cluster capi-quickstart \
   --kubernetes-version v1.19.7 \
   --control-plane-machine-count=3 \
   --worker-machine-count=3 \
@@ -597,7 +597,7 @@ The Docker provider is not designed for production use and is intended for devel
 </aside>
 
 ```bash
-clusterctl config cluster capi-quickstart --flavor development \
+clusterctl generate cluster capi-quickstart --flavor development \
   --kubernetes-version v1.19.7 \
   --control-plane-machine-count=3 \
   --worker-machine-count=3 \
@@ -612,7 +612,7 @@ Machine Deployments, etc.
 
 The file can be eventually modified using your editor of choice.
 
-See [clusterctl config cluster] for more details.
+See [clusterctl generate cluster] for more details.
 
 #### Apply the workload cluster
 
@@ -761,7 +761,7 @@ See the [clusterctl] documentation for more detail about clusterctl supported ac
 [capa]: https://cluster-api-aws.sigs.k8s.io
 [capv-upload-images]: https://github.com/kubernetes-sigs/cluster-api-provider-vsphere/blob/master/docs/getting_started.md#uploading-the-machine-images
 [clusterawsadm]: https://cluster-api-aws.sigs.k8s.io/clusterawsadm/clusterawsadm.html
-[clusterctl config cluster]: ../clusterctl/commands/config-cluster.md
+[clusterctl generate cluster]: ../clusterctl/commands/generate-cluster.md
 [clusterctl get kubeconfig]: ../clusterctl/commands/get-kubeconfig.md
 [clusterctl]: ../clusterctl/overview.md
 [Docker]: https://www.docker.com/