Skoči na vsebino

Vsebniki

Vsebniki predstavljajo individualno enoto z ustreznim naborom programske opreme, vključno z ustreznimi knjižnicami in nastavitvami za učinkovito delovanje v okolju. Tehnologija omogoča zanesljivost, prenosljivost, izolacijo, varnost in zagon programske opreme vsebnikov znotraj ali izven ukazne vrstice. Slednje omogoča, da se programska oprema prilagodi okolju superračunalnika. Posamezne distribucije omogočajo različne pristope in mehanizme, ki zagotavljajo fleksibilnost in konfiguracijo okolja. Gruča Vega že ima platformo za vsebnike Apptainer nameščeno in prilagojeno delu na superračunalnikih (HPC).

Na HPC Vega so vsebniki na voljo na $PATH: /ceph/hpc/software/containers/singularity

Vsebniki Apptainer

Apptainer je platforma, namenjena ustvarjanju in zaganjanju vsebnikov znotraj superračunalniškega okolja. Vsebniki imajo dostop do skupne operacijskega sistema, datotečnega sistema in programske opreme, nameščene na vozliščih. Slednja upošteva privilegije operacijskega sistema (v našem primeru je to RHEL), ki omogoča uporabo in prenos ustreznih pravic sistemskega uporabniškega računa. Če se odločimo za namestitev lastnega vsebnika, lahko namestimo programsko opremo, knjižnice in prilagodimo okolje v njem tako, da ustreza našim potrebam. Zaradi omejene izolacije moramo biti pozorni na ustreznost in združljivost okolja, ki ga vzpostavimo. V nasprotnem primeru vsebnik ne bo deloval pravilno ali pa sploh ne bo deloval. Apptainer zagotavlja visoko stopnjo prenosljivosti – z uporabo formata Singularity Image Format (SIF) – ter ponovljivost priprave vsebnikov s pomočjo definicijskih oziroma opisnih datotek (.def/ .dsc).

Apptainer (prej Singularity) je odprtokodni fork programa Singularity. Večinoma sta medsebojno zamenljiva, zato lahko svoje delovne tokove v Singularityju enostavno prilagodite, da bodo delovali tudi z Apptainerjem.

Več informacij najdete v uradni dokumentaciji.

Ukazi Apptainer

Če ne želite ustvarjati lastnega vsebnika, lahko uporabite že pripravljene vsebnike iz javnih repozitorijev (npr. Docker Hub, Sylabs Library ipd.). Ukaz apptainer pull prenese izbrani vsebnik na VEGA datotečni sistem in ga shrani v datoteko formata .sif, ki jo lahko kasneje uporabljate za izvajanje programov. Splošna oblika ukaza:

apptainer pull <image-name>.sif <hub>://<image>[:tag]

kjer: - <image-name>.sif določa ime datoteke, ki bo ustvarjena na vašem računu, - <hub> določa vir prenosa (npr. docker, library), - <image> predstavlja ime vsebnika iz izbranega vira prenosa, - [:tag] pa je izbirna oznaka različice vsebnika (npr. latest, 2.15, cuda12).

Naslednji ukaz prenese najnovejšo različico vsebnika TensorFlow iz Docker Hub repozitorija:

apptainer pull tensorflow.sif docker://tensorflow/tensorflow:latest

Po uspešnem prenosu bo v trenutnem direktoriju ustvarjena .sif datoteka, npr. container.sif. To datoteko lahko nato uporabite za zagon aplikacij znotraj vsebnika.

Zagon vsebnika

Ko imate vsebnik prenesen v datoteki .sif, ga lahko zaženete na več načinov, odvisno od tega, kaj želite narediti.

Ukaz run zažene privzeti program, ki je nastavljen v vsebniku:

apptainer run container.sif

Za izhod iz vsebnika uporabite ukaz exit.

Ukaz exec zažene točno določen ukaz znotraj vsebnika:

apptainer exec container.sif <command>

Primer:

apptainer exec tensorflow.sif python --version

Z ukazom exec lahko s pomočjo vsebnika zaženete tudi skripte. Primer:

apptainer exec tensorflow.sif python script.py

Zagon z ukazom exec je najpogosteje uporabljen način dela na HPC sistemih, saj omogoča zagon posameznih programov znotraj vsebnika.

Interaktivno lupino znotraj vsebnika zaženemo z ukazom shell:

apptainer shell container.sif

Sedaj lahko izvajate ukaze neposredno znotraj vsebnika. Primer:

Apptainer> python --version
Apptainer> ls
Apptainer> pwd

Za izhod iz vsebnika uporabite ukaz exit.

Pregled informacij o vsebniku

Za izpis osnovnih podatkov o vsebniku uporabite:

apptainer inspect container.sif

Za prikaz ukaza, ki se izvede ob uporabi apptainer run, uporabite:

apptainer inspect --runscript container.sif

Za prikaz definicijske datoteke vsebnika uporabite:

apptainer inspect --deffile container.sif

Nekateri vsebniki vsebujejo dodatna navodila za uporabo, ki jih prikažemo z:

apptainer run-help container.sif

Za pregled vseh razpoložljivih ukazov uporabite:

apptainer help

Za pomoč pri posameznem ukazu uporabite:

apptainer help <command>

Priprava lastnega vsebnika

Če predpripravljen vsebnik ne vsebuje vseh programov ali nastavitev, ki jih potrebujete, lahko ustvarite lasten vsebnik. Lastni vsebnik lahko pripravite na več načinov, lahko tudi tako, da jih združite. Uporabite lahko tudi predhodno pripravljene vsebnike, jih razporedite in jih prilagodite svojim potrebam. Če pa vam to ne ustreza, lahko ustvarite lastni vsebnik s pomočjo definicijske datoteke. Slednja vam omogoča višjo raven ponovljivosti vsebnika samega (vedno dobite isti rezultat, morate pa biti previdni, da ne uporabite najnovejših oznak).

Predloge so na voljo v različnih repozitorijih za zagon (angl. bootstrap repositories), kot so:

Celotni seznam repozitorijev je na voljo na spletni strani: Navodila za uporabnike

Dodatne funkcionalnosti in uporaba različnih stikal:

Singularity Image Format (SIF) je vsebnik samo za branje, ki omogoča prenosljivost. Če so potrebne spremembe v vsebniku, se lahko pretvori v "sandbox" ali uporabi dodatna funkcionalnost "Persistent Overlays", ki je na voljo s stikalom --overlay.

Več informacij najdete povezavi.

Če je vsebnik pripravljen s stikalom --sandbox, se lahko vsebnik sam ureja neposredno s stikalom --writable. Sistemske direktorije lahko vpnete v vsebnik z uporabo stikala --bind $PATH.

Več informacij najdete povezavi.

Graditev

Zapisljiv vsebnik (sandbox) lahko ustvarite iz obstoječe slike v izbranem repozitoriju:

apptainer build --sandbox --fix-perms <container>/ <hub>://<image>:[tag]

kjer: - <containr> predstavlja imenik, v katerega bo vsebnik ustvarjen, - <hub> določa vir prenosa (npr. docker, library), - <image> predstavlja ime vsebnika iz izbranega vira prenosa, - [:tag] pa je izbirna oznaka različice vsebnika.

Naslednji primer ustvari zapisljiv vsebnik na osnovi Ubuntu 24.04:

apptainer build --sandbox --fix-perms ubuntu_container/ docker://ubuntu:24.04

Lupina

Če uporabljate zapisljiv sandbox vsebnik, ga lahko odprete v interaktivni lupini, ki omogoča spreminjanje vsebine:

apptainer shell --writable --fakeroot container/

Fakeroot je funkcionalnost, ki omogoča uporabnikokm brez privilegijev, da pridobijo ustrezne pravice "root" znotraj vsebnikov s stikalom -–fakeroot. Pravice gostiteljskih sistemov datotek (FS) so ustrezno preslikane znotraj vsebnika. Poleg tega se priporoča, da uporabite stikalo --fix-perms, ki ustrezno uravnava in prilagaja pravice znotraj vsebnika.

Več informacij najdete povezavi.

Opomba

Fakeroot za vse uporabnike je privzeto nastavljen na način root-mapped user namespace. Če za namen izdelave lastnih vsebnikov potrebujete rootless mode, pošljite zahtevo za omogočitev na support@sling.si

Izvršitev

Če želite v vsebniku izvesti posamezen ukaz, ne da bi odprli interaktivno lupino, uporabite ukaz exec.

apptainer exec <container> <command>

Naslednji ukaz izvede ukaz whoami v zapisljivem sandbox vsebniku:

apptainer exec --fakeroot container/ whoami

Predpomnilnik

Apptainer med prenosom in gradnjo vsebnikov začasno shranjuje datoteke v predpomnilnik (cache). Tako ob ponovni uporabi ni potrebno znova prenašati istih podatkov, kar pospeši delo in zmanjša omrežni promet.

Za pregled datotek, ki so trenutno shranjene v predpomnilniku, uporabite:

apptainer cache list

Če želite sprostiti prostor na datotečnem sistemu, lahko vsebino predpomnilnika izbrišete:

apptainer cache clean --type=all

Priprava definicijske datoteke

Definicijska datoteka (definition file) vsebuje navodila za gradnjo vsebnika. V njej določite osnovno sliko, namestitev programske opreme, okoljske spremenljivke in druge nastavitve. Definicijsko datoteko lahko ustvarite z urejevalnikom besedila:

$ vim example.def

Definicijska datoteka je sestavljena iz več delov. Prvi del definicijske datoteke predstavlja izvorna slika, ki določa iz katere slike bo vsebnik ustvarjen. Primer:

Bootstrap: docker
From: ubuntu:24.04

V tem primeru se kot osnova uporabi Ubuntu 24.04 iz repozitorija Docker Hub.

V %environment delu definicijske datoteke določimo okoljske spremenljivke, ki bodo na voljo ob vsakem zagonu vsebnika. Primer:

%environment
    export LC_ALL=C

V %post delu definicijske datoteke namestimo programe, knjižnice in ustvarimo imenike. Primer:

%post
   apt-get -y update
   apt-get -y install <package-name>
   apt-get clean

V %runscript delu definicijske datoteke določimo, kaj se izvede ob uporabi ukaza apptainer run. Primer:

%runscript
    echo "This is what happens when you run the container."

V razdelek %labels lahko zapišemo dodatne informacije o vsebniku. Primer:

%labels
   Maintainer Y
   Version 1.0

V razdelek %help lahko vključimo navodila za uporabo vsebnika. Primer:

%help
    Description of help section.

Primer celotne definicijske datoteke izgleda sledeče:

bootstrap: docker
from: ubuntu:latest

%environment
    export LC_ALL=C
%runscript
    echo "This is what happens when you run the container.."
%post 
   apt-get -y update
   apt-get -y install <package-name>
   apt-get clean
%labels
   Maintainer Y
   Version 1.0
%help
    Description of help section.

Vsebnik samo za branje (stisnjen squashfs) je format SIF (Singularity Image Format), ki se lahko pretvori v sliko s stikalom --writable ali stikalom sandbox na direktorije sandbox. Zapisljivo stikalo (za razliko od direktorijev sandbox) ne omogoča stalnih/trajnih sprememb.

Če želite spreminjati obstoječ SIF vsebnik, ga najprej pretvorite v sandbox obliko:

$ apptainer build --sandbox --fakeroot  container/ container.sif

Po pretvorbi lahko vsebnik odprete v zapisljivem načinu:

$ apptainer build --sandbox --fakeroot  container.simg container.sif

Uporaba vsebnikov HPC Vega

Na HPC Vega so na voljo različni vsebniki na /ceph/hpc/software/containers/singularity. V tem direktoriju so na voljo:

  • .sif slike za neposredno poganjanje programske opreme v vsebnikih;
  • .def definicijske datoteke za prilagoditev na lastne potrebe.

Neposredna uporaba Apptainer slik na HPC Vega

V primeru, ko vsebnik vsebuje vso potrebno programsko opremo in je potrebno zgolj poganjanje vsebnika, to preprosto storimo z ukazom apptainer run .... Primer:

apptainer run /ceph/hpc/software/containers/singularity/images/tensorflow-23.09-tf2-py3.sif

ali

apptainer exec /ceph/hpc/software/containers/singularity/images/tensorflow-23.09-tf2-py3.sif python3 ...

Navedeno se požene znotraj okolja Slurm.

Uporaba definicijskih datotek za Apptainer

Definicijske datoteke si lahko prilagodimo za svoj primer uporabe (verzija programske opreme, dodatna orodja...). V tem primeru je potrebno datoteko .def skopirati iz /ceph/hpc/software/containers/singularity/def/ na home direktorij, jo urediti skladno s potrebami in tam pognati apptainer build, na primer: 

apptainer build --fakeroot moj_tensorflow-23.09-tf2-py3.def my_container.sif

Primer Apptainer definicijske datoteke za MPI aplikacijo

Pri uporabi host MPI mora biti aplikacija v vsebniku prevedena z isto različico MPI, kot jo uporablja host.

Naslednji primer prikazuje gradnjo vsebnika z OpenMPI 4.1.6 in prevod MPI aplikacije z isto MPI različico:

Bootstrap: docker 
From: ubuntu:22.04 
%post 
    apt-get update apt-get install -y \ build-essential wget ca-certificates 

    # Namestitev OpenMPI 4.1.6 
    wget https://download.open-mpi.org/release/open-mpi/v4.1/openmpi-4.1.6.tar.gz 
    tar xf openmpi-4.1.6.tar.gz 
    cd openmpi-4.1.6 
    ./configure --prefix=/opt/openmpi 
    make -j$(nproc) 
    make install 

    export PATH=/opt/openmpi/bin:$PATH 
    export LD_LIBRARY_PATH=/opt/openmpi/lib:$LD_LIBRARY_PATH 

    # Prevod aplikacije z isto MPI različico 
    cd /tmp 
    tar xf myprogram.tar.gz 
    cd myprogram 
    ./configure CC=mpicc 
    make 
    make install 

%environment 
    export PATH=/opt/openmpi/bin:$PATH 
    export LD_LIBRARY_PATH=/opt/openmpi/lib:$LD_LIBRARY_PATH

Po prenosu vsebnika na Vego naložimo enako različico MPI: 

module load OpenMPI/4.1.6

Nato aplikacijo zaženemo s sistemom MPI:

mpirun -np 4 apptainer exec my_container.sif /usr/local/bin/myprogram

Pomembno: Različica MPI v vsebniku mora biti enaka različici MPI na Vegi (npr. OpenMPI 4.1.6). Če se različici razlikujeta, lahko pride do napak pri zagonu ali nezdružljivosti.

Uporaba GPU aplikacije v Apptainer vsebniku (CUDA)

Apptainer omogoča uporabo NVIDIA GPU naprav v vsebniku z možnostjo --nv. Pri tem se v vsebnik prenesejo potrebne NVIDIA knjižnice iz gostiteljskega sistema (Vega), medtem ko vsebnik vsebuje uporabniške CUDA knjižnice in aplikacijo.

Pomembno: Verzija CUDA v kontejnerju mora biti združljiva z NVIDIA gonilnikom, nameščenim na Vegi. Gonilnika NVIDIA ne nameščamo v kontejner.

Primer definicijske datoteke

Primer uporablja CUDA 12.4 okolje in aplikacijo, ki se prevede z uporabo nvcc in se namesti v /usr/local/bin. Definicija datoteke je podana v cuda.def:

Bootstrap: docker
From: nvidia/cuda:12.4.1-devel-ubuntu22.04

%post
    apt-get update
    apt-get install -y build-essential cmake git

    # Preverjanje CUDA okolja v vsebniku
    nvcc --version

    # Prenos izvorne kode GPU aplikacije
    cd /opt
    git clone https://github.com/example/mycudaapp.git

    # Premik v direktorij aplikacije
    cd /opt/mycudaapp

    # Priprava ločenega direktorija za gradnjo
    mkdir build
    cd build

    # Konfiguracija in prevod aplikacije
    cmake ..
    make -j$(nproc)

    # Prevedeni program kopiramo v imenik, ki je del spremenljivke PATH.
    cp mycudaapp /usr/local/bin/

%environment
    export PATH=/usr/local/cuda/bin:/usr/local/bin:$PATH
    export LD_LIBRARY_PATH=/usr/local/cuda/lib64:$LD_LIBRARY_PATH

%runscript
    exec /usr/local/bin/mycudaapp "$@"

Primer uporablja namišljeno CUDA aplikacijo z imenom mycudaapp. Pred gradnjo vsebnika mora uporabnik prilagoditi nekaj vrstic glede na svojo aplikacijo:

  • Povezavo https://github.com/example/mycudaapp.git zamenjajte z naslovom repozitorija svoje aplikacije.
  • Vrstico cd /opt/mycudaapp zamenjanjte z imenom svojega direktorija.
  • Primer predpostavlja, da projekt uporablja CMake. Če vaša aplikacija uporablja drugačen postopek gradnje, ustrezno prilagodite ukaze v razdelku %post.
  • Vrstica cp mycudaapp /usr/local/bin/ predpostavlja, da po prevajanju nastane izvršljiva datoteka z imenom mycudaapp. Če je ime programa drugačno, ga ustrezno zamenjajte.
  • V razdelku %runscript datoteko mycudaapp zamenjajte z imenom svoje izvršljive datoteke.

Gradnja vsebnika: apptainer build mycudaapp.sif cuda.def

Za zagon programa z uporabo GPU vsebinika na Vegi, najprej definiramo posel za Slurm, ki uporablja particijo gpu. V sbatch skripti pred zagonom programa naložimo modul s pravilno verzijo cuda: module load CUDA/12.4

Za več informacij glejte uradno dokumentacijo: