[Kubernetes] Karpenter 문제 해결: 노드 프로비저닝 실패 디버깅 가이드

Karpenter 문제 해결 때문에 밤에 이벤트 로그 붙잡고 계신 적, 한 번쯤 있으시죠? 저도 처음엔 “오토스케일링은 붙여놓으면 알아서 되겠지” 했다가, 정작 트래픽이 몰리는 순간 Pod(파드, 쿠버네티스의 최소 배포 단위)는 Pending(펜딩, 스케줄 대기)인데 노드는 안 뜨고, Karpenter 로그는 뭔가 말은 많은데 핵심은 안 보이는 상황을 여러 번 겪었습니다. 특히 Kubernetes 노드 프로비저닝이 실패하면 서비스 지연이 바로 드러나기 때문에, 이 구간은 감으로 보면 안 되더라고요.

이번 글은 AWS 환경에서 Karpenter를 운영할 때 자주 만나는 오토스케일링 실패 패턴을 기준으로 정리했습니다. 제가 홈랩과 실무 환경에서 직접 부딪히며 정리한 흐름이라, 문서만 읽었을 때보다 훨씬 빠르게 원인을 좁히는 데 도움이 되실 겁니다. 핵심은 하나입니다. Karpenter 디버깅은 “Pending Pod → 스케줄링 조건 → Karpenter 로그 → 클라우드 리소스” 순서로 봐야 한다는 점입니다.

Pending Pod, Karpenter controller, AWS 인프라 리소스가 어떻게 연결되는지 보여주는 전체 흐름도입니다.

Karpenter 문제 해결, 왜 이렇게 헷갈릴까요?

쉽게 말해 Karpenter는 “Pod가 요구하는 조건에 맞춰 새 노드를 빠르게 계산하고 띄워주는 컨트롤러”입니다. 그런데 실제로는 중간에 확인할 레이어가 꽤 많습니다. Kubernetes scheduler(스케줄러), Karpenter controller(컨트롤러), IAM(권한 체계), subnet/security group(서브넷/보안 그룹), instance type(인스턴스 타입) 조건, 그리고 quota(할당량)까지 다 연결돼 있거든요.

저도 처음엔 Karpenter 로그만 뒤졌습니다. 근데 실제로 써보니까 문제의 출발점은 의외로 Pod 스펙인 경우가 많더라고요. 예를 들어 CPU 요청량이 과하게 잡혀 있거나, 특정 아키텍처만 허용했거나, taint/toleration(테인트/톨러레이션) 조합이 안 맞으면 Karpenter가 아무리 열심히 계산해도 답이 없습니다.

• Pod 조건 문제: requests/limits, nodeSelector, affinity, toleration 충돌
• Karpenter 설정 문제: NodePool(노드풀) 또는 기존 Provisioner(프로비저너) 제약이 너무 빡빡함
• AWS 리소스 문제: IAM 누락, 태그 미설정, 서브넷 발견 실패
• 용량 문제: 가용 영역 용량 부족, 인스턴스 타입 제한 과다, 계정 할당량 부족

여기서 중요한 포인트! Karpenter 문제 해결은 “왜 노드가 안 떴지?”가 아니라 “왜 이 Pod를 만족하는 노드를 계산하지 못했지?”로 질문을 바꾸면 훨씬 빨라집니다.

Karpenter 디버깅의 기본 원리

제가 실제로 보는 순서는 거의 고정입니다. 삽질 좀 했습니다 ㅎㅎ 결국 순서를 정해두는 게 제일 낫더라고요.

1. Pending 상태의 Pod를 확인합니다.
2. 해당 Pod의 이벤트와 스케줄링 실패 메시지를 읽습니다.
3. Karpenter controller 로그에서 같은 시점의 에러를 확인합니다.
4. NodePool/EC2NodeClass 또는 기존 Provisioner/AWSNodeTemplate 조건을 검토합니다.
5. AWS 측 리소스 발견, 권한, 용량 문제를 점검합니다.

이 흐름을 안 지키면 로그는 잔뜩 보는데 정작 원인을 놓치기 쉽습니다. 특히 이벤트 메시지 한 줄이 전체 방향을 정해주는 경우가 많아요.

Karpenter 디버깅 1단계: Pending Pod부터 확인하기

가장 먼저 해야 할 일은 “안 뜨는 노드”가 아니라 “대기 중인 Pod”를 보는 겁니다. 아래 명령어부터 시작해 보세요.

kubectl get pods -A --field-selector=status.phase=Pending
kubectl describe pod -n <namespace> <pod-name>
kubectl get events -A --sort-by=.lastTimestamp

여기서 제가 제일 먼저 보는 건 다음 세 가지입니다.

• Insufficient cpu/memory: 리소스 요청량이 현재/예상 노드와 맞지 않는 경우
• node affinity mismatch: nodeSelector 또는 affinity 조건이 과도한 경우
• untolerated taint: 노드 taint를 Pod가 허용하지 않는 경우

예를 들어 이런 Pod 스펙은 흔히 문제를 만듭니다.

apiVersion: v1
kind: Pod
metadata:
  name: inflate
spec:
  nodeSelector:
    kubernetes.io/arch: amd64
  containers:
    - name: pause
      image: public.ecr.aws/eks-distro/kubernetes/pause:3.7
      resources:
        requests:
          cpu: "2"
          memory: "2Gi"

이 자체는 틀린 YAML은 아닙니다. 다만 NodePool이 arm64만 허용하거나, 너무 작은 인스턴스 타입만 열어놨다면 Karpenter는 새 노드를 못 만듭니다. 결국 Kubernetes 노드 프로비저닝 실패처럼 보이지만, 시작점은 Pod 조건이죠.

Karpenter 디버깅 2단계: 컨트롤러 로그에서 에러 패턴 찾기

그다음은 Karpenter 로그입니다. 저는 보통 아래처럼 확인합니다.

kubectl logs -n karpenter deploy/karpenter --since=30m
kubectl logs -n karpenter deploy/karpenter --since=30m | grep -i "error"
kubectl logs -n karpenter deploy/karpenter --since=30m | grep -i "provision"

로그에서 자주 보는 키워드는 대략 이렇습니다.

처음엔 이게 뭔가 싶었는데, 로그를 “읽는” 게 아니라 “분류”하기 시작하니까 속도가 확 달라지더라고요. 특히 access denied 계열은 쿠버네티스 문제가 아니라 거의 AWS 권한 문제였습니다.

Karpenter 컨트롤러 로그, NodePool 조건, EC2 관련 리소스를 함께 점검하는 디버깅 흐름 예시입니다.

실전 구현: NodePool/Provisioner 조건 점검하기

운영 중인 Karpenter 버전에 따라 리소스 이름이 다를 수 있습니다. 최근 계열은 NodePool/EC2NodeClass 조합을 많이 쓰고, 예전 문서에서는 Provisioner/AWSNodeTemplate 예제가 남아 있습니다. 그래서 제 습관은 “내 클러스터에 실제로 어떤 CRD가 있는지 먼저 보는 것”입니다.

kubectl api-resources | grep -i karpenter
kubectl get nodepools
kubectl get ec2nodeclasses
kubectl get provisioners

예를 들어 NodePool이 너무 제한적으로 잡혀 있으면 문제가 생깁니다.

apiVersion: karpenter.sh/v1
kind: NodePool
metadata:
  name: default
spec:
  template:
    spec:
      requirements:
        - key: kubernetes.io/arch
          operator: In
          values: ["amd64"]
        - key: kubernetes.io/os
          operator: In
          values: ["linux"]

여기서 흔한 실수는 이런 겁니다.

• 인스턴스 패밀리 조건을 너무 좁게 설정
• 특정 가용 영역만 허용
• spot(스팟)만 허용했는데 해당 시점에 용량이 부족
• daemonset(데몬셋) 오버헤드를 고려하지 않고 너무 작은 타입만 허용

제가 직접 해보니 조건을 처음부터 정교하게 만드는 것보다, 일단 넉넉하게 열고 정상 프로비저닝을 확인한 뒤 점진적으로 좁히는 방식이 훨씬 덜 고생합니다.

권장 점검 명령어

kubectl describe nodepool <nodepool-name>
kubectl get ec2nodeclass <class-name> -o yaml
kubectl get provisioner <name> -o yaml

설정에서 확인할 항목은 다음과 같습니다.

1. 아키텍처 제약이 Pod와 맞는지
2. 용량 타입(on-demand/spot) 제약이 과하지 않은지
3. 서브넷/보안 그룹 선택 조건이 실제 AWS 태그와 일치하는지
4. 노드 만료, 통합(consolidation) 정책이 과도하게 공격적이지 않은지

⚠️ 오토스케일링 실패를 만드는 대표 원인 5가지

이 섹션은 제가 실제로 많이 봤던 순서대로 적겠습니다. Karpenter 디버깅에서 제일 시간을 많이 잡아먹는 부분이기도 합니다.

1. IAM(권한 체계) 누락

컨트롤러가 EC2 인스턴스를 생성하거나 조회할 권한이 없으면 노드가 당연히 안 뜹니다. 로그에 access denied, unauthorized 류 메시지가 보이면 거의 이쪽입니다. EKS에서 IRSA(IAM Roles for Service Accounts, 서비스어카운트용 IAM 역할)를 쓰는 경우, role annotation과 정책 연결 상태를 다시 확인해 보세요.

2. Subnet/Security Group 태그 문제

Karpenter는 보통 태그 기반으로 서브넷과 보안 그룹을 찾습니다. 근데 태그가 빠져 있거나 selector 조건과 안 맞으면 리소스를 발견하지 못합니다. 저는 이걸 네트워크 문제로 착각해서 한참 헤맸었는데, 사실은 태그 오타 하나였던 적도 있습니다.

3. 인스턴스 타입 제한 과다

예를 들어 특정 세대, 특정 패밀리, 특정 크기만 허용해 놓으면 실시간 수용 용량이 없을 때 바로 막힙니다. 운영에서는 후보군을 넓혀야 합니다. 특히 spot만 쓰는 환경은 더 그렇습니다.

4. Pod 요청량 과다 또는 DaemonSet 오버헤드 미반영

실제로 써보니까 작은 워크로드 하나만 보지 말고, CNI(컨테이너 네트워크 인터페이스), 로그 에이전트, 모니터링 에이전트 같은 데몬셋 자원까지 같이 봐야 하더라고요. 남는 것 같아도 실제 스케줄 가능 용량은 더 작습니다.

5. AWS 계정 할당량 또는 AZ 용량 이슈

설정이 멀쩡해도 특정 가용 영역에서 타입 수급이 안 될 수 있습니다. 이럴 땐 Karpenter 자체 버그보다 클라우드 용량 이슈일 가능성도 큽니다. 그래서 저는 가능한 한 여러 AZ와 여러 타입을 열어둡니다.

kubectl get events -A --sort-by=.lastTimestamp
kubectl describe pod -n <namespace> <pod-name>
kubectl describe nodepool <nodepool-name>

설정 예시: 디버깅용으로 조건을 단순화해보기

문제가 길어질 때는 조건을 줄여서 정상 동작 여부부터 확인하는 게 좋습니다. 아래처럼 Pod를 단순화해서 테스트해 보세요.

apiVersion: v1
kind: Pod
metadata:
  name: karpenter-debug
spec:
  containers:
    - name: pause
      image: public.ecr.aws/eks-distro/kubernetes/pause:3.7
      resources:
        requests:
          cpu: "250m"
          memory: "256Mi"

이 Pod조차 스케줄이 안 되면, 애플리케이션 문제가 아니라 Karpenter 또는 인프라 레이어 문제로 보는 게 맞습니다. 반대로 이건 뜨는데 실제 서비스 Pod만 안 뜬다면, 그때는 requests/affinity/toleration을 더 자세히 보시면 됩니다.

디버깅용 Pod YAML, kubectl describe 출력, NodePool 설정을 함께 비교하는 장면을 표현한 이미지입니다.

검증 방법: 노드가 정말 의도대로 프로비저닝됐는지 확인

노드가 하나 떴다고 끝이 아닙니다. 저는 아래 순서로 꼭 확인합니다.

1. 새 노드가 생성됐는지 확인
2. Pending Pod가 Running으로 전환됐는지 확인
3. 노드 라벨, taint, allocatable 자원이 기대와 맞는지 확인
4. 불필요하게 큰 인스턴스가 뜨지 않았는지 확인

kubectl get nodes
kubectl get pods -A -o wide
kubectl describe node <node-name>
kubectl top nodes

확인 포인트는 단순합니다.

• Pod가 실제로 새 노드에 배치됐는가
• 노드 라벨이 workload 조건과 맞는가
• CPU/메모리 여유가 너무 적거나 너무 많지 않은가
• 오토스케일링 실패가 반복되지 않는가

드디어 됐다! 싶은 순간이 여기인데요, 여기서 끝내면 안 됩니다. 몇 분 후 consolidation이나 만료 정책 때문에 노드가 정리되면서 다시 Pending이 생길 수도 있거든요. 그래서 최소한 짧은 부하 테스트나 재배포 한 번은 꼭 해보시는 걸 권합니다.

새 노드 생성 이후 Pending Pod가 Running으로 바뀌고 자원 사용량이 안정화된 결과 화면 예시입니다.

운영 팁: 제가 실제로 적용하는 Karpenter 문제 해결 체크리스트

혹시 이런 경험 있으신가요? 로그는 많은데 뭘 먼저 봐야 할지 몰라서 계속 왔다 갔다 하게 되는 상황이요. 그래서 저는 아래 체크리스트를 만들어 두고 그대로 봅니다.

이 체크리스트만 잘 지켜도 Karpenter 문제 해결 시간이 꽤 줄어듭니다. 그리고 이전 글에서 다룬 클러스터 리소스 요청량 설계 내용과 같이 보시면 더 이해가 쉬우실 겁니다. 다음 글에서는 Karpenter와 Cluster Autoscaler를 어떤 기준으로 나눠 볼지 정리해보려고 합니다.

Karpenter 문제 해결 순서를 한 장으로 요약한 체크리스트 인포그래픽입니다.

정리: Karpenter 문제 해결은 순서가 전부입니다

오늘 내용의 핵심은 복잡하지 않습니다. 오토스케일링 실패가 보이면 바로 AWS 콘솔부터 열지 말고, 먼저 Pending Pod 이벤트를 확인하세요. 그다음 Karpenter 로그, 그리고 NodePool/Provisioner 제약, 마지막으로 IAM과 네트워크 태그를 보는 흐름이 가장 효율적이었습니다.

저도 처음엔 Karpenter가 너무 똑똑해서 알아서 다 해줄 줄 알았는데, 실제로는 “조건을 어떻게 열고, 어떤 로그를 먼저 읽느냐”가 훨씬 중요하더라고요. 특히 Kubernetes 노드 프로비저닝 이슈는 한 군데만 봐서는 잘 안 풀립니다. 대신 순서를 지키면 생각보다 금방 풀립니다.

혹시 지금도 Karpenter 디버깅 중이시라면, 오늘 소개한 명령어 세트부터 그대로 실행해 보세요. 그리고 Pod 이벤트 한 줄, Karpenter 로그 한 줄만 정확히 읽어도 방향이 확 잡힐 겁니다. 이거 진짜 편하더라고요.