콘텐츠로 이동

OpenShift에서 RBLN NPU를 위한 커널 파라미터 설정 (Supermicro AMD)

이 문서는 OpenShift 환경에서 RBLN NPU Operator를 사용할 때 필요한 커널 부트 파라미터를 설정하는 방법을 설명합니다.

이러한 파라미터는 디바이스의 안정적인 동작을 위해 필요하며, NPU 워크로드가 스케줄링되는 노드에 반드시 적용되어야 합니다. 설정은 OpenShift MachineConfig Operator(MCO)를 통해 수행됩니다.

이 설정이 적용되지 않으면, NPU가 정상적으로 동작하지 않을 수 있습니다.

대상 하드웨어

이 가이드는 다음 환경에서 검증되었습니다:

항목 값
벤더 Supermicro
CPU AMD
NPU RBLN-CA25
드라이버 RBLN Driver v3.0.0

커널 파라미터

다음 커널 파라미터는 NPU의 안정적이고 최적의 동작을 위해 필요합니다:

파라미터 설명
transparent_hugepage=madvise THP를 madvise 모드로 설정. 애플리케이션이 madvise(MADV_HUGEPAGE)로 명시적으로 요청한 영역에만 THP 적용
pcie_aspm=force PCIe Active State Power Management 강제 활성화
pci=pcie_bus_perf PCIe 버스 성능 최적화 모드 설정
pci=bfsort PCI 디바이스 BFS(Breadth-First Search) 정렬 활성화
iommu.strict=1 IOMMU strict 모드 활성화 (DMA unmap 시 즉시 IOTLB flush)

사전 요구사항

  • OpenShift Container Platform 4.x 클러스터
  • cluster-admin 권한
  • OpenShift CLI(oc) 설치 및 로그인 완료
  • (선택) Node Feature Discovery Operator v0.16+ — 자동 하드웨어 식별 사용 시 필요

하드웨어 식별

MachineConfig를 적용하기 전에 대상 노드가 Supermicro AMD 서버인지 확인합니다.

수동 확인

1
2
3
4
5
# 시스템 제조사 확인
oc debug node/<NODE_NAME> -- chroot /host dmidecode -s system-manufacturer

# CPU 모델 확인
oc debug node/<NODE_NAME> -- chroot /host bash -c "grep 'model name' /proc/cpuinfo | head -1"

기대 출력:

1
2
Supermicro
model name : AMD EPYC ...

(선택) NFD NodeFeatureRule을 활용한 자동 식별

NFD v0.16+에서는 system.dmiid.sys_vendor feature를 통해 노드의 DMI 벤더 정보를 읽을 수 있습니다. NodeFeatureRule을 작성하면 조건에 맞는 노드에 자동으로 커스텀 라벨을 부여할 수 있습니다.

Note

system.dmiid는 NFD 내장 feature이지만, 자동으로 라벨이 생성되지는 않습니다. 반드시 NodeFeatureRule을 작성해야 합니다.

참고 문서:

NodeFeatureRule 생성

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
apiVersion: nfd.k8s-sigs.io/v1alpha1
kind: NodeFeatureRule
metadata:
  name: smci-amd-detection
spec:
  rules:
    - name: "detect-supermicro"
      labels:
        hardware.io/vendor-supermicro: "true"
      matchFeatures:
        - feature: system.dmiid
          matchExpressions:
            sys_vendor: {op: In, value: ["Supermicro"]}
    - name: "detect-amd-cpu"
      labels:
        hardware.io/cpu-amd: "true"
      matchFeatures:
        - feature: cpu.model
          matchExpressions:
            vendor_id: {op: In, value: ["AMD"]}

1
oc apply -f <NFR_YAML_FILE>

라벨 확인

적용 후 대상 노드에서 아래 라벨이 자동 생성되는지 확인합니다:

1
oc get node <NODE_NAME> -o jsonpath='{.metadata.labels}' | python3 -m json.tool | grep hardware.io

기대 출력:

1
2
"hardware.io/vendor-supermicro": "true",
"hardware.io/cpu-amd": "true",

NFD 라벨을 MCP nodeSelector에 활용

NFD 라벨이 활성화되면 수동 node-role 라벨링 없이 MCP의 nodeSelector에서 직접 활용할 수 있습니다. 이 경우 커스텀 MachineConfigPool 생성의 MCP YAML에서 nodeSelector를 아래와 같이 변경합니다:

1
2
3
4
  nodeSelector:
    matchLabels:
      hardware.io/vendor-supermicro: "true"
      hardware.io/cpu-amd: "true"

이렇게 구성하면 Supermicro AMD 노드가 클러스터에 추가될 때 자동으로 MCP에 포함되어, 수동 라벨링 없이 커널 파라미터가 적용됩니다.

커널 파라미터 적용

Warning

MachineConfig의 machineconfiguration.openshift.io/role 라벨이 worker로 설정되면, 해당 설정은 기본 worker MCP에 적용됩니다.

1
2
3
이 경우 **클러스터 내 모든 worker 노드에 적용되며**, 노드 재부팅이 발생합니다.

적용 범위를 제한하려면, 특정 노드(예: Supermicro AMD 서버)만 선택하는 커스텀 MCP를 생성하고, MachineConfig의 role 라벨을 해당 MCP 이름으로 설정해야 합니다.

아래 절차에서 __MCP_NAME__을 대상 환경에 맞는 이름으로 변경하세요. (예: smci-ca25-amd)

사전 확인

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
# 노드 상태 확인
oc get nodes

# 대상 노드 라벨 확인
oc get node <NODE_NAME> --show-labels

# 기존 MCP 목록 확인
oc get mcp

# 현재 커널 파라미터 확인 (적용 전 baseline 기록)
oc debug node/<NODE_NAME> -- chroot /host cat /proc/cmdline

커스텀 MachineConfigPool 생성

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
apiVersion: machineconfiguration.openshift.io/v1
kind: MachineConfigPool
metadata:
  name: __MCP_NAME__
spec:
  machineConfigSelector:
    matchExpressions:
      - key: machineconfiguration.openshift.io/role
        operator: In
        values:
          - worker
          - __MCP_NAME__
  nodeSelector:
    matchLabels:
      node-role.kubernetes.io/__MCP_NAME__: ""

Note

NFD 자동 식별을 사용하는 경우 nodeSelector를 NFD 라벨을 MCP nodeSelector에 활용의 NFD 라벨로 대체하세요.

1
2
3
4
5
# MCP 생성
oc apply -f <MCP_YAML_FILE>

# 대상 노드에 role 라벨 부여 (NFD 자동 식별 사용 시 생략)
oc label node <NODE_NAME> node-role.kubernetes.io/__MCP_NAME__=""

MCP 상태 확인:

1
2
oc get mcp __MCP_NAME__
# UPDATED=True, DEGRADED=False 확인

MachineConfig 적용

MachineConfig 이름 규칙 (99- prefix)

MCO는 MachineConfig를 이름의 사전순으로 정렬한 뒤 순차적으로 병합하여 최종 rendered config를 생성합니다. 숫자 prefix는 적용 우선순위를 결정합니다:

Prefix 용도
00- OpenShift 기본 설정 (예: 00-worker)
01- 기본 런타임/kubelet 설정
50- 운영 커스텀 설정
99- 사용자 커스텀 설정 (최후에 병합, 기존 설정 override)

99- prefix를 사용하면 기존 OpenShift 기본 MC보다 나중에 병합되어, 커널 파라미터가 최종 config에 확실히 반영됩니다.

멱등성

MCO는 MachineConfig 적용 시 선언적(declarative) 방식으로 동작합니다. 동일한 MC를 다시 oc apply하거나, 이미 적용된 커널 파라미터와 동일한 MC가 존재하는 경우:

  • MCO가 현재 rendered config와 새 rendered config를 비교합니다.
  • 변경이 없으면 노드 재부팅이 발생하지 않습니다.
  • MCP 상태는 UPDATED=True를 유지합니다.

즉, 이미 동일한 커널 파라미터가 적용된 상태에서 같은 MC를 다시 apply해도 불필요한 재부팅 없이 안전하게 무시됩니다.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
apiVersion: machineconfiguration.openshift.io/v1
kind: MachineConfig
metadata:
  name: 99-grub-kargs-amd-smci-ca25
  labels:
    machineconfiguration.openshift.io/role: __MCP_NAME__
spec:
  kernelArguments:
    - transparent_hugepage=madvise
    - pcie_aspm=force
    - pci=pcie_bus_perf
    - pci=bfsort
    - iommu.strict=1

1
oc apply -f <MC_YAML_FILE>

롤아웃 모니터링

MachineConfig 적용 후 MCO가 대상 노드를 자동으로 cordon → drain → reboot 합니다.

