Skip to main content
NodeOverlays are an Alpha feature (karpenter.sh/v1alpha1). The API may change in future versions. Enable with the NodeOverlays feature gate.
Karpenter uses NodeOverlays to inject alternative instance type information into the scheduling simulation. NodeOverlays let you fine-tune instance pricing and add extended resources to instance types, enabling more accurate scheduling decisions for real-world factors like savings plans, licensing costs, and custom hardware resources not captured in base cloud provider data. NodeOverlays work by modifying the instance type information Karpenter uses during its scheduling simulation. When evaluating which instance types can satisfy pending pod requirements, Karpenter applies matching NodeOverlays to adjust pricing or add resources before making provisioning decisions.

​
Use cases

  • Custom pricing — account for savings plans or reserved instance commitments by overriding instance prices so consolidation decisions reflect your actual costs
  • Extended resources — add custom capacity (e.g., hugepages-2Mi, custom device slices) to instance types so pods requesting those resources can be scheduled
  • Licensing costs — adjust instance prices to reflect software licensing overhead

​
NodeOverlay configuration

apiVersion: karpenter.sh/v1alpha1
kind: NodeOverlay
metadata:
  name: example-overlay
spec:
  # Priority when multiple overlays match the same instance type
  weight: 10

  # Requirements select which instance types this overlay applies to
  requirements:
    - key: node.kubernetes.io/instance-type
      operator: In
      values: ["m5.large", "m5.xlarge"]
    - key: karpenter.sh/capacity-type
      operator: In
      values: ["spot"]
    - key: karpenter.k8s.aws/instance-cpu
      operator: Gte
      values: ["32"]

  # Set an absolute price (mutually exclusive with priceAdjustment)
  price: "5.00"

  # Or adjust the existing price (mutually exclusive with price)
  priceAdjustment: "+10%"  # or "-0.50" for absolute adjustment

  # Extended resources to add to matching instance types
  capacity:
    hugepages-2Mi: 100Mi
    hugepages-1Gi: 2Gi
    custom-device/gpu-slice: 4

​
Field reference

​
spec.weight
integer
Priority for conflict resolution when multiple NodeOverlays match the same instance type. Higher weight takes precedence. When weights are equal, alphabetical ordering by name applies. Defaults to 0.
​
spec.requirements
array
Requirements that determine which instance types this overlay applies to. Uses the same format as NodePool requirements and supports all standard Kubernetes label selectors.An empty requirements array applies the overlay to all instance types.Supports all well-known labels and AWS-specific labels.
There is a limit of 100 on the total number of requirements per NodeOverlay.
​
spec.price
string
Absolute price override. Completely replaces the cloud provider’s reported price. Karpenter is currency-agnostic.Mutually exclusive with priceAdjustment.
​
spec.priceAdjustment
string
Modifies the existing price. Accepts:
  • Percentage: "+15%" or "-10%"
  • Absolute: "+5.00" or "-2.50"
Mutually exclusive with price.
​
spec.capacity
object
Extended resources to add to matching instance types. These are added to existing capacity — they do not replace or modify standard resources (CPU, memory, storage).
capacity:
  smarter-devices/fuse: 1
  custom-hardware/accelerator: 2

​
Conflict resolution

When multiple NodeOverlays match the same instance type:
  1. Weight-based precedence — higher weight values take precedence
  2. Alphabetical ordering — when weights are equal, overlays are applied alphabetically by name
  3. Field-level merging — higher-weight overlays override price/priceAdjustment from lower-weight overlays; capacity fields from different overlays are merged

​
Conflict resolution example

apiVersion: karpenter.sh/v1alpha1
kind: NodeOverlay
metadata:
  name: overlay-a
spec:
  weight: 5
  requirements:
    - key: node.kubernetes.io/instance-type
      operator: In
      values: ["m5.large"]
  priceAdjustment: "-10%"
  capacity:
    hugepages-2Mi: 50Mi
---
apiVersion: karpenter.sh/v1alpha1
kind: NodeOverlay
metadata:
  name: overlay-b
spec:
  weight: 10  # Higher weight — overrides price adjustment
  requirements:
    - key: node.kubernetes.io/instance-type
      operator: In
      values: ["m5.large"]
  priceAdjustment: "-20%"
  capacity:
    custom-device/gpu: 1  # Merged with overlay-a's capacity
Result for m5.large:
  • Price adjustment: -20% (from overlay-b, overrides overlay-a)
  • Capacity: hugepages-2Mi: 50Mi (from overlay-a) + custom-device/gpu: 1 (from overlay-b)

​
Integration with consolidation

NodeOverlay modifications are automatically incorporated into Karpenter’s consolidation process:
  • Price adjustments affect consolidation decisions by changing the cost calculations used for replacement evaluation
  • Capacity additions are considered when evaluating whether workloads can move between nodes
  • Changes take effect through normal consolidation cycles — no additional drift detection or forced node replacement is required
When a NodeOverlay changes, Karpenter incorporates it into its next consolidation evaluation. Significant pricing changes may trigger node replacements.

​
Status and observability

status:
  conditions:
  - type: ValidationSucceeded
    status: "False"
    lastTransitionTime: "2024-07-24T18:30:00Z"
    reason: "Conflict"
    message: "conflict with another overlay"
ConditionDescription
Ready=TrueOverlay is applied to matching instance types
Ready=FalseConfiguration conflict, requirement mismatch, or other error

​
Limitations

  • NodeOverlays can only add extended resources — they cannot modify or remove standard resources (CPU, memory, storage)
  • Capacity modifications only affect Karpenter’s scheduling simulation; actual node resources must be configured through other means (e.g., device plugins, DaemonSets)
  • Price adjustments influence scheduling decisions but do not affect actual cloud provider billing
  • The karpenter.sh/v1alpha1 API may change in future releases

Build docs developers (and LLMs) love

Get started for freeTalk to us