sigs.k8s.io/cluster-api@v1.6.3/docs/book/src/developer/architecture/controllers/metadata-propagation.md (about)

     1  # Metadata propagation
     2  Cluster API controllers implement consistent metadata (labels & annotations) propagation across the core API resources.
     3  This behaviour tries to be consistent with Kubernetes apps/v1 Deployment and ReplicaSet.
     4  New providers should behave accordingly fitting within the following pattern:
     5  
     6  ![](../../../images/metadata-propagation.jpg)
     7  
     8  ## Cluster Topology
     9  ControlPlaneTopology labels are labels and annotations are continuously propagated to ControlPlane top-level labels and annotations
    10  and ControlPlane MachineTemplate labels and annotations.
    11  - `.spec.topology.controlPlane.metadata.labels` => `ControlPlane.labels`, `ControlPlane.spec.machineTemplate.metadata.labels`
    12  - `.spec.topology.controlPlane.metadata.annotations` => `ControlPlane.annotations`, `ControlPlane.spec.machineTemplate.metadata.annotations`
    13  
    14  MachineDeploymentTopology labels and annotations are continuously propagated to MachineDeployment top-level labels and annotations
    15  and MachineDeployment MachineTemplate labels and annotations.
    16  - `.spec.topology.machineDeployments[i].metadata.labels` => `MachineDeployment.labels`, `MachineDeployment.spec.template.metadata.labels`
    17  - `.spec.topology.machineDeployments[i].metadata.annotations` => `MachineDeployment.annotations`, `MachineDeployment.spec.template.metadata.annotations`
    18  
    19  ## ClusterClass
    20  ControlPlaneClass labels are labels and annotations are continuously propagated to ControlPlane top-level labels and annotations
    21  and ControlPlane MachineTemplate labels and annotations.
    22  - `.spec.controlPlane.metadata.labels` => `ControlPlane.labels`, `ControlPlane.spec.machineTemplate.metadata.labels`
    23  - `.spec.controlPlane.metadata.annotations` => `ControlPlane.annotations`, `ControlPlane.spec.machineTemplate.metadata.annotations`
    24  Note: ControlPlaneTopology labels and annotations take precedence over ControlPlaneClass labels and annotations.
    25  
    26  MachineDeploymentClass labels and annotations are continuously propagated to MachineDeployment top-level labels and annotations
    27  and MachineDeployment MachineTemplate labels and annotations.
    28  - `.spec.workers.machineDeployments[i].template.metadata.labels` => `MachineDeployment.labels`, `MachineDeployment.spec.template.metadata.labels`
    29  - `.spec.worker.machineDeployments[i].template.metadata.annotations` => `MachineDeployment.annotations`, `MachineDeployment.spec.template.metadata.annotations`
    30  Note: MachineDeploymentTopology labels and annotations take precedence over MachineDeploymentClass labels and annotations.
    31  
    32  ## KubeadmControlPlane
    33  Top-level labels and annotations do not propagate at all.
    34  - `.labels` => Not propagated.
    35  - `.annotations` => Not propagated.
    36  
    37  MachineTemplate labels and annotations continuously propagate to new and existing Machines, InfraMachines and BootstrapConfigs.
    38  - `.spec.machineTemplate.metadata.labels` => `Machine.labels`, `InfraMachine.labels`, `BootstrapConfig.labels`
    39  - `.spec.machineTemplate.metadata.annotations` => `Machine.annotations`, `InfraMachine.annotations`, `BootstrapConfig.annotations`
    40  
    41  ## MachineDeployment
    42  Top-level labels do not propagate at all.
    43  Top-level annotations continuously propagate to MachineSets top-level annotations.
    44  - `.labels` => Not propagated.
    45  - `.annotations` => MachineSet.annotations
    46  
    47  Template labels continuously propagate to MachineSets top-level and MachineSets template metadata.
    48  Template annotations continuously propagate to MachineSets template metadata.
    49  - `.spec.template.metadata.labels` => `MachineSet.labels`, `MachineSet.spec.template.metadata.labels`
    50  - `.spec.template.metadata.annotations` => `MachineSet.spec.template.metadata.annotations`
    51  
    52  ## MachineSet
    53  Top-level labels and annotations do not propagate at all.
    54  - `.labels` => Not propagated.
    55  - `.annotations` => Not propagated.
    56  
    57  Template labels and annotations continuously propagate to new and existing Machines, InfraMachines and BootstrapConfigs.
    58  - `.spec.template.metadata.labels` => `Machine.labels`, `InfraMachine.labels`, `BootstrapConfig.labels`
    59  - `.spec.template.metadata.annotations` => `Machine.annotations`, `InfraMachine.annotations`, `BootstrapConfig.annotations`
    60  
    61  ## Machine
    62  Top-level labels that meet a specific cretria are propagated to the Node labels and top-level annotatation are not propagated.
    63  - `.labels.[label-meets-criteria]` => `Node.labels`
    64  - `.annotations` => Not propagated.
    65  
    66  Label should meet one of the following criterias to propagate to Node: 
    67  - Has `node-role.kubernetes.io` as prefix.
    68  - Belongs to `node-restriction.kubernetes.io` domain.
    69  - Belongs to `node.cluster.x-k8s.io` domain.  
    70  
    71