diff --git a/cmd/clusterctl/client/init.go b/cmd/clusterctl/client/init.go index a3e9909951ee..1cc2f87872d2 100644 --- a/cmd/clusterctl/client/init.go +++ b/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("") } diff --git a/docs/book/src/SUMMARY.md b/docs/book/src/SUMMARY.md index 1ff3bb8cc735..e3f767679b79 100644 --- a/docs/book/src/SUMMARY.md +++ b/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) diff --git a/docs/book/src/clusterctl/commands/commands.md b/docs/book/src/clusterctl/commands/commands.md index 07f1099d29b8..b6fa8e1044df 100644 --- a/docs/book/src/clusterctl/commands/commands.md +++ b/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) diff --git a/docs/book/src/clusterctl/commands/config-cluster.md b/docs/book/src/clusterctl/commands/config-cluster.md index 38808bf0b9db..22c484ebe4bf 100644 --- a/docs/book/src/clusterctl/commands/config-cluster.md +++ b/docs/book/src/clusterctl/commands/config-cluster.md @@ -1,5 +1,14 @@ # clusterctl config cluster + + The `clusterctl config cluster` command returns a YAML template for creating a workload cluster. For example diff --git a/docs/book/src/clusterctl/commands/generate-cluster.md b/docs/book/src/clusterctl/commands/generate-cluster.md new file mode 100644 index 000000000000..281ff121a585 --- /dev/null +++ b/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. diff --git a/docs/book/src/clusterctl/commands/init.md b/docs/book/src/clusterctl/commands/init.md index 309acdbfe24a..65bd4e3480ba 100644 --- a/docs/book/src/clusterctl/commands/init.md +++ b/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.

How can I known which variables a provider requires?

Users can refer to the provider documentation for the list of variables to be set or use the -`clusterctl config provider ` command to get a list of expected variable names. +`clusterctl generate provider --describe` command to get a list of expected variable names. diff --git a/docs/book/src/clusterctl/commands/move.md b/docs/book/src/clusterctl/commands/move.md index fe28a4c41170..c3286b86491f 100644 --- a/docs/book/src/clusterctl/commands/move.md +++ b/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 diff --git a/docs/book/src/clusterctl/configuration.md b/docs/book/src/clusterctl/configuration.md index 4099dd6b7354..2c6d386259f0 100644 --- a/docs/book/src/clusterctl/configuration.md +++ b/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 diff --git a/docs/book/src/clusterctl/developers.md b/docs/book/src/clusterctl/developers.md index bc6ade6cc0de..5b1111460cf2 100644 --- a/docs/book/src/clusterctl/developers.md +++ b/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. diff --git a/docs/book/src/clusterctl/overview.md b/docs/book/src/clusterctl/overview.md index 99cb5755054c..4770078b01b3 100644 --- a/docs/book/src/clusterctl/overview.md +++ b/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. diff --git a/docs/book/src/clusterctl/provider-contract.md b/docs/book/src/clusterctl/provider-contract.md index 9d4a8503e8c1..1f0b60254be8 100644 --- a/docs/book/src/clusterctl/provider-contract.md +++ b/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 ` (`` in this case), will +Additionally, the value of the command argument to `clusterctl generate cluster ` (`` in this case), will be applied to every occurrence of the `${ CLUSTER_NAME }` variable. ## OwnerReferences chain diff --git a/docs/book/src/developer/e2e.md b/docs/book/src/developer/e2e.md index 7ea8647495b2..a7477448ad00 100644 --- a/docs/book/src/developer/e2e.md +++ b/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 diff --git a/docs/book/src/tasks/using-kustomize.md b/docs/book/src/tasks/using-kustomize.md index dbe6e3dc2015..4aa67ec0d8ae 100644 --- a/docs/book/src/tasks/using-kustomize.md +++ b/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 diff --git a/docs/book/src/user/quick-start.md b/docs/book/src/user/quick-start.md index 82e3ed85aa0b..cd8d4afc6dd2 100644 --- a/docs/book/src/user/quick-start.md +++ b/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 - ``` @@ -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 ```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/