노드 문제 감지기

노드 문제 감지기는 노드 상태를 모니터링하고 하드웨어, 커널 또는 컨테이너 런타임 문제와 같은 일반적인 노드 문제를 감지하는 오픈소스 라이브러리입니다. Google Distributed Cloud의 각 노드에서 systemd 서비스로 실행됩니다.

Google Distributed Cloud 출시 버전 1.10.0부터 노드 문제 감지기가 기본적으로 사용 설정됩니다.

추가 지원이 필요하면 Cloud Customer Care에 연락합니다. 다음을 비롯한 지원 리소스에 관한 자세한 내용은 지원 받기를 참조하세요.

  • 지원 케이스를 여는 요구사항
  • 문제 해결에 도움이 되는 도구(예: 환경 구성, 로그, 측정항목)
  • 지원되는 구성요소

어떤 문제를 감지하나요?

노드 문제 감지기는 다음과 같은 유형의 문제를 감지할 수 있습니다.

  • 응답하지 않는 런타임 데몬과 같은 컨테이너 런타임 문제
  • CPU, 메모리, 디스크 장애와 같은 하드웨어 문제
  • 커널 교착 상태 또는 손상된 파일 시스템과 같은 커널 문제

노드 문제 감지기는 노드에서 실행되며 Kubernetes API 서버에 문제를 NodeCondition 또는 Event로 보고합니다. NodeCondition은 노드에서 포드를 실행할 수 없게 만드는 문제이고 Event는 포드에 제한된 영향을 주는 일시적인 문제이지만 그렇더라도 충분히 보고할 가치가 있는 중요한 문제로 고려됩니다.

다음 표에서는 노드 문제 감지기에서 발견된 NodeConditions 및 자동으로 복구 가능한지 여부를 설명합니다.

조건 이유 자동 복구 지원1
KernelDeadlock 커널 프로세스가 필요한 리소스를 해제하기 위해 다른 커널 프로세스를 기다리는 동안 멈춰 있습니다. 아니요
ReadonlyFilesystem 디스크가 가득 참과 같은 문제로 인해 클러스터가 파일 시스템에 쓸 수 없습니다. 아니요
FrequentKubeletRestart kubelet이 자주 다시 시작되어 노드에서 포드를 효과적으로 실행할 수 없습니다. 아니요
FrequentDockerRestart Docker 데몬이 20분 동안 5회 넘게 다시 시작되었습니다. 아니요
FrequentContainerdRestart 컨테이너 런타임이 20분 동안 5회 넘게 다시 시작되었습니다. 아니요
FrequentUnregisterNetDevice 노드에서 네트워크 기기 등록 해제가 자주 발생합니다. 아니요
KubeletUnhealthy 노드가 올바르게 작동하지 않거나 컨트롤 플레인에 응답하지 않습니다. 아니요
ContainerRuntimeUnhealthy 컨테이너 런타임이 올바르게 작동하지 않아 포드가 노드에서 실행되거나 예약되지 않습니다. 아니요
CorruptDockerOverlay2 Docker overlay2 스토리지 드라이버 디렉터리 내에 파일 시스템 문제나 불일치가 있습니다. 아니요
OrphanContainers2 컨테이너에 해당하는 포드가 삭제되었지만 해당 컨테이너가 계속 노드에 있습니다. 아니요
FailedCgroupRemoval2 일부 cgroup이 고정 상태입니다. 예

1 버전 1.32 이상에서는 일부 조건에 감지된 문제를 자동으로 복구하는 기능이 지원됩니다.

2 버전 1.32 이상에서 지원됩니다.

노드 문제 감지기에서 보고되는 일부 Events 유형의 예시는 다음과 같습니다.

  • Warning TaskHung node/vm-worker-1-user-a12fabb4a99cb92-ddfce8832fd90f6f.lab.anthos kernel: task docker:7 blocked for more than 300 seconds.
  • Warning KernelOops node/vm-worker-1-user-a12fabb4a99cb92-ddfce8832fd90f6f.lab.anthos kernel: BUG: unable to handle kernel NULL pointer dereference at 00x0.

어떤 문제를 복구하나요?

버전 1.32부터 노드 문제 감지기가 일부 NodeConditions를 발견하면 노드에서 해당 문제를 자동으로 복구할 수 있습니다. 버전 1.32부터 자동 복구를 지원하는 유일한 NodeCondition은 FailedCgroupRemoval입니다.

감지된 문제를 확인하는 방법

다음 kubectl describe 명령어를 실행하여 NodeConditions 및 Events를 찾습니다.

kubectl describe node NODE_NAME \
    --kubeconfig=KUBECONFIG

다음을 바꿉니다.

  • NODE_NAME: 확인할 노드의 이름

  • KUBECONFIG: 클러스터 kubeconfig 파일 경로

노드 문제 감지기를 사용 설정 및 중지하는 방법

기본적으로 노드 문제 감지기가 사용 설정되어 있지만 node-problem-detector-config ConfigMap 리소스에서 노드 문제 감지기를 사용 중지할 수 있습니다. 명시적으로 사용 중지하지 않는 한 노드 문제 감지기는 노드에 문제가 있음을 나타내는 특정 조건에서 노드를 지속적으로 모니터링합니다.

특정 클러스터에서 노드 문제 감지기를 사용 중지하려면 다음 단계를 수행합니다.

  1. node-problem-detector-config ConfigMap 리소스를 수정합니다.

    kubectl edit configmap node-problem-detector-config \
    --kubeconfig=KUBECONFIG \
    --namespace=CLUSTER_NAMESPACE

    다음을 바꿉니다.

    • KUBECONFIG: 클러스터 kubeconfig 파일 경로

    • CLUSTER_NAMESPACE: 노드 문제 감지기를 사용 설정하려는 클러스터의 네임스페이스입니다.

    이 명령어는 node-problem-detector-config 리소스를 수정할 수 있는 텍스트 편집기를 자동으로 시작합니다.

  2. node-problem-detector-config 리소스 정의에서 data.enabled를 false로 설정합니다.

    apiVersion: v1
kind: ConfigMap
metadata:
  creationTimestamp: "2025-04-19T21:36:44Z"
  name: node-problem-detector-config
...
data:
  enabled: "false"

    처음에는 node-problem-detector-config ConfigMap에 data 필드가 없으므로 이 필드를 추가해야 할 수 있습니다.

  3. 리소스를 업데이트하려면 변경사항을 저장하고 편집기를 닫습니다.

노드 문제 감지기를 다시 사용 설정하려면 앞선 단계를 수행하되 node-problem-detector-config 리소스 정의에서 data.enabled를 true로 설정합니다.

자동 복구 사용 설정 및 사용 중지 방법

버전 1.32부터 노드 문제 감지기는 특정 NodeConditions를 확인하고 노드에서 해당 문제를 자동으로 복구합니다. 기본적으로 자동 복구는 지원되는 NodeConditions에 사용 설정되어 있지만 node-problem-detector-config ConfigMap 리소스에서 사용 중지될 수 있습니다.

특정 클러스터에서 자동 복구 동작을 사용 중지하려면 다음 단계를 수행합니다.

  1. node-problem-detector-config ConfigMap 리소스를 수정합니다.

    kubectl edit configmap node-problem-detector-config \
    --kubeconfig=KUBECONFIG \
    --namespace=CLUSTER_NAMESPACE

    다음을 바꿉니다.

    • KUBECONFIG: 클러스터 kubeconfig 파일 경로

    • CLUSTER_NAMESPACE: 노드 문제 감지기를 사용 설정하려는 클러스터의 네임스페이스입니다.

    이 명령어는 node-problem-detector-config 리소스를 수정할 수 있는 텍스트 편집기를 자동으로 시작합니다.

  2. node-problem-detector-config 리소스 정의에서 data.check-only를 true로 설정합니다.

    apiVersion: v1
kind: ConfigMap
metadata:
  creationTimestamp: "2025-04-19T21:36:44Z"
  name: node-problem-detector-config
...
data:
  enabled: "true"
  check-only: "true"

    처음에는 node-problem-detector-config ConfigMap에 data 필드가 없으므로 이 필드를 추가해야 할 수 있습니다. check-only를 "true"로 설정하면 지원되는 모든 조건의 자동 복구가 사용 중지됩니다.

  3. 리소스를 업데이트하려면 변경사항을 저장하고 편집기를 닫습니다.

자동 복구를 지원하는 모든 NodeConditions에 다시 사용 설정하려면 node-problem-detector-config ConfigMap에서 data.check-only를 "false"로 설정합니다.

노드 문제 감지기를 중지하고 다시 시작하는 방법

노드 문제 감지기는 각 노드에서 systemd 서비스로 실행됩니다. 지정된 노드의 노드 문제 감지기를 관리하려면 SSH를 사용하여 노드에 액세스하고 다음 systemctl 명령어를 실행합니다.

  • 노드 문제 감지기를 사용 중지하려면 다음 명령어를 실행합니다.

    systemctl stop node-problem-detector

  • 노드 문제 감지기를 다시 시작하려면 다음 명령어를 실행합니다.

    systemctl restart node-problem-detector

  • 노드 문제 감지기가 특정 노드에서 실행 중인지 확인하려면 다음 명령어를 실행합니다.

    systemctl is-active node-problem-detector

지원되지 않는 기능

Google Distributed Cloud에서는 다음 노드 문제 감지기를 맞춤설정할 수 없습니다.

  • Stackdriver 또는 Prometheus와 같은 다른 모니터링 시스템으로 노드 문제 감지기 보고서 내보내기
  • 검색할 NodeConditions 또는 Events 맞춤설정
  • 사용자 정의 모니터링 스크립트 실행

다음 단계

추가 지원이 필요하면 Cloud Customer Care에 연락합니다. 다음을 비롯한 지원 리소스에 관한 자세한 내용은 지원 받기를 참조하세요.

  • 지원 케이스를 여는 요구사항
  • 문제 해결에 도움이 되는 도구(예: 환경 구성, 로그, 측정항목)
  • 지원되는 구성요소