EKS Node Monitoring Agent

2025-08-26 작성2026-06-30 수정18분 읽기

개요

EKS Node Monitoring Agent(NMA)는 AWS가 제공하는 노드 상태 모니터링 도구입니다. EKS 클러스터의 노드에서 발생하는 하드웨어 및 시스템 레벨 문제를 자동으로 감지하고 보고합니다. 2024년에 정식 출시된 이 서비스는 노드 자동 복구(Node Auto Repair) 기능과 함께 작동하여 클러스터의 안정성을 향상시킵니다.

문제 해결

전통적인 EKS 클러스터 운영에서는 다음의 문제들이 있었습니다:

하드웨어 장애의 조기 감지 부족
시스템 레벨 문제의 수동 모니터링 필요
노드 상태 변화에 대한 지연된 대응
문제 감지와 자동 복구의 통합 부재

NMA는 이러한 문제들을 해결하기 위해 설계되었습니다.

EKS Node Monitoring Agent란?

주요 특징

로그 기반 문제 감지: 시스템 로그를 실시간으로 분석하여 패턴 매칭
자동 이벤트 생성: 문제 감지 시 Kubernetes Events 및 Node Conditions 자동 생성
CloudWatch 통합: 감지된 문제를 CloudWatch로 전송하여 중앙 집중식 모니터링
EKS Add-on 지원: 간편한 설치 및 관리

중요

NMA는 노드 상태 문제를 자동으로 감지하는 유용한 도구이지만, 단독으로는 완전한 모니터링 솔루션이 될 수 없습니다. 다음의 제한 사항을 고려한 적절한 기대치 설정과 보완 도구 활용이 필요합니다.

핵심 권장사항

✅ 권장하는 사용법

NMA를 노드 상태 감지 레이어로 활용
Container Insights나 Prometheus로 메트릭 수집 보완
Node Auto Repair와 함께 사용하여 자동 복구 구현
환경별 특성에 맞게 임계값 조정

❌ 피해야 할 사용법

NMA만으로 전체 모니터링 의존 불가
급격한 하드웨어 장애 대응 불가

1. 설계 목표

1.1 포괄적인 노드 상태 모니터링

NMA는 EKS 노드의 다양한 시스템 컴포넌트를 모니터링합니다:

Container Runtime: Docker/containerd의 상태 확인
Storage System: 디스크 공간 및 I/O 성능 모니터링
Networking: 네트워크 연결성 및 구성 검증
Kernel: 커널 모듈 및 시스템 상태 점검
Accelerated Hardware: GPU(NVIDIA) 및 Neuron 칩 상태 (하드웨어 감지 시)

1.2 Kubernetes 네이티브 통합

NMA는 controller-runtime을 사용하여 Kubernetes와 긴밀하게 통합됩니다:

mgr, err := controllerruntime.NewManager(controllerruntime.GetConfigOrDie(), controllerruntime.Options{
    Logger:                 log.FromContext(ctx),
    Scheme:                 scheme.Scheme,
    HealthProbeBindAddress: controllerHealthProbeAddress,
    BaseContext:            func() context.Context { return ctx },
    Metrics:                server.Options{BindAddress: controllerMetricsAddress},
})

1.3 다양한 EKS 환경 지원

REST 설정 로직에서 확인할 수 있듯이, NMA는 다양한 EKS 환경을 지원합니다:

EKS Auto: 특별한 사용자 impersonation 플로우 사용
Legacy RBAC: 기존 권한 모델 지원
Standard: 표준 Pod 기반 인증

2. 아키텍처 및 동작 원리

2.1 Agent Startup 및 초기화 흐름

다음 다이어그램은 NMA의 시작 과정과 모니터링 루프의 전체 흐름을 보여줍니다.

2.2 모니터 등록 및 관리

NMA는 모니터 구성을 통해 각 서브시스템을 관리합니다. 다음은 모니터 등록의 구조를 보여줍니다.

var monitorConfigs = []monitorConfig{
    {
        Monitor:       &runtime.RuntimeMonitor{},
        ConditionType: rules.ContainerRuntimeReady,
    },
    {
        Monitor:       storage.NewStorageMonitor(),
        ConditionType: rules.StorageReady,
    },
    // ... 추가 모니터들
}

각 모니터는 해당하는 Node Condition과 연결되어 상태를 보고합니다.

2.3 Node Condition 기반 상태 보고

NMA는 Kubernetes의 Node Condition 메커니즘을 활용하여 각 서브시스템의 상태를 보고합니다:

ContainerRuntimeReady: 컨테이너 런타임 상태
StorageReady: 스토리지 시스템 상태
NetworkingReady: 네트워킹 상태
KernelReady: 커널 상태
AcceleratedHardwareReady: GPU/Neuron 하드웨어 상태 (조건부)

2.4 실시간 진단 기능

NodeDiagnostic CRD를 통한 온디맨드 진단 실행:

diagnosticController := controllers.NewNodeDiagnosticController(mgr.GetClient(), hostname, runtimeContext)

이를 통해 운영자는 특정 노드에서 실시간으로 진단 명령을 실행할 수 있습니다.

2.5 관찰 가능성 (Observability)

NMA는 다양한 엔드포인트를 통해 관찰 가능성을 제공합니다:

Health Probe (:8081): Kubernetes 헬스 체크
Metrics (:8080): Prometheus 메트릭 노출
PProf (:8082): Go 프로파일링 (선택적)

2.6 콘솔 진단 로깅

-console-diagnostics 플래그 활성화 시, 시스템 정보를 /dev/console에 주기적으로 기록:

if enableConsoleDiagnostics {
    startConsoleDiagnostics(ctx)
}

이는 인스턴스 레벨에서의 가시성을 제공합니다.

2.7 배포 및 운영 특징

2.7.1 DaemonSet 기반 배포

agent.tpl.yaml에서 확인할 수 있듯이, NMA는 DaemonSet으로 배포되어 모든 워커 노드에서 실행됩니다:

kind: DaemonSet
apiVersion: apps/v1
metadata:
  name: eks-node-monitoring-agent
  namespace: kube-system

2.7.2 노드 선택 및 제약사항

values.yaml의 affinity 설정을 통해 특정 노드 타입에서만 실행되도록 제한:

Fargate 노드 제외
EKS Auto 컴퓨트 타입 제외
HyperPod 노드 제외
AMD64/ARM64 아키텍처만 지원

2.7.3 권한 관리

agent.tpl.yaml의 RBAC 설정을 통한 최소 권한 원칙 적용:

rules:
  # monitoring permissions
  - apiGroups: [""]
    resources: ["events"]
    verbs: ["create", "patch"]
  # nodediagnostic permissions
  - apiGroups: ["eks.amazonaws.com"]
    resources: ["nodediagnostics"]
    verbs: ["get", "watch", "list"]

2.7.4 리소스 효율성

values.yaml에 정의된 리소스 제한으로 경량 운영:

resources:
  requests:
    cpu: 10m
    memory: 30Mi
  limits:
    cpu: 250m
    memory: 100Mi

2.8 감지 가능한 문제 유형

NMA가 감지하는 노드 헬스 이슈는 심각도(Severity) 에 따라 두 종류로 구분됩니다. 이 구분은 Node Auto Repair의 동작 여부를 결정하므로 정확히 이해해야 합니다.

Condition: 노드 교체(Replace) 또는 재부팅(Reboot)이 필요한 종료성(terminal) 이슈. Auto Repair가 활성화된 경우 복구 액션을 수행합니다.
Event: 일시적이거나 비치명적인 이슈, 또는 차선의 노드 구성. Auto Repair 액션을 트리거하지 않으며 조사·알림 용도로만 기록됩니다.

각 모니터링 컨디션 타입(ContainerRuntimeReady, KernelReady, NetworkingReady, StorageReady, AcceleratedHardwareReady) 아래에 다수의 세부 이슈가 매핑됩니다. 동일 컨디션 타입이라도 세부 이슈별로 Severity가 Condition인지 Event인지가 다릅니다.

2.8.1 Container Runtime 이슈 (`ContainerRuntimeReady`)

containerd 부하·장애로 노드 문제가 발생하는 시나리오와 직접 관련됩니다.

