망분리(Disconnected) 또는 에어 갭(Air-gapped) 환경에서 RBLN NPU Operator 설치¶

개요¶

이 문서는 인터넷에 직접 접근할 수 없는 망분리(disconnected) 또는 에어 갭(air-gapped) OpenShift Container Platform 클러스터에 RBLN NPU Operator를 설치하고 구성하는 방법을 설명합니다. 이러한 환경에서는 모든 컨테이너 이미지, Operator 카탈로그, RBLN 드라이버를 모든 노드가 접근 가능한 내부 레지스트리에 미리 미러링해야 합니다.

설치 절차 자체는 표준 OpenShift 설치 가이드 흐름과 동일하며, 그 앞에 미러링과 미러 레지스트리 구성 단계가 추가됩니다. 이 문서의 모든 절차는 이미 설치되어 동작 중인 클러스터에 적용합니다.

보안이나 컴플라이언스를 위해 엄격한 네트워크 격리가 필요한 환경에서는 클러스터 노드가 registry.redhat.io, Docker Hub, ghcr.io 같은 공개 레지스트리에서 이미지를 가져올 수 없습니다. 대신 필요한 이미지를 내부 레지스트리에 한 번 미러링하고, 모든 이미지 pull이 그 레지스트리로 향하도록 클러스터를 구성합니다.

같은 제약이 OperatorHub에도 적용됩니다. 기본 OperatorHub 소스는 OLM(Operator Lifecycle Manager)이 registry.redhat.io에서 카탈로그 이미지를 직접 가져오는 것을 전제하므로, 망분리 클러스터에서는 OLM이 기본 소스에 접근할 수 없습니다. 따라서 기본 소스를 비활성화하고, 미러된 카탈로그를 가리키는 CatalogSource로 대체합니다(미러 레지스트리 구성 참고).

망분리 환경은 두 가지 형태로 나뉩니다. 하나는 통제된 egress를 가진 미러 호스트(배스천 호스트)를 통해 미러를 갱신할 수 있는 환경이고, 다른 하나는 미러링된 콘텐츠를 이동식 미디어로 반입해야 하는 완전히 격리된 에어 갭(air-gapped) 환경입니다. 이 문서는 전자를 토폴로지 A, 후자를 토폴로지 B로 설명합니다. 두 방식 모두 동일한 이미지 집합을 미러링하며, 차이는 콘텐츠가 내부 레지스트리에 도달하는 경로뿐입니다.

토폴로지 A — 통제된 egress를 통한 미러링¶

클러스터 노드는 인터넷 egress가 없지만, 별도의 미러 호스트가 통제된 forward proxy를 통해 이미지를 가져와 내부 레지스트리에 push 합니다. 이동식 미디어 반입 없이 미러를 갱신할 수 있습니다.

토폴로지 A. 미러 호스트만 egress를 갖습니다. 클러스터는 내부 레지스트리에서만 pull 하며, 미러는 oc-mirror 재실행으로 갱신합니다.

토폴로지 B — 에어 갭(이동식 미디어)¶

연결된 네트워크와 에어 갭 환경 사이에 네트워크 경로가 전혀 없습니다. 연결된 호스트에서 이미지를 디스크 아카이브로 내려받아 이동식 미디어로 옮긴 뒤, 에어 갭 측에서 내부 레지스트리로 import 합니다. 최고 수준의 격리가 요구되는 환경에 해당합니다.

토폴로지 B. oc-mirror를 두 번 실행합니다 — 연결된 호스트에서 디스크로 미러링(mirror-to-disk)한 뒤, 아카이브를 이동식 미디어로 반입해 내부 레지스트리로 import 합니다.

사전 요구사항¶

단계를 진행하기 전에 다음 사항을 확인하세요:

NPU 워커 노드가 포함된, 정상적으로 작동하는 OpenShift Container Platform 클러스터(4.19 이상)와 cluster-admin 권한. OpenShift Container Platform 설치에 대한 자세한 내용은 OpenShift Container Platform 설치 가이드를 참고하세요.
Docker v2-2 사양을 지원하고 모든 클러스터 노드에서 접근 가능한 내부 이미지 레지스트리(예: Quay). 클러스터가 신뢰하는 TLS 인증서 필요.
oc, oc-mirror 바이너리와 미러링 대상 상위 레지스트리 자격증명을 갖춘 미러 호스트.
Red Hat pull secret과 Rebellions 레지스트리(repo.rebellions.ai) pull 자격증명. repo.rebellions.ai 접근에는 RBLN Portal 계정 인증이 필요합니다.
Rebellions NPU가 장착된 노드(PCI vendor ID 1eff).

컨테이너 이미지 미러링¶

미러링 대상은 RBLN NPU Operator와 NFD(Node Feature Discovery) Operator 두 가지이며, 하나의 ImageSetConfiguration(imageset-config.yaml)으로 함께 정의합니다. 두 대상 모두 필수입니다. 예시의 카탈로그 인덱스 태그(v4.21)는 클러스터의 OpenShift 버전에 맞게 지정합니다.

미러링 대상	구성
RBLN NPU Operator	certified operator 카탈로그(operand 이미지 포함) + `rbln-smd`·`rbln-driver` additional images (`repo.rebellions.ai` pull 자격증명 필요)
NFD	redhat operator 카탈로그의 Node Feature Discovery Operator — RBLN NPU Operator 의존성

ImageSetConfiguration¶

RBLN NPU Operator와 관련 operand 이미지는 certified operator 카탈로그에, RBLN NPU Operator가 의존하는 NFD Operator는 redhat operator 카탈로그에 포함되어 제공됩니다. 카탈로그에 포함되지 않는 rbln-smd과 rbln-driver 이미지만 별도의 additionalImages로 구성합니다. 두 이미지를 받으려면 repo.rebellions.ai pull 자격증명이 필요합니다(사전 요구사항 참고). RBLNDriver의 image 경로는 rebellions/rbln-driver인 반면 실제 드라이버 이미지는 NPU family 경로(rebellions/atom/rbln-driver)에 있습니다. 따라서 additionalImages에는 family 경로의 이미지를 지정합니다.

# imageset-config.yaml
apiVersion: mirror.openshift.io/v2alpha1
kind: ImageSetConfiguration
mirror:
  operators:
    - catalog: registry.redhat.io/redhat/certified-operator-index:v4.21
      packages:
        - name: rbln-npu-operator      # operand 이미지 포함
    - catalog: registry.redhat.io/redhat/redhat-operator-index:v4.21
      packages:
        - name: nfd
  additionalImages:
    - name: repo.rebellions.ai/rebellions/rbln-smd:<driver_version>
    - name: repo.rebellions.ai/rebellions/atom/rbln-driver:<driver_version>-<kernel_version>-rhel<rhel_version>

노드 커널 버전 일치

rbln-driver는 특정 커널 버전에 맞춰 빌드된 precompiled 이미지로 제공됩니다. NPU 노드의 커널 버전을 고정하고, 그에 맞는 이미지를 이미지 집합에 반드시 포함하세요. 노드 커널과 일치하는 드라이버 이미지가 미러되어 있지 않으면 망분리 클러스터에서 드라이버를 로드할 수 없습니다. 확인 방법은 아래 커널·RHEL 버전 확인을 참고하세요.

커널·RHEL 버전 확인¶

RBLN 드라이버 이미지는 특정 커널 버전에 맞춰 사전 컴파일(precompiled)되어 제공되며, 이미지 태그는 다음 규칙을 따릅니다.

1	`<driver_version>-<kernel_version>-rhel<rhel_version>`

드라이버가 로드될 때 노드의 커널 버전으로 동일한 규칙의 태그를 조합하여 이미지를 pull 하므로, 미러링한 태그가 클러스터 노드의 커널 버전과 정확히 일치해야 합니다. 커널·RHEL 버전은 클러스터의 노드 정보에서 다음과 같이 직접 확인합니다.

노드 커널 버전 조회

$ oc get nodes -o custom-columns='NAME:.metadata.name,KERNEL-VERSION:.status.nodeInfo.kernelVersion'
NAME       KERNEL-VERSION
worker-0   5.14.0-570.107.1.el9_6.x86_64
worker-1   5.14.0-570.107.1.el9_6.x86_64