1
2
3
4
5
6
7
8
# MCP 상태 감시 (UPDATING=True → False 될 때까지 대기)
watch oc get mcp __MCP_NAME__

# 노드 상태 감시 (SchedulingDisabled → Ready)
watch oc get nodes

# 렌더링된 MC 확인
oc get mc | grep rendered-__MCP_NAME__

검증

커널 파라미터 확인

1
oc debug node/<NODE_NAME> -- chroot /host cat /proc/cmdline

아래 파라미터가 cmdline 출력에 포함되어 있는지 확인합니다:

  • transparent_hugepage=madvise
  • pcie_aspm=force
  • pci=pcie_bus_perf
  • pci=bfsort
  • iommu.strict=1

THP 상태 확인

1
oc debug node/<NODE_NAME> -- chroot /host cat /sys/kernel/mm/transparent_hugepage/enabled

기대 출력:

1
always [madvise] never

MCP 최종 상태 확인

1
oc get mcp __MCP_NAME__
필드 기대값
UPDATED True
UPDATING False
DEGRADED False

롤백

문제 발생 시 MachineConfig를 삭제하면 원래 커널 파라미터로 복원됩니다.

Warning

아래 삭제 순서를 반드시 준수하세요. 순서를 지키지 않으면 노드가 Degraded 상태에 빠질 수 있습니다. (복구 방법: Degraded 복구)

롤백 절차

삭제 순서:

1
MC 삭제 → 재부팅 완료 대기 → 노드 라벨 제거 → MCP 삭제

Step 1. MachineConfig 삭제

1
oc delete mc 99-grub-kargs-amd-smci-ca25

Step 2. 롤아웃 완료 대기

MCO가 kargs 없는 config를 re-render하고 노드를 재부팅합니다. 반드시 완료될 때까지 대기합니다.

1
2
watch oc get mcp __MCP_NAME__
# UPDATED=True, UPDATING=False, DEGRADED=False 확인

Step 3. 커널 파라미터 제거 확인

이전에 추가한 커널 파라미터가 없는지 확인합니다:

1
oc debug node/<NODE_NAME> -- chroot /host cat /proc/cmdline

정리

커널 파라미터 제거 확인 후 MCP와 라벨을 정리합니다.

Step 4. 노드 라벨 제거

1
oc label node <NODE_NAME> node-role.kubernetes.io/__MCP_NAME__-

Step 5. MCP 삭제

1
oc delete mcp __MCP_NAME__

트러블슈팅

Degraded 복구

증상: MCP 또는 노드 라벨을 MC보다 먼저 삭제한 경우, 노드의 currentConfig annotation이 이미 삭제된 rendered MachineConfig를 참조하여 Degraded 상태에 빠집니다.

1
Node <NODE_NAME> is reporting: "missing MachineConfig rendered-<MCP>-xxxxx"

원인: MCO는 MC를 삭제할 때 해당 MCP에 소속된 노드에 대해서만 re-render를 수행합니다. 노드가 MCP에서 이탈한 상태에서 MC를 삭제하면 MCO가 처리할 대상 노드가 없어 커널 파라미터가 그대로 남게 됩니다.

복구 절차:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
# 1. MCP 재생성
oc apply -f <MCP_YAML_FILE>

# 2. 노드에 라벨 다시 부여
oc label node <NODE_NAME> node-role.kubernetes.io/__MCP_NAME__=""

# 3. 새 rendered config 이름 확인
oc get mcp __MCP_NAME__ -o jsonpath='{.spec.configuration.name}'

# 4. 노드의 currentConfig annotation을 새 rendered config로 강제 업데이트
oc annotate node <NODE_NAME> \
  machineconfiguration.openshift.io/currentConfig=<NEW_RENDERED_CONFIG> \
  machineconfiguration.openshift.io/desiredConfig=<NEW_RENDERED_CONFIG> \
  --overwrite

# 5. MCD pod 재시작 (stale state 초기화)
MCD_POD=$(oc get pods -n openshift-machine-config-operator -o wide \
  | grep <NODE_NAME> | grep machine-config-daemon | awk '{print $1}')
oc delete pod $MCD_POD -n openshift-machine-config-operator

# 6. MCP 정상화 확인
watch oc get mcp __MCP_NAME__
# UPDATED=True, DEGRADED=False 확인

# 7. 정상화 후 올바른 순서대로 정리 (롤백 절차 → 정리)