Node Problem Detector 설치 및 관리

Node Problem Detector는 각 워커 노드에서 실행되며 커널과 컨테이너 런타임 등 노드 구성 요소의 문제를 감지합니다. 감지한 문제는 Kubernetes API 서버에 이벤트(Event) 또는 노드 상태(NodeCondition)로 보고하므로 kubectl get events와 kubectl describe node 명령으로 확인할 수 있습니다. 자세한 내용은 Node Problem Detector 공식 문서를 참고하시기 바랍니다.

Node Problem Detector는 Node Local DNS Cache와 독립적으로 동작합니다. 노드 단위 DNS 캐시가 필요한 경우 Node Local DNS Cache 설치 및 관리를 참고하시기 바랍니다.

Node Problem Detector는 노드의 CPU와 메모리 사용량을 수집하는 node-exporter 기반의 노드 모니터링을 대체하지 않습니다.

안내

• Kubernetes 1.32 및 1.33: 필요한 경우 이 가이드에 따라 설치하고 삭제할 수 있습니다. 설치한 Node Problem Detector는 사용자가 관리하는 Helm 릴리스입니다.
• Kubernetes 1.34 이상: 클러스터에 기본으로 설치되며 Kubernetes Engine에서 관리합니다. 중복으로 설치하거나 임의로 삭제하지 마세요. Helm 릴리스로 관리되지 않으므로 helm list 출력에 표시되지 않을 수 있습니다. DaemonSet을 삭제한 경우 자동 복구가 지연될 수 있으므로 상태를 확인한 후 헬프데스크 > 기술 문의로 문의하시기 바랍니다.
• Kubernetes 1.32 또는 1.33 클러스터에 이 가이드로 설치한 경우, 1.34 이상으로 업그레이드하기 전에 Step 5. Node Problem Detector 삭제에 따라 Helm 릴리스를 삭제합니다. 기존 릴리스가 남아 있으면 사용자 설치본과 기본 설치본이 동시에 동작하여 동일한 문제가 여러 번 보고되거나 이벤트와 NodeCondition이 중복 또는 경합할 수 있습니다.

Step 1. 사전 작업

이 가이드의 설치 절차는 Kubernetes 1.32 및 1.33 클러스터에만 적용합니다. Kubernetes 1.34 이상 클러스터에서는 설치 절차를 수행하지 말고 Step 3. 배포 상태 확인과 Step 4. 운영 모니터링을 참고하시기 바랍니다.

클러스터와 도구 준비

1. Node Problem Detector를 설치할 Kubernetes Engine 클러스터를 생성합니다.
2. 생성한 클러스터에 명령을 실행할 수 있도록 kubectl 제어 설정을 수행합니다.
3. Helm 공식 문서를 참고하여 Helm 3을 설치합니다.

대상 클러스터의 kubeconfig를 환경 변수로 설정합니다.

kubeconfig 설정

export KUBE_CONFIG=/path/to/cluster-kubeconfig.yaml

클러스터의 Kubernetes 버전을 확인합니다.

Kubernetes 버전 확인

kubectl --kubeconfig=$KUBE_CONFIG version

Kubernetes minor 버전에 맞춰 환경 변수를 설정합니다. 다음은 Kubernetes 1.33 클러스터의 예시입니다.

Helm 차트 버전 설정

export K8S_MINOR=1.33
export CHART_VERSION=${K8S_MINOR}.0

Kubernetes 버전	Helm 차트 버전
1.32	1.32.0
1.33	1.33.0

Node Problem Detector Helm 차트는 카카오클라우드 Public OCI 레지스트리에서 제공합니다. 별도의 Helm 저장소를 등록하지 않고 설치할 수 있습니다.

기존 배포와 레지스트리 확인

기존에 설치된 Node Problem Detector가 있는지 확인합니다.

기존 배포 확인

helm --kubeconfig=$KUBE_CONFIG list -n kube-system -a

kubectl --kubeconfig=$KUBE_CONFIG get daemonset -n kube-system \
    | grep -E 'node-problem-detector' || true

기존 배포가 있으면 중복으로 설치하지 말고 Helm 릴리스 이름, 적용된 설정값 및 관리 주체를 먼저 확인합니다. Node Problem Detector를 중복으로 배포하면 동일한 문제가 여러 번 보고될 수 있습니다.

helm list 출력에는 ke-cilium, ke-tigera-operator와 같이 Kubernetes Engine이 관리하는 시스템 릴리스가 표시될 수 있습니다. 시스템 릴리스는 수정하거나 삭제하지 마세요.

워커 노드에서 다음 레지스트리에 접근할 수 있는지 확인합니다.

ke-container-registry.kr-central-2.kcr.dev

운영 클러스터에 바로 배포하지 말고 동일한 Kubernetes 버전, CNI, 노드 OS 및 어드미션 정책을 사용하는 개발 또는 스테이징 클러스터에서 설치와 롤백을 먼저 검증합니다.

Step 2. Node Problem Detector 설치

이 절차는 Kubernetes 1.32 및 1.33 클러스터에만 적용합니다. Kubernetes 1.34 이상 클러스터에서는 실행하지 마세요.

Helm 차트의 기본값과 생성될 리소스를 확인합니다.

Helm 차트 기본값 확인

helm show values \
    oci://ke-container-registry.kr-central-2.kcr.dev/ke-helm-public/node-problem-detector \
    --version $CHART_VERSION

Node Problem Detector 사전 검증

helm template node-problem-detector \
    oci://ke-container-registry.kr-central-2.kcr.dev/ke-helm-public/node-problem-detector \
    --version $CHART_VERSION \
    --namespace kube-system \
    | kubectl --kubeconfig=$KUBE_CONFIG apply --dry-run=server -f -

Node Problem Detector는 기본적으로 privileged 컨테이너, hostPath, ServiceAccount 및 RBAC 리소스를 사용합니다. Pod Security Admission, Kyverno 또는 Gatekeeper 정책을 사용하는 클러스터에서는 dry-run 결과를 확인하고 필요한 정책을 먼저 적용합니다.

사전 검증에 성공하면 Node Problem Detector를 설치합니다.

Node Problem Detector 설치

helm --kubeconfig=$KUBE_CONFIG upgrade --install node-problem-detector \
    oci://ke-container-registry.kr-central-2.kcr.dev/ke-helm-public/node-problem-detector \
    --version $CHART_VERSION \
    --namespace kube-system \
    --wait \
    --timeout 5m

Step 3. 배포 상태 확인

Kubernetes 1.32 및 1.33

이 가이드에 따라 설치한 Helm 릴리스의 상태를 확인합니다.

Helm 릴리스 상태 확인

helm --kubeconfig=$KUBE_CONFIG status node-problem-detector -n kube-system

DaemonSet과 파드가 모든 대상 워커 노드에서 정상 실행되는지 확인합니다.

DaemonSet과 파드 확인

kubectl --kubeconfig=$KUBE_CONFIG get daemonset \
    node-problem-detector -n kube-system

kubectl --kubeconfig=$KUBE_CONFIG get pod -n kube-system -o wide \
    -l app.kubernetes.io/instance=node-problem-detector

kubectl --kubeconfig=$KUBE_CONFIG rollout status \
    daemonset/node-problem-detector -n kube-system

Kubernetes 1.34 이상

Kubernetes 1.34 이상 클러스터의 Node Problem Detector는 Helm 릴리스로 관리되지 않습니다. 따라서 Helm 상태 확인을 건너뛰고 Kubernetes Engine에서 관리하는 DaemonSet을 확인합니다.

플랫폼 관리 DaemonSet 확인

kubectl --kubeconfig=$KUBE_CONFIG get daemonset -n kube-system \
    | grep node-problem-detector

노드 이벤트와 상태 확인

Node Problem Detector가 보고한 노드 이벤트(Event)와 상태(NodeCondition)를 확인합니다. {node-name}을 실제 워커 노드 이름으로 변경합니다.

노드 이벤트 확인

kubectl --kubeconfig=$KUBE_CONFIG get events -A \
    --field-selector involvedObject.kind=Node

노드 상태 확인

kubectl --kubeconfig=$KUBE_CONFIG describe node {node-name}

다음 항목을 모두 충족하면 배포 상태가 정상인 것으로 판단합니다.

• DaemonSet의 Ready 수가 대상 워커 노드 수와 일치합니다.
• 워커 노드가 Ready 상태를 유지합니다.
• Node Problem Detector가 잘못된 노드 상태나 과도한 이벤트를 생성하지 않습니다.
• Kubernetes 1.32 및 1.33에서 직접 설치한 경우 Helm 릴리스가 deployed 상태입니다.

Step 4. 운영 모니터링

배포 후 다음 항목을 모니터링합니다.

• 워커 노드의 Ready 상태 변화
• Node Problem Detector가 생성한 이벤트와 노드 상태
• Kubernetes 이벤트의 비정상적인 증가
• Node Problem Detector 파드의 재시작 횟수와 오류 로그

Kubernetes 1.32 및 1.33에서 이 가이드로 직접 설치한 경우 다음 명령으로 설정값과 로그를 확인할 수 있습니다.

적용된 설정값과 로그 확인

helm --kubeconfig=$KUBE_CONFIG get values node-problem-detector \
    -n kube-system -a

kubectl --kubeconfig=$KUBE_CONFIG logs -n kube-system \
    -l app.kubernetes.io/instance=node-problem-detector \
    --tail=100

Kubernetes 1.34 이상에서 Kubernetes Engine이 관리하는 Node Problem Detector에 문제가 지속되면 DaemonSet, 노드 상태 및 이벤트를 확인한 후 헬프데스크에 문의하시기 바랍니다.

Step 5. Node Problem Detector 삭제

이 절차는 Kubernetes 1.32 및 1.33에서 이 가이드로 직접 설치한 Helm 릴리스에만 적용합니다. Kubernetes 1.34 이상에 기본으로 설치된 Node Problem Detector는 이 절차로 삭제할 수 없습니다.

삭제할 Helm 릴리스를 확인합니다. helm list는 현재 네임스페이스의 릴리스만 표시하므로 kube-system 네임스페이스를 명시합니다.

삭제 대상 Helm 릴리스 확인

helm --kubeconfig=$KUBE_CONFIG list -n kube-system -a \
    | grep -E '^node-problem-detector[[:space:]]'

필요한 경우 삭제 전에 현재 설정값을 백업합니다.

적용된 설정값 백업

helm --kubeconfig=$KUBE_CONFIG get values node-problem-detector \
    -n kube-system -a -o yaml > node-problem-detector-values-backup.yaml

Node Problem Detector를 삭제합니다.

Node Problem Detector 삭제

helm --kubeconfig=$KUBE_CONFIG uninstall node-problem-detector \
    --namespace kube-system \
    --wait \
    --timeout 5m

Helm 릴리스와 Kubernetes 리소스가 삭제되었는지 확인합니다.

삭제 결과 확인

helm --kubeconfig=$KUBE_CONFIG list -n kube-system -a \
    | grep -E '^node-problem-detector[[:space:]]' || true

kubectl --kubeconfig=$KUBE_CONFIG get daemonset -n kube-system \
    | grep '^node-problem-detector[[:space:]]' || true

Node Problem Detector가 생성한 기존 Kubernetes 이벤트는 Helm 릴리스를 삭제해도 이벤트 보존 기간 동안 남아 있을 수 있습니다. 삭제한 후 새로운 관련 이벤트 또는 노드 상태가 계속 발생하지 않는지 확인합니다.

Step 6. 장애 발생 시 복구

워커 노드가 NotReady 상태로 전환되거나 비정상적인 노드 상태 또는 과도한 이벤트가 발생하면 먼저 상태를 확인합니다.

장애 상태 확인

kubectl --kubeconfig=$KUBE_CONFIG get daemonset -n kube-system \
    | grep node-problem-detector

kubectl --kubeconfig=$KUBE_CONFIG get events -A \
    --field-selector involvedObject.kind=Node

Kubernetes 1.32 및 1.33에서 이 가이드로 직접 설치한 경우 로그와 Helm 릴리스 이력을 확인합니다.

로그와 Helm 릴리스 이력 확인

kubectl --kubeconfig=$KUBE_CONFIG logs -n kube-system \
    -l app.kubernetes.io/instance=node-problem-detector \
    --tail=200

helm --kubeconfig=$KUBE_CONFIG history node-problem-detector -n kube-system

이전에 정상적으로 동작한 리비전(revision)이 있으면 해당 리비전으로 롤백합니다.

Node Problem Detector 롤백

helm --kubeconfig=$KUBE_CONFIG rollback node-problem-detector {revision} \
    --namespace kube-system \
    --wait \
    --timeout 5m

첫 설치에 실패했거나 롤백 후에도 문제가 지속되면 Step 5. Node Problem Detector 삭제에 따라 Helm 릴리스를 삭제합니다.

Kubernetes 1.34 이상에서 Kubernetes Engine이 관리하는 Node Problem Detector는 Helm 이력 확인과 롤백 대상이 아닙니다. DaemonSet 상태, 파드 로그, 노드 상태 및 이벤트를 확인한 후에도 문제가 지속되면 헬프데스크에 문의하시기 바랍니다.

복구 후에는 다음 항목을 다시 확인합니다.

• 워커 노드가 Ready 상태를 유지합니다.
• Node Problem Detector 파드가 정상적으로 실행됩니다.
• 비정상적인 노드 상태 또는 이벤트가 더 이상 증가하지 않습니다.