sigs.k8s.io/cluster-api@v1.7.1/docs/book/src/developer/architecture/controllers/machine-pool.md (about) 1 # MachinePool Controller 2 3  4 5 The MachinePool controller's main responsibilities are: 6 7 * Setting an OwnerReference on each MachinePool object to: 8 * The associated Cluster object. 9 * The associated BootstrapConfig object. 10 * The associated InfrastructureMachinePool object. 11 * Copy data from `BootstrapConfig.Status.DataSecretName` to `MachinePool.Spec.Template.Spec.Bootstrap.DataSecretName` if 12 `MachinePool.Spec.Template.Spec.Bootstrap.DataSecretName` is empty. 13 * Setting NodeRefs on MachinePool instances to be able to associate them with Kubernetes nodes. 14 * Deleting Nodes in the target cluster when the associated MachinePool instance is deleted. 15 * Keeping the MachinePool's Status object up to date with the InfrastructureMachinePool's Status object. 16 * Finding Kubernetes nodes matching the expected providerIDs in the workload cluster. 17 18 After the machine pool controller sets the OwnerReferences on the associated objects, it waits for the bootstrap 19 and infrastructure objects referenced by the machine to have the `Status.Ready` field set to `true`. When 20 the infrastructure object is ready, the machine pool controller will attempt to read its `Spec.ProviderIDList` and 21 copy it into `MachinePool.Spec.ProviderIDList`. 22 23 The machine pool controller uses the kubeconfig for the new workload cluster to watch new nodes coming up. 24 When a node appears with a `Node.Spec.ProviderID` in `MachinePool.Spec.ProviderIDList`, the machine pool controller 25 increments the number of ready replicas. When all replicas are ready and the infrastructure ref is also 26 `Ready`, the machine pool controller marks the machine pool as `Running`. 27 28 ## Contracts 29 30 ### Cluster API 31 32 Cluster associations are made via labels. 33 34 #### Expected labels 35 36 | what | label | value | meaning | 37 | --- | --- | --- | --- | 38 | MachinePool | `cluster.x-k8s.io/cluster-name` | `<cluster-name>` | Identify a machine pool as belonging to a cluster with the name `<cluster-name>`| 39 40 ### Bootstrap provider 41 42 The BootstrapConfig object **must** have a `status` object. 43 44 The CRD name must have the format produced by `sigs.k8s.io/cluster-api/util/contract.CalculateCRDName(Group, Kind)`. 45 46 To override the bootstrap provider, a user (or external system) can directly set the `MachinePool.Spec.Bootstrap.DataSecretName` 47 field. This will mark the machine as ready for bootstrapping and no bootstrap data secret name 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 InfrastructureMachinePool object **must** have both `spec` and `status` objects. 77 78 The CRD name must have the format produced by `sigs.k8s.io/cluster-api/util/contract.CalculateCRDName(Group, Kind)`. 79 80 #### Required `spec` fields 81 82 The `spec` object **must** have at least one field defined: 83 84 * `providerIDList` - the list of cloud provider IDs identifying the instances. 85 86 #### Required `status` fields 87 88 The `status` object **must** have at least one field defined: 89 90 * `ready` - a boolean field indicating if the infrastructure is ready to be used or not. 91 92 #### Optional `status` fields 93 94 The `status` object **may** define several fields that do not affect functionality if missing: 95 96 * `failureReason` - is a string that explains why a fatal error has occurred, if possible. 97 * `failureMessage` - is a string that holds the message contained by the error. 98 * `infrastructureMachineKind` - the kind of the InfraMachines. This should be set if the InfrastructureMachinePool plans to support MachinePool Machines. 99 100 **Note:** Infrastructure providers can support MachinePool Machines by having the InfraMachinePool set the `infrastructureMachineKind` to the kind of their InfrastructureMachines. The InfrastructureMachinePool will be responsible for creating InfrastructureMachines as the MachinePool is scaled up, and the MachinePool controller will create Machines for each InfrastructureMachine and set the ownerRef. The InfrastructureMachinePool will be responsible for deleting the Machines as the MachinePool is scaled down in order for the Machine deletion workflow to function properly. In addition, the InfrastructureMachines must also have the following labels set by the InfrastructureMachinePool: `cluster.x-k8s.io/cluster-name` and `cluster.x-k8s.io/pool-name`. The `MachinePoolNameLabel` must also be formatted with `capilabels.MustFormatValue()` so that it will not exceed character limits. 101 102 Example 103 ```yaml 104 kind: MyMachinePool 105 apiVersion: infrastructure.cluster.x-k8s.io/v1beta1 106 spec: 107 providerIDList: 108 - cloud:////my-cloud-provider-id-0 109 - cloud:////my-cloud-provider-id-1 110 status: 111 ready: true 112 infrastructureMachineKind: InfrastructureMachine 113 ``` 114 115 #### Externally Managed Autoscaler 116 117 A provider may implement an InfrastructureMachinePool that is externally managed by an autoscaler. For example, if you are using a Managed Kubernetes provider, it may include its own autoscaler solution. To indicate this to Cluster API, you would decorate the MachinePool object with the following annotation: 118 119 `"cluster.x-k8s.io/replicas-managed-by": ""` 120 121 Cluster API treats the annotation as a "boolean", meaning that the presence of the annotation is sufficient to indicate external replica count management, with one exception: if the value is `"false"`, then that indicates to Cluster API that replica enforcement is nominal, and managed by Cluster API. 122 123 Providers may choose to implement the `cluster.x-k8s.io/replicas-managed-by` annotation with different values (e.g., `external-autoscaler`, or `karpenter`) that may inform different provider-specific behaviors, but those values will have no effect upon Cluster API. 124 125 The effect upon Cluster API of this annotation is that during autoscaling events (initiated externally, not by Cluster API), when more or fewer MachinePool replicas are observed compared to the `Spec.Replicas` configuration, it will update its `Status.Phase` property to the value of `"Scaling"`. 126 127 Example: 128 ```yaml 129 kind: MyMachinePool 130 apiVersion: infrastructure.cluster.x-k8s.io/v1alpha3 131 spec: 132 providerIDList: 133 - cloud:////my-cloud-provider-id-0 134 - cloud:////my-cloud-provider-id-1 135 - cloud:////my-cloud-provider-id-2 136 replicas: 1 137 status: 138 ready: true 139 phase: Scaling 140 infrastructureMachineKind: InfrastructureMachine 141 ``` 142 143 It is the provider's responsibility to update Cluster API's `Spec.Replicas` property to the value observed in the underlying infra environment as it changes in response to external autoscaling behaviors. Once that is done, and the number of providerID items is equal to the `Spec.Replicas` property, the MachinePools's `Status.Phase` property will be set to `Running` by Cluster API. 144 145 ### Secrets 146 147 The machine pool controller will use a secret in the following format: 148 149 | secret name | field name | content | 150 |:---:|:---:|---| 151 |`<cluster-name>-kubeconfig`|`value`|base64 encoded kubeconfig that is authenticated with the workload cluster|