Edit book

docs/book/src/tasks/experimental-features/cluster-class/write-clusterclass.md

@@ -137,6 +137,55 @@ For more details please see: [clusterctl alpha topology plan].
 
 </aside>
 
+## ClusterClass with MachinePools
+
+ClusterClass also supports MachinePool workers. They work very similar to MachineDeployments. MachinePools
+can be specified in the ClusterClass template under the workers section like so:
+
+```yaml
+apiVersion: cluster.x-k8s.io/v1beta1
+kind: ClusterClass
+metadata:
+  name: docker-clusterclass-v0.1.0
+spec:
+  workers:
+    machinePools:
+    - class: default-worker
+      template:
+        bootstrap:
+          ref:
+            apiVersion: bootstrap.cluster.x-k8s.io/v1beta1
+            kind: KubeadmConfigTemplate
+            name: quick-start-default-worker-bootstraptemplate
+        infrastructure:
+          ref:
+            apiVersion: infrastructure.cluster.x-k8s.io/v1beta1
+            kind: DockerMachinePoolTemplate
+            name: quick-start-default-worker-machinepooltemplate
+```
+
+They can then be similarly defined as workers in the cluster template like so:
+
+```yaml
+apiVersion: cluster.x-k8s.io/v1beta1
+kind: Cluster
+metadata:
+  name: my-docker-cluster
+spec:
+  topology:
+    workers:
+      machinePools:
+      - class: default-worker
+        name: mp-0
+        replicas: 4
+        metadata:
+          labels:
+            mpLabel: mpLabelValue
+          annotations:
+            mpAnnotation: mpAnnotationValue
+        failureDomain: region
+```
+
 ## ClusterClass with MachineHealthChecks
 
 `MachineHealthChecks` can be configured in the ClusterClass for the control plane and for a 
@@ -393,11 +442,11 @@ spec:
 
 This section will explain more advanced features of ClusterClass patches.
 
-### MachineDeployment variable overrides
+### MachineDeployment & MachinePool variable overrides
 
 If you want to use many variations of MachineDeployments in Clusters, you can either define
 a MachineDeployment class for every variation or you can define patches and variables to
-make a single MachineDeployment class more flexible.
+make a single MachineDeployment class more flexible. The same applies for MachinePools.
 
 In the following example we make the `instanceType` of a `AWSMachineTemplate` customizable.
 First we define the `workerMachineType` variable and the corresponding patch:
@@ -446,7 +495,7 @@ spec:
 ```
 
 In the Cluster resource the `workerMachineType` variable can then be set cluster-wide and
-it can also be overridden for an individual MachineDeployment.
+it can also be overridden for an individual MachineDeployment or MachinePool.
 
 ```yaml
 apiVersion: cluster.x-k8s.io/v1beta1
@@ -498,6 +547,12 @@ referenced in patches:
 - `builtin.machineDeployment.{infrastructureRef.name,bootstrap.configRef.name}`
     - Please note, these variables are only available when patching the templates of a MachineDeployment
       and contain the values of the current `MachineDeployment` topology.
+- `builtin.machinePool.{replicas,version,class,name,topologyName}`
+    - Please note, these variables are only available when patching the templates of a MachinePool 
+      and contain the values of the current `MachinePool` topology.
+- `builtin.machinePool.{infrastructureRef.name,bootstrap.configRef.name}`
+    - Please note, these variables are only available when patching the templates of a MachinePool
+      and contain the values of the current `MachinePool` topology.
 
 Builtin variables can be referenced just like regular variables, e.g.:
 ```yaml
@@ -522,8 +577,8 @@ spec:
 **Tips & Tricks**
 
 Builtin variables can be used to dynamically calculate image names. The version used in the patch 
-will always be the same as the one we set in the corresponding MachineDeployment (works the same way 
-with `.builtin.controlPlane.version`).
+will always be the same as the one we set in the corresponding MachineDeployment or MachinePool 
+(works the same way with `.builtin.controlPlane.version`).
 
 ```yaml
 apiVersion: cluster.x-k8s.io/v1beta1
@@ -813,13 +868,17 @@ accessible via built in variables:
 - `builtin.machineDeployment.version`, represent the desired version for each specific MachineDeployment object;
   this version changes only after the upgrade for the control plane is completed, and in case of many
   MachineDeployments in the same cluster, they are upgraded sequentially.
