Add metadata propagation docs

docs/book/src/SUMMARY.md

@@ -47,6 +47,7 @@
         - [MachineHealthCheck](./developer/architecture/controllers/machine-health-check.md)
         - [Control Plane](./developer/architecture/controllers/control-plane.md)
         - [MachinePool](./developer/architecture/controllers/machine-pool.md)
+        - [Metadata propagation](./developer/architecture/controllers/metadata-propagation.md)
         - [Multi-tenancy](./developer/architecture/controllers/multi-tenancy.md)
         - [Support multiple instances](./developer/architecture/controllers/support-multiple-instances.md)
     - [Provider Implementers](./developer/providers/implementers.md)

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

@@ -0,0 +1,33 @@
+# 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: 
+
+## KubeadmControlPlane
+Top-level labels and annotations do not propagate at all.
+MachineTemplate labels and annotations propagate to Machines, InfraMachines and KubeadmConfig.
+
+- .labels =>
+- .annotations =>
+- .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.
+Template labels propagate to MachineSets top-level and MachineSets template metadata.
+Template annotations propagate to MachineSets template metadata.
+
+- .labels =>
+- .annotations => MachineSet.annotations
+- .spec.template.metadata.labels => MachineSet.labels, MachineSet.spec.template.metadata.labels
+- .spec.template.metadata.annotations => MachineSet.spec.template.metadata.annotations
+
+## MachineSet
+Top-level labels and annotations do not propagate at all.
+Template labels and annotations propagate to Machines, InfraMachines and BootstrapConfig.
+
+- .labels =>
+- .annotations =>
+- .spec.template.metadata.labels => Machine.labels, InfraMachine.labels, BootstrapConfig.labels
+- .spec.template.metadata.annotations => Machine.annotations, InfraMachine.annotations, BootstrapConfig.labels