oc get nodes -o wide의 KERNEL-VERSION 열에서도 같은 값을 확인할 수 있습니다. RHEL 버전은 커널 버전 문자열에 포함되어 있으며, el9_6은 RHEL 9.6을 의미합니다.

드라이버 이미지 태그 조합

조회한 커널 버전·RHEL 버전과 사용할 드라이버 버전으로 태그를 조합하여 ImageSetConfiguration의 additionalImages에 포함합니다. 예를 들어 드라이버 버전이 3.2.2이고 위 커널 버전을 사용하는 경우:
1
repo.rebellions.ai/rebellions/atom/rbln-driver:3.2.2-5.14.0-570.107.1.el9_6.x86_64-rhel9.6

Note

미러 작업을 수행하는 호스트에서 클러스터에 접근할 수 없는 경우, OpenShift 릴리스의 커널·RHEL 버전은 해당 릴리스의 driver-toolkit 이미지에서도 확인할 수 있습니다.

$ DTK=$(oc adm release info --image-for=driver-toolkit \
    quay.io/openshift-release-dev/ocp-release:<ocp_version>-x86_64)
$ podman run --rm $DTK cat /etc/driver-toolkit-release.json

oc-mirror 실행¶

앞에서 정의한 ImageSetConfiguration으로 oc-mirror를 실행합니다. 실행 방식은 토폴로지에 따라 다릅니다.

토폴로지 A — 내부 레지스트리로 직접 미러링¶

미러 호스트가 통제된 egress로 상위 레지스트리에서 이미지를 가져와 내부 레지스트리에 바로 push 합니다.

레지스트리 인증

미러 작업을 수행할 호스트에서 상위 레지스트리와 내부 레지스트리에 로그인합니다. RBLN 드라이버·데몬 이미지를 제공하는 repo.rebellions.ai에는 발급받은 RBLN Portal 계정으로 로그인합니다.
1 2 3
$ docker login registry.redhat.io $ docker login repo.rebellions.ai # RBLN Portal 계정 $ docker login registry.internal:8443 # 내부 레지스트리
미러 실행

대상 레지스트리를 docker://로 지정하면 이미지가 곧바로 push 됩니다. 레지스트리로 직접 미러링할 때는 작업 파일과 생성 매니페스트를 저장할 로컬 디렉터리를 지정하는 --workspace 옵션이 필요합니다. --remove-signatures 플래그는 이미지 서명을 복사 대상에서 제외하여, 서명을 지원하지 않는 내부 레지스트리로 push 할 때 발생하는 오류를 방지합니다.
1 2
$ oc-mirror --v2 --config imageset-config.yaml --remove-signatures \ --workspace file://./workspace docker://registry.internal:8443
산출물 확인

실행이 끝나면 workspace 디렉터리의 working-dir/cluster-resources/에 ImageDigestMirrorSet·ImageTagMirrorSet와 CatalogSource 매니페스트가 생성됩니다. 이 파일들은 다음 단계 미러 레지스트리 구성에서 클러스터에 적용합니다.

토폴로지 B — 디스크 경유(에어 갭)¶

연결된 호스트와 에어 갭 환경 사이에 네트워크 경로가 없으므로, oc-mirror를 실행하고 아카이브를 이동식 미디어로 옮깁니다.

연결된 호스트 — 디스크로 미러링

