liminfoSingularity Reference
Singularity/Apptainer HPC 컨테이너 정의파일/명령어 레퍼런스
Singularity Reference 소개
Singularity/Apptainer 레퍼런스는 HPC 환경에서 Apptainer(구 Singularity) 컨테이너를 사용하는 연구자와 시스템 관리자를 위한 실용적인 명령어 참고 자료입니다. SIF(Singularity Image Format) 단일 파일 읽기 전용 컨테이너 형식, Docker 이미지 변환, 핵심 명령어(Docker Hub나 .def 파일로 이미지를 생성하는 apptainer build, 컨테이너 내 명령 실행을 위한 apptainer exec, 대화형 세션용 apptainer shell, runscript 실행을 위한 apptainer run, Docker Hub/NGC/OCI 레지스트리에서 이미지를 다운로드하는 apptainer pull)를 다룹니다.
정의 파일(.def) 섹션에서는 빌드 레시피를 완전히 문서화합니다. Bootstrap 소스 선택(docker, library, localimage, debootstrap, yum, oras, scratch), 빌드 중 패키지 설치 및 컴파일을 위한 %post 섹션, 런타임 PATH와 LD_LIBRARY_PATH 설정을 위한 %environment, 호스트 파일을 컨테이너로 복사하는 %files, 기본 실행 동작을 위한 %runscript, 자동 빌드 검증을 위한 %test, 메타데이터를 위한 %labels를 다룹니다. 디렉토리 매핑을 위한 --bind, 고급 마운트 구문을 위한 --mount, 읽기 전용 SIF에 쓰기 레이어를 추가하는 --overlay, 홈 디렉토리 격리를 위한 --no-home 등 바인드 마운트와 오버레이 파일시스템 옵션도 수록되어 있습니다.
HPC 전용 기능이 광범위하게 다루어집니다. --nv(NVIDIA CUDA 라이브러리 자동 바인딩)와 --rocm(AMD ROCm)을 통한 GPU 패스스루, Bind 모델(호스트 MPI가 컨테이너를 실행)과 Hybrid 모델(컨테이너 내부 MPI, PMI2/PMIx 지원)의 MPI 지원, srun과 환경변수(APPTAINER_BIND, APPTAINER_NV)를 활용한 SLURM 스케줄러 연동, 데몬용 백그라운드 인스턴스 관리, 원격 레지스트리 운영(Sylabs Cloud/OCI 레지스트리 push/pull), PGP 기반 이미지 서명 및 검증, 보안 옵션(seccomp, AppArmor 프로필), 사용자 네임스페이스를 활용한 비root 컨테이너 빌드용 fakeroot를 포함합니다.
주요 기능
- 핵심 명령어: apptainer build(Docker/def/sandbox에서), exec, shell, run, pull과 --fakeroot, --force 옵션
- 정의 파일 섹션: Bootstrap 소스, %post 설치, %environment 변수, %files 복사, %runscript, %test 검증
- 바인드 마운트와 오버레이: --bind 디렉토리 매핑, --mount 고급 구문, --overlay 쓰기 레이어, --no-home 격리
- GPU 패스스루: NVIDIA CUDA 자동 바인딩을 위한 --nv, AMD ROCm을 위한 --rocm, 호스트 드라이버 호환성 참고
- MPI 병렬 실행: Bind 모델(mpirun + apptainer exec)과 PMI2/PMIx 지원 Hybrid 모델
- SLURM 연동: srun과 apptainer exec, SBATCH 지시문, APPTAINER_* 환경변수 설정
- 보안: 비root 빌드를 위한 --fakeroot, PGP 이미지 서명/검증, seccomp 및 AppArmor 프로필
- 인스턴스 관리, 원격 레지스트리 push/pull, Docker 변환, apptainer inspect, 캐시 설정
자주 묻는 질문
Singularity와 Apptainer의 차이점은 무엇인가요?
Apptainer는 이전에 Singularity로 알려진 프로젝트의 현재 이름입니다. 2021년 Linux Foundation으로 이관되면서 Apptainer로 개명되었습니다. 명령줄 도구는 singularity에서 apptainer로, 환경변수는 SINGULARITY_*에서 APPTAINER_*로 변경되었습니다. 핵심 기능과 SIF 이미지 형식은 동일합니다. Singularity CE(Community Edition)는 Sylabs에서 별도로 유지됩니다.
Docker 이미지에서 컨테이너를 빌드하는 방법은?
apptainer build my_container.sif docker://ubuntu:22.04로 Docker 이미지를 SIF 형식으로 변환합니다. GPU 워크로드: apptainer build container.sif docker://nvidia/cuda:12.0-runtime. 정의 파일로 빌드: apptainer build container.sif my.def. SIF 대신 쓰기 가능한 디렉토리는 --sandbox, root 권한 없이 빌드는 --fakeroot를 사용합니다.
.def 정의 파일이란 무엇이며 어떤 섹션이 있나요?
.def 파일은 Apptainer 컨테이너의 빌드 레시피입니다. 주요 섹션: Bootstrap/From(기반 이미지 소스), %labels(메타데이터), %post(패키지 설치를 위한 빌드 시 명령), %environment(PATH 등 런타임 환경변수), %files(호스트 파일을 컨테이너로 복사), %runscript(컨테이너 실행 시 기본 명령), %test(자동 빌드 검증), %help(사용법 문서)입니다.
Apptainer에서 GPU 가속은 어떻게 사용하나요?
NVIDIA GPU는 --nv 플래그를 추가합니다: apptainer exec --nv container.sif python3 train.py. 호스트 CUDA 라이브러리와 GPU 장치가 자동으로 컨테이너에 바인딩됩니다. AMD GPU는 --rocm을 사용합니다. 컨테이너에는 GPU 드라이버를 설치할 필요 없이 호스트 드라이버를 사용합니다. 컨테이너 내 CUDA 툴킷 버전이 호스트 드라이버 버전과 호환되는지 확인하세요.
Apptainer 컨테이너에서 MPI는 어떻게 작동하나요?
Bind 모델(권장)은 호스트 MPI로 컨테이너를 실행합니다: mpirun -np 4 apptainer exec container.sif ./my_mpi_app. 호스트와 컨테이너 MPI 버전이 ABI 호환되어야 합니다. Hybrid 모델은 컨테이너 내부 MPI와 PMI2/PMIx로 프로세스를 관리합니다. SLURM 사용 시: srun apptainer exec container.sif ./my_mpi_app. 베어메탈 실행과 비슷한 성능을 제공합니다.
읽기 전용 SIF 컨테이너에서 데이터를 유지하는 방법은?
--bind로 호스트 디렉토리를 마운트합니다: apptainer exec --bind /data:/mnt container.sif command. 기본 마운트는 $HOME, /tmp, /proc, /sys, /dev를 포함합니다. SIF에 쓰기 레이어를 추가하려면 --overlay를 사용합니다. apptainer overlay create --size 500 overlay.img로 오버레이를 만든 후, apptainer exec --overlay overlay.img container.sif bash로 사용합니다. 오버레이의 변경사항은 세션 간에 유지됩니다.
Apptainer를 SLURM과 어떻게 연동하나요?
SLURM 배치 스크립트에서 srun apptainer exec container.sif your_command를 사용합니다. SBATCH에서 --gres=gpu:1, apptainer에서 --nv로 GPU 접근을 설정합니다. 환경변수로 설정: APPTAINER_BIND(마운트), APPTAINER_NV=1(GPU). 필요한 경우 apptainer를 모듈로 로드합니다. 컨테이너는 SLURM이 작업에 할당한 동일한 리소스를 사용합니다.
HPC에서 root 접근 없이 컨테이너를 빌드하는 방법은?
--fakeroot를 사용합니다: apptainer build --fakeroot container.sif my.def. 사용자 네임스페이스를 활용하여 빌드 환경 내에서 root를 에뮬레이션합니다. 시스템 관리자가 /etc/subuid, /etc/subgid에 사용자를 설정해야 합니다(apptainer config fakeroot --add username). 또는 root 접근이 가능한 로컬 머신에서 빌드한 후 SIF 파일을 HPC 클러스터로 전송하는 방법도 있습니다.