Docs
Wave Karpenter
Getting Started

Getting Started with Karpenter Integration

This guide assumes you already have an Amazon EKS cluster with Karpenter installed and at least one NodePool configured.

Follow these steps to enable Karpenter integration in Wave. The entire process takes about 5 minutes if you already have cert-manager installed.

Prerequisites

Before you begin, ensure you have the following:

  • Amazon EKS cluster with Karpenter v0.32+ installed and at least one NodePool configured
  • Wave 3.1.0+ (Helm chart version 3.1.0 or later)
  • kubectl configured to access your EKS cluster
  • Helm 3.x installed locally
  • cert-manager installed in your cluster (required for Spot Workload Placement webhook TLS). If you only need the Dashboard and Node Warmup features, cert-manager is optional.

If you don't have cert-manager installed yet, you can install it with:

CMD
kubectl apply -f https://github.com/cert-manager/cert-manager/releases/latest/download/cert-manager.yaml

Wait for all cert-manager pods to be ready before proceeding.

Step 1: Enable Karpenter

In your wa-values.yaml Helm values file, set karpenter.enabled to true:

wa-values.yaml
karpenter:
  enabled: true

This single flag activates all three Karpenter integration features: Dashboard monitoring, Node Warmup, and Spot Workload Placement.

You can selectively enable or disable individual features. See the Karpenter Configuration reference for all available options.

Step 2: Configure Webhook TLS

The Spot Workload Placement feature uses a MutatingWebhookConfiguration to intercept pod creation events. Kubernetes requires all webhooks to use TLS. You have two options for provisioning the TLS certificate.

Option A: cert-manager (Recommended)

If cert-manager is installed, Wave automatically creates a self-signed Certificate resource. No additional configuration is needed — this is the default behavior when karpenter.enabled is true.

wa-values.yaml
karpenter:
  enabled: true
  webhook:
    certManager:
      enabled: true   # default when cert-manager is detected

Option B: Custom Certificate

If you prefer to manage TLS certificates yourself (e.g., using your organization's internal CA), provide the certificate and key as a Kubernetes Secret:

wa-values.yaml
karpenter:
  enabled: true
  webhook:
    certManager:
      enabled: false
    tls:
      secretName: wa-karpenter-webhook-tls   # your pre-created TLS Secret
⚠️

When using a custom certificate, you are responsible for certificate rotation. Expired certificates will cause the webhook to reject pod creation requests, potentially blocking deployments.

Create the TLS Secret before installing Wave:

CMD
kubectl create secret tls wa-karpenter-webhook-tls \
  --cert=path/to/tls.crt \
  --key=path/to/tls.key \
  -n wave-autoscale

Step 3: Install or Upgrade

Run the Helm install (or upgrade) command with your values file:

CMD
helm upgrade --install wave-autoscale wave-autoscale/wave-autoscale \
  -n wave-autoscale --create-namespace \
  -f wa-values.yaml

If this is a fresh installation, helm upgrade --install will perform an install. If Wave is already deployed, it will upgrade in place with the new Karpenter settings.

Step 4: Verify Installation

After the Helm release is deployed, verify that all Karpenter integration components are running correctly.

Check the Webhook

CMD
kubectl get mutatingwebhookconfiguration | grep wave-autoscale

You should see a wave-autoscale-karpenter-webhook entry.

Check the ClusterRole

CMD
kubectl get clusterrole | grep wave-autoscale-karpenter

The ClusterRole grants Wave read access to Karpenter NodePool and NodeClaim resources.

Check the TLS Secret

CMD
kubectl get secret -n wave-autoscale | grep webhook-tls

A wa-karpenter-webhook-tls Secret should be present, containing the TLS certificate used by the webhook.

Check cert-manager Certificate (if using Option A)

CMD
kubectl get certificate -n wave-autoscale

The Certificate resource should show Ready: True. If it doesn't, check cert-manager logs:

CMD
kubectl logs -n cert-manager -l app=cert-manager --tail=50
⚠️

If any of the verification steps fail, check the Wave controller logs for errors:

CMD
kubectl logs -n wave-autoscale -l app=wave-autoscale-core --tail=100

What's Next

Now that Karpenter integration is enabled, explore each feature in detail:

  • Dashboard — Monitor your Karpenter nodes, NodePools, costs, and disruption events in real time
  • Node Warmup — Configure proactive node pre-provisioning and image pre-caching for 10x faster pod startup
  • Spot Workload Placement — Set up automatic spot/on-demand splitting with per-deployment thresholds
  • Karpenter Configuration (Helm Values) — Full list of Helm values for fine-tuning Karpenter integration
OverviewDashboard