레지스트리 인증 후, 이미지를 로컬 디스크 아카이브로 내려받습니다(대상이 file://).
1 2
$ oc-mirror --v2 --config imageset-config.yaml --remove-signatures \ file://./archive
이동식 미디어 반입

생성된 ./archive 디렉터리를 imageset-config.yaml과 함께 USB·이동식 디스크 등 이동식 미디어에 담아 에어 갭 측 호스트로 옮깁니다.
에어 갭 측 — 내부 레지스트리로 import

반입한 아카이브를 내부 레지스트리로 push 합니다(원본이 --from file://).
1 2
$ oc-mirror --v2 --config imageset-config.yaml --from file://./archive \ docker://registry.internal:8443
산출물(IDMS/ITMS, CatalogSource)은 이 단계에서 에어 갭 측에 생성되며, 토폴로지 A와 동일하게 미러 레지스트리 구성에서 적용합니다.

미러 레지스트리 구성¶

미러링 후, 클러스터가 내부 레지스트리에 인증하고 그 인증서를 신뢰하며, 이미지 pull이 내부 레지스트리로 향하도록 구성합니다.

global pull secret 갱신

내부 레지스트리 자격증명을 클러스터 global pull secret에 추가합니다.

$ oc get secret/pull-secret -n openshift-config \
    --template='{{index .data ".dockerconfigjson" | base64decode}}' > pull-secret.json
$ oc registry login --registry="registry.internal:8443" \
    --auth-basic="<username>:<password>" --to=pull-secret.json
$ oc set data secret/pull-secret -n openshift-config \
    --from-file=.dockerconfigjson=pull-secret.json

레지스트리 CA 신뢰 구성

내부 레지스트리 CA를 클러스터 신뢰 번들에 추가합니다.

$ oc create configmap registry-ca -n openshift-config \
    --from-file=registry.internal..8443=rootCA.pem
$ oc patch image.config.openshift.io/cluster --type=merge \
    -p '{"spec":{"additionalTrustedCA":{"name":"registry-ca"}}}'

생성된 클러스터 리소스 적용

oc-mirror가 생성한 클러스터 리소스를 적용합니다: 이미지 pull을 내부 레지스트리로 리다이렉트하는 ImageDigestMirrorSet·ImageTagMirrorSet와, 미러된 카탈로그의 CatalogSource입니다. <WORKSPACE_DIR>는 토폴로지 A에서는 ./workspace, 토폴로지 B에서는 ./archive입니다.
1
$ oc apply -f <WORKSPACE_DIR>/working-dir/cluster-resources/
기본 OperatorHub 소스 비활성화

개요에서 설명한 대로 망분리 클러스터에서는 OLM이 기본 소스에 접근할 수 없습니다. 앞 단계에서 적용한 미러된 CatalogSource가 유일한 Operator 소스가 되도록 기본 소스를 비활성화합니다.
1 2
$ oc patch OperatorHub cluster --type json \ -p '[{"op":"add","path":"/spec/disableAllDefaultSources","value":true}]'

미러된 카탈로그 검증¶

Operator를 설치하기 전에, 미러된 CatalogSource가 정상 동작하는지 확인합니다.

$ oc get catalogsource -n openshift-marketplace
$ oc get pods -n openshift-marketplace
$ oc get packagemanifests -n openshift-marketplace | grep -e rbln-npu-operator -e nfd

카탈로그 Pod가 Running 상태이고 rbln-npu-operator·nfd의 PackageManifest가 조회되면 정상입니다. 웹 콘솔의 Operators > OperatorHub에서도 미러된 Operator가 표시됩니다.

설치 단계¶

미러링과 레지스트리 구성이 끝나면 이후 설치 단계는 연결 환경과 동일합니다. OpenShift용 RBLN NPU Operator 설치 가이드를 따라 진행하되, NFD Operator와 RBLN NPU Operator의 Subscription CR을 생성할 때 다음 사항만 추가로 반영하세요.

spec.source를 미러된 CatalogSource 이름으로 지정하세요(예: cs-certified-operator-index-v4-21, NFD는 cs-redhat-operator-index-v4-21). 실제 이름은 미러된 카탈로그 검증에서 확인하세요.
1 2 3
# rbln-npu-subscription.yaml — spec.source만 표준 가이드와 다릅니다 spec: source: cs-certified-operator-index-v4-21

설치 확인¶

표준 설치 가이드의 설치 확인 절차를 따릅니다. 망분리 환경에서는 추가로 rbln-system 네임스페이스의 Pod 중 ImagePullBackOff 상태가 없는지 확인하세요. 없다면 필요한 이미지가 모두 미러링되어 내부 레지스트리로 리다이렉트된 것입니다.

$ oc get pods -n rbln-system