오퍼레이터 관찰가능성¶

이 문서는 RBLN NPU Operator의 상태를 모니터링하는 두 가지 방법인 오퍼레이터 메트릭과 Kubernetes 이벤트를 다룹니다. NPU 디바이스 자체의 텔레메트리(활용률, 온도, 전력 등)는 Metrics Exporter에서 확인할 수 있습니다.

오퍼레이터 메트릭¶

오퍼레이터는 정책·드라이버 reconcile 결과, NPU 노드 수, 드라이버 업그레이드 진행 상황 같은 자체 상태 메트릭을 Prometheus 형식으로 노출합니다. Helm 값 operator.metrics.enabled로 활성화 여부를 제어합니다(기본값 true).

메트릭 정보¶

메트릭	타입	레이블	설명
`rbln_operator_clusterpolicy_reconcile_status`	Gauge	—	마지막 `RBLNClusterPolicy` reconcile 결과(0=성공, 1=notReady, 2=unavailable)
`rbln_operator_driver_reconcile_status`	Gauge	`name`	`RBLNDriver` CR별 마지막 reconcile 결과
`rbln_operator_reconcile_total`	Counter	`controller`	실행된 reconcile 횟수
`rbln_operator_reconcile_failed_total`	Counter	`controller`	ready에 도달하지 못한 reconcile 횟수
`rbln_operator_npu_nodes`	Gauge	`workload`	워크로드 타입별 NPU 대상 노드 수
`rbln_operator_workload_coverage_state`	Gauge	`workload`	워크로드 커버리지 집계 상태(0=empty ~ 3=uncovered)
`rbln_operator_driver_pool_ready_ratio`	Gauge	`driver`, `pool`	드라이버 풀별 ready/desired 비율
`rbln_operator_driver_upgrade_nodes`	Gauge	`state`	드라이버 업그레이드 상태별 노드 수

오퍼레이터는 controller-runtime 표준 메트릭(controller_runtime_*, workqueue_*, rest_client_*, go_*)도 같은 엔드포인트에서 함께 노출합니다.

Prometheus Operator로 수집하기¶

Prometheus Operator를 사용한다면 Helm 값에서 차트가 제공하는 ServiceMonitor를 활성화하세요.

operator:
  metrics:
    serviceMonitor:
      enabled: true

엔드포인트가 인가를 요구하므로, 스크랩 대상을 UP 상태로 만들려면 차트가 생성하는 metrics-reader ClusterRole을 Prometheus의 ServiceAccount에 바인딩해야 합니다.

$ kubectl create clusterrolebinding rbln-operator-metrics-scraper \
  --clusterrole=<release>-rbln-npu-operator-metrics-reader \
  --serviceaccount=<monitoring-namespace>:<prometheus-serviceaccount>

403 응답

ServiceMonitor를 활성화했는데도 스크랩 대상이 403 Forbidden으로 남아 있다면 위 metrics-reader 바인딩 누락 여부를 확인하세요.

오퍼레이터 이벤트¶

오퍼레이터는 상태 전이와 실패를 Kubernetes 이벤트로 기록하므로, kubectl describe만으로 언제 무엇이 일어났는지 확인할 수 있습니다.

Reason	타입	대상	발생 시점
`DriverUpgradeStarted`	Normal	Node	노드가 업그레이드 대상으로 선정되어 cordon 단계로 진입
`NodeDrained`	Normal	Node	노드 drain 성공
`NodeDrainFailed`	Warning	Node	cordon 또는 drain 실패
`DriverUpgradeCompleted`	Normal	Node	노드 업그레이드 완료
`DriverUpgradeFailed`	Warning	Node	노드 업그레이드 실패
`ComponentApplyFailed`	Warning	RBLNClusterPolicy	정책이 관리하는 컴포넌트(Device Plugin, NPU Feature Discovery 등)의 매니페스트 적용 실패
`DriverInstallFailed`	Warning	RBLNDriver	드라이버 설치용 컴포넌트(노드 풀별 드라이버 DaemonSet 등)의 매니페스트 적용 실패
`AllComponentsReady`	Normal	RBLNClusterPolicy	정책이 관리하는 모든 컴포넌트가 준비를 마쳐 정책 상태가 `ready`로 바뀜
`DriverReady`	Normal	RBLNDriver	모든 노드 풀에서 드라이버가 준비를 마쳐 드라이버 상태가 `ready`로 바뀜
`PolicyIgnored`	Normal	RBLNClusterPolicy	활성 `RBLNClusterPolicy`가 이미 존재해 나중에 생성한 정책을 무시함(클러스터당 정책 1개만 유효)

오퍼레이터는 상태가 실제로 바뀔 때 한 번만 이벤트를 발행하며, 정상 상태에서 반복되는 reconcile 루프에서는 다시 발행하지 않습니다.

드라이버 자동 업그레이드 중에는 오퍼레이터가 각 노드에 DriverUpgradeStarted → NodeDrained → DriverUpgradeCompleted 순서로 이벤트를 기록합니다.

이벤트 조회¶

특정 노드의 업그레이드 이벤트를 시간순으로 조회합니다.

$ kubectl get events -A \
  --field-selector involvedObject.kind=Node,involvedObject.name=<node> \
  --sort-by=.lastTimestamp

커스텀 리소스의 이벤트는 describe 출력 하단의 Events 섹션에서 확인할 수 있습니다.

$ kubectl describe rblnclusterpolicy <name>
$ kubectl describe rblndriver <name>

이벤트 보존 기간

Kubernetes는 이벤트를 기본 1시간 동안만 보존합니다. 이벤트가 만료된 뒤에는 오퍼레이터 로그와 커스텀 리소스의 condition에서 같은 이력을 확인할 수 있습니다.

$ kubectl logs -n <namespace> deployment/<release>-rbln-npu-operator-controller-manager
$ kubectl get rblnclusterpolicy <name> -o jsonpath='{.status.conditions}'