이름	심각도	설명	복구 액션
`PodStuckTerminating`	Condition	CRI 오류 등으로 Pod가 과도하게 종료 지연되어 상태 진행 불가	Replace
`ContainerRuntimeFailed`	Event	런타임이 컨테이너 생성에 실패(반복 시 장애 신호)	None
`KubeletFailed`	Event	kubelet이 failed 상태로 진입	None
`DeprecatedContainerdConfiguration`	Event	deprecated 이미지 매니페스트(v2 schema 1) 풀 발생	None
`Liveness/ReadinessProbeFailures`	Event	Probe 실패 감지(앱 코드 문제 또는 타임아웃 부족 가능성)	None
`[Name]RepeatedRestart` / `ServiceFailedToStart`	Event	systemd 유닛의 잦은 재시작 / 시작 실패	None

→ 핵심: containerd가 완전히 망가져 Pod가 종료되지 못하는 수준(PodStuckTerminating)만 Condition으로 분류되어 노드 교체로 이어집니다. 단순 컨테이너 생성 실패(ContainerRuntimeFailed)는 Event로만 기록되며 자동 복구되지 않습니다.

2.8.2 Kernel / Networking / Storage 주요 이슈

Condition(자동 복구 대상)으로 분류되는 대표 항목만 정리합니다. 그 외 다수 항목은 Event입니다.

컨디션 타입	Condition 이슈(Replace)	대표 Event 이슈
`KernelReady`	`ForkFailedOutOfPIDs` (PID/메모리 고갈)	`SoftLockup`, `KernelBug`, `ApproachingKernelPidMax`, `ConntrackExceededKernel`
`NetworkingReady`	`IPAMDNotRunning`, `IPAMDNotReady`, `InterfaceNotUp/Running`, `MissingLoopbackInterface`	`ConntrackExceeded`, `BandwidthIn/OutExceeded`, `PPSExceeded`, `NetworkSysctl`
`StorageReady`	(해당 표의 항목은 모두 Event)	`EBSVolumeIOPS/ThroughputExceeded`, `IODelays`, `KubeletDiskUsageSlow`

DiskPressure / MemoryPressure / PIDPressure 는 자동 복구 대상이 아님

DiskPressure, MemoryPressure, PIDPressure는 표준 Kubernetes 컨디션이며, Node Auto Repair가 의도적으로 반응하지 않습니다. 이들은 노드 자체 결함보다 애플리케이션 동작·워크로드 구성·리소스 한계 문제일 가능성이 높아, 적절한 기본 복구 액션을 정의하기 어렵기 때문입니다. 이 경우 Kubernetes의 node-pressure eviction 동작에 위임됩니다.

→ containerd 부하가 메모리/디스크 압박이나 PID 고갈 형태로 표출되면 노드는 자동 교체되지 않습니다. 부하가 런타임 자체 실패(PodStuckTerminating 등 Condition)로 잡혀야 Auto Repair가 동작합니다.

2.8.3 Accelerated Hardware 이슈 (`AcceleratedHardwareReady`)

NVIDIA GPU·AWS Neuron 가속기 헬스를 감지합니다. NVIDIA XID 에러는 well-known 코드만 Condition(NvidiaXID[Code]Error)으로 분류되어 복구를 트리거하며, 미등록 코드는 Event(NvidiaXID[Code]Warning)로만 기록됩니다. 세부 XID 코드별 복구 액션(Reboot/Replace)은 AWS 공식 문서를 참조합니다.

대표 이슈	심각도	복구 액션
`NvidiaXID[Code]Error` (well-known)	Condition	Replace 또는 Reboot (코드별 상이)
`NvidiaNVLinkError`, `NvidiaDoubleBitError`	Condition	Replace
`NeuronDMAError`, `NeuronHBMUncorrectableError`	Condition	Replace
`DCGMError`, `DCGMDiagnosticFailure`	Condition	None
`NvidiaThermalError`, `NvidiaPowerError`, `NvidiaPageRetirement`	Event	None

3. Node Auto Repair 연동

NMA는 단독으로는 가시성(NodeCondition·이벤트 노출)만 제공합니다. Node Auto Repair와 함께 사용해야 감지된 Condition에 대한 자동 교체·재부팅이 이루어집니다.

3.1 NMA 유무에 따른 Auto Repair 반응 대상

구성	Auto Repair가 반응하는 대상
Auto Repair 단독 (NMA 없음)	kubelet의 `Ready` 컨디션, 수동 삭제된 node object, 클러스터 조인 실패한 관리형 노드그룹 인스턴스
Auto Repair + NMA	위 항목 추가로 `AcceleratedHardwareReady`, `ContainerRuntimeReady`, `KernelReady`, `NetworkingReady`, `StorageReady`

