[release-1.4] 📖 update book on in-place propagation

docs/book/src/developer/architecture/controllers/machine-deployment.md

@@ -11,3 +11,16 @@ Its main responsibilities are:
 * Updating the status of MachineDeployment objects
 
 ![](../../../images/cluster-admission-machinedeployment-controller.png)
+
+## In-place propagation
+Changes to the following fields of the MachineDeployment are propagated in-place to the MachineSet and do not trigger a full rollout:
+- `.annotations`
+- `.spec.template.metadata.labels`
+- `.spec.template.metadata.annotations`
+- `.spec.minReadySeconds`
+- `.spec.template.spec.nodeDrainTimeout`
+- `.spec.template.spec.nodeDeletionTimeout`
+- `.spec.template.spec.nodeVolumeDetachTimeout`
+- `.spec.strategy.rollingUpdate.deletePolicy`
+
+Note: In cases where changes to any of these fields are paired with rollout causing changes, the new values are propagated only to the new MachineSet. 

docs/book/src/developer/architecture/controllers/machine-set.md

@@ -1,6 +1,6 @@
 # MachineSet
 
-A MachineSet is an immutable abstraction over [Machines](./machine.md).
+A MachineSet is an abstraction over [Machines](./machine.md).
 
 Its main responsibilities are:
 * Adopting unowned Machines that aren't assigned to a MachineSet
@@ -9,3 +9,17 @@ Its main responsibilities are:
   * Monitoring the status of those booted machines
 
 ![](../../../images/cluster-admission-machineset-controller.png)
+
+## In-place propagation
+Changes to the following fields of MachineSet are propagated in-place to the Machine without needing a full rollout:
+- `.spec.template.metadata.labels`
+- `.spec.template.metadata.annotations`
+- `.spec.template.spec.nodeDrainTimeout`
+- `.spec.template.spec.nodeDeletionTimeout`
+- `.spec.template.spec.nodeVolumeDetachTimeout`
+
+Changes to the following fields of MachineSet are propagated in-place to the InfrastructureMachine and BootstrapConfig:
+- `.spec.machineTemplate.metadata.labels`
+- `.spec.machineTemplate.metadata.annotations`
+
+Note: Changes to these fields will not be propagated to Machines that are marked for deletion (example: because of scale down).

docs/book/src/developer/architecture/controllers/metadata-propagation.md

@@ -1,25 +1,51 @@
 # Metadata propagation
 Cluster API controllers implement consistent metadata (labels & annotations) propagation across the core API resources.
 This behaviour tries to be consistent with Kubernetes apps/v1 Deployment and ReplicaSet.
-New providers should behave accordingly fitting within the following pattern: 
+New providers should behave accordingly fitting within the following pattern:
+
+![](../../../images/metadata-propagation.jpg)
+
+## Cluster Topology
+ControlPlaneTopology labels are labels and annotations are continuously propagated to ControlPlane top-level labels and annotations
+and ControlPlane MachineTemplate labels and annotations.
+- `.spec.topology.controlPlane.metadata.labels` => `ControlPlane.labels`, `ControlPlane.spec.machineTemplate.metadata.labels`
+- `.spec.topology.controlPlane.metadata.annotations` => `ControlPlane.annotations`, `ControlPlane.spec.machineTemplate.metadata.annotations`
+
+MachineDeploymentTopology labels and annotations are continuously propagated to MachineDeployment top-level labels and annotations
+and MachineDeployment MachineTemplate labels and annotations.
+- `.spec.topology.machineDeployments[i].metadata.labels` => `MachineDeployment.labels`, `MachineDeployment.spec.template.metadata.labels`
+- `.spec.topology.machineDeployments[i].metadata.annotations` => `MachineDeployment.annotations`, `MachineDeployment.spec.template.metadata.annotations`
+
+## ClusterClass
+ControlPlaneClass labels are labels and annotations are continuously propagated to ControlPlane top-level labels and annotations
+and ControlPlane MachineTemplate labels and annotations.
+- `.spec.controlPlane.metadata.labels` => `ControlPlane.labels`, `ControlPlane.spec.machineTemplate.metadata.labels`
+- `.spec.controlPlane.metadata.annotations` => `ControlPlane.annotations`, `ControlPlane.spec.machineTemplate.metadata.annotations`
+Note: ControlPlaneTopology labels and annotations take precedence over ControlPlaneClass labels and annotations.
+
+MachineDeploymentClass labels and annotations are continuously propagated to MachineDeployment top-level labels and annotations
+and MachineDeployment MachineTemplate labels and annotations.
+- `.spec.workers.machineDeployments[i].template.metadata.labels` => `MachineDeployment.labels`, `MachineDeployment.spec.template.metadata.labels`
+- `.spec.worker.machineDeployments[i].template.metadata.annotations` => `MachineDeployment.annotations`, `MachineDeployment.spec.template.metadata.annotations`
+Note: MachineDeploymentTopology labels and annotations take precedence over MachineDeploymentClass labels and annotations.
 
 ## KubeadmControlPlane
 Top-level labels and annotations do not propagate at all.
 - `.labels` => Not propagated.
 - `.annotations` => Not propagated.
 
