Apptainer-kontit

Tässä osiossa annetaan ohjeet konttien rakentamiseen ja ajamiseen Apptainerilla CSC:n supertietokoneilla. Vaikka keskitymme CSC-kohtaiseen käyttöön ja parhaisiin käytäntöihin, virallinen Apptainer-dokumentaatio toimii kattavana yleiskäytön viitteenä. Käytännönläheisiä ohjeita löydät Esimerkit -osiosta, joka sisältää CSC-järjestelmiin räätälöityjä konkreettisia esimerkkejä.

Huomaa, että Apptainer tunnettiin aiemmin nimellä Singularity, ja vanha nimi voi edelleen tulla vastaan ohjelmiston sisäisissä osissa ja vanhassa dokumentaatiossa. Projekti nimettiin uudelleen, kun se siirtyi Sylabsilta Linux Foundationille, mutta ydintoiminnallisuus pysyi samana. Sylabs ylläpitää projektista haarautusta nimeltä SingularityCE.

Miksi käyttää Apptaineria

Apptainer-kontti-imago on yksi pakattu tiedosto, joka sisältää kaiken sovelluksen ajamiseen tarvittavan. Tämä muuttumaton tiedosto sisältää täydellisen juuritiedostojärjestelmän, mukaan lukien kaikki sovellukset, kirjastot ja riippuvuudet, sekä metadataa, kuten ympäristömuuttujia ja ajonaikaisia asetuksia. Apptainer käyttää imageilleen Singularity Image Format (SIF) -muotoa, jonka tunnistaa .sif-tiedostopäätteestä.

Apptainer-konttien avulla voit valita pohjaimageksi minkä tahansa Linux-jakelun, kuten Ubuntun, Rocky Linuxin tai OpenSUSEn, ja hyödyntää sen omaa paketinhallintaa ohjelmistojen asentamiseen kyseisessä ympäristössä. Konttien rakentamiseen CSC:n supertietokoneilla liittyy kuitenkin tiettyjä rajoituksia, erityisesti silloin, kun valittu pohjaimage poikkeaa isäntäjärjestelmän Linux-jakelusta. Näitä ongelmia ja niiden ratkaisuja käsitellään tarkemmin myöhemmin.

Ohjelmiston ajaminen Apptainer-kontista voi merkittävästi parantaa käynnistysaikoja ja vähentää I/O-pullonkauloja Lustre rinnakkaistiedostojärjestelmässä. Tämä on erityisen hyödyllistä sovelluksille, jotka sisältävät paljon tiedostoja tai lataavat käynnistyksen aikana suuren määrän jaettuja kirjastoja. Esimerkiksi Python-ympäristöt ovat tunnettuja tästä ongelmasta laajojen moduuliriippuvuuksiensa ja dynaamisen latauskäyttäytymisensä vuoksi.

Apptainer-kontit varmistavat toistettavan ajon, koska niiden imagot ovat muuttumattomia. Kun kontti-imago on kerran rakennettu, se pysyy muuttumattomana, mikä takaa yhdenmukaisen toiminnan eri järjestelmissä ja ajan kuluessa. Lisäksi Apptainerin build-määrittelyt dokumentoivat tarkasti vaiheet, paketit ja asetukset, joilla kontti on luotu, mikä tekee koko rakennusprosessista läpinäkyvän ja toistettavan.

Kontti-imageilla on yksi tärkeä rajoitus: ne eivät ole yhdisteltäviä. Toisin kuin perinteisissä paketinhallintajärjestelmissä, joissa ohjelmistoja voidaan lisätä järjestelmään vähitellen, olemassa olevia kontteja ei voi yksinkertaisesti yhdistää uuden kontin luomiseksi. Esimerkiksi se, että sinulla on yksi kontti Pythonille ja toinen R:lle, ei anna pääsyä molempiin ympäristöihin samanaikaisesti. Jos haluat käyttää molempia työkaluja yhdessä, sinun on luotava uusi kontti-imago, joka sisältää sekä Python- että R-asennukset alusta alkaen.

Konttien ajaminen

Apptainerin käyttäminen suoraan

Oletetaan, että meillä on kontti-imago nimeltä container.sif. Voimme suorittaa mielivaltaisen komennon (korvaa mycommand) kontin sisällä komennolla apptainer exec seuraavasti:

apptainer exec container.sif mycommand

Voimme tuoda isäntäjärjestelmän hakemistoja kontin sisälle bind mounttien avulla. Roihussa voimme liittää eri levyalueet konttiin käsin seuraavasti:

apptainer exec --bind="/users,/projappl,/scratch,/dataset,$TMPDIR,$LOCAL_SCRATCH" container.sif mycommand