3.2 컨디션별 복구 대기 시간 및 액션

기본 동작이며 EKS Auto Mode·관리형 노드그룹·Karpenter에 공통 적용됩니다. Reboot은 관리형 노드그룹에서만 지원되며, Auto Mode·Karpenter는 모두 Replace로 동작합니다.

컨디션	복구 대기	액션
`AcceleratedHardwareReady`	10분	Replace 또는 Reboot
`ContainerRuntimeReady`	30분	Replace
`KernelReady`	30분	Replace
`NetworkingReady`	30분	Replace
`StorageReady`	30분	Replace
`Ready`	30분	Replace
`DiskPressure` / `MemoryPressure`	N/A	None

3.3 폭주 방지 안전장치

대량 장애 시 노드가 연쇄 교체되는 것을 막기 위해 기본적으로 다음 상황에서 신규 복구 액션이 중단됩니다(진행 중인 복구는 계속).

관리형 노드그룹: 노드가 5개 초과이고 그룹의 20%를 초과하는 노드가 unhealthy인 경우, 또는 ARC(Application Recovery Controller) zonal shift 발생 시
Auto Mode / Karpenter: NodePool의 20%를 초과하는 노드가 unhealthy인 경우(독립 NodeClaim은 클러스터의 20%)

3.4 활성화 방법

EKS Auto Mode: 항상 활성(설정 변경 불가)
Karpenter: feature gate NodeRepair=true 설정
관리형 노드그룹: 콘솔 "Enable node auto repair" 체크박스 / CLI --node-repair-config enabled=true / eksctl nodeRepairConfig.enabled: true

관리형 노드그룹은 maxUnhealthyNodeThresholdCount/Percentage, maxParallelNodesRepairedCount/Percentage, 그리고 컨디션·사유별 nodeRepairConfigOverrides(예: 특정 NVIDIA XID 에러는 즉시 Replace, 다른 코드는 NoAction)로 세부 동작을 커스터마이징할 수 있습니다.

4. 배포 방식별 차이점

4.1 Manual Mode (DaemonSet)

장점:

유연한 버전 관리
ConfigMap 기반 설정 변경
커스텀 설정 가능

단점:

kubelet 의존성 높음
노드 부트스트랩 시 지연
kubelet 장애 시 영향 받음

4.2 EKS Auto Mode

장점:

AMI에 직접 내장
kubelet과 독립적 실행
더 높은 가용성
빠른 문제 감지

단점:

업데이트 시 AMI 교체 필요
커스터마이징 제한적

5. 기술적 제한사항

5.1 메트릭 수집 한계

NMA는 메트릭 수집 도구가 아님: 성능 메트릭(CPU, 메모리 사용률 등) 수집 불가
로그 파싱 방식: cAdvisor를 사용하지 않으며, 순수 로그 분석 기반
Prometheus 엔드포인트: 제한적인 건강 상태 메트릭만 노출 (포트 8080)

5.2 대체 백엔드 사용 시 제약

CloudWatch 외 백엔드 사용 시

네이티브 ADOT 통합 없음
Prometheus 메트릭 범위 매우 제한적
설정 변경 옵션 부재
공식 문서 및 지원 부족

5.3 하드웨어 장애 감지 한계

감지 가능:

✅ 점진적 성능 저하
✅ I/O 에러 증가
✅ 메모리 ECC 에러

감지 불가능:

❌ 급작스런 전원 차단
❌ 즉각적인 하드웨어 고장
❌ 네트워크 완전 단절

6. 권장 구현 전략

6.1 다층 모니터링 아키텍처

통합 모니터링 스택:
├── L1: 상태 감지 (NMA)
│   └── 노드 문제 조기 감지
├── L2: 메트릭 수집 (Container Insights/Prometheus)
│   └── 상세 성능 데이터
├── L3: 자동 대응 (Node Auto Repair)
│   └── 문제 노드 자동 교체
└── L4: 통합 대시보드 (CloudWatch/Grafana)
    └── 종합 모니터링 뷰

6.2 Prometheus 사용 시 권장 구성

NMA와 Node Exporter를 함께 사용할 때는 다음 구성을 권장합니다.

apiVersion: v1
kind: Service
metadata:
  name: monitoring-stack
spec:
  components:
    - name: nma
      purpose: "노드 상태 이벤트"
      port: 8080
    - name: node-exporter
      purpose: "상세 시스템 메트릭"
      port: 9100
    - name: kube-state-metrics
      purpose: "클러스터 상태 메트릭"
      port: 8080

7. 비용 및 성능 고려사항

7.1 리소스 사용량

NMA는 매우 가벼운 구성 요소입니다. EKS 애드온/Helm 차트 기본값 기준 리소스 요청·제한은 다음과 같습니다.

리소스	requests	limits
CPU	10m	250m
Memory	30Mi	100Mi

NVIDIA GPU 인스턴스에서는 DCGM 서버 컴포넌트(nv-hostengine)가 추가로 기동되며, dcgmAgent.resources.* 값으로 별도 조정할 수 있습니다. 리소스 요청·제한은 애드온 구성값(monitoringAgent.resources.*)으로 환경에 맞게 조정합니다.

7.2 CloudWatch 비용

항목	비용
커스텀 메트릭	$0.30/metric/month
이벤트	$1.00/million events
로그	$0.50/GB ingested

8. 모범 사례

8.1 프로덕션 배포

단계적 롤아웃: Dev → Staging → Production
알림 임계값 조정: 환경별 특성 고려
자동 복구 신중히 활성화: 초기에는 모니터링만
정기적인 테스트: 월별 장애 시뮬레이션

8.2 다른 도구와의 통합

조합	설명
NMA + Container Insights	완전한 AWS 네이티브 가시성
NMA + Prometheus + Grafana	오픈소스 기반 모니터링 스택
NMA + Datadog/New Relic	엔터프라이즈급 모니터링 솔루션

참고 자료

공식 문서

Detect node health issues and enable automatic node repair — NMA·Auto Repair 개요 및 NodeCondition 목록
Detect node health issues with the EKS node monitoring agent — 감지 이슈 전체 표(Condition/Event), XID 코드, 애드온 구성값
Automatically repair nodes in EKS clusters — 컨디션별 복구 액션·타임아웃, 안전장치, 커스터마이징
aws/eks-node-monitoring-agent — NMA 소스 코드 및 Helm 차트

기술 블로그

Amazon EKS introduces node monitoring and auto repair capabilities — 출시 발표 및 아키텍처 설명

개요​

문제 해결​

EKS Node Monitoring Agent란?​

주요 특징​

1. 설계 목표​

1.1 포괄적인 노드 상태 모니터링​

1.2 Kubernetes 네이티브 통합​

1.3 다양한 EKS 환경 지원​

2. 아키텍처 및 동작 원리​

2.1 Agent Startup 및 초기화 흐름​

2.2 모니터 등록 및 관리​

2.3 Node Condition 기반 상태 보고​

2.4 실시간 진단 기능​

2.5 관찰 가능성 (Observability)​

2.6 콘솔 진단 로깅​

2.7 배포 및 운영 특징​

2.7.1 DaemonSet 기반 배포​

2.7.2 노드 선택 및 제약사항​

2.7.3 권한 관리​

2.7.4 리소스 효율성​

2.8 감지 가능한 문제 유형​

2.8.1 Container Runtime 이슈 (ContainerRuntimeReady)​

2.8.2 Kernel / Networking / Storage 주요 이슈​

2.8.3 Accelerated Hardware 이슈 (AcceleratedHardwareReady)​

3. Node Auto Repair 연동​

3.1 NMA 유무에 따른 Auto Repair 반응 대상​

3.2 컨디션별 복구 대기 시간 및 액션​

3.3 폭주 방지 안전장치​

3.4 활성화 방법​

4. 배포 방식별 차이점​

4.1 Manual Mode (DaemonSet)​

4.2 EKS Auto Mode​

5. 기술적 제한사항​

5.1 메트릭 수집 한계​

5.2 대체 백엔드 사용 시 제약​

5.3 하드웨어 장애 감지 한계​

6. 권장 구현 전략​

6.1 다층 모니터링 아키텍처​

6.2 Prometheus 사용 시 권장 구성​

7. 비용 및 성능 고려사항​

7.1 리소스 사용량​

7.2 CloudWatch 비용​

8. 모범 사례​

8.1 프로덕션 배포​

8.2 다른 도구와의 통합​

참고 자료​

공식 문서​

기술 블로그​

관련 문서 (내부)​

개요