-MachineTemplate labels and annotations propagate to Machines, InfraMachines and BootstrapConfigs.
+MachineTemplate labels and annotations continuously propagate to new and existing Machines, InfraMachines and BootstrapConfigs.
 - `.spec.machineTemplate.metadata.labels` => `Machine.labels`, `InfraMachine.labels`, `BootstrapConfig.labels`
 - `.spec.machineTemplate.metadata.annotations` => `Machine.annotations`, `InfraMachine.annotations`, `BootstrapConfig.annotations`
 
 ## MachineDeployment
 Top-level labels do not propagate at all.
-Top-level annotations propagate to MachineSets top-level annotations.
+Top-level annotations continuously propagate to MachineSets top-level annotations.
 - `.labels` => Not propagated.
 - `.annotations` => MachineSet.annotations
 
-Template labels propagate to MachineSets top-level and MachineSets template metadata.
-Template annotations propagate to MachineSets template metadata.
+Template labels continuously propagate to MachineSets top-level and MachineSets template metadata.
+Template annotations continuously propagate to MachineSets template metadata.
 - `.spec.template.metadata.labels` => `MachineSet.labels`, `MachineSet.spec.template.metadata.labels`
 - `.spec.template.metadata.annotations` => `MachineSet.spec.template.metadata.annotations`
 
@@ -28,6 +54,18 @@ Top-level labels and annotations do not propagate at all.
 - `.labels` => Not propagated.
 - `.annotations` => Not propagated.
 
-Template labels and annotations propagate to Machines, InfraMachines and BootstrapConfigs.
+Template labels and annotations continuously propagate to new and existing Machines, InfraMachines and BootstrapConfigs.
 - `.spec.template.metadata.labels` => `Machine.labels`, `InfraMachine.labels`, `BootstrapConfig.labels`
 - `.spec.template.metadata.annotations` => `Machine.annotations`, `InfraMachine.annotations`, `BootstrapConfig.annotations`
+
+## Machine
+Top-level labels that meet a specific cretria are propagated to the Node labels and top-level annotatation are not propagated.
+- `.labels.[label-meets-criteria]` => `Node.labels`
+- `.annotations` => Not propagated.
+
+Label should meet one of the following criterias to propate to Node: 
+- Has `node-role.kubernetes.io` as prefix.
+- Belongs to `node-restriction.kubernetes.io` domain.
+- Belongs to `node.cluster.x-k8s.io` domain.  
+
+

docs/book/src/images/cluster-admission-machinedeployment-controller.plantuml

@@ -21,6 +21,7 @@ repeat
   else 
     if (RollingUpdate Deployment Strategy) then (yes)
       :Select newest MachineSet;
+      :Propagate in-place changes to newest MachineSet;
       if (Too Many replicas) then (yes)
         #LightBlue:Scale machineSet down;
       elseif (Not Enough Replicas)
@@ -33,6 +34,7 @@ repeat
       endif
     elseif (OnDelete Deployment Strategy) then (yes)
       :Select newest MachineSet;
+      :Propagate in-place changes to newest MachineSet;
       if (Too Many replicas) then (yes)
         #LightBlue:Scale machineSet down;
       elseif (Not Enough Replicas)

docs/book/src/images/cluster-admission-machineset-controller.plantuml

@@ -11,6 +11,7 @@ repeat
       #LightBlue:Adopt machine;
     endif
   repeat while (More machines) is (yes)
+  :Propagate in-place changes to existing Machines;
   if (Not enough replicas) then (yes)
     #LightBlue:Boot new machine;
   elseif (Too many replicas) then (yes)

docs/book/src/tasks/control-plane/kubeadm-control-plane.md

@@ -37,5 +37,19 @@ Cluster API Machines:
   [Machine Deletion Phase Hooks proposal](https://github.com/kubernetes-sigs/cluster-api/blob/main/docs/proposals/20200602-machine-deletion-phase-hooks.md)
   for additional details.
 
+### In-place propagation
+Changes to the following fields of KubeadmControlPlane are propagated in-place to the Machines and do not trigger a full rollout:
+- `.spec.machineTemplate.metadata.labels`
+- `.spec.machineTemplate.metadata.annotations`
+- `.spec.nodeDrainTimeout`
+- `.spec.nodeDeletionTimeout`
+- `.spec.nodeVolumeDetachTimeout`
+
+Changes to the following fields of KubeadmControlPlane are propagated in-place to the InfrastructureMachine and KubeadmConfig:
+- `.spec.machineTemplate.metadata.labels`
+- `.spec.machineTemplate.metadata.annotations`
+
+Note: Changes to these fields will not be propagated to Machines, InfraMachines and KubeadmConfigs that are marked for deletion (example: because of scale down).
+
 <!-- links -->
 [upgrades]: ../upgrading-clusters.md#how-to-upgrade-the-kubernetes-control-plane-version