Käytön helpottamiseksi voimme käyttää komentoa csc-common-bind, joka tulostaa yleisten levyalueiden listan, jolloin niitä ei tarvitse kirjoittaa itse:

apptainer exec --bind="$(csc-common-bind)" container.sif mycommand

Roihu-GPU:ssa voimme lisätä Nvidia GPU -tuen --nv-valitsimella seuraavasti:

apptainer exec --nv container.sif mycommand

Voimme käyttää samoja valitsimia myös komentojen apptainer run ja apptainer shell kanssa.

Kontti-imagejen rakentaminen

Tässä osiossa kerrotaan, miten Apptainerilla muunnetaan olemassa olevia Docker- ja OCI-imageja SIF-imageiksi, miten rakennetaan uusia SIF-imageja määrittelytiedostoista ja miten kontteja voidaan kehittää interaktiivisesti muokattavana sandboxina eli (ch)root-hakemistona. Lisäksi käsittelemme, miten rakennusympäristö määritetään Roihussa: missä rakennetaan ja mitä väliaikais-, välimuisti- ja bind mount -hakemistoja käytetään.

Linux-jakelun valitseminen pohjaimageksi

Kun valitset kontillesi pohjaimagen, voit valita useista Linux-jakeluista, joilla kullakin on oma paketinhallintansa. Red Hat Enterprise Linux (RHEL) -pohjaisille jakeluille, jotka käyttävät DNF-paketinhallintaa, suosittuja vaihtoehtoja ovat RedHat Universal Base Images (UBI), joita on saatavilla imageina redhat/ubi8 ja redhat/ubi9, sekä yhteisövetoiset vaihtoehdot kuten rockylinux ja almalinux. Jos suosit SUSE-pohjaisia järjestelmiä, joissa käytetään Zypper-paketinhallintaa, opensuse/leap tarjoaa vakaan perustan. Debian-pohjaisissa jakeluissa, joissa käytetään APT-paketinhallintaa, sekä debian että ubuntu tarjoavat hyvin ylläpidettyjä pohjaimageja laajoilla pakettivarastoilla.

Vaikka Apptainer sallii konttien rakentamisen käyttäen mitä tahansa Linux-jakelua pohjaimagena, rakentamiseen CSC:n supertietokoneilla liittyy joitakin rajoituksia, koska käytössä on Apptainerin fakeroot-tila ilman unprivileged user namespaceja. Tässä ympäristössä tietyt etuoikeutetut komennot, joita suoritetaan tavallisesti pakettien asennuksen aikana, epäonnistuvat. Esimerkiksi paketinhallinnat suorittavat usein etuoikeutettuja komentoja, kuten useradd ja groupadd, osana asennusskriptejään, ja nämä epäonnistuvat fakeroot-ympäristössä.

Käyttämällä pohjaimagea samasta tuoteperheestä kuin isäntäjärjestelmä voidaan vähentää fakeroot-tilan käytöstä konttien rakentamisessa aiheutuvien ongelmien määrää. Jos käytät pohjaimagea, joka ei ole samasta tuoteperheestä kuin isäntäjärjestelmä, varaudu siihen, että useampia paketteja ei voida asentaa onnistuneesti. Paras tapa selvittää tämä on kokeilla kontin rakentamista.

Voit tunnistaa isäntäjärjestelmäsi Linux-jakelun seuraavasti:

cat /etc/os-release

stdout

NAME="Red Hat Enterprise Linux"
VERSION="9.8 (Plow)"
ID="rhel"
ID_LIKE="fedora"
VERSION_ID="9.8"
...

Vaikka pohjaimage vastaisi isäntäjärjestelmää, jotkin pakettien asennusskriptit kutsuvat silti yllä mainittuja etuoikeutettuja komentoja. Voimme kiertää tämän korvaamalla ongelmalliset komennot valeversioilla, jotka onnistuvat aina:

cp /usr/bin/true /usr/sbin/useradd
cp /usr/bin/true /usr/sbin/groupadd

Tämä lähestymistapa mahdollistaa pakettien asennuksen onnistumisen samalla, kun käyttöoikeuksiin liittyvät virheet ohitetaan.

Ohjelmistojen asentaminen konttiin

Tyypillinen tapa asentaa ohjelmistoja konttiin on aloittaa käyttämällä järjestelmän paketinhallintaa, kuten DNF:ää, APT:tä tai Zypperiä, "järjestelmätason" ohjelmistojen asentamiseen hakemistoon /usr, ja asentaa sen jälkeen ohjelmistoja käyttäjätilan paketinhallinnalla, kuten Pipillä, Condalla tai Spackilla, tai asentaa ohjelmistoja käsin hakemistoon /usr/local tai yksilölliseen hakemistoon polun /opt alle.

