Wave Karpenter CRDs

These kinds configure Wave Karpenter in CRD Mode. Use WaveKarpenterNodeWarmup for Node Warmup and WaveKarpenterSpotPlacement for Spot Workload Placement. Both kinds require Wave Karpenter to be enabled in your installation.

WaveKarpenterNodeWarmup

WaveKarpenterNodeWarmup configures proactive node provisioning for a Karpenter NodePool. It targets the NodePool by name and combines a warmup mode (warmupType) with a scheduling mode (scheduleType) to select one of three warmup strategies.

Scope: cluster-scoped — no metadata.namespace required.

apiVersion: wavek8s.com/v1alpha1
kind: WaveKarpenterNodeWarmup
metadata:
  name: checkout-warmup
spec:
  nodepoolName: default-nodepool
  warmupType: max_pod      # max_pod | trigger
  scheduleType: scheduled  # always | scheduled
  enabled: true
  enableImagePrepull: true
  options:
    cronExpression: "0 0 9 * * 1-5 *"
    cronDurationMin: 540
    podSizeBufferPct: 20
    consolidationDisabledMin: 30
    useAllAzs: true
    excludeStatefulsetPods: false

Spec fields

options fields — max_pod + always

options fields — max_pod + scheduled

options fields — trigger + scheduled

Notes

• Valid (warmupType, scheduleType) combinations. Three combinations are accepted; one is explicitly rejected:

  warmupType	scheduleType	Result
  max_pod	always	Continuously monitors and provisions when no existing node fits the largest pod
  max_pod	scheduled	Same as above, but only during the cron window
  trigger	scheduled	Provisions a fixed node spec on the cron schedule
  trigger	always	Rejected — reports ValidationFailed

• options is conditionally required. max_pod + always can omit the options block entirely (all fields have defaults). All other combinations require at least the fields marked Required in the tables above; omitting them reports ValidationFailed.

• Cron format is 7-field. Cron expressions follow the sec min hour dom month dow year format. Example: "0 0 9 * * 1-5 *" fires at 09:00:00 on weekdays every year.

• nodeVcpus and nodeMemoryGi must be supported values. The trigger strategy only provisions node types Wave explicitly supports. Unsupported values report ValidationFailed.

• Overlapping cron windows on the same NodePool are rejected. Two max_pod + scheduled warmups targeting the same NodePool whose cron windows overlap report Conflicted. Resolve by adjusting the cron expression or duration. This check does not apply across NodePools or to trigger warmups.

• max_pod + always and max_pod + scheduled cannot coexist on the same NodePool. Only one schedule type (Always or Scheduled) is allowed per NodePool for max_pod warmup. Attempting to add a second with a different scheduleType reports Conflicted.

• RefNotFound self-heals. A CR whose nodepoolName does not match any live Karpenter NodePool succeeds at kubectl apply time. Wave reports RefNotFound in .status.conditions and reconciles automatically when the NodePool appears.

WaveKarpenterSpotPlacement

WaveKarpenterSpotPlacement configures automatic On-Demand / Spot replica splitting for a single workload. Wave injects nodeAffinity rules via a MutatingWebhookConfiguration — no changes to your workload YAML are required.

Scope: namespaced — must be created in the same namespace as the target workload.

apiVersion: wavek8s.com/v1alpha1
kind: WaveKarpenterSpotPlacement
metadata:
  name: checkout-spot-placement
  namespace: payment
spec:
  targetRef:
    kind: Deployment
    name: checkout-api
  podSplitThreshold: 5
  placementStrategy: prefer
  enabled: true

Spec fields

Notes

• Namespaced — create the CR in the same namespace as the target workload. The CR and the workload must share the namespace; cross-namespace targeting is not supported.

• targetRef.kind should be one of Deployment, Rollout, or DeploymentConfig. Unrecognized values are not rejected — they are silently treated as Deployment, so double-check spelling.

• podSplitThreshold must be >= 1. A value of 0 reports ValidationFailed. The CRD schema does not enforce a minimum at the API server level, so this check runs at reconcile time.

• TargetNotFound self-heals. A CR whose target workload does not yet exist succeeds at kubectl apply time. Wave reports TargetNotFound in .status.conditions and reconciles automatically when the workload appears. Apply order does not matter.

• Webhook TLS is required. Spot Placement depends on a registered MutatingWebhookConfiguration with a valid TLS certificate. Without it, affinity rules are never injected. See Getting Started for TLS setup.

• prefer vs require. Use prefer for most workloads — pods fall back to On-Demand if Spot capacity is unavailable. Use require only for fault-tolerant batch jobs that should never run On-Demand.