+- `builtin.machinePool.version`, represent the desired version for each specific MachinePool object;
+  this version changes only after the upgrade for the control plane is completed, and in case of many
+  MachinePools in the same cluster, they are upgraded sequentially.
 
 This info should provide the bases for developing version-aware patches, allowing the patch author to determine when a
 patch should adapt to the new Kubernetes version by choosing one of the above variables. In practice the
 following rules applies to the most common use cases:
 
 - When developing a version-aware patch for the control plane, `builtin.controlPlane.version` must be used.
 - When developing a version-aware patch for MachineDeployments, `builtin.machineDeployment.version` must be used.
+- When developing a version-aware patch for MachinePools, `builtin.machinePool.version` must be used.
 
 **Tips & Tricks**:
 

docs/proposals/20210526-cluster-class-and-managed-topologies.md

@@ -70,7 +70,7 @@ status: provisional
 ## Glossary
 
 ### ClusterClass
-A collection of templates that define a topology (control plane, machine deployments, and machine pools) to be used to continuously reconcile one or more Clusters.
+A collection of templates that define a topology (control plane, machine deployments and machine pools) to be used to continuously reconcile one or more Clusters.
 
 ### Topology
 A topology refers to a Cluster that provides a single control point to manage its own topology; the topology is defined by a ClusterClass.
@@ -85,7 +85,7 @@ We're enhancing the Cluster CRD and controller to use a ClusterClass resource to
 
 Currently, Cluster API does not expose a native way to provision multiple clusters of the same configuration. The ClusterClass object is supposed to act as a collection of template references which can be used to create managed topologies.
 
-Today, the Cluster object is a logical grouping of components which describe an underlying cluster. The user experience to create a cluster requires the user to create a bunch of underlying resources such as KCP (control plane provider), MachineDeployments, MachinePools, and infrastructure or bootstrap templates for those resources which logically end up representing the cluster. Since the cluster configuration is spread around multiple components, upgrading the cluster version is hard as it requires changes to different fields in different resources to perform an upgrade. The ClusterClass object aims at reducing this complexity by delegating the responsibility of lifecycle managing these underlying resources to the Cluster controller.
+Today, the Cluster object is a logical grouping of components which describe an underlying cluster. The user experience to create a cluster requires the user to create a bunch of underlying resources such as KCP (control plane provider), MachineDeployments, MachinePools and infrastructure or bootstrap templates for those resources which logically end up representing the cluster. Since the cluster configuration is spread around multiple components, upgrading the cluster version is hard as it requires changes to different fields in different resources to perform an upgrade. The ClusterClass object aims at reducing this complexity by delegating the responsibility of lifecycle managing these underlying resources to the Cluster controller.
 
 This method of provisioning the cluster would act as a single control point for the entire cluster. Scaling the nodes, adding/removing sets of worker nodes and upgrading cluster kubernetes versions would be achievable by editing the topology. This would facilitate the maintenance of existing clusters as well as ease the creation of newer clusters.
 
@@ -205,7 +205,7 @@ at high level the new CRD contains:
   - And/or a set of MachinePoolClasses, each one with:
     - The reference to the bootstrap template (e.g. KubeadmConfigTemplate) to be used when creating machine pools.
     - The reference to the infrastructureMachinePool template (e.g. DockerMachinePoolTemplate) to be used when creating machine pools.
-    - Additional attributes to be set when creating the machine pool object, like metadata, nodeDrainTimeout, rolloutStrategy etc.
+    - Additional attributes to be set when creating the machine pool object, like metadata, nodeDrainTimeout, etc.
 - A list of patches, allowing to change above templates for each specific Cluster.
 - A list of variable definitions, defining a set of additional values the users can provide on each specific cluster;
   those values can be used in patches. 
@@ -269,14 +269,14 @@ API definitions; additionally please consider the following:
 **ClusterClass**
 
 - It is not allowed to change apiGroup or Kind for the referenced templates (with the only exception of the bootstrap templates).
-- MachineDeploymentClass & MachinePoolClass cannot be removed as long as they are used in Clusters.
+- MachineDeploymentClass and MachinePoolClass cannot be removed as long as they are used in Clusters.
 - It’s the responsibility of the ClusterClass author to ensure the patches are semantically valid, in the sense they
   generate valid templates for all the combinations of the corresponding variables in input.
 - Variables cannot be removed as long as they are used in Clusters.
 - When changing variable definitions, the system validates schema changes against existing clusters and blocks in case the changes are  
   not compatible (the variable value is not compatible with the new variable definition).
 
-Note: we are considering adding a field to allow smoother deprecations of MachineDeploymentClass & MachinePoolClass and/or variables, but this
+Note: we are considering adding a field to allow smoother deprecations of MachineDeploymentClass, MachinePoolClass and/or variables, but this
 is not yet implemented as of today.
 
 **Cluster**