Rakennuspaikka

Roihussa voimme rakentaa kontteja kirjautumissolmuilla ja laskentasolmuilla. Huomaa, että Roihu-CPU:ssa ja Roihu-GPU:ssa on eri prosessoriarkkitehtuurit, joten rakenna kontti samalla puolella, jolla aiot sitä ajaa. Rakentaaksemme laskentasolmulla voimme varata interaktiivisen Slurm-työn seuraavasti:

sinteractive --cores 4 --mem 4000 --time 0:15:00

Väliaikaishakemisto

Ympäristömuuttujan TMPDIR on osoitettava paikalliselle levylle. Apptainer käyttää sitä tunnistaakseen hakemiston väliaikaishakemistokseen kontin rakentamisen aikana. Roihu asettaa ympäristömuuttujan TMPDIR automaattisesti kirjautumissolmuilla ja kaikissa töissä. Paikallista levyä ei tarvitse varata erikseen, eikä se kuluta laskutusyksiköitä (BUs). Saatavilla oleva kapasiteetti riippuu solmusta: kirjautumissolmuilla 80 GB ja töissä 20 GiB:stä useisiin teratavuihin allokaatiotyypistä riippuen. Katso tarkat määrät kohdasta Roihun levyalueet. Lustren rinnakkaistiedostojärjestelmää ei voi (eikä pidä) käyttää väliaikaishakemistona.

Välimuistihakemisto

Apptainer tallentaa kerrokset ja blobit, kuten pohjaimaget, välimuistihakemistoon. Oletussijainti on kotihakemistossa ($HOME/.apptainer), jossa Roihussa on 15 GiB:n kiintiö, jonka jo yksi pohjaimage voi ylittää. Siksi suosittelemme vaihtamaan välimuistin sijainnin scratch-alueelle (korvaa <project> omalla projektillasi):

export APPTAINER_CACHEDIR=/scratch/<project>/$USER/.apptainer

Scratch-alueella oleva välimuisti säilyy istuntojen välillä, joten toistuvat rakennukset voivat hyödyntää jo ladattuja kerroksia uudelleen. Vastapainona Lustre on paikallislevyä hitaampi, ja välimuisti lasketaan mukaan scratch-alueen 250 GiB:n kiintiöön. Jos tarvitset välimuistia vain yhtä rakennusta varten, aseta sen sijaan APPTAINER_CACHEDIR=$TMPDIR, jolloin se katoaa istunnon päättyessä.

Voimme myös tarvittaessa tyhjentää välimuistihakemiston:

apptainer cache clean

Väliaikaishakemiston bind mounttaus

Oletuksena Apptainer bind mounttaa isäntäjärjestelmän /tmp-hakemiston rakennusympäristön /tmp-hakemistoksi. Roihussa /tmp:n koko on kuitenkin rajallinen, joten bind mounttaamme paikallislevyn ($TMPDIR) hakemistoon /tmp, jotta levytila ei lopu kesken, seuraavasti: --bind="$TMPDIR:/tmp".

SIF-imagen rakentaminen olemassa olevasta Docker- tai OCI-imagesta

Voimme hakea olemassa olevia kontti-imageja konttirekisteristä pullaamalla ne. Apptainer muuntaa ne Docker- tai OCI-muodosta Singularity Image Format (SIF) -muotoon.

apptainer build rockylinux.sif docker://docker.io/rockylinux/rockylinux:9.8

SIF-imagen rakentaminen määrittelytiedostosta

Apptainerin määrittelytiedostot kirjoitetaan käyttäen .def-tiedostopäätettä. Tässä on yksinkertainen esimerkki kontin määrittelystä:

container.def

Bootstrap: docker
From: docker.io/rockylinux/rockylinux:9.8

%post
    # Replace the failing commands with always succeeding dummies.
    cp /usr/bin/true /usr/sbin/useradd
    cp /usr/bin/true /usr/sbin/groupadd

    # Continue to install software into the container normally.
    dnf -y update  # would fail without the dummies

Voimme kutsua Apptaineria rakentamaan kontin (container.sif) määrittelytiedostosta (container.def) käyttäen fakerootia seuraavasti:

apptainer build --fakeroot --bind="$TMPDIR:/tmp" container.sif container.def

Katso lisää esimerkkejä Apptainerin määrittelytiedostoista Esimerkit -osiosta.

Kehittäminen interaktiivisella sandboxilla

