AWS re:Post Knowledge Center Feedback Survey

Help us improve the AWS re:Post Knowledge Center by sharing your feedback in a brief survey. Your input can influence how we create and update our content to better support your AWS journey.

Amazon EKS에서 NVIDIA Device Plugin 설치 시 발생하는 NVML 라이브러리 로딩 오류 대응 방법

5분 분량

콘텐츠 수준: 중급

본 기사에서는 올바른 AMI를 선택하여 EKS GPU 노드를 구성하는 방법과 발생 가능한 문제의 트러블슈팅 방법을 다룹니다.

Overview

Amazon EKS 클러스터에서 GPU 노드를 사용할 때 NVIDIA Device Plugin 설치 시 아래와 같은 에러가 발생하는 경우가 있습니다.

main.go:279] Retrieving plugins.
factory.go:31] No valid resources detected, creating a null CDI handler
factory.go:104] Detected non-NVML platform: could not load NVML library: libnvidia-ml.so.1: cannot open shared object file: No such file or directory
factory.go:104] Detected non-Tegra platform: /sys/devices/soc0/family file not found
factory.go:112] Incompatible platform detected
factory.go:113] If this is a GPU node, did you configure the NVIDIA Container Toolkit?
factory.go:114] You can check the prerequisites at: https://github.com/NVIDIA/k8s-device-plugin#prerequisites
factory.go:115] You can learn how to set the runtime at: https://github.com/NVIDIA/k8s-device-plugin#quick-start
factory.go:116] If this is not a GPU node, you should set up a toleration or nodeSelector to only deploy this plugin on GPU nodes
main.go:132] error starting plugins: error creating plugin manager: unable to create plugin manager: platform detection failed

이 문서에서는 올바른 AMI를 선택하여 EKS GPU 노드를 구성하는 방법과 발생 가능한 문제의 트러블슈팅 방법을 다룹니다.

Resolution

1. 현재 사용 중인 AMI 확인

먼저 현재 사용 중인 AMI가 EKS GPU 노드용으로 적합한지 확인합니다. 아래 명령어로 AMI 정보를 확인하세요.

aws ec2 describe-images \
  --image-ids {ami-id} \
  --region {region-code} \
  --query 'Images[0].[Name,Description]' \
  --output text

예시 출력:

Deep Learning OSS Nvidia Driver AMI GPU PyTorch 2.8 (Amazon Linux 2023) 20251103 
Supported EC2 instances: G4dn, G5, G6, Gr6, G6e, P4, P4de, P5, P5e, P5en, P6-B200.

해당 AMI는 EKS 노드용이 아닙니다. Deep Learning AMI는 ML 워크로드를 위한 독립 실행형 EC2 인스턴스용으로 설계되었으며, EKS 클러스터 통합에 필요한 kubelet, containerd 설정 등이 포함되어 있지 않습니다.

2. Amazon EKS 최적화 가속 AMI 사용

EKS GPU 노드에는 Amazon EKS 최적화 가속 Amazon Linux AMI를 사용해야 합니다. 이 AMI에는 다음이 사전 설치되어 있습니다: [1]

NVIDIA 드라이버
NVIDIA Container Toolkit
AWS Neuron 드라이버 (Inferentia/Trainium 인스턴스용)

권장 AMI ID를 얻는 방법:

aws ssm get-parameter \
  --name /aws/service/eks/optimized-ami/{cluster-version}/{os-version}/{cpu-architecture}/nvidia/recommended/image_id \
  --region {region-code} \
  --query "Parameter.Value" \
  --output text

파라미터 설명:

cluster-version: EKS 클러스터 버전 (예: 1.33)
os-version: 운영체제 버전 (amazon-linux-2 또는 amazon-linux-2023)
cpu-architecture: CPU 아키텍처 (x86_64 또는 arm64)
region-code: AWS 리전 (예: us-east-1)

예시:

aws ssm get-parameter \
  --name /aws/service/eks/optimized-ami/1.33/amazon-linux-2023/x86_64/nvidia/recommended/image_id \
  --region us-east-1 \
  --query "Parameter.Value" \
  --output text

출력 예시: ami-0efa341496d305795

AMI 확인:

aws ec2 describe-images \
  --image-ids ami-0efa341496d305795 \
  --region us-east-1 \
  --query 'Images[0].[Name,Description]' \
  --output text

출력:

amazon-eks-node-al2023-x86_64-nvidia-1.33-v20251120
EKS-optimized Kubernetes node based on Amazon Linux 2023, (k8s: 1.33.5, containerd: 2.1.*)

AMI 릴리스 정보는 GitHub에서 확인할 수 있습니다: [2]

3. NVIDIA Device Plugin 배포

올바른 AMI로 GPU 노드를 클러스터에 조인한 후, NVIDIA Device Plugin을 DaemonSet으로 배포합니다. [3]

kubectl apply -f https://raw.githubusercontent.com/NVIDIA/k8s-device-plugin/vX.X.X/deployments/static/nvidia-device-plugin.yml

GPU 할당 가능 여부 확인:

kubectl get nodes "-o=custom-columns=NAME:.metadata.name,GPU:.status.allocatable.nvidia\.com/gpu"

4. GPU 동작 테스트

테스트 Pod 생성 (nvidia-smi.yaml):

apiVersion: v1
kind: Pod
metadata:
  name: nvidia-smi
spec:
  restartPolicy: OnFailure
  containers:
  - name: nvidia-smi
    image: nvidia/cuda:tag
    args:
    - "nvidia-smi"
    resources:
      limits:
        nvidia.com/gpu: 1

배포 및 로그 확인:

kubectl apply -f nvidia-smi.yaml
kubectl logs nvidia-smi

정상 출력 예시:

|-------------------------------+----------------------+----------------------+
| GPU  Name        Persistence-M| Bus-Id        Disp.A | Volatile Uncorr. ECC |
| Fan  Temp  Perf  Pwr:Usage/Cap|         Memory-Usage | GPU-Util  Compute M. |
|===============================+======================+======================|
|   0  Tesla V100-SXM2...  On   | 00000000:00:1C.0 Off |                    0 |
| N/A   46C    P0    47W / 300W |      0MiB / 16160MiB |      0%      Default |
+-------------------------------+----------------------+----------------------+
+-----------------------------------------------------------------------------+
| Processes:                                                       GPU Memory |
|  GPU       PID   Type   Process name                             Usage      |
|=============================================================================|
|  No running processes found                                                 |
+-----------------------------------------------------------------------------+

Further Troubleshooting

문제: Amazon EKS 최적화 가속 AMI를 사용했는데도 NVML 오류가 발생합니다.

원인: userdata 스크립트로 인해 containerd 설정이 재정의되어 기본 런타임이 nvidia에서 runc로 변경되었을 수 있습니다.

해결 방법:

노드에 접속하여 현재 런타임을 확인:
```
cat /etc/containerd/config.toml | grep default_runtime_name
```
출력이 "runc"인 경우 다음 단계를 진행합니다.
UserData 확인

/etc/eks/bootstrap.sh (AL2) 나 nodeadm init (AL2023) 이 UserData를 통해 중복으로 호출되는 경우, 해당 설정으로 인해 containerd 구성이 재정의되었을 가능성이 있습니다.

이 경우 해당 라인을 제거하거나, Userdata 에 NVIDIA 런타임으로 재설정하는 라인을 추가합니다: [4]
```
/usr/bin/nvidia-ctk runtime configure --runtime=containerd --set-as-default
```
새로운 UserData 를 사용해 노드를 생성
새 노드에 접속하여 설정 변경 확인:
```
cat /etc/containerd/config.toml | grep default_runtime_name
```
출력이 "nvidia" 라면 정상적으로 설정된 것입니다.