오퍼레이터 관찰가능성¶

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

오퍼레이터 메트릭¶

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

메트릭 정보¶

메트릭	타입	레이블	설명
`rbln_operator_clusterpolicy_reconcile_status`	Gauge	—	마지막 `RBLNClusterPolicy` 조정 결과(0=성공, 1=notReady, 2=unavailable)
`rbln_operator_driver_reconcile_status`	Gauge	`name`	`RBLNDriver` CR별 마지막 조정 결과
`rbln_operator_reconcile_total`	Counter	`controller`	실행된 조정 횟수
`rbln_operator_reconcile_failed_total`	Counter	`controller`	ready에 도달하지 못한 조정 횟수
`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_owned_nodes`	Gauge	`driver`	각 `RBLNDriver`에 라우팅된 노드 수. 0으로 초기화되므로 매칭되는 노드가 없어도 시리즈가 사라지지 않고 `0`으로 표시됩니다
`rbln_operator_driver_uncovered_nodes`	Gauge	—	드라이버 대상이지만 소유 `RBLNDriver`가 없는 NPU 노드 수
`rbln_operator_driver_selector_conflict_nodes`	Gauge	`driver`	이 드라이버의 셀렉터가 다른 `RBLNDriver`와 충돌하는 노드 수
`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만으로 언제 무엇이 일어났는지 확인할 수 있습니다. 커스텀 리소스에서 발생한 실패는 다음 표의 대응 관계에 따라 각 리소스의 Ready 조건에도 반영됩니다. 이벤트가 만료된 뒤에는 이 조건이 현재 상태의 기준이 됩니다.

사유(`reason`)	타입	대상	발생 시점	대응 `Ready` 조건
`DriverUpgradeStarted`	Normal	Node	노드가 업그레이드 대상으로 선정되어 cordon 단계로 진입	—
`NodeDrained`	Normal	Node	노드 drain 성공	—
`NodeDrainFailed`	Warning	Node	cordon 또는 drain 실패	—
`DriverUpgradeCompleted`	Normal	Node	노드 업그레이드 완료	—
`DriverUpgradeFailed`	Warning	Node	노드 업그레이드 실패	—
`DriverOwnerChanged`	Normal	Node	노드를 소유하는 `RBLNDriver`가 지정되거나 변경됨	—
`DriverNodeUncovered`	Warning	Node	매칭되는 셀렉터가 없거나 셀렉터 충돌이 해소되지 않아 노드가 소유 `RBLNDriver`를 잃음	—
`ComponentApplyFailed`	Warning	RBLNClusterPolicy	정책이 관리하는 컴포넌트(Device Plugin, NPU Feature Discovery 등)의 매니페스트 적용 실패	`False / ComponentApplyFailed`
`DriverInstallFailed`	Warning	RBLNDriver	드라이버 설치용 컴포넌트(노드 풀별 드라이버 DaemonSet 등)의 매니페스트 적용 실패	`False / Error`
`InvalidSpec`	Warning	RBLNDriver	`nodeSelector`에 예약 키를 사용했거나 리소스 이름이 63자를 초과함	`False / InvalidSpec`
`ConflictingNodeSelector`	Warning	RBLNDriver	특정 노드에서 `nodeSelector`가 다른 `RBLNDriver`와 충돌함	`False / ConflictingNodeSelector`
`DriverImageNotFound`	Warning	RBLNDriver	해당 풀에 대해 조합된 드라이버 이미지가 레지스트리에 없음. 약 5분마다 재확인하며 이미지를 게시하면 자동으로 해소됨	`False / DriverImageNotFound`
`DriverFamilyLabelMissing`	Warning	RBLNDriver	소유한 노드에 사용 가능한 `rebellions.ai/npu.family` 레이블이 없음	`False / DriverFamilyLabelMissing`
`AllActiveWorkloadsReady`	Normal	RBLNClusterPolicy	정책이 관리하는 모든 컴포넌트가 준비를 마쳐 정책 상태가 `ready`로 바뀜	`True / AllActiveWorkloadsReady`
`DriverReady`	Normal	RBLNDriver	모든 노드 풀에서 드라이버가 준비를 마쳐 드라이버 상태가 `ready`로 바뀜	`True / AllDriverPoolsReady`
`PolicyIgnored`	Normal	RBLNClusterPolicy	활성 `RBLNClusterPolicy`가 이미 존재해 나중에 생성한 정책을 무시함(클러스터당 정책 1개만 유효)	`False / PolicyIgnored`

오퍼레이터는 상태가 실제로 바뀔 때 한 번만 이벤트를 발행하며, 정상 상태에서 반복되는 조정(reconcile) 루프에서는 다시 발행하지 않습니다. 네 가지 드라이버 검증 경고(InvalidSpec, ConflictingNodeSelector, DriverImageNotFound, DriverFamilyLabelMissing)는 이벤트 사유와 리소스 세대(metadata.generation)의 조합마다 한 번씩만 발행됩니다. 따라서 사양이 바뀌지 않은 상태에서 문제가 해소되었다가 다시 발생하면 Ready 조건만 갱신되고 이벤트는 다시 발행되지 않습니다. 노드 라우팅 이벤트 두 가지는 노드의 소유자가 실제로 바뀌는 조정 과정에서만 발행됩니다.

두 CRD 모두 클러스터 범위이므로, 이벤트는 오퍼레이터 네임스페이스가 아니라 default 네임스페이스에 기록됩니다.

드라이버 자동 업그레이드 중에는 오퍼레이터가 각 노드에 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시간 동안만 보존합니다. 현재 상태는 .status.conditions에서 확인하고, 장기 추세와 알림에는 rbln_operator_* 메트릭을 사용하세요.

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

이벤트가 보이지 않을 때

같은 오브젝트에서 서로 다른 실패가 짧은 시간에 몰리면 Kubernetes 클라이언트의 스팸 필터에 의해 일부 이벤트가 누락될 수 있습니다. 이 경우에도 Ready 조건과 메트릭에는 현재 상태가 반영됩니다.

로깅¶

오퍼레이터는 Kubernetes 클라이언트 라이브러리가 생성하는 레코드를 포함한 구조화된 로그를 stdout에 출력합니다. 다음 차트 값으로 로그를 설정합니다.

operator:
  logging:
    level: info              # error | info | debug | panic 또는 logr V(N)을 뜻하는 정수 N
    encoder: json            # json | console
    timeEncoding: rfc3339nano
    develMode: false

잘못된 로깅 값으로 인한 오퍼레이터 시작 실패

level이나 encoder에 잘못된 값을 지정하면 기본값으로 되돌아가지 않고 오퍼레이터가 시작 시점에 중단됩니다. 적용 전에 값을 확인하세요.

Kubernetes 클라이언트 라이브러리 로그 레코드의 상세도를 높이려면 level을 올리고 컨테이너 인자로 klog -v도 함께 지정해야 합니다.

CRD 동기화 훅은 오퍼레이터보다 먼저 실행되므로 이 값을 상속받을 수 없습니다. crds.upgrade.logging.level과 crds.upgrade.logging.format으로 따로 설정하며, 오퍼레이터와 달리 잘못된 값을 지정하면 기본값으로 되돌아갑니다.

오퍼레이터가 관리하는 컴포넌트는 별도의 로그 설정을 사용합니다. 컴포넌트 로깅을 참고하세요.