Voimme myös rakentaa Apptainer-sandboxeja fakerootilla. Sandboxit ovat hyödyllisiä konttien interaktiiviseen kehittämiseen. Sandbox on luotava paikalliselle levylle ($TMPDIR), ei Lustren rinnakkaistiedostojärjestelmään.

Voimme alustaa sandboxin pohjaimagesta seuraavasti:

apptainer build --fakeroot --sandbox "$TMPDIR/rockylinux" docker://docker.io/rockylinux/rockylinux:9.8

Sen jälkeen voimme käynnistää shellin sandboxissa ja asentaa siihen ohjelmistoja:

apptainer shell --fakeroot --writable --contain --cleanenv --bind="$TMPDIR:/tmp" "$TMPDIR/rockylinux"

Voimme käyttää samoja keinoja epäonnistuvien komentojen korvaamiseen sandboxissa:

cp /usr/bin/true /usr/sbin/useradd
cp /usr/bin/true /usr/sbin/groupadd

Nyt voimme asentaa ohjelmistoja normaalisti:

dnf -y update

Roihun pohjaimaget

CSC tarjoaa erilliset pohjaimaget sekä Roihu-CPU:lle että Roihu-GPU:lle. Nämä pohjaimaget on rakennettu Rocky Linux 9 -imagejen päälle. Jokainen image sisältää yhden Spackilla rakennetun ohjelmistopinon sekä sen riippuvuudet ja modulefile-tiedostot ympäristön aktivoimiseksi. Ohjelmistoversiot vastaavat järjestelmäohjelmistojen versioita.

Pohjaimagejen avulla voit rakentaa kontteja, joiden ohjelmistopino on identtinen alustan kanssa, kuten optimoituja MPI-kontteja. Tuloksena syntyvät kontti-imaget ovat omavaraisia eivätkä vaadi binäärien bind mounttausta ajon aikana. Nämä kontit eivät kuitenkaan ole siirrettäviä muihin koneisiin. Kontti-imaget ovat saatavilla OCI-muodossa Satamassa, joka on CSC:n kontti-imagerekisteri.

Roihu-CPU-solmut käyttävät x86_64-prosessoreita, kun taas Roihu-GPU-solmut käyttävät Arm-pohjaisia (aarch64) Nvidia Grace -prosessoreita. CPU-pohjaimaget on siksi rakennettu x86_64:lle ja GPU-pohjaimaget aarch64:lle, eikä toiselle puolelle rakennettu kontti toimi toisella. Rakenna konttisi sillä kirjautumissolmulla, joka vastaa niitä solmuja, joilla aiot ajaa niitä: roihu-cpu.csc.fi tai roihu-gpu.csc.fi. Samasta syystä konttirekisterin pohjaimage toimii vain, jos siitä on saatavilla rakennus käyttämällesi arkkitehtuurille.

Roihu-CPU:n pohjaimaget ovat seuraavat:

satama.csc.fi/r_installation_spack/core-cpu-gcc-15.2.0:v2026_03 (4.54 GB)

Roihu-GPU:n pohjaimaget ovat seuraavat:

satama.csc.fi/r_installation_spack/core-gpu-gcc-15.2.0-cuda-13.1.1:v2026_03 (13.7 GB)
satama.csc.fi/r_installation_spack/core-gpu-gcc-14.3.0-cuda-12.9.1:v2026_03 (15.9 GB)
satama.csc.fi/r_installation_spack/core-gpu-gcc-13.4.0-cuda-12.6.3:v2026_03 (13.5 GB)

Käytännön käyttöä varten katso esimerkit Roihu-CPU-pohjakontin rakentamisesta ja ajamisesta OSU micro benchmarks -ohjelmistolla sekä Roihu-GPU-pohjakontin rakentamisesta ja ajamisesta NCCL-testeillä.

Koneoppimiseen tarkoitetut pohjaimaget Roihu-GPU:lle

Yllä kuvattujen yleisten pohjaimagejen lisäksi, joiden tavoitteena on toistaa Roihun ympäristö mahdollisimman tarkasti, on olemassa myös vaihtoehtoinen joukko Rocky Linux 9:ään perustuvia pohjaimageja, joihin Python 3, MPI ja CUDA on asennettu tavallisilla Rocky Linuxin RPM-paketeilla Spackin sijaan. Tämä lähestymistapa tuottaa kontin, joka ei ole identtinen Roihun isäntäjärjestelmän kanssa, mutta jota voi joissakin tapauksissa olla helpompi laajentaa kuin yleisiä kontteja. Huomaa, että nämä imaget ovat vain Roihu-GPU:ta varten.

Imaget on luotu erityisesti yleisesti käytettyjen koneoppimiskehysten tarpeet huomioiden. Erityisesti CSC:n asennukset ohjelmistoille PyTorch, TensorFlow, JAX ja vLLM on tehty näitä imageja käyttäen.

Ensin on joukko ml-base-imageja, joita käytetään kaikkien muiden imagejen perustana. Ne sisältävät Python 3:n, MPI:n ja CUDAn Roihu-GPU:n kanssa yhteensopivassa kokoonpanossa.

Esimerkiksi:

satama.csc.fi/r_installation_aida/ml-base:rocky9.7_gcc12_py3.12_cuda12.9 - käyttää CUDA 12.9:ää
satama.csc.fi/r_installation_aida/ml-base:rocky9.7_gcc12_py3.12_cuda13 - käyttää CUDA 13.0:aa

PyTorchilla on kahdenlaisia imageja: pytorch-base ja pytorch. pytorch-base-image sisältää perusasennuksen PyTorchista sekä suuren joukon olennaisia paketteja, jotka on asennettu Python Package Indexin (PyPI) kautta, mukaan lukien Accelerate, Dask, JupyterLab, Pandas, Scikit-learn ja Transformers. pytorch-image lisää mukaan monimutkaisempia asennuksia, kuten xFormers, OpenCV, ffcv, PyTorch geometric, DeepSpeed, FAISS, Flash attention ja Transformer Engine. pytorch-image on se, jota käytetään CSC:n PyTorch-asennuksessa, kun taas pytorch-base voi olla hyödyllinen kevyempänä pohjaimagena omia asennuksia varten.

satama.csc.fi/r_installation_aida/pytorch-base:2.13_cuda13_roihu
satama.csc.fi/r_installation_aida/pytorch:2.13_cuda13_roihu

Lopuksi myös TensorFlow-, JAX- ja vLLM-asennuksille on omat vastaavat konttinsa Satamassa:

satama.csc.fi/r_installation_aida/tensorflow:2.21_cuda12.9_roihu
satama.csc.fi/r_installation_aida/jax:0.10_cuda13_roihu
satama.csc.fi/r_installation_aida/vllm:0.29.0_cuda13_roihu

Kaikki imaget löytyvät Sataman r_installation_aida-repositorista. Imaget on rakennettu Podmanilla, ja kaikki niiden rakentamiseen käytetyt Podman-reseptit löytyvät GitHubista.

Voit rakentaa omia imagejasi näiden pohjalta samalla tavalla kuin muidenkin pohjaimagejen kanssa; prosessi on kuvattu aiemmin tällä sivulla. Esimerkki määrittelytiedostosta, kun rakennetaan ml-base-imagen päälle käyttäen CUDA 13.0:aa:

container.def

Bootstrap: docker
From: satama.csc.fi/r_installation_aida/ml-base:rocky9.7_gcc12_py3.12_cuda13
%post
    # Build your application here with normal Linux commands, for example:
    dnf install some_useful_rpm_package
    pip install some_useful_python_package

Koneoppimisen oppaamme sisältää myös ohjeen siitä, miten ml-base-konttiamme voi laajentaa sandboxin avulla.

Aineistojen lukeminen SquashFS-tiedostosta

Voimme myös välttää I/O-pullonkauloja aineistoissa, jotka koostuvat suuresta määrästä pieniä tiedostoja, kokoamalla ne yhdeksi SquashFS-tiedostoksi. SquashFS-tiedosto voidaan bind mountata kontin sisälle ja sitä voidaan käyttää vain luku -tilassa. Seuraava esimerkki purkaa aineiston paikalliselle levylle, luo aineistosta SquashFS-tiedoston ja siirtää sen sitten takaisin scratch-alueelle:

# Extract individual files to local drive
cd $TMPDIR
tar xf /scratch/<project>/mydataset.tar

# Create squashfs file
mksquashfs mydataset mydataset.sqfs -processors 4

# Move the resulting squashfs file back to the shared drive
mv mydataset.sqfs /scratch/<project>/

Nyt voimme bind mountata aineiston seuraavasti:

apptainer exec --bind=/scratch/<project>/mydataset.sqfs:/data:image-src=/ container.sif mycommand

Data on saatavilla kontin sisällä polussa /data.

Konttikääreet

Tykky -konttikääre on saatavilla kontitettujen Pip- ja Conda-asennusten luomiseen kääreskriptien avulla. Jos Tykky on sinulle ennestään tuttu, voit jatkaa sen käyttöä, mutta suosittelemme konttien rakentamista ja ajamista suoraan, kuten edellisissä osioissa on kuvattu.