콘텐츠로 이동

쿠버네티스 지원

기존 쿠버네티스 클러스터에서 LPU를 사용하려면 노드에 드라이버와 툴킷을 준비하고, 클러스터에 ha-lpu-operator를 추가한 뒤 워크로드에서 LPU 수를 요청합니다.

위치 추가하거나 바꿀 것
LPU 노드 hyperaccel-lpu 설치와 런타임의 CDI 설정
클러스터 ha-lpu-operator Helm 차트
기존 Pod·Deployment 컨테이너의 resources.limits에 hyperaccel.ai/lpu 추가

노드와 클러스터 준비

Kubernetes 1.31 이상인 클러스터에서, LPU가 꽂힌 노드마다 다음을 확인합니다.

  • hyperaccel-lpu가 설치되어 드라이버와 툴킷을 사용할 수 있는가
  • 기존 containerd·CRI-O가 CDI 스펙을 읽도록 설정되어 있는가 — 컨테이너 지원 참고

Webhook 인증서를 cert-manager로 관리할 경우 클러스터에 cert-manager가 준비되어 있어야 합니다. 인증서를 직접 제공하는 경우는 아래 설정을 사용합니다.

클러스터에 Operator 추가

ha-lpu-operator가 아직 없는 클러스터에 설치합니다.

차트와 구성요소 이미지는 하이퍼엑셀이 발급한 계정으로 로그인해 받습니다. 먼저 Helm을 로그인하고, 구성요소 이미지를 받을 Secret을 만듭니다. 차트는 이 Secret을 harbor-secret이라는 이름으로 찾습니다.

1
2
3
4
helm registry login public.hyperaccel.net
kubectl create namespace bertha-system
kubectl -n bertha-system create secret docker-registry harbor-secret \
  --docker-server=public.hyperaccel.net --docker-username=<아이디> --docker-password=<비밀번호>
1
2
helm install ha-lpu-operator oci://public.hyperaccel.net/hyperaccel-public/charts/ha-lpu-operator \
  --version 0.1.8 --namespace bertha-system --create-namespace

차트는 오퍼레이터와 기본 BerthaCluster를 만들고, 오퍼레이터가 device-plugin 등 LPU 구성요소를 관리합니다. NFD(node-feature-discovery)는 차트에 포함되어 있습니다. 이미 설치했다면 다시 설치하지 않고 상태부터 확인합니다.

1
2
3
kubectl get berthacluster -n bertha-system
kubectl get nodes -L hyperaccel.ai/lpu.count,hyperaccel.ai/lpu-max-contiguous
kubectl describe node <node_name> | grep hyperaccel.ai/lpu

BerthaCluster가 Ready이고 노드에 hyperaccel.ai/lpu 리소스가 보이면 Pod에서 요청할 수 있습니다. validator는 노드의 드라이버와 장치 파일을 확인한 뒤 device-plugin과 feature-discovery가 동작하도록 합니다.

기존 인증서 설정 사용

기본 구성을 바꿀 때는 Helm values의 berthaCluster.spec 아래를 수정합니다. Webhook 인증서는 다음 설정 중 환경에 맞는 경로를 사용합니다.

설정 인증서
webhook.tlsSecretName 직접 만든 Secret
webhook.certManager.issuerRef 지정한 cert-manager Issuer
둘 다 없음 (기본) 오퍼레이터가 자체 서명 ClusterIssuer를 만듭니다

Pod에서 카드 쓰기

기존 Pod의 spec.containers[] 또는 Deployment의 spec.template.spec.containers[]에서 resources.limits에 hyperaccel.ai/lpu를 추가합니다. 기존 CPU·메모리 설정은 유지합니다.

1
2
3
resources:
  limits:
    hyperaccel.ai/lpu: 1

SDK 이미지로 카드 한 장의 연결만 확인하려면 다음 Pod를 사용합니다. Pod를 만드는 네임스페이스에도 harbor-secret이 있어야 합니다.

lpu-test.yaml
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
apiVersion: v1
kind: Pod
metadata:
  name: lpu-test
spec:
  containers:
    - name: sdk
      image: public.hyperaccel.net/hyperaccel-public/hyperaccel-sdk:v0.0.6
      command: ["python3", "-c", "import hart; print(hart.get_device_count())"]
      resources:
        limits:
          hyperaccel.ai/lpu: 1
  imagePullSecrets:
    - name: harbor-secret
  restartPolicy: Never
1
2
3
kubectl apply -f lpu-test.yaml
kubectl wait --for=jsonpath='{.status.phase}'=Succeeded pod/lpu-test --timeout=180s
kubectl logs lpu-test      # 1

Pod가 완료되고 카드 수 1이 출력되면 연결 확인이 끝납니다.

vLLM 서빙

기존 Deployment에서 vLLM 컨테이너의 이미지·실행 옵션·LPU 요청을 변경합니다. 아래는 spec.template.spec.containers[]에서 바꿀 부분만 보여 주는 예제입니다. 이미지를 받으려면 spec.template.spec.imagePullSecrets에 harbor-secret을 넣고, 그 네임스페이스에도 위와 같은 Secret을 만듭니다.

1
2
3
4
5
image: public.hyperaccel.net/hyperaccel-public/vllm-hyperaccel:0.0.6
args: ["vllm", "serve", "Qwen/Qwen3-8B", "--max-model-len", "2048", "--no-enable-prefix-caching", "--no-async-scheduling"]
resources:
  limits:
    hyperaccel.ai/lpu: 1

모델과 컨텍스트 길이는 기존 워크로드에 맞춥니다. LPU 두 장에 나눠 올리려면 hyperaccel.ai/lpu: 2와 --pipeline-parallel-size 2를 함께 지정합니다. 서빙 옵션은 vLLM 설정 가이드를 참고하면 됩니다.

기존 운영 설정에서는 다음만 함께 확인합니다.

기존 설정 LPU 사용 시 확인할 것
모델 캐시 기존 볼륨을 사용합니다. PVC를 참조하면 같은 네임스페이스에 준비되어 있어야 하며, 다른 노드에서도 쓸 수 있는지는 스토리지 제약을 확인합니다
시작·준비 검사 모델 내려받기와 커널 준비 시간을 startupProbe에 반영합니다. 시작 검사 실패는 재시작을 유발할 수 있고, readinessProbe 실패는 트래픽에서 제외할 뿐 그 자체로 재시작하지 않습니다
업데이트 전략 기존 Pod가 LPU를 모두 점유하면 새 Pod가 자원을 기다릴 수 있습니다. 중단 없는 교체에는 새 Pod용 LPU와 스토리지 여유가 필요합니다

여유 LPU 없이 기존 Pod를 먼저 내리고 교체하려면 Deployment의 spec 아래에 다음을 설정합니다. 이 경우 새 모델이 준비될 때까지 서비스가 중단됩니다.

1
2
strategy:
  type: Recreate

노드 라벨

feature-discovery가 붙이는 라벨입니다. nodeSelector나 affinity에 그대로 씁니다.

라벨 예 뜻
hyperaccel.ai/lpu.present true 카드가 있는 노드
hyperaccel.ai/lpu.count 8 카드 수
hyperaccel.ai/lpu-max-contiguous 2 한 PCIe 스위치 아래 카드 수의 최댓값

카드를 2장 이상 요청한 Pod에는 웹훅이 "lpu-max-contiguous가 요청 수 이상인 노드를 선호"하는 조건을 더합니다. 같은 스위치 아래 카드끼리 묶이면 카드 사이 통신이 그 스위치 안에서 끝납니다. 선호 조건이라 맞는 노드가 없어도 Pod는 뜹니다.

메트릭

기존 Prometheus Operator에 ha-lpu-exporter를 수집 대상으로 추가합니다. exporter는 bertha-system의 Pod에서 이름이 metrics인 포트(9401)로 /metrics를 제공합니다.

아래 PodMonitor의 metadata.namespace와 metadata.labels는 기존 Prometheus의 podMonitorNamespaceSelector·podMonitorSelector에 맞춥니다. 예제의 monitoring과 release: kube-prometheus-stack은 해당 선택 조건을 사용하는 환경의 값입니다. spec.namespaceSelector는 exporter가 있는 bertha-system을 가리킵니다. BerthaCluster 이름을 바꿨다면 app.kubernetes.io/instance도 실제 값으로 바꿉니다.

ha-lpu-exporter-podmonitor.yaml
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
apiVersion: monitoring.coreos.com/v1
kind: PodMonitor
metadata:
  name: ha-lpu-exporter
  namespace: monitoring
  labels:
    release: kube-prometheus-stack
spec:
  namespaceSelector:
    matchNames:
      - bertha-system
  selector:
    matchLabels:
      app.kubernetes.io/name: exporter
      app.kubernetes.io/instance: ha-lpu-operator
  podMetricsEndpoints:
    - port: metrics
      path: /metrics
      interval: 15s
1
kubectl apply -f ha-lpu-exporter-podmonitor.yaml

기존 수집 대상의 선택 조건을 덮어쓰지 않고 이 PodMonitor가 선택되도록 추가합니다. Prometheus의 Targets 에서 exporter가 UP인지 확인한 뒤 lpu_device_up을 조회합니다. UP은 수집 성공 여부이고 lpu_device_up은 카드 응답 여부입니다.

지표 뜻
lpu_device_up 카드가 응답하는가
lpu_device_wedged 카드가 멈춘 상태인가
lpu_fw_errors_total 펌웨어 오류 수
lpu_temperature_celsius 온도
lpu_power_watts 전력
lpu_dram_used_bytes 카드 메모리 사용량
lpu_pcie_link_degraded PCIe 링크가 최대 속도보다 낮게 붙었는가
lpu_pod_lpu_count Pod별 배정 카드 수

문제 해결

증상 확인
Pod가 Pending kubectl describe pod의 이벤트. 노드에 hyperaccel.ai/lpu가 없으면 kubectl get berthacluster -n bertha-system과 validator 로그
BerthaCluster가 Ready가 아님 kubectl get pods -n bertha-system. validator가 실패하면 그 노드의 드라이버부터
컨테이너 안에 /dev/ha*가 없음 노드에서 ha-ctk precheck. 런타임의 CDI 설정
할당 가능 수가 카드 수보다 적음 device-plugin이 고장 난 카드를 신규 배정에서 제외했는지 확인. 지표 lpu_device_up, lpu_device_wedged
Prometheus에 exporter가 안 보임 PodMonitor 네임스페이스·라벨 선택 조건과 Pod 조회 권한. 대상이 DOWN이면 metrics 포트·경로와 네트워크 확인