From 1e458b5e318c34dc6c7208f752d1079497ce24aa Mon Sep 17 00:00:00 2001 From: Stefan Bueringer Date: Mon, 17 Jan 2022 12:58:46 +0100 Subject: [PATCH] ClusterClass: restructure documentation --- docs/book/src/SUMMARY.md | 4 +- .../commands/alpha-topology-plan.md | 3 + docs/book/src/clusterctl/commands/commands.md | 2 +- .../src/clusterctl/commands/config-cluster.md | 107 ------------------ .../cluster-class/index.md | 14 ++- ...{upgrade-cluster.md => operate-cluster.md} | 4 +- 6 files changed, 18 insertions(+), 116 deletions(-) create mode 100644 docs/book/src/clusterctl/commands/alpha-topology-plan.md delete mode 100644 docs/book/src/clusterctl/commands/config-cluster.md rename docs/book/src/tasks/experimental-features/cluster-class/{upgrade-cluster.md => operate-cluster.md} (98%) diff --git a/docs/book/src/SUMMARY.md b/docs/book/src/SUMMARY.md index 40f916935d11..d413a478f12d 100644 --- a/docs/book/src/SUMMARY.md +++ b/docs/book/src/SUMMARY.md @@ -20,8 +20,8 @@ - [ClusterResourceSet](./tasks/experimental-features/cluster-resource-set.md) - [ClusterClass](./tasks/experimental-features/cluster-class/index.md) - [Writing a ClusterClass](./tasks/experimental-features/cluster-class/write-clusterclass.md) - - [Upgrading a Cluster](./tasks/experimental-features/cluster-class/upgrade-cluster.md) - [Changing a ClusterClass](./tasks/experimental-features/cluster-class/change-clusterclass.md) + - [Operating a managed Cluster](./tasks/experimental-features/cluster-class/operate-cluster.md) - [Ignition Bootstrap configuration](./tasks/experimental-features/ignition.md) - [clusterctl CLI](./clusterctl/overview.md) - [clusterctl Commands](clusterctl/commands/commands.md) @@ -34,6 +34,8 @@ - [upgrade](clusterctl/commands/upgrade.md) - [delete](clusterctl/commands/delete.md) - [completion](clusterctl/commands/completion.md) + - [alpha rollout](clusterctl/commands/alpha-rollout.md) + - [alpha topology plan](clusterctl/commands/alpha-topology-plan.md) - [clusterctl Configuration](clusterctl/configuration.md) - [clusterctl Provider Contract](clusterctl/provider-contract.md) - [clusterctl for Developers](clusterctl/developers.md) diff --git a/docs/book/src/clusterctl/commands/alpha-topology-plan.md b/docs/book/src/clusterctl/commands/alpha-topology-plan.md new file mode 100644 index 000000000000..cc5dd5d779ac --- /dev/null +++ b/docs/book/src/clusterctl/commands/alpha-topology-plan.md @@ -0,0 +1,3 @@ +# clusterctl alpha topology plan + +**Under Construction** diff --git a/docs/book/src/clusterctl/commands/commands.md b/docs/book/src/clusterctl/commands/commands.md index b6fa8e1044df..0d746bdd366a 100644 --- a/docs/book/src/clusterctl/commands/commands.md +++ b/docs/book/src/clusterctl/commands/commands.md @@ -10,4 +10,4 @@ * [`clusterctl delete`](delete.md) * [`clusterctl completion`](completion.md) * [`clusterctl alpha rollout`](alpha-rollout.md) -* [`clusterctl config cluster` (deprecated)](config-cluster.md) +* [`clusterctl alpha topology plan`](alpha-topology-plan.md) diff --git a/docs/book/src/clusterctl/commands/config-cluster.md b/docs/book/src/clusterctl/commands/config-cluster.md deleted file mode 100644 index a0875b5951b9..000000000000 --- a/docs/book/src/clusterctl/commands/config-cluster.md +++ /dev/null @@ -1,107 +0,0 @@ -# clusterctl config cluster - - - -The `clusterctl config cluster` command returns a YAML template for creating a workload cluster. - -For example - -``` -clusterctl config cluster my-cluster --kubernetes-version v1.16.3 --control-plane-machine-count=3 --worker-machine-count=3 > my-cluster.yaml -``` - -Creates 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 config 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 config cluster my-cluster --kubernetes-version v1.16.3 \ - --infrastructure aws > my-cluster.yaml -``` - -or - -``` -clusterctl config 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 config 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 config 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 config cluster my-cluster --kubernetes-version v1.16.3 \ - --from https://github.com/my-org/my-repository/blob/main/my-template.yaml > my-cluster.yaml -``` - -or - -``` -clusterctl config 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 config cluster`. - -Please refer to the providers documentation for more info about the required variables or use the -`clusterctl config 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/tasks/experimental-features/cluster-class/index.md b/docs/book/src/tasks/experimental-features/cluster-class/index.md index e54ad688ba18..441b5539c7aa 100644 --- a/docs/book/src/tasks/experimental-features/cluster-class/index.md +++ b/docs/book/src/tasks/experimental-features/cluster-class/index.md @@ -8,15 +8,17 @@ ClusterClass is a powerful abstraction implemented on top of existing interfaces **Variable name to enable/disable the feature gate**: `CLUSTER_TOPOLOGY` Additional documentation: +* Background information: [ClusterClass and Managed Topologies CAEP](https://github.com/kubernetes-sigs/cluster-api/blob/main/docs/proposals/202105256-cluster-class-and-managed-topologies.md) * For ClusterClass authors: - * [Writing a ClusterClass](./write-clusterclass.md) - * Publishing a ClusterClass is documented in the [clusterctl Provider contract] -* For Cluster operators: - * Creating a Cluster is documented in the [Quick Start guide] - * [Upgrading a Cluster](./upgrade-cluster.md) + * [Writing a ClusterClass](./write-clusterclass.md) * [Changing a ClusterClass](./change-clusterclass.md) -* Additional background information can be found in the [ClusterClass and Managed Topologies CAEP](https://github.com/kubernetes-sigs/cluster-api/blob/main/docs/proposals/202105256-cluster-class-and-managed-topologies.md) + * Publishing a ClusterClass for clusterctl usage: [clusterctl Provider contract] +* For Cluster operators: + * Creating a Cluster: [Quick Start guide] + * [Operating a managed Cluster](./operate-cluster.md) + * Planning topology rollouts: [clusterctl alpha topology plan] [Quick Start guide]: ../../../user/quick-start.md [clusterctl Provider contract]: ../../../clusterctl/provider-contract.md +[clusterctl alpha topology plan]: ../../../clusterctl/commands/alpha-topology-plan.md diff --git a/docs/book/src/tasks/experimental-features/cluster-class/upgrade-cluster.md b/docs/book/src/tasks/experimental-features/cluster-class/operate-cluster.md similarity index 98% rename from docs/book/src/tasks/experimental-features/cluster-class/upgrade-cluster.md rename to docs/book/src/tasks/experimental-features/cluster-class/operate-cluster.md index e3a66f9f7726..535788633efb 100644 --- a/docs/book/src/tasks/experimental-features/cluster-class/upgrade-cluster.md +++ b/docs/book/src/tasks/experimental-features/cluster-class/operate-cluster.md @@ -1,4 +1,6 @@ -# Upgrade a Cluster using Managed Topology +# Operating a managed Cluster + +## Upgrade the Cluster The `spec.topology` field added to the Cluster object as part of ClusterClass allows changes made on the Cluster to be propagated across all relevant objects. This turns a Kubernetes cluster upgrade into a one-touch operation. Let's assume we have created a CAPD cluster with ClusterClass and Kubernetes v1.21.2 (as documented in the [Quick Start guide]). Looking at the cluster, the version of the control plane and the MachineDeployments is v1.21.2.