Singularityの利用方法

概要

玄界にはコンテナ環境としてSingularityが整備されています。 Dockerは利用できませんが、SingularityからDockerコンテナを利用することができます。ログインノードでもコンテナを利用できますが、ログインノード上のプロセスにはメモリ使用量の制限が行われているため、大容量のコンテナの利用時には問題が発生する（メモリ不足により実行できない）ことがあります。そのような際には計算ノードを使用してください。

Singularityの詳細な使い方や本ページで紹介している以外の機能、オプションなどについてはSingularityのマニュアルやsingularity helpコマンドを参照してください。

利用準備

singularityを利用するにはあらかじめmoduleをloadしておく必要があります。

[ku40000105@genkai0001 ~]$ module load singularity-ce/4.1.3
[ku40000105@genkai0001 ~]$ module list
Currently Loaded Modulefiles:
 1) singularity-ce/4.1.3(default)
[ku40000105@genkai0001 ~]$ singularity --version
singularity-ce version 4.1.3
[ku40000105@genkai0001 ~]$

コンテナイメージの取得・構築

singularity pullやsingularity buildによりコンテナイメージの取得・構築が可能です。

Docker HubからDockerコンテナを取得して利用する際は、以下のようにdocker://を付けてパスを指定する必要があります。

[ku40000105@genkai0001 ~]$ singularity build ubuntu_23.10.sif docker://ubuntu:23.10
INFO:    Starting build...
INFO:    Fetching OCI image...
26.0MiB / 26.0MiB [==============================================================================================================================] 100 % 2.2 MiB/s 0s
INFO:    Extracting OCI image...
INFO:    Inserting Singularity configuration...
INFO:    Creating SIF file...
INFO:    Build complete: ubuntu_23.10.sif
[ku40000105@genkai0001 ~]$

（singularity pull ubuntu_23.10.sif docker://ubuntu:23.10 でも同様に取得が可能です。）

NVIDIA NGC Catalog からはGPU関係の構築済みコンテナの取得が可能です。容量の大きなコンテナもあり、取得・構築に時間がかかることがある点に注意してください。（以下の例のpull処理はログインノードで 17 分ほどかかりました。データのダウンロードよりも Extracting OCI image 以降の処理に時間がかかっているようでした。）

[ku40000105@genkai0001 ~]$ singularity pull docker://nvcr.io/nvidia/nvhpc:24.5-devel-cuda_multi-ubuntu22.04
INFO:    Converting OCI blobs to SIF format
INFO:    Starting build...
INFO:    Fetching OCI image...
2.4MiB / 2.4MiB [=====================================================================================================================================================================] 100 % 4.5 MiB/s 0s
139.2MiB / 139.2MiB [=================================================================================================================================================================] 100 % 4.5 MiB/s 0s
28.2MiB / 28.2MiB [===================================================================================================================================================================] 100 % 4.5 MiB/s 0s
6.4GiB / 6.4GiB [=====================================================================================================================================================================] 100 % 4.5 MiB/s 0s
1.9MiB / 1.9MiB [=====================================================================================================================================================================] 100 % 4.5 MiB/s 0s
3.9GiB / 3.9GiB [=====================================================================================================================================================================] 100 % 4.5 MiB/s 0s
INFO:    Extracting OCI image...
INFO:    Inserting Singularity configuration...
INFO:    Creating SIF file...
[ku40000105@genkai0001 ~]$

コンテナイメージの利用

取得したコンテナイメージを利用する（コンテナを用いてプログラムを実行する）には、 singularity exec コマンドや singularity shell コマンドを用います。

コンテナ上でコマンドを実行する

singularity exec コマンドを使うとコンテナ上で指定のコマンドを実行させることができます。以下の例では、玄界にインストールされているOSではなく、コンテナのOS情報が表示されていることが確認できます。

[ku40000105@genkai0001 ~]$ singularity exec ubuntu_23.10.sif cat /etc/os-release
PRETTY_NAME="Ubuntu 23.10"
NAME="Ubuntu"
VERSION_ID="23.10"
VERSION="23.10 (Mantic Minotaur)"
VERSION_CODENAME=mantic
ID=ubuntu
ID_LIKE=debian
HOME_URL="https://www.ubuntu.com/"
SUPPORT_URL="https://help.ubuntu.com/"
BUG_REPORT_URL="https://bugs.launchpad.net/ubuntu/"
PRIVACY_POLICY_URL="https://www.ubuntu.com/legal/terms-and-policies/privacy-policy"
UBUNTU_CODENAME=mantic
LOGO=ubuntu-logo
[ku40000105@genkai0001 ~]$

コンテナ上で対話型にコマンドを実行する

singularity shell コマンドを使うとコンテナ上で対話的にコマンドを実行することができます。

[ku40000105@genkai0001 ~]$ singularity shell ubuntu_23.10.sif
Singularity> cat /etc/os-release
PRETTY_NAME="Ubuntu 23.10"
NAME="Ubuntu"
VERSION_ID="23.10"
VERSION="23.10 (Mantic Minotaur)"
VERSION_CODENAME=mantic
ID=ubuntu
ID_LIKE=debian
HOME_URL="https://www.ubuntu.com/"
SUPPORT_URL="https://help.ubuntu.com/"
BUG_REPORT_URL="https://bugs.launchpad.net/ubuntu/"
PRIVACY_POLICY_URL="https://www.ubuntu.com/legal/terms-and-policies/privacy-policy"
UBUNTU_CODENAME=mantic
LOGO=ubuntu-logo
Singularity> （Ctrl+dで終了）
exit
[ku40000105@genkai0001 ~]$

バッチジョブ実行時にコンテナを使う

バッチジョブ実行時にコンテナを使う場合はジョブ投入時に -L jobenv=singularity オプションを追加してください。

バッチジョブ例

#!/bin/sh
#PJM -L rscgrp=b-batch
#PJM -L gpu=1
#PJM -L elapse=0:10:00
#PJM -L jobenv=singularity
#PJM -j
module load singulariy-ce
singularity exec container.sif command

バッチジョブ実行で singularity shell コマンドを実行してしまうとコマンド入力受付状態で待つことになってしまうため注意してください。

インタラクティブジョブ実行の場合も同様にpjsubコマンドに対するオプションの追加が必要です。

[ku40000105@genkai0001 ~]$ pjsub --interact -L rscgrp=b-inter,elapse=1:00:00,gpu=1,jobenv=singularity
[INFO] PJM 0000 pjsub Job 14528 submitted.
[INFO] PJM 0081 .connected.
[INFO] PJM 0082 pjsub Interactive job 14528 started.
$ module load singularity-ce
$ singularity shell ubuntu_23.10.sif
Singularity> cat /etc/debian_version
trixie/sid
Singularity>
exit
[ku40000105@genkai0001 ~]$ singularity exec ubuntu_23.10.sif cat /etc/os-release
PRETTY_NAME="Ubuntu 23.10"
NAME="Ubuntu"
VERSION_ID="23.10"
VERSION="23.10 (Mantic Minotaur)"
VERSION_CODENAME=mantic
ID=ubuntu
ID_LIKE=debian
HOME_URL="https://www.ubuntu.com/"
SUPPORT_URL="https://help.ubuntu.com/"
BUG_REPORT_URL="https://bugs.launchpad.net/ubuntu/"
PRIVACY_POLICY_URL="https://www.ubuntu.com/legal/terms-and-policies/privacy-policy"
UBUNTU_CODENAME=mantic
LOGO=ubuntu-logo
$ ログアウト
[INFO] PJM 0083 pjsub Interactive job 14528 completed.
[ku40000105@genkai0001 ~]$

pjsubコマンドのオプションを付け忘れるとコンテナの実行時にエラーが発生するため注意してください。以下は付け忘れた場合の例です。

[ku40000105@genkai0001 ~]$ pjsub --interact -L rscgrp=b-inter,elapse=1:00:00,gpu=1
[INFO] PJM 0000 pjsub Job 14501 submitted.
[INFO] PJM 0081 .connected.
[INFO] PJM 0082 pjsub Interactive job 14501 started.
$ module load singularity-ce
$ singularity shell ubuntu_23.10.sif
ERROR  : Failed to create mount namespace: mount namespace requires privileges, check Singularity installation
$ singularity exec ubuntu_23.10.sif cat /etc/os-release
ERROR  : Failed to create mount namespace: mount namespace requires privileges, check Singularity installation
$ exit
ログアウト
[INFO] PJM 0083 pjsub Interactive job 14501 completed.
[ku40000105@genkai0001 ~]$

コンテナからGPUを使う

ノードグループBやCでコンテナからGPUを使いたい場合は、singularity exec や singularity pull を実行する際に --nv オプションを追加してください。 --nv オプションが指定されていないとコンテナからGPUを認識することができません。

[ku40000105@genkai0001 ~]$ pjsub --interact -L rscgrp=b-inter,elapse=1:00,gpu=1,jobenv=singularity
[INFO] PJM 0000 pjsub Job 14529 submitted.
[INFO] PJM 0081 .connected.
[INFO] PJM 0082 pjsub Interactive job 14529 started.
$ module load singularity-ce
# NVIDIA HPC SDKコンテナからGPUを参照できる例（`--nv`オプションあり）
$ singularity shell --nv nvhpc_24.5-devel-cuda_multi-ubuntu22.04.sif
Singularity> nvidia-smi
Tue Jun 18 16:17:41 2024
+---------------------------------------------------------------------------------------+
| NVIDIA-SMI 535.154.05             Driver Version: 535.154.05   CUDA Version: 12.2     |
|-----------------------------------------+----------------------+----------------------+
| GPU  Name                 Persistence-M | Bus-Id        Disp.A | Volatile Uncorr. ECC |
| Fan  Temp   Perf          Pwr:Usage/Cap |         Memory-Usage | GPU-Util  Compute M. |
|                                         |                      |               MIG M. |
|=========================================+======================+======================|
|   0  NVIDIA H100                    On  | 00000000:1C:00.0 Off |                    0 |
| N/A   20C    P0              68W / 700W |      0MiB / 95830MiB |      0%      Default |
|                                         |                      |             Disabled |
+-----------------------------------------+----------------------+----------------------+

+---------------------------------------------------------------------------------------+
| Processes:                                                                            |
|  GPU   GI   CI        PID   Type   Process name                            GPU Memory |
|        ID   ID                                                             Usage      |
|=======================================================================================|
|  No running processes found                                                           |
+---------------------------------------------------------------------------------------+
Singularity> nvidia-smi -L
GPU 0: NVIDIA H100 (UUID: GPU-03fb7359-eec6-36a3-9746-0bc092721223)
Singularity> pgaccelinfo

CUDA Driver Version:           12020
NVRM version:                  NVIDIA UNIX x86_64 Kernel Module  535.154.05  Thu Dec 28 15:37:48 UTC 2023

Device Number:                 0
Device Name:                   NVIDIA H100
Device Revision Number:        9.0
Global Memory Size:            99875094528
Number of Multiprocessors:     132
Concurrent Copy and Execution: Yes
Total Constant Memory:         65536
Total Shared Memory per Block: 49152
Registers per Block:           65536
Warp Size:                     32
Maximum Threads per Block:     1024
Maximum Block Dimensions:      1024, 1024, 64
Maximum Grid Dimensions:       2147483647 x 65535 x 65535
Maximum Memory Pitch:          2147483647B
Texture Alignment:             512B
Clock Rate:                    1980 MHz
Execution Timeout:             No
Integrated Device:             No
Can Map Host Memory:           Yes
Compute Mode:                  default
Concurrent Kernels:            Yes
ECC Enabled:                   Yes
Memory Clock Rate:             1593 MHz
Memory Bus Width:              6144 bits
L2 Cache Size:                 62914560 bytes
Max Threads Per SMP:           2048
Async Engines:                 5
Unified Addressing:            Yes
Managed Memory:                Yes
Concurrent Managed Memory:     Yes
Preemption Supported:          Yes
Cooperative Launch:            Yes
Cluster Launch:                Yes
Unified Function Pointers:     Yes
Default Target:                cc90
Singularity>
exit
# NVIDIA HPC SDKコンテナからGPUを参照できない例（`--nv`オプションなし）
$ singularity shell nvhpc_24.5-devel-cuda_multi-ubuntu22.04.sif
Singularity> nvidia-smi
bash: nvidia-smi: command not found
Singularity> nvidia-smi -L
bash: nvidia-smi: command not found
Singularity> pgaccelinfo
No accelerators found.
Try pgaccelinfo -v for more information
Singularity> pgaccelinfo -v
libcuda.so not found
No accelerators found.
Check that you have installed the CUDA driver properly
Check that your LD_LIBRARY_PATH environment variable points to the CUDA runtime installation directory
Singularity>
exit
$

レシピファイルからコンテナを構築する

レシピファイル（DockerにおけるDockerfileに相当）からカスタマイズされたコンテナを作ることができます。ログインノードでも実行可能です。

なお、構築するコンテナによっては構築作業中にGPUが参照できる必要がある（参照できないとGPUに対応したコンテナ環境が構築できない）ことがあります。そのような場合にはノードグループBやCでコンテナの構築を行ってください。

# 最近のUbuntuでは標準でインストールされていないnslookupコマンドが使えるように、dnsutilsパッケージを組み込んだコンテナを作る例
# レシピファイルの確認
[ku40000105@genkai0001 ~]$ cat ubuntu.def
Bootstrap: docker
From:ubuntu:24.04

%post
apt-get update -y
apt-get install -y dnsutils
[ku40000105@genkai0001 ~]$
# レシピファイルを用いたコンテナの構築
[ku40000105@genkai0001 ~]$ singularity build -f test.sif ./ubuntu.def
INFO:    Starting build...
INFO:    Fetching OCI image...
28.3MiB / 28.3MiB [==============================================================================================================================] 100 % 8.2 MiB/s 0s
INFO:    Extracting OCI image...
INFO:    Inserting Singularity configuration...
INFO:    Running post scriptlet
+ apt-get update -y
Get:1 http://archive.ubuntu.com/ubuntu noble InRelease [256 kB]
中略
Get:16 http://archive.ubuntu.com/ubuntu noble-backports/universe amd64 Packages [7519 B]
Fetched 22.9 MB in 5s (4567 kB/s)
Reading package lists... Done
+ apt-get install -y dnsutils
Reading package lists... Done
Building dependency tree... Done
Reading state information... Done
The following additional packages will be installed:
  bind9-dnsutils bind9-host bind9-libs krb5-locales libbsd0 libedit2 libgssapi-krb5-2 libicu74 libjson-c5 libk5crypto3 libkeyutils1 libkrb5-3 libkrb5support0
  liblmdb0 libmaxminddb0 libnghttp2-14 libuv1t64 libxml2
Suggested packages:
  krb5-doc krb5-user mmdb-bin
The following NEW packages will be installed:
  bind9-dnsutils bind9-host bind9-libs dnsutils krb5-locales libbsd0 libedit2 libgssapi-krb5-2 libicu74 libjson-c5 libk5crypto3 libkeyutils1 libkrb5-3
  libkrb5support0 liblmdb0 libmaxminddb0 libnghttp2-14 libuv1t64 libxml2
0 upgraded, 19 newly installed, 0 to remove and 0 not upgraded.
Need to get 14.1 MB of archives.
After this operation, 46.3 MB of additional disk space will be used.
Get:1 http://archive.ubuntu.com/ubuntu noble/main amd64 krb5-locales all 1.20.1-6ubuntu2 [13.8 kB]
中略
Processing triggers for libc-bin (2.39-0ubuntu8.2) ...
INFO:    Creating SIF file...
INFO:    Build complete: test.sif
[ku40000105@genkai0001 ~]$
# 構築したコンテナの確認
[ku40000105@genkai0001 ~]$ singularity exec test.sif nslookup google.com
Server:         172.16.0.21
Address:        172.16.0.21#53

Non-authoritative answer:
Name:   google.com
Address: 142.250.206.238
Name:   google.com
Address: 2404:6800:400a:804::200e

[ku40000105@genkai0001 ~]$

コンテナを再構築する（コンテナイメージの編集を行う）

レシピファイルを使うのではなく、対話型処理によりコンテナを編集し再構築することもできます。ただしこの機能の利用にはファイルシステムの制限があるため、計算ノード上のSSDを使う必要があります。（ノードグループB, Cではジョブ起動後に${PJM_SSD_DIR}でSSDを参照できます。）

操作手順としては、ディレクトリ（フォルダ）に展開された形式のコンテナを用意し、専用のオプションを付けてコンテナを起動して編集操作を行い、改めてコンテナファイルにまとめます。

以下に具体的な例を示します。

# コンテナの編集の例として、最近のUbuntuに含まれていないnslookupプログラムの導入を試みる
[ku40000105@genkai0002 ~]$ singularity build -s ./ubuntu docker://ubuntu:latest
[ku40000105@genkai0002 ~]$ singularity shell ./ubuntu.sif
Singularity> nslookup google.com
bash: nslookup: command not found
Singularity>
exit
[ku40000105@genkai0002 ~]$
# コンテナの構築を行う
# jobenv=singularityオプションを付けてインタラクティブジョブを起動（一番ポイント消費が少ないリソースグループであるmigの1サブGPUを利用）
[ku40000105@genkai0002 ~]$ pjsub --interact -L rscgrp=b-inter-mig,elapse=1:00:00,gpu=1,jobenv=singularity
[INFO] PJM 0000 pjsub Job 116222 submitted.
[INFO] PJM 0081 .connected.
[INFO] PJM 0082 pjsub Interactive job 116222 started.
# SSDへ移動
[ku40000105@b0037 ~]$ cd $PJM_SSD_DIR
# singularity-ce moduleをloadし、ubuntuのコンテナを-sオプション付きでビルド（コンテナファイルの代わりにディレクトリが作られる）
[ku40000105@b0037 116222]$ module load singularity-ce
[ku40000105@b0037 116222]$ singularity build -s ./ubuntu docker://ubuntu:latest
INFO:    Starting build...
INFO:    Fetching OCI image...
28.3MiB / 28.3MiB [==========================================================================================================================================] 100 % 0.0 b/s 0s
INFO:    Extracting OCI image...
INFO:    Inserting Singularity configuration...
INFO:    Creating sandbox directory...
INFO:    Build complete: ./ubuntu
# -f -w オプションを付けてsingularity shellを起動（コンテナ上での作業によりファイルが更新される）
[ku40000105@b0037 116222]$ singularity shell -f -w ./ubuntu
WARNING: Skipping mount /etc/localtime [binds]: /etc/localtime doesn't exist in container
WARNING: Skipping mount /etc/libibverbs.d [binds]: /etc/libibverbs.d doesn't exist in container
# パッケージ管理情報の更新
Singularity> apt update -y
（省略）
# nslookupコマンドを含むdnsutilsをインストール
Singularity> apt install -y dnsutils
（省略）
Singularity>
exit
# コンテナファイルにビルドし直す
[ku40000105@b0037 116222]$ singularity build -f ${HOME}/ubuntu_dnsutils.sif ./ubuntu
INFO:    Starting build...
INFO:    Creating SIF file...
INFO:    Build complete: /home/pj24001603/ku40000105/ubuntu_dnsutils.sif
# インタラクティブジョブを終了（SSDに作成したファイルは全て消失する）
[ku40000105@b0037 116222]$ exit
[INFO] PJM 0083 pjsub Interactive job 116222 completed.
[ku40000105@genkai0002 ~]$
# ビルドしたコンテナではnslookupプログラムを実行することができることを確認する
[ku40000105@genkai0002 ~]$ singularity shell ./ubuntu_dnsutils.sif
Singularity> nslookup google.com
Server:         172.16.0.21
Address:        172.16.0.21#53

Non-authoritative answer:
Name:   google.com
Address: 172.217.25.174
Name:   google.com
Address: 2404:6800:400a:80a::200e

Singularity>
exit
[ku40000105@genkai0002 ~]$