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

     1  # Machine  Controller
     2  
     3  ![](../../../images/cluster-admission-machine-controller.png)
     4  
     5  The Machine controller's main responsibilities are:
     6  
     7  * Setting an OwnerReference on:
     8      * Each Machine object to the Cluster object.
     9      * The associated BootstrapConfig object.
    10      * The associated InfrastructureMachine object.
    11  * Copy data from `BootstrapConfig.Status.DataSecretName` to `Machine.Spec.Bootstrap.DataSecretName` if
    12  `Machine.Spec.Bootstrap.DataSecretName` is empty.
    13  * Setting NodeRefs to be able to associate machines and Kubernetes nodes.
    14  * Deleting Nodes in the target cluster when the associated machine is deleted.
    15  * Cleanup of related objects.
    16  * Keeping the Machine's Status object up to date with the InfrastructureMachine's Status object.
    17  * Finding Kubernetes nodes matching the expected providerID in the workload cluster.
    18  
    19  After the machine controller sets the OwnerReferences on the associated objects, it waits for the bootstrap
    20  and infrastructure objects referenced by the machine to have the `Status.Ready` field set to `true`. When
    21  the infrastructure object is ready, the machine controller will attempt to read its `Spec.ProviderID` and
    22  copy it into `Machine.Spec.ProviderID`.
    23  
    24  The machine controller uses the kubeconfig for the new workload cluster to watch new nodes coming up.
    25  When a node appears with `Node.Spec.ProviderID` matching `Machine.Spec.ProviderID`, the machine controller
    26  transitions the associated machine into the `Provisioned` state. When the infrastructure ref is also
    27  `Ready`, the machine controller marks the machine as `Running`.
    28  
    29  ## Contracts
    30  
    31  ### Cluster API
    32  
    33  Cluster associations are made via labels.
    34  
    35  #### Expected labels
    36  
    37  | what | label | value | meaning |
    38  | --- | --- | --- | --- |
    39  | Machine | `cluster.x-k8s.io/cluster-name` | `<cluster-name>` | Identify a machine as belonging to a cluster with the name `<cluster-name>`|
    40  | Machine | `cluster.x-k8s.io/control-plane` | `true` | Identifies a machine as a control-plane node |
    41  
    42  ### Bootstrap provider
    43  
    44  The BootstrapConfig object **must** have a `status` object.
    45  
    46  To override the bootstrap provider, a user (or external system) can directly set the `Machine.Spec.Bootstrap.Data`
    47  field. This will mark the machine as ready for bootstrapping and no bootstrap data will be copied from the
    48  BootstrapConfig object.
    49  
    50  #### Required `status` fields
    51  
    52  The `status` object **must** have several fields defined:
    53  
    54  * `ready` - a boolean field indicating the bootstrap config data is generated and ready for use.
    55  * `dataSecretName` - a string field referencing the name of the secret that stores the generated bootstrap data.
    56  
    57  #### Optional `status` fields
    58  
    59  The `status` object **may** define several fields that do not affect functionality if missing:
    60  
    61  * `failureReason` - a string field explaining why a fatal error has occurred, if possible.
    62  * `failureMessage` - a string field that holds the message contained by the error.
    63  
    64  Example:
    65  
    66  ```yaml
    67  kind: MyBootstrapProviderConfig
    68  apiVersion: bootstrap.cluster.x-k8s.io/v1alpha3
    69  status:
    70      ready: true
    71      dataSecretName: "MyBootstrapSecret"
    72  ```
    73  
    74  ### Infrastructure provider
    75  
    76  The InfrastructureMachine object **must** have both `spec` and `status` objects.
    77  
    78  #### Required `spec` fields
    79  
    80  The `spec` object **must** at least one field defined:
    81  
    82  * `providerID` - a cloud provider ID identifying the machine.
    83  
    84  #### Optional `spec` fields
    85  
    86  The `spec` object **may** define several fields that do not affect functionality if missing:
    87  
    88  * `failureDomain` - is a string identifying the failure domain the instance is running in.
    89  
    90  #### Required `status` fields
    91  
    92  The `status` object **must** at least one field defined:
    93  
    94  * `ready` - a boolean field indicating if the infrastructure is ready to be used or not.
    95  
    96  #### Optional `status` fields
    97  
    98  The `status` object **may** define several fields that do not affect functionality if missing:
    99  
   100  * `failureReason` - is a string that explains why a fatal error has occurred, if possible.
   101  * `failureMessage` - is a string that holds the message contained by the error.
   102  * `addresses` - is a `MachineAddresses` (a list of `MachineAddress`) which represents host names, external IP addresses, internal IP addresses,
   103  external DNS names, and/or internal DNS names for the provider's machine instance. `MachineAddress` is
   104  defined as:
   105      - `type` (string): one of `Hostname`, `ExternalIP`, `InternalIP`, `ExternalDNS`, `InternalDNS`
   106      - `address` (string)
   107  
   108  Example:
   109  ```yaml
   110  kind: MyMachine
   111  apiVersion: infrastructure.cluster.x-k8s.io/v1alpha3
   112  spec:
   113      providerID: cloud:////my-cloud-provider-id
   114  status:
   115      ready: true
   116  ```
   117  
   118  ### Secrets
   119  
   120  The Machine controller will create a secret or use an existing secret in the following format:
   121  
   122  | secret name | field name | content |
   123  |:---:|:---:|---|
   124  |`<cluster-name>-kubeconfig`|`value`|base64 encoded kubeconfig that is authenticated with the child cluster|