콘텐츠로 이동

컨테이너 지원

이미 컨테이너 런타임이 동작하는 Linux 호스트에서 LPU를 사용하려면 다음 세 부분을 준비합니다.

위치 추가하거나 바꿀 것
LPU 호스트 hyperaccel-lpu 패키지로 드라이버와 컨테이너 툴킷(ha-ctk) 준비
기존 런타임 CDI를 활성화하고 /etc/cdi의 스펙을 읽도록 설정
컨테이너 실행 사용할 LPU를 CDI 이름으로 요청

CDI(Container Device Interface)는 LPU의 장치 파일과 사용자 모드 드라이버 라이브러리를 컨테이너에 전달하는 데 사용합니다. ha-ctk가 이 정보를 /etc/cdi/lpu.yaml에 기록하므로, 실행할 때는 장치 경로를 하나씩 나열하지 않고 LPU 이름을 지정합니다.

호스트 준비

빠른 설치에 따라 LPU 호스트에 hyperaccel-lpu를 설치합니다. 이미 설치되어 있다면 카드 검색과 CDI 스펙부터 확인합니다. 원격 Docker를 쓰는 경우에도 이 작업은 데몬 호스트에서 합니다.

1
2
3
ha-ctk precheck     # 드라이버, 장치 파일, 스펙, 런타임 설정을 점검하고 빠진 것을 알려 줍니다
ha-ctk cdi list     # 호스트에서 발견한 카드 목록
ha-ctk cdi validate # 저장된 스펙을 읽어 CDI 이름이 해석되는지 확인

스펙이 없거나 카드 구성이 바뀌었으면 sudo ha-ctk cdi generate로 다시 만듭니다. cdi list는 호스트의 카드 목록이고, cdi validate는 저장된 스펙의 이름 해석을 확인합니다. 컨테이너에 실제로 연결됐는지는 아래 SDK 실행으로 확인합니다.

Docker 설정과 실행

기존 Docker에서 필요한 변경은 CDI 활성화와 스펙 검색 경로 설정입니다. Linux Docker Engine 25 이상에서 CDI를 사용할 수 있고, 28.3.0부터는 기본 활성화됩니다. 이미 CDI가 켜져 있고 /etc/cdi를 읽고 있다면 설정 변경과 재시작을 생략합니다.

CDI 설정이 필요한 경우 기존 /etc/docker/daemon.json을 보관한 뒤 다음을 실행합니다.

1
2
3
4
sudo ha-ctk runtime configure --runtime docker --dry-run
sudo ha-ctk runtime configure --runtime docker
sudo dockerd --validate --config-file /etc/docker/daemon.json
sudo systemctl restart docker

ha-ctk가 바꾸는 항목은 features.cdi=true와 cdi-spec-dirs=["/etc/cdi","/var/run/cdi"]입니다. --dry-run은 변경 내용을 출력만 합니다. 실제 설정 후에도 툴킷이 Docker를 재시작하지는 않으므로 직접 적용해야 합니다. 재시작은 실행 중인 컨테이너에 영향을 줄 수 있어 유지보수 시간에 진행합니다.

이후 기존 docker run 명령에 --device hyperaccel.ai/lpu=0을 추가하면 LPU 한 장을 요청할 수 있습니다. SDK 이미지에서 연결을 확인하는 예제입니다.

1
2
3
docker run --rm --device hyperaccel.ai/lpu=0 \
  public.hyperaccel.net/hyperaccel-public/hyperaccel-sdk:v0.0.6 \
  python3 -c "import hart; print(hart.get_device_count())"

카드 수 1이 출력되고 종료 코드가 0이면 연결 확인이 끝납니다. 호스트에 Python SDK를 별도로 설치할 필요는 없습니다.

카드 선택

--device에 지정하는 이름으로 사용할 카드를 바꿉니다.

CDI 이름 요청 대상
hyperaccel.ai/lpu=0 0번 카드
hyperaccel.ai/lpu=0000_35_00.0 해당 PCI 주소의 카드
hyperaccel.ai/lpu=all 모든 카드

번호는 부팅할 때 드라이버가 카드를 찾은 순서라, 카드를 바꾸거나 고장 난 카드가 빠지면 달라질 수 있습니다. 같은 카드를 지정해야 하면 lspci -d 20fb:로 확인한 PCI 주소에서 콜론(:)을 밑줄(_)로 바꿔 사용합니다. =all로 확인할 때는 컨테이너의 카드 수가 호스트에서 확인한 사용 가능한 전체 카드 수와 같아야 합니다.

containerd 설정과 실행

단독 실행: nerdctl

CDI를 지원하는 nerdctl이 이미 준비되어 있다면 Docker와 마찬가지로 --device를 추가합니다. nerdctl은 CDI 스펙을 직접 읽으므로, 이 경로에는 containerd의 CRI 설정 변경이나 재시작이 필요하지 않습니다.

1
2
3
sudo nerdctl run --rm --net=none --device hyperaccel.ai/lpu=0 \
  public.hyperaccel.net/hyperaccel-public/hyperaccel-sdk:v0.0.6 \
  python3 -c "import hart; print(hart.get_device_count())"

Docker 예제와 같이 1이 출력되고 종료 코드가 0인지 확인합니다.

오케스트레이터용 CRI 설정

containerd 1.7의 CRI에서 CDI가 꺼져 있다면 다음을 적용합니다. 기존 설정 파일의 version = 2 구성을 전제로 합니다. ha-ctk는 기존 /etc/containerd/config.toml의 [plugins."io.containerd.grpc.v1.cri"]에 enable_cdi=true와 스펙 검색 경로를 설정합니다.

1
2
3
sudo ha-ctk runtime configure --runtime containerd --dry-run
sudo ha-ctk runtime configure --runtime containerd
sudo systemctl restart containerd

기본 경로가 아니면 --config를 실제 설정 파일에 맞추고, 재시작은 노드 유지보수 시간에 진행합니다. containerd 2.x는 CDI가 기본 활성화되고 플러그인 키가 다르므로 위 1.x용 설정 명령을 그대로 적용하지 않습니다.

CRI를 통한 LPU 연결은 쿠버네티스의 Pod 예제로 확인합니다.

CRI-O 설정과 사용

기존 CRI-O가 /etc/cdi의 스펙을 읽고 있다면 추가 설정은 필요하지 않습니다. 검색 경로를 추가해야 할 때는 다음을 적용합니다. ha-ctk는 /etc/crio/crio.conf.d/99-ha-cdi.conf에 cdi_spec_dirs를 기록합니다.

1
2
3
sudo ha-ctk runtime configure --runtime crio --dry-run
sudo ha-ctk runtime configure --runtime crio
sudo systemctl restart crio

설정 파일을 보관한 뒤 노드 유지보수 시간에 적용합니다. CRI-O는 Docker처럼 직접 실행하는 CLI가 아니라 CRI 서버이므로, LPU 요청과 확인은 쿠버네티스의 Pod 예제를 사용합니다.

ha-ctk 명령

명령 하는 일
ha-ctk precheck 호스트 점검. 설치는 하지 않고 무엇이 빠졌는지만 알려 줍니다
ha-ctk cdi generate CDI 스펙을 다시 만듭니다
ha-ctk cdi list 호스트에서 발견한 카드 정보를 보여 줍니다
ha-ctk cdi validate 저장된 스펙을 파싱하고 CDI 이름을 해석합니다. 하드웨어 실행 검사는 아닙니다
ha-ctk cdi remove 스펙을 지웁니다
ha-ctk runtime configure 런타임 설정 파일을 씁니다. 서비스는 재시작하지 않습니다
ha-ctk daemon 쿠버네티스 노드에서 상주하며 스펙을 다시 씁니다. 오퍼레이터가 띄웁니다

문제 해결

컨테이너 안에 /dev/ha*가 없거나 unresolvable CDI devices hyperaccel.ai/lpu=0이 나오면 아래 순서로 봅니다.

1
2
3
4
ls /dev/ha*                    # 1. 호스트에 장치 파일이 있는가
ha-ctk precheck                # 2. 점검이 통과하는가
ha-ctk cdi list                # 3. 호스트에서 카드가 검색되는가
ha-ctk cdi validate            # 4. 저장된 스펙에서 요청 이름이 해석되는가

1번에서 막히면 툴킷이 아니라 드라이버 문제입니다. 빠른 설치의 표를 확인하세요. 스펙이 없거나 카드 구성이 바뀌었으면 sudo ha-ctk cdi generate 후 다시 확인합니다. 그다음 위에서 선택한 경로의 설정·클라이언트 버전·스펙 검색 경로를 확인하고 SDK 검증을 다시 실행합니다.