RBLN NPU Operator 업그레이드¶

이 문서는 모든 RBLN 컴포넌트를 관리하는 오퍼레이터 차트를 새 버전으로 업그레이드하는 방법을 설명합니다. 드라이버 버전 롤아웃(RBLNDriver 라이프사이클)은 NPU 드라이버 업그레이드 워크플로우를 참고하세요.

업그레이드 수행¶

차트가 오퍼레이터 CRD를 자동으로 동기화하므로 helm upgrade 명령 하나로 업그레이드할 수 있습니다. 설치 시 사용한 릴리스 이름과 네임스페이스를 그대로 사용해 명령을 실행하고, 업그레이드를 재현할 수 있도록 새 버전을 명시적으로 지정합니다.

$ helm upgrade rbln-npu-operator \
     oci://docker.io/rebellions/rbln-npu-operator-chart \
     --version 0.4.5 \
     --namespace rbln-system

설치할 때 사용한 사용자 정의 Helm 값을 그대로 적용하려면 -f my-values.yaml을 전달하거나 설치 시 사용한 --set 오버라이드를 다시 지정합니다.

사용 가능한 버전 태그는 Docker Hub의 차트 페이지에서 확인할 수 있습니다.

CRD 자동 동기화¶

Helm은 차트에 포함된 CRD를 최초 helm install 시에만 적용하고 helm upgrade 시에는 갱신하지 않습니다. 오퍼레이터의 CRD 스키마는 릴리스마다 변경되므로, 차트는 pre-install/pre-upgrade 훅 Job으로 이를 보완합니다. 이 Job은 설치하거나 업그레이드할 때마다 최신 CRD를 server-side apply 방식으로 적용합니다. 훅은 이미지에 내장된 /opt/rbln/crds 경로의 CRD를 오퍼레이터 이미지의 crd-apply 바이너리로 적용하므로, 별도의 kubectl 이미지나 수동 kubectl apply 단계가 필요 없습니다.

훅은 기본적으로 활성화되어 있으며(crds.upgrade.enabled: true) 별도의 설정이 필요 없습니다. 오퍼레이터 이미지는 non-root로 실행되고 고정 사용자 ID를 지정하지 않으므로, 훅은 일반 Kubernetes와 OpenShift 모두에서 동작합니다. OpenShift에서는 Security Context Constraints가 허용 범위 내의 UID를 할당합니다.

차트는 helm uninstall 시에도 CRD를 삭제하지 않으므로, 업그레이드 과정에서 기존 커스텀 리소스가 유지됩니다.

CRD 수동 적용¶

Argo CD나 Flux 같은 GitOps 도구가 이미 CRD를 원하는 상태로 유지하고 있다면, 충돌을 피하기 위해 훅을 비활성화합니다.

crds:
  upgrade:
    enabled: false

훅을 비활성화한 경우, helm upgrade를 실행하기 전에 변경된 CRD를 직접 적용합니다. 릴리스 태그를 고정한 뒤, 차트가 관리하는 두 CRD(RBLNClusterPolicy, RBLNDriver)를 적용합니다. CRD의 크기와 필드 소유권 제약 때문에 --server-side 옵션이 필요합니다.

$ kubectl apply --server-side --force-conflicts -f \
  https://raw.githubusercontent.com/RBLN-SW/rbln-npu-operator/v0.4.5/config/crd/bases/rebellions.ai_rblnclusterpolicies.yaml

$ kubectl apply --server-side --force-conflicts -f \
  https://raw.githubusercontent.com/RBLN-SW/rbln-npu-operator/v0.4.5/config/crd/bases/rebellions.ai_rblndrivers.yaml

두 CRD와 helm upgrade 명령의 --version 플래그에는 동일한 태그를 사용하세요.

스키마가 변경되는 경우 CRD를 먼저 적용하세요

훅을 비활성화했고 새 릴리스에 CRD 스키마 변경이 포함되어 있다면, helm upgrade를 실행하기 전에 갱신된 CRD를 먼저 적용해야 합니다. 그렇지 않으면 스키마 검증이 실패하거나 새 필드가 누락될 수 있습니다.

업그레이드 검증¶

클러스터 폴리시와 드라이버 커스텀 리소스가 ready 상태로 다시 수렴할 때까지 대기합니다.

$ kubectl wait --for=jsonpath='{.status.state}'=ready \
    rblnclusterpolicy --all --timeout=10m

$ kubectl wait --for=jsonpath='{.status.state}'=ready \
    rblndriver --all --timeout=10m

업그레이드 진행 중 워크로드 타입별 진척 상황은 status.workloads[]로 조회할 수 있습니다. 전체 명령은 설치 검증에서 확인할 수 있습니다.

RBLN NPU Operator 업그레이드¶

업그레이드 수행¶

CRD 자동 동기화¶

CRD 수동 적용¶

업그레이드 검증¶

관련 문서¶