Aller au contenu principal

Apptainer

Apptainer (anciennement Singularity) est la solution de conteneurisation disponible sur eXplor-v2. Il s'agit d'un système de conteneurisation multi-plateformes open source développé par Sylabs. L'un des principaux avantages des conteneurs est de permettre la reproductibilité de calculs scientifiques sans gros effort de portage d'un système à l'autre. Cette solution est performante et très adaptée aussi bien pour le calcul haute performance que pour le calcul en intelligence artificielle.

À l'aide des conteneurs Apptainer, les utilisateurs peuvent travailler dans des environnements de leur choix et de leur conception, ces environnements complets pouvant facilement être copiés et exécutés sur le supercalculateur eXplor-v2.

Pour plus de détails, vous pouvez consulter la documentation officielle d'Apptainer.

Docker et Podman non disponibles

Docker n'est pas disponible sur eXplor-v2 pour des raisons de politiques de sécurité (accès root nécessaires). Les images Docker sont néanmoins exploitables dans un environnement Apptainer.

Podman n'est pas disponible sur eXplor-v2 pour des raisons techniques (compatibilité avec le file system).

Recommandations d'usage​

L'image Apptainer que vous allez manipuler peut être volumineuse. Il est recommandé de lancer les commandes Apptainer (build, pull, run, exec, etc.) depuis l'espace $WORK ou $SCRATCH pour éviter une saturation d'espace.

De plus, les ressources en mémoire RAM étant limitées sur les nœuds de connexion, il est fortement recommandé d'utiliser les nœuds de pré/post-traitement ou une allocation interactive pour la construction ou la conversion de conteneurs nécessitant des ressources importantes.

Module​

Apptainer est accessible par la commande module :

module load apptainer/1.4.5

Pour obtenir des informations sur le module Apptainer, il suffit d'utiliser la commande suivante :

module show apptainer/1.4.5

Le module configure :

  • le chemin vers l'exécutable apptainer (/soft/apps/manual/softwares/apptainer/bin) ;
  • les pages de manuel ;
  • les répertoires de cache et temporaires via APPTAINER_CACHEDIR et APPTAINER_TMPDIR.

L'installation comprend :

  • bin/apptainer : binaire principal ;
  • bin/singularity : lien symbolique vers apptainer pour la compatibilité avec les scripts Singularity ;
  • libexec/apptainer/bin/starter et starter-suid : binaires d'amorçage, dont la version SUID pour les fonctionnalités nécessitant des privilèges.
Apptainer n'est pas chargé par défaut

Vous devez charger explicitement le module Apptainer dans chaque session interactive et dans chaque script Slurm qui utilise des conteneurs.

Système de fichiers temporaire​

Une fois le module chargé, un répertoire temporaire $APPTAINER_CACHEDIR est créé automatiquement dans votre espace disque $SCRATCH personnel. Il contiendra le système de fichiers du conteneur lors de son exécution.

Ne pas modifier $APPTAINER_CACHEDIR

Il est fortement recommandé de ne pas modifier la variable d'environnement $APPTAINER_CACHEDIR afin de ne pas dépasser les quotas des autres espaces disques et d'en simplifier le nettoyage automatique.

Environnement d'exécution​

Une fois votre conteneur prêt, vous devez le placer dans le répertoire dédié $APPTAINER_ALLOWED_DIR afin qu'il soit analysé et autorisé à l'usage sur les nœuds de calcul.

Variable $APPTAINER_ALLOWED_DIR

La variable $APPTAINER_ALLOWED_DIR définit un chemin unique par utilisateur et ce chemin n'est pas modifiable.

La copie et la suppression de conteneurs dans cet espace s'effectuent via la commande idrcontmgr (ou équivalent sur eXplor-v2). Cette dernière autorise ou non la copie des conteneurs sur cet espace, en vérifiant au préalable si le conteneur obéit aux contraintes de sécurité définies par le centre.

Limite de conteneurs

Cet espace $APPTAINER_ALLOWED_DIR est limité à 20 conteneurs.

Un conteneur peut être copié dans l'espace d'exécution autorisé via la commande idrcontmgr de la manière suivante :

idrcontmgr cp my-container.sif

La suppression s'effectue d'une manière similaire :

idrcontmgr rm my-container.sif

Cette commande permet également d'afficher le contenu de l'espace d'exécution autorisé :

idrcontmgr ls

Construction d'une image Apptainer​

Les modes de construction d'images Apptainer nécessitant d'être super utilisateur (root) ne sont pas disponibles sur eXplor-v2. Il n'est donc pas possible de construire une image Apptainer à partir d'un fichier de définition. Pour ce type d'image, il est donc laissé au soin des utilisateurs de les créer depuis une autre machine, puis de les rapatrier sur eXplor-v2.

Depuis une des frontales d'eXplor-v2, il est toutefois permis de créer une image Apptainer depuis des dépôts existants (Apptainer, Docker, etc.) sous forme d'un fichier .sif.

Construction d'une image depuis un dépôt public​

Depuis l'espace disque $WORK ou $SCRATCH, un utilisateur peut créer une image Apptainer depuis un dépôt public existant (Apptainer, Docker, etc.) en lançant la commande apptainer build :

apptainer build image-apptainer-tensorflow.sif docker://tensorflow/tensorflow:latest-gpu-py3

Sur cet exemple, la commande est utilisée pour télécharger une image depuis le dépôt public Docker, pour ensuite construire une image Apptainer au format .sif.

Conversion d'une image SANDBOX au format .sif​

L'utilisation des conteneurs sous forme de SANDBOX n'est pas autorisée sur eXplor-v2. Néanmoins, il est tout à fait possible de convertir une image SANDBOX au format .sif. Il suffit d'utiliser la commande apptainer build :

apptainer build mon_conteneur.sif mon_conteneur_sandbox/

Exécution d'un shell dans une image Apptainer​

La commande apptainer run permet de lancer un conteneur Apptainer et un shell à l'intérieur de ce conteneur. L'exécution de cette commande requiert l'utilisation du mode interactif sur un nœud de calcul.

Par exemple, pour la partition CPU, il vous faudra ouvrir un terminal directement sur un nœud de calcul sur lequel des ressources vous sont réservées (ici 10 cœurs) en utilisant la commande suivante :

srun --pty --ntasks=1 --cpus-per-task=10 --hint=nomultithread bash

puis lancer le conteneur en mode shell via la commande suivante :

apptainer shell $APPTAINER_ALLOWED_DIR/mon_conteneur_cpu.sif

Pour la partition GPU, la manipulation est quasi identique en allouant les bonnes ressources sur un nœud GPU, puis en lançant le conteneur shell comme précédemment, en utilisant l'option --nv afin de prendre en compte les cartes NVIDIA :

apptainer shell --nv $APPTAINER_ALLOWED_DIR/mon_conteneur_gpu.sif

Exécution d'un code dans une image Apptainer en mode batch​

Exécution d'un code parallèle MPI​

Pour soumettre un travail MPI en batch sur eXplor-v2, il faut :

Créer un script de soumission​

Voici un exemple pour la partition CPU par défaut (40 cœurs physiques), enregistré dans le fichier apptainer_mpi.slurm :

#!/bin/bash
#SBATCH --job-name=ApptainerMPI          # nom du job
#SBATCH --ntasks=40                      # Nombre total de processus MPI
#SBATCH --ntasks-per-node=40             # Nombre de processus MPI par noeud
#SBATCH --time=00:10:00                  # Temps d'exécution maximum demandé (HH:MM:SS)
#SBATCH --output=ApptainerMPI%j.out      # Nom du fichier de sortie
#SBATCH --error=ApptainerMPI%j.out       # Nom du fichier d'erreur (ici commun avec la sortie)

# on se place dans le répertoire de soumission
cd ${SLURM_SUBMIT_DIR}

# nettoyage des modules chargés en interactif et hérités par défaut
module purge

# chargement des modules
module load apptainer/1.4.5

# echo des commandes lancées
set -x

# exécution du code depuis l'espace d'exécution autorisé.
# Selon l'implémentation de MPI installée dans le conteneur, on positionnera l'option --mpi=pmix_v2 ou --mpi=pmix_v3
srun --mpi=pmix_v2 apptainer exec $APPTAINER_ALLOWED_DIR/my-container_CPU.sif ./exec_mpi
Option --mpi

Pour l'exécution d'un code parallèle MPI depuis une image Apptainer, et selon l'implémentation de MPI installée dans le conteneur, on positionnera l'option --mpi=pmix_v2 ou --mpi=pmix_v3 à l'exécution.

Option --mpi à valider selon le conteneur

Pour l'exécution d'un code parallèle MPI depuis une image Apptainer, l'option --mpi à utiliser dépend de l'implémentation de MPI installée dans le conteneur (OpenMPI, Intel MPI, MPICH, etc.).

Lorsque votre conteneur sera prêt :

  1. identifiez le MPI dans le conteneur (mpirun --version, mpiexec --version) ;
  2. testez les options --mpi=pmix_v2, --mpi=pmix_v3 et sans option avec un petit programme MPI ;
  3. figez l'option qui fonctionne dans votre script Slurm.

Exemple de commentaire à ajouter dans le script une fois validé :

# MPI dans le conteneur : OpenMPI 4.1.5
# Option Slurm validée : --mpi=pmix_v3
# Testé le 2025-08-25 sur partition compute, 40 tasks

Soumettre ce script via la commande sbatch​

sbatch apptainer_mpi.slurm

Exécution d'un code GPU​

Pour soumettre un travail GPU en batch sur eXplor-v2, il faut :

Créer un script de soumission​

Voici un exemple pour la partition GPU par défaut (nœuds 4-GPU V100 avec 40 cœurs physiques), enregistré dans le fichier apptainer_gpu.slurm :

#!/bin/bash
#SBATCH --job-name=ApptainerGPU          # nom du job
#SBATCH --partition=gpu                  # partition GPU
#SBATCH --ntasks=1                       # nombre total de tâches (= nombre de GPU ici)
#SBATCH --gres=gpu:1                     # nombre de GPU par nœud (1/4 des GPU)
#SBATCH --cpus-per-task=10               # nombre de cœurs CPU par tâche (1/4 du noeud 4-GPU)
#SBATCH --time=00:10:00                  # Temps d'exécution maximum demandé (HH:MM:SS)
#SBATCH --output=ApptainerGPU%j.out      # Nom du fichier de sortie
#SBATCH --error=ApptainerGPU%j.out       # Nom du fichier d'erreur (ici commun avec la sortie)

# on se place dans le répertoire de soumission
cd ${SLURM_SUBMIT_DIR}

# nettoyage des modules chargés en interactif et hérités par défaut
module purge

# chargement des modules
module load apptainer/1.4.5

# echo des commandes lancées
set -x

# exécution du code depuis l'espace d'exécution autorisé avec l'option --nv afin de prendre en compte les cartes NVIDIA
srun apptainer exec --nv $APPTAINER_ALLOWED_DIR/my-container_GPU.sif python ./my_model.py

Soumettre ce script via la commande sbatch​

sbatch apptainer_gpu.slurm

Pages associées​