AWS Node Termination Handler

AWS 2025. 3. 20. 09:20

728x90

개요

AWS Node Termination Handler(NTH)는 EC2 인스턴스가 종료될 수 있는 이벤트(예: EC2 유지보수, 스팟 인스턴스 종료, ASG Scale-In, AZ 리밸런스, API/콘솔을 통한 인스턴스 종료 등)에 대응하여 Kubernetes가 적절히 반응하도록 돕는 도구입니다. 이를 통해 애플리케이션이 정상적으로 종료되지 않거나 가용성을 복구하는 데 시간이 오래 걸리는 문제를 방지할 수 있습니다.

NTH는 두 가지 모드로 동작합니다.

IMDS(Instance Metadata Service) Processor - 각 노드에서 실행되며, IMDS를 모니터링하여 이벤트 발생 시 해당 노드를 cordon(스케줄링 방지) 및 drain(현재 실행 중인 워크로드 종료) 처리합니다.
Queue Processor - Amazon EventBridge에서 SQS 큐를 통해 전달되는 EC2 관련 이벤트를 모니터링하고, 감지된 인스턴스를 Kubernetes API를 통해 cordon 및 drain 처리합니다.

EKS 관리형 노드 그룹을 사용하는 경우 NTH가 필요하지 않습니다.

주요 기능

IMDS Processor (DaemonSet으로 배포)
- IMDS에서 다음 이벤트를 감지:
  - 스팟 인스턴스 종료 알림
  - 예약된 이벤트
  - 인스턴스 리밸런스 추천
  - Autoscaling Group(ASG) 타겟 라이프사이클 상태 변경
- IMDS는 ASG 라이프사이클 훅을 지원하지 않음.
Queue Processor (Deployment로 배포)
- SQS 큐에서 다음 이벤트를 감지:
  - 스팟 인스턴스 종료 알림
  - AWS Health에서 제공하는 예약된 이벤트
  - 인스턴스 리밸런스 추천
  - ASG 종료 라이프사이클 훅(Scale-In, AZ 리밸런스, 비정상 인스턴스 종료 등)
  - 인스턴스 상태 변경 이벤트
- ASG 라이프사이클 훅을 활용하여 종료를 지연시키고, SQS를 통해 알림을 수신 후 노드를 cordon 및 drain 처리.
- EC2 API를 통해 종료된 인스턴스의 상태 변경을 감지하고 Kubernetes 노드를 정상적으로 종료하도록 유도.

라이프사이클 하트비트 기능 (Queue Processor 전용)

ASG 라이프사이클 이벤트 발생 시 최대 48시간까지 종료를 지연할 수 있도록 하트비트 신호를 전송 가능.
Kubernetes podTerminationGracePeriod를 최대 90초까지 설정하여 컨테이너가 정상적으로 종료될 시간을 확보 가능.
예제:
- 하트비트 간격: 1000초
- 하트비트 유지 시간: 4500초
- 하트비트 타임아웃: 3000초
- 4500초 동안 하트비트를 전송하여 종료를 지연한 후, 최종적으로 7000초에 인스턴스 종료.

설치 및 구성

Helm을 사용한 설치 예제

helm upgrade --install aws-node-termination-handler \
  --namespace kube-system \
  --set enableSqsTerminationDraining=true \
  --set heartbeatInterval=1000 \
  --set heartbeatUntil=4500

모드 설정
- enableSqsTerminationDraining=true → Queue Processor 활성화
- enableSqsTerminationDraining=false → IMDS Processor 활성화
IMDS Processor 모드의 주요 설정
- enableSpotInterruptionDraining: 스팟 종료 감지 활성화
- enableRebalanceMonitoring: 리밸런스 감지 활성화
- enableScheduledEventDraining: 예약된 이벤트 감지 활성화
Queue Processor 모드에서 감지 이벤트 필터링
- EventBridge 규칙을 수정하여 특정 이벤트를 필터링 가능.

메트릭 수집 (Prometheus 연동)

Queue Processor 모드
- ServiceMonitor를 사용해 Prometheus Operator로 수집.
- 또는 prometheus.yml에서 정적 타겟으로 추가.

extraScrapeConfigs: |
  - job_name: 'aws-node-termination-handler'
    static_configs:
      - targets:
          - 'aws-node-termination-handler.kube-system.svc.cluster.local:9092'

IMDS Processor 모드
- PodMonitor를 사용해 Prometheus Operator로 수집.

IMDS Processor vs Queue Processor 비교

기능	IMDS Processor	Queue Processor
스팟 인스턴스 종료 감지	✅	✅
예약된 이벤트 감지	✅	✅
인스턴스 리밸런스 추천 감지	✅	✅
ASG 종료 라이프사이클 훅	❌	✅
ASG 타겟 라이프사이클 상태 변경 감지	✅	❌
AZ 리밸런스 추천 감지	❌	✅
인스턴스 상태 변경 이벤트 감지	❌	✅
라이프사이클 하트비트 전송	❌	✅

사용 고려 사항

EKS 관리형 노드 그룹을 사용하면 필요 없음.
Queue Processor 모드가 IMDS 모드보다 다양한 종료 이벤트를 감지할 수 있음.
긴 종료 시간을 필요로 하는 경우 Queue Processor 모드에서 하트비트 기능 활용 가능.
Prometheus를 통해 운영 메트릭을 수집하고 모니터링 가능.

라이선스 및 커뮤니케이션

Apache-2.0 라이선스로 오픈 소스 제공.
이슈 등록 및 기능 요청은 GitHub에서 가능.
**Kubernetes Slack (#provider-aws 채널)**을 통해 커뮤니티와 소통 가능.

결론

AWS Node Termination Handler는 Kubernetes에서 EC2 인스턴스 종료 이벤트를 감지하고 정상적인 종료 절차를 수행하도록 도와주는 도구입니다. IMDS Processor와 Queue Processor 두 가지 방식으로 운영 가능하며, 보다 정밀한 제어가 필요한 경우 Queue Processor 모드를 선택하는 것이 유리합니다.