Karpenter 통합 시작하기

이 가이드는 Karpenter가 설치되고 NodePool이 하나 이상 구성된 Amazon EKS 클러스터가 이미 있다고 가정합니다.

다음 단계를 따라 Wave에서 Karpenter 통합을 활성화합니다. cert-manager가 이미 설치되어 있다면 전체 과정은 약 5분이면 충분합니다.

사전 요구사항

시작하기 전에 다음 사항을 확인하세요.

Karpenter v0.32 이상이 설치되고 NodePool이 하나 이상 구성된 Amazon EKS 클러스터
Wave 3.1.0 이상 (Helm chart 버전 3.1.0 이상)
EKS 클러스터에 접근하도록 구성된 kubectl
로컬에 설치된 Helm 3.x
클러스터에 설치된 cert-manager (Spot Workload Placement webhook TLS에 필요). Dashboard와 Node Warmup 기능만 사용한다면 cert-manager는 선택 사항입니다.

cert-manager가 아직 설치되어 있지 않다면 다음 명령으로 설치할 수 있습니다.

CMD

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

계속 진행하기 전에 모든 cert-manager pod가 Ready 상태가 될 때까지 기다리세요.

1단계: Karpenter 활성화

wa-values.yaml Helm values 파일에서 karpenter.enabled를 true로 설정합니다.

wa-values.yaml

karpenter:
  enabled: true

이 플래그 하나로 Dashboard 모니터링, Node Warmup, Spot Workload Placement까지 Karpenter 통합 기능 세 가지가 모두 활성화됩니다.

개별 기능을 선택적으로 켜고 끌 수 있습니다. 사용 가능한 모든 옵션은 Karpenter Configuration 참고 문서를 확인하세요.

2단계: Webhook TLS 구성

Spot Workload Placement 기능은 MutatingWebhookConfiguration을 사용해 pod 생성 이벤트를 가로챕니다. Kubernetes는 모든 webhook이 TLS를 사용하도록 요구합니다. TLS 인증서를 발급하는 방법은 두 가지입니다.

Option A: cert-manager (권장)

cert-manager가 설치되어 있으면 Wave가 자체 서명된 Certificate 리소스를 자동으로 생성합니다. 추가 구성이 필요 없습니다. karpenter.enabled가 true일 때의 기본 동작입니다.

wa-values.yaml

karpenter:
  enabled: true
  webhook:
    certManager:
      enabled: true   # default when cert-manager is detected

Option B: 사용자 지정 인증서

TLS 인증서를 직접 관리하려는 경우(예: 조직의 내부 CA 사용), 인증서와 키를 Kubernetes Secret으로 제공합니다.

wa-values.yaml

karpenter:
  enabled: true
  webhook:
    certManager:
      enabled: false
    tls:
      secretName: wa-karpenter-webhook-tls   # your pre-created TLS Secret

⚠️

사용자 지정 인증서를 사용할 경우 인증서 갱신은 직접 관리해야 합니다. 인증서가 만료되면 webhook이 pod 생성 요청을 거부하여 배포가 막힐 수 있습니다.

Wave를 설치하기 전에 TLS Secret을 생성하세요.

CMD

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

3단계: 설치 또는 업그레이드

values 파일을 사용해 Helm install(또는 upgrade) 명령을 실행합니다.

CMD

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

처음 설치하는 경우 helm upgrade --install이 설치를 수행합니다. Wave가 이미 배포되어 있다면 새로운 Karpenter 설정으로 그 자리에서 업그레이드합니다.

4단계: 설치 확인

Helm 릴리스가 배포된 후, Karpenter 통합 컴포넌트가 모두 정상적으로 동작하는지 확인합니다.

Webhook 확인

CMD

kubectl get mutatingwebhookconfiguration | grep wave-autoscale

wave-autoscale-karpenter-webhook 항목이 표시되어야 합니다.

ClusterRole 확인

CMD

kubectl get clusterrole | grep wave-autoscale-karpenter

이 ClusterRole은 Wave에 Karpenter의 NodePool 및 NodeClaim 리소스에 대한 읽기 권한을 부여합니다.

TLS Secret 확인

CMD

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

webhook이 사용하는 TLS 인증서를 담은 wa-karpenter-webhook-tls Secret이 존재해야 합니다.

cert-manager Certificate 확인 (Option A 사용 시)

CMD

kubectl get certificate -n wave-autoscale

Certificate 리소스는 Ready: True로 표시되어야 합니다. 그렇지 않다면 cert-manager 로그를 확인하세요.

CMD

kubectl logs -n cert-manager -l app=cert-manager --tail=50

⚠️

확인 단계 중 하나라도 실패하면 Wave controller 로그에서 오류를 확인하세요.

CMD

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

다음 단계

Karpenter 통합을 활성화했다면 이제 각 기능을 자세히 살펴보세요.

Dashboard: Karpenter 노드, NodePool, 비용, disruption 이벤트를 실시간으로 모니터링합니다
Node Warmup: 노드를 사전 프로비저닝하고 이미지를 pre-caching하도록 구성해 pod 시작 속도를 10배 높입니다
Spot Workload Placement: deployment별 임계값으로 spot/on-demand 자동 분할을 설정합니다
Karpenter Configuration (Helm Values): Karpenter 통합을 세부 조정하기 위한 Helm values 전체 목록

개요 대시보드