NPU 드라이버 업그레이드 워크플로우¶

이 문서는 Kubernetes에서 NPU 드라이버 업그레이드를 수행하는 방법을 설명합니다. 본 문서는 다음 내용을 다룹니다:

아키텍처 및 흐름 — 업그레이드를 조율하는 두 컴포넌트(operator, driver-manager)와 드라이버 Pod 시작 시 각 노드에서 수행되는 작업
업그레이드 모드 및 정책 — Operator 관리 vs 수동 롤아웃, 그리고 upgradePolicy 설정 방법(cordon, drain, reboot 등)
운영 옵션 — 특정 노드를 업그레이드에서 제외하는 방법

아키텍처 및 흐름¶

아키텍처 개요¶

NPU 드라이버 업그레이드는 두 컴포넌트가 협력하여 수행됩니다.

컴포넌트	역할
`rbln-npu-operator`	클러스터 수준 오케스트레이션 및 업그레이드 정책 집행
`rbln-k8s-driver-manager`	노드 로컬 드라이버 상태 조정(reconciliation)

설정에 따라 업그레이드는 다음 모드 중 하나로 동작합니다.

모드	설정	설명
Operator 관리 롤아웃	`autoUpgrade: true`	오퍼레이터가 노드 전반에 롤아웃 조율
수동 롤아웃	`autoUpgrade: false`	관리자가 업그레이드를 명시적으로 트리거

드라이버 업그레이드는 두 계층으로 나뉘어 관리됩니다.

1. rbln-npu-operator (클러스터 오케스트레이션)¶

오퍼레이터는 클러스터 전역 업그레이드 오케스트레이션을 관리합니다.

주요 책임은 다음과 같습니다.

드라이버 업그레이드가 필요한 노드 탐지
업그레이드 정책(upgradePolicy) 집행
롤아웃 병렬도 제어(maxParallelUpgrades)
다음과 같은 노드 유지보수 작업 조율:
- cordon
- drain
- reboot
노드 전반에 걸친 업그레이드 롤아웃 진행

오퍼레이터는 노드의 드라이버 상태를 직접 관리하지 않습니다. 대신 드라이버 Pod 재시작을 트리거하고, 이 과정이 노드 로컬 동기화로 이어집니다.

2. rbln-k8s-driver-manager (노드 드라이버 동기화)¶

rbln-k8s-driver-manager는 드라이버 DaemonSet 내부에서 실행되며, 각 노드의 드라이버 상태를 동기화(reconcile)하는 역할을 담당합니다.

주요 책임은 다음과 같습니다.

노드의 현재 드라이버 상태 탐지
드라이버 업그레이드 동안 노드에 함께 배포된 컴포넌트들을 일시 중지
필요 시 드라이버 제거/설치 수행
워크로드 재개를 위한 노드 라벨 복원

동기화 프로세스는 노드에서 드라이버 Pod가 시작될 때마다 트리거됩니다.

드라이버 동기화 흐름¶

노드에서 드라이버 Pod가 시작되면 initContainer가 rbln-k8s-driver-manager에 구현된 reconcile-driver-state 로직을 실행합니다.

단계	동작
1. 노드 라벨 읽기	`rebellions.ai/npu.deploy.*` 라벨을 읽어 관련 컴포넌트 Pod 실행 여부 결정
2. 관련 컴포넌트 일시 중지	라벨을 `paused-for-driver-upgrade`로 교체하여 DaemonSet 중지 및 기존 Pod 종료
3. Pod 종료 대기	NPU Operator와 관련된 컴퍼넌트 Pod가 모두 종료될 때까지 대기
4. 드라이버 상태 동기화	드라이버 이미지 다이제스트가 일치하면 기존 드라이버 제거를 건너뜀. 아니면 커널 모듈 언로드, 이전 아티팩트 제거, 새 드라이버 설치
5. 노드 라벨 복원	원래 라벨을 복원하여 관련 컴포넌트 Pod 재스케줄링 가능

결과적으로 노드의 모든 컴포넌트가 업그레이드된 드라이버로 재시작됩니다.

업그레이드 모드 및 정책¶

AutoUpgrade 모드 (`autoUpgrade: true`)¶

AutoUpgrade가 활성화되면, 오퍼레이터가 정책 기반으로 노드 전반의 롤아웃을 수행합니다.

업그레이드 동작은 upgradePolicy로 제어됩니다.

업그레이드 흐름¶

오퍼레이터가 선택한 각 노드에 대해:

단계	동작
1	신규 워크로드 유입 방지를 위해 노드 cordon
2	기존 NPU 워크로드를 정책에 따라 처리: `waitForCompletion`, `npuPodDeletion`, `drain`
3	드라이버 Pod 재시작을 통해 노드 로컬 동기화 트리거
4	선택적으로 노드 재부팅 수행
5	노드 검증 완료
6	노드 uncordon

그다음 오퍼레이터는 maxParallelUpgrades에 따라 다음 노드 배치로 진행합니다.

노드 업그레이드 대상 선정¶

다음 조건에서 업그레이드 대상 노드가 감지됩니다.

드라이버 DaemonSet 리비전 변경
명시적인 업그레이드 요청 발생

오퍼레이터는 maxParallelUpgrades 값을 기준으로 업그레이드 노드를 선택합니다.

값	동작
`1`	한 번에 노드 1개씩 업그레이드(순차)
`0`	병렬 업그레이드 제한 없음

재부팅 워크플로우¶

선택적 재부팅 지원은 다음과 같이 활성화할 수 있습니다.

driver:
  upgradePolicy:
    reboot:
      enable: true
      rebootTimeoutSeconds: 600
      image:
        registry: docker.io
        image: rebellions/rbln-node-reboot
        version: latest

활성화 시:

단계	동작
1	오퍼레이터가 reboot helper Pod를 통해 재부팅 트리거
2	노드가 일시적으로 `NotReady` 상태가 됨
3	재부팅 검증 후 노드가 `Ready` 상태로 복귀

수동 모드 (`autoUpgrade: false`)¶

AutoUpgrade가 비활성화되면 드라이버 DaemonSet은 OnDelete 전략을 사용합니다.

DaemonSet 템플릿이 변경되더라도 드라이버 Pod는 자동으로 재시작되지 않습니다.

대신 업그레이드는 관리자의 명시적 작업으로 진행됩니다.

수동 업그레이드 절차¶

관리자가 노드를 선택
노드 유지보수 작업 수행(일반적으로 cordon 및 drain)
관리자가 드라이버 Pod를 삭제:
1
$ kubectl delete pod <driver-pod>
새로운 드라이버 Pod 생성
initContainer가 드라이버 동기화 흐름을 트리거

동기화 중 rbln-k8s-driver-manager는 다음을 수행합니다.

관련된 컴포넌트 Pod들을 일시 중지
노드 드라이버 상태 업데이트
완료 후 노드 라벨 복원

동기화가 끝나면 관련된 컴포넌트 Pod들이 자동으로 다시 스케줄링됩니다.

Helm 설정¶

설정 예시:

driver:
  upgradePolicy:
    autoUpgrade: true
    maxParallelUpgrades: 1
    waitForCompletion:
      timeoutSeconds: 0
      podSelector: ""
    npuPodDeletion:
      force: false
      timeoutSeconds: 300
    drain:
      enable: true
      force: false
      deleteEmptyDirData: false
      podSelector: ""
      timeoutSeconds: 300
    reboot:
      enable: true
      rebootTimeoutSeconds: 0
      image:
        registry: docker.io
        image: rebellions/rbln-node-reboot
        version: latest

업그레이드 정책 참조¶

설정	설명
`autoUpgrade`	오퍼레이터 관리 드라이버 업그레이드 활성화/비활성화
`maxParallelUpgrades`	동시 업그레이드 최대 노드 수. `1` = 순차, `0` = 제한 없음
`waitForCompletion`	Pod 축출 전 선택한 Pod 또는 Job 완료 대기
`npuPodDeletion`	NPU Pod 축출 동작. `force: false` = 보수적(unmanaged Pod 시 차단 가능). `force: true` = 적극적 축출
`drain`	노드 drain. `enable: true` = 오퍼레이터가 drain 수행. `force: true` = 차단 Pod 있어도 계속 시도
`reboot`	선택적 재부팅. `rebootTimeoutSeconds` = 재부팅 검증 최대 시간; `0` = 타임아웃 없음

운영 옵션¶

드라이버 업그레이드 건너뛰기¶

특정 노드에서 드라이버 업그레이드를 건너뛰려면:

kubectl label node <node-name> rebellions.ai/npu-driver-upgrade.skip=true

업그레이드를 다시 활성화하려면:

kubectl label node <node-name> rebellions.ai/npu-driver-upgrade.skip-

이 라벨은 오퍼레이터가 업그레이드 대상을 선정할 때 평가되며, 주로 오퍼레이터 관리 롤아웃(autoUpgrade: true)에서 사용됩니다.