Add HardwareAffinity field to TinkerbellMachineConfig API

This adds a new HardwareAffinity field that provides advanced hardware selection
using Kubernetes-style label selectors with required and preferred affinity terms.

Key changes:
- Add HardwareAffinity, HardwareAffinityTerm, WeightedHardwareAffinityTerm types
- Support required terms (OR'd together) and preferred terms (weighted scoring)
- Support matchLabels and matchExpressions in label selectors
- Add validation for mutual exclusivity with HardwareSelector
- Add validation for weight range (1-100) and operator types
- Make HardwareSelector and HardwareAffinity mutable (changes affect new machines only)
- Update template generation for control plane, worker, and etcd nodes
- Update hardware validation assertions and reconciler

The HardwareAffinity field is mutually exclusive with the existing HardwareSelector.
Both fields are now mutable - changes only affect new machine provisioning as
existing machines keep their assigned hardware via CAPT's ownership labels.

Author: rahulbabu95

docs/content/en/docs/getting-started/baremetal/bare-spec.md

@@ -342,8 +342,8 @@ In the example, there are `TinkerbellMachineConfig` sections for control plane (
 The following fields identify information needed to configure the nodes in each of those groups.
 >**_NOTE:_** Currently, you can only have one machine group for all machines in the control plane, although you can have multiple machine groups for the workers.
 >
-### hardwareSelector (required)
-Use fields under `hardwareSelector` to add key/value pair labels to match particular machines that you identified in the CSV file where you defined the machines in your cluster.
+### hardwareSelector (optional)
+Use `hardwareSelector` to add key/value pair labels to match particular machines that you identified in the CSV file where you defined the machines in your cluster.
 Choose any label name you like.
 For example, if you had added the label `node=cp-machine` to the machines listed in your CSV file that you want to be control plane nodes, the following `hardwareSelector` field would cause those machines to be added to the control plane:
 ```yaml
@@ -356,6 +356,110 @@ spec:
   hardwareSelector:
     node: "cp-machine"
 ```
+
+>**_NOTE:_** Either `hardwareSelector` or `hardwareAffinity` must be specified, but not both. Use `hardwareSelector` for simple single-label matching, or `hardwareAffinity` for advanced selection with multiple terms and weighted preferences.
+
+### hardwareAffinity (optional)
+Use `hardwareAffinity` for advanced hardware selection when you need more control than `hardwareSelector` provides. This field allows you to specify required and preferred affinity terms using Kubernetes-style label selectors.
+
+The `hardwareAffinity` field has two sub-fields:
+- `required`: A list of hardware affinity terms that are OR'd together. Hardware must match at least one term to be considered. At least one required term must be specified.
+- `preferred`: A list of weighted hardware affinity terms. Hardware matching these terms are preferred according to the weights provided (1-100), but are not required.
+
+#### hardwareAffinity.required
+Required hardware affinity terms. Each term contains a `labelSelector` with `matchLabels` and/or `matchExpressions`. Multiple terms in the `required` array are implicitly OR'd together - hardware must match at least one term to be eligible for selection.
+
+#### hardwareAffinity.preferred
+Preferred hardware affinity terms with weights. Each term contains:
+- `weight`: A value from 1-100 indicating preference strength
+- `hardwareAffinityTerm`: The affinity term with a `labelSelector`
+
+#### Example: Simple required affinity
+```yaml
+---
+apiVersion: anywhere.eks.amazonaws.com/v1alpha1
+kind: TinkerbellMachineConfig
+metadata:
+  name: my-cluster-name-cp
+spec:
+  hardwareAffinity:
+    required:
+    - labelSelector:
+        matchLabels:
+          node: "cp-machine"
+  osFamily: ubuntu
+```
+
+#### Example: Multiple required terms (OR'd together)
+When you specify multiple items in the `required` array, they are implicitly OR'd together. Hardware must match at least one of the terms to be eligible. In this example, hardware in either `rack-1` OR `rack-2` will be selected:
+```yaml
+---
+apiVersion: anywhere.eks.amazonaws.com/v1alpha1
+kind: TinkerbellMachineConfig
+metadata:
+  name: my-cluster-name-cp
+spec:
+  hardwareAffinity:
+    required:
+    - labelSelector:
+        matchLabels:
+          rack: "rack-1"
+    - labelSelector:
+        matchLabels:
+          rack: "rack-2"
+  osFamily: ubuntu
+```
+
+#### Example: Required with preferred terms
+```yaml
+---
+apiVersion: anywhere.eks.amazonaws.com/v1alpha1
+kind: TinkerbellMachineConfig
+metadata:
+  name: my-cluster-name-workers
+spec:
+  hardwareAffinity:
+    required:
+    - labelSelector:
+        matchLabels:
+          role: "worker"
+    preferred:
+    - weight: 100
+      hardwareAffinityTerm:
+        labelSelector:
+          matchLabels:
+            gpu: "true"
+    - weight: 50
+      hardwareAffinityTerm:
+        labelSelector:
+          matchLabels:
+            ssd: "true"
+  osFamily: ubuntu
+```
+
+#### Example: Using matchExpressions for complex selection
+```yaml
+---
+apiVersion: anywhere.eks.amazonaws.com/v1alpha1
+kind: TinkerbellMachineConfig
+metadata:
+  name: my-cluster-name-cp
+spec:
+  hardwareAffinity:
+    required:
+    - labelSelector:
+        matchExpressions:
+        - key: rack
+          operator: In
+          values:
+          - rack-1
+          - rack-2
+          - rack-3
+  osFamily: ubuntu
+```
+
+>**_NOTE:_** Either `hardwareSelector` or `hardwareAffinity` must be specified, but not both. Use `hardwareSelector` for simple single-label matching, or `hardwareAffinity` for advanced selection with multiple terms and weighted preferences.
+
 ### osFamily (required)
 Operating system on the machine. Permitted values: `ubuntu` and `redhat` (Default: `ubuntu`).
 

docs/content/en/docs/getting-started/baremetal/baremetal-getstarted.md

@@ -213,7 +213,7 @@ Follow these steps if you want to use your initial cluster to create and manage
      >   ```
      > * For creating multiple workload clusters, it is essential that the hardware labels and selectors defined for a given workload cluster are unique to that workload cluster. For instance, for an EKS Anywhere cluster named `eksa-workload1`, the hardware that is assigned for this cluster should have labels that are only going to be used for this cluster like `type=eksa-workload1-cp` and `type=eksa-workload1-worker`.
      Another workload cluster named `eksa-workload2` can have labels like `type=eksa-workload2-cp` and `type=eksa-workload2-worker`. Please note that even though labels can be arbitrary, they need to be unique for each workload cluster. Not specifying unique cluster labels can cause cluster creations to behave in unexpected ways which may lead to unsuccessful creations and unstable clusters.
-     See the [hardware selectors]({{< relref "./bare-spec/#hardwareselector-required" >}}) section for more information
+     See the [hardware selectors]({{< relref "./bare-spec/#hardwareselector-optional" >}}) section for more information
 
 1. Check the workload cluster:
 

pkg/api/v1alpha1/tinkerbellmachineconfig.go

@@ -70,15 +70,9 @@ func validateTinkerbellMachineConfig(config *TinkerbellMachineConfig) error {
 		return fmt.Errorf("TinkerbellMachineConfig: %v", err)
 	}
 
-	if len(config.Spec.HardwareSelector) == 0 {
-		return fmt.Errorf("TinkerbellMachineConfig: missing spec.hardwareSelector: %s", config.Name)
-	}
-
-	if len(config.Spec.HardwareSelector) != 1 {
-		return fmt.Errorf(
-			"TinkerbellMachineConfig: spec.hardwareSelector must contain only 1 key-value pair: %s",
-			config.Name,
-		)
+	// Validate hardware selection (HardwareSelector vs HardwareAffinity)
+	if err := validateHardwareSelection(config); err != nil {
+		return err
 	}
 
 	if config.Spec.OSFamily == "" {
@@ -112,6 +106,137 @@ func validateTinkerbellMachineConfig(config *TinkerbellMachineConfig) error {
 	return nil
 }
 
+// validateHardwareSelection validates the hardware selection configuration.
+// HardwareSelector and HardwareAffinity are mutually exclusive.
+func validateHardwareSelection(config *TinkerbellMachineConfig) error {
+	hasSelector := !config.Spec.HardwareSelector.IsEmpty()
+	hasAffinity := config.Spec.HardwareAffinity != nil
+
+	// Check mutual exclusivity
+	if hasSelector && hasAffinity {
+		return fmt.Errorf("TinkerbellMachineConfig: hardwareSelector and hardwareAffinity are mutually exclusive: %s", config.Name)
+	}
+
+	// At least one must be specified
+	if !hasSelector && !hasAffinity {
+		return fmt.Errorf("TinkerbellMachineConfig: either hardwareSelector or hardwareAffinity must be specified: %s", config.Name)
+	}
+
+	// Validate HardwareSelector if present
+	if hasSelector {
+		if len(config.Spec.HardwareSelector) != 1 {
+			return fmt.Errorf(
+				"TinkerbellMachineConfig: spec.hardwareSelector must contain only 1 key-value pair: %s",
+				config.Name,
+			)
+		}
+		return nil
+	}
+
+	// Validate HardwareAffinity if present
+	return validateHardwareAffinity(config.Spec.HardwareAffinity, config.Name)
+}
+
+// validateHardwareAffinity validates the HardwareAffinity configuration.
+func validateHardwareAffinity(affinity *HardwareAffinity, configName string) error {
+	// Required terms must have at least one entry
+	if len(affinity.Required) == 0 {
+		return fmt.Errorf("TinkerbellMachineConfig: hardwareAffinity.required must have at least one term: %s", configName)
+	}
+
+	// Validate each required term
+	for i, term := range affinity.Required {
+		if err := validateLabelSelector(&term.LabelSelector, configName, fmt.Sprintf("required[%d]", i)); err != nil {
+			return err
+		}
+	}
+
+	// Validate each preferred term
+	for i, weightedTerm := range affinity.Preferred {
+		// Validate weight range (1-100)
+		if weightedTerm.Weight < 1 || weightedTerm.Weight > 100 {
+			return fmt.Errorf("TinkerbellMachineConfig: preferred term weight must be in range [1, 100], got %d: %s", weightedTerm.Weight, configName)
+		}
+
+		if err := validateLabelSelector(&weightedTerm.HardwareAffinityTerm.LabelSelector, configName, fmt.Sprintf("preferred[%d]", i)); err != nil {
+			return err
+		}
+	}
+
+	return nil
+}
+
+// validateLabelSelector validates a Kubernetes LabelSelector.
+func validateLabelSelector(selector *metav1.LabelSelector, configName, path string) error {
+	// Validate matchExpressions
+	for j, expr := range selector.MatchExpressions {
+		// Validate operator
+		if !isValidLabelSelectorOperator(expr.Operator) {
+			return fmt.Errorf("TinkerbellMachineConfig: invalid matchExpression operator '%s' in %s.labelSelector.matchExpressions[%d], must be one of: In, NotIn, Exists, DoesNotExist: %s",
+				expr.Operator, path, j, configName)
+		}
+
+		// Validate values for In/NotIn operators
+		if expr.Operator == metav1.LabelSelectorOpIn || expr.Operator == metav1.LabelSelectorOpNotIn {
+			if len(expr.Values) == 0 {
+				return fmt.Errorf("TinkerbellMachineConfig: matchExpression with operator %s must have non-empty values in %s.labelSelector.matchExpressions[%d]: %s",
+					expr.Operator, path, j, configName)
+			}
+		}
+
+		// Validate that Exists/DoesNotExist don't have values
+		if expr.Operator == metav1.LabelSelectorOpExists || expr.Operator == metav1.LabelSelectorOpDoesNotExist {
+			if len(expr.Values) > 0 {
+				return fmt.Errorf("TinkerbellMachineConfig: matchExpression with operator %s must not have values in %s.labelSelector.matchExpressions[%d]: %s",
+					expr.Operator, path, j, configName)
+			}
+		}
+	}
+
+	return nil
+}
+
+// isValidLabelSelectorOperator checks if the operator is a valid LabelSelector operator.
+func isValidLabelSelectorOperator(op metav1.LabelSelectorOperator) bool {
+	switch op {
+	case metav1.LabelSelectorOpIn, metav1.LabelSelectorOpNotIn,
+		metav1.LabelSelectorOpExists, metav1.LabelSelectorOpDoesNotExist:
+		return true
+	default:
+		return false
+	}
+}
+
+// ValidateHardwareAffinityOperator validates a single operator string.
+func ValidateHardwareAffinityOperator(op string) bool {
+	return isValidLabelSelectorOperator(metav1.LabelSelectorOperator(op))
+}
+
+// ValidateHardwareAffinityWeight validates a weight value.
+func ValidateHardwareAffinityWeight(weight int32) bool {
+	return weight >= 1 && weight <= 100
+}
+
+// ValidateLabelSelectorRequirement validates a single LabelSelectorRequirement.
+func ValidateLabelSelectorRequirement(req metav1.LabelSelectorRequirement) error {
+	if !isValidLabelSelectorOperator(req.Operator) {
+		return fmt.Errorf("invalid operator '%s'", req.Operator)
+	}
+
+	switch req.Operator {
+	case metav1.LabelSelectorOpIn, metav1.LabelSelectorOpNotIn:
+		if len(req.Values) == 0 {
+			return fmt.Errorf("operator %s requires non-empty values", req.Operator)
+		}
+	case metav1.LabelSelectorOpExists, metav1.LabelSelectorOpDoesNotExist:
+		if len(req.Values) > 0 {
+			return fmt.Errorf("operator %s must not have values", req.Operator)
+		}
+	}
+
+	return nil
+}
+
 func setTinkerbellMachineConfigDefaults(machineConfig *TinkerbellMachineConfig) {
 	if machineConfig.Spec.OSFamily == "" {
 		machineConfig.Spec.OSFamily = Bottlerocket

pkg/api/v1alpha1/tinkerbellmachineconfig_types.go

@@ -10,9 +10,18 @@ import (
 
 // TinkerbellMachineConfigSpec defines the desired state of TinkerbellMachineConfig.
 type TinkerbellMachineConfigSpec struct {
-	HardwareSelector HardwareSelector `json:"hardwareSelector"`
-	TemplateRef      Ref              `json:"templateRef,omitempty"`
-	OSFamily         OSFamily         `json:"osFamily"`
+	// HardwareSelector is a simple key-value selector for hardware.
+	// Use this for straightforward single-label hardware selection.
+	// Mutually exclusive with HardwareAffinity.
+	// +optional
+	HardwareSelector HardwareSelector `json:"hardwareSelector,omitempty"`
+
+	// HardwareAffinity allows advanced hardware selection using required
+	// and preferred affinity terms. Mutually exclusive with HardwareSelector.
+	// +optional
+	HardwareAffinity *HardwareAffinity `json:"hardwareAffinity,omitempty"`
+	TemplateRef      Ref               `json:"templateRef,omitempty"`
+	OSFamily         OSFamily          `json:"osFamily"`
 	//+optional
 	// OSImageURL can be used to override the default OS image path to pull from a local server.
 	// OSImageURL is a URL to the OS image used during provisioning. It must include
@@ -39,6 +48,36 @@ func (s HardwareSelector) ToString() (string, error) {
 	return string(encoded), nil
 }
 
+// HardwareAffinity defines required and preferred hardware affinities.
+type HardwareAffinity struct {
+	// Required are the required hardware affinity terms. The terms are OR'd
+	// together - hardware must match at least one term to be considered.
+	// At least one required term must be specified.
+	Required []HardwareAffinityTerm `json:"required"`
+
+	// Preferred are the preferred hardware affinity terms. Hardware matching
+	// these terms are preferred according to the weights provided.
+	// +optional
+	Preferred []WeightedHardwareAffinityTerm `json:"preferred,omitempty"`
+}
+
+// HardwareAffinityTerm defines a single hardware affinity term.
+type HardwareAffinityTerm struct {
+	// LabelSelector is used to select hardware by labels.
+	LabelSelector metav1.LabelSelector `json:"labelSelector"`
+}
+
+// WeightedHardwareAffinityTerm is a HardwareAffinityTerm with an associated weight.
+type WeightedHardwareAffinityTerm struct {
+	// Weight associated with matching the corresponding term, in range 1-100.
+	// +kubebuilder:validation:Minimum=1
+	// +kubebuilder:validation:Maximum=100
+	Weight int32 `json:"weight"`
+
+	// HardwareAffinityTerm is the term associated with the weight.
+	HardwareAffinityTerm HardwareAffinityTerm `json:"hardwareAffinityTerm"`
+}
+
 func (c *TinkerbellMachineConfig) PauseReconcile() {
 	c.Annotations[pausedAnnotation] = "true"
 }