Support max-size annotation for per-MachineDeployment node limits

[parthyadav3105]

Description

What
Add support for cluster.x-k8s.io/cluster-api-autoscaler-node-group-max-size annotation to enforce per-MachineDeployment node limits.

Why
It is not something that is part of the core Karpenter contract, but it can be useful in case of CAPI providers where the user wants to enforce per-MachineDeployment node limits.

Especially, when they group multiple MachineDeployments under one NodePool as instance types for cost effective scheduling. While NodePool do offer spec.limits on the NodePool level, it does not control how much a particular MachineDeployment can be scaled.

The max-size annotation can help in putting a cap on the number of nodes per MachineDeployment. Same as cluster-api-autoscaler does.

Proposed Changes
The change will require reading the annotation and comparing it against the MachineDeployment's spec.replicas. If spec.replicas >= max-size, then set Available: false in the offering.

This will plug seamlessly with Available flag while support for capacity-types (reserved, on-demand, spot) and pricing is added in the offering in the future.

If this looks good, I can open a PR for this.

[parthyadav3105]

cc @elmiko, @maxcao13

[elmiko]

i think this makes sense, aside from setting Available: false, if a NodeClaim is requested on a MachineDeployment at max size, would the claim fail?

[parthyadav3105]

If there is no other machine deployment in the NodePool that would meet the requirements, then it would fail and Karpenter will keep waiting for an instance type to be available in the next iteration.

The Karpenter scheduling algorithm will fail with logs: (Available: false)

{"level":"INFO","time":"2026-04-14T16:30:07.901Z","logger":"controller","message":"skipping, nodepool requirements filtered out all instance types","controller":"provisioner","namespace":"","name":"","reconcileID":"68b4fd1b-4e6e-42b4-946f-974ea5003662","NodePool":{"name":"default"}}

---

aside from setting Available: false, if a NodeClaim is requested on a MachineDeployment at max size, would the claim fail?

Yes. As a fallback, when Karpenter is outdated with the offering metadata, we will also have a Create-time safety net, which will fail the new NodeClaim request completely at capi-karpenter-provider:

{"level":"ERROR","time":"2026-04-14T16:29:30.295Z","logger":"controller","message":"failed launching nodeclaim","controller":"nodeclaim.lifecycle","controllerGroup":"karpenter.sh","controllerKind":"NodeClaim","NodeClaim":{"name":"default-sx7gh"},"namespace":"","name":"default-sx7gh","reconcileID":"45795d4f-3c5f-412a-b660-ad02fb897dd2","error":"insufficient capacity, MachineDeployment \"ctr1-md0\" has reached its maximum size"}

It returns InsufficientCapacityError to Karpenter, completely failing the NodeClaim. Karpenter will delete this NodeClaim and try again in the next cycle with a fresh pod batch.

---

Let us take an example NodePool which limits CPU to 20:

apiVersion: karpenter.sh/v1
kind: NodePool
metadata:
  name: default
spec:
  limits:
    cpu: 20     # 4cpu * 5 nodes
  template:
    ....

Say, we have two MachineDeployments that are members of the CAPI node class in this cluster:

apiVersion: cluster.x-k8s.io/v1beta2
kind: MachineDeployment
metadata:
  annotations:
    capacity.cluster-autoscaler.kubernetes.io/cpu: "4"
    capacity.cluster-autoscaler.kubernetes.io/labels: kubernetes.io/arch=amd64
    capacity.cluster-autoscaler.kubernetes.io/maxPods: "110"
    capacity.cluster-autoscaler.kubernetes.io/memory: 8126Mi
    cluster.x-k8s.io/cluster-api-autoscaler-node-group-max-size: "2"   # capped at two nodes
  labels:
    node.cluster.x-k8s.io/karpenter-member: "yes"
  name: md0
spec:
  clusterName: ctr1
  replicas: 2   # already at max

---
apiVersion: cluster.x-k8s.io/v1beta2
kind: MachineDeployment
metadata:
  annotations:
    capacity.cluster-autoscaler.kubernetes.io/cpu: "4"
    capacity.cluster-autoscaler.kubernetes.io/labels: kubernetes.io/arch=amd64
    capacity.cluster-autoscaler.kubernetes.io/maxPods: "110"
    capacity.cluster-autoscaler.kubernetes.io/memory: 8126Mi
    # no max-size annotation, unlimited from the CAPI side
  labels:
    node.cluster.x-k8s.io/karpenter-member: "yes"
  name: md1
spec:
  clusterName: ctr1
  replicas: 1

The max-size annotation ensures that md0 never exceeds 2 nodes. Since Karpenter will see md0 as Available: false, it will filter it out. Since md1 has no max-size annotation, it remains the only available instance type. Karpenter will provision new NodeClaims against md1 until the NodePool-level limits (cpu: 20) are reached.

[elmiko]

sounds good to me.