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 viitteenä yleiseen käyttöön. 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 haarautettua versiota nimeltä SingularityCE.

Perustelut

Apptainer-konttikuva 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ää kuvilleen Singularity Image Format (SIF) -muotoa, jonka tunnistaa .sif-tiedostopäätteestä.

Apptainer-konttien avulla voit valita peruskuvaksi 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 valitsemasi peruskuva eroaa 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 suorituksen, koska niiden kuvat ovat muuttumattomia. Kun konttikuva 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, joita käytettiin kontin luomiseen, mikä tekee koko rakennusprosessista läpinäkyvän ja toistettavan.

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

Konttien ajaminen

Apptainerin suora käyttö

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

apptainer exec container.sif mycommand

Voimme tuoda isäntäjärjestelmän hakemistoja kontin sisälle käyttöön 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 luettelon, 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.

Konttikuvien rakentaminen

Tässä osiossa selitetään, miten Apptainerilla muunnetaan olemassa olevia Docker- ja OCI-kuvia SIF-kuviksi, miten uusia SIF-kuvia rakennetaan 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 peruskuvaksi

Kun valitset kontillesi peruskuvaa, voit valita useista Linux-jakeluista, joilla kullakin on oma paketinhallintansa. Red Hat Enterprise Linux (RHEL) -pohjaisissa jakeluissa, jotka käyttävät DNF-paketinhallintaa, suosittuja vaihtoehtoja ovat RedHat Universal Base Images (UBI), joita on saatavilla kuvina 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ä peruskuvia laajoilla pakettivarastoilla.

Vaikka Apptainer mahdollistaa konttien rakentamisen käyttäen mitä tahansa Linux-jakelua peruskuvana, rakentamiseen CSC:n supertietokoneilla liittyy joitakin rajoituksia, koska käytössä on Apptainerin fakeroot-tila ilman käyttäjänimiavaruuksia ilman korotettuja oikeuksia. Tässä ympäristössä tietyt etuoikeutetut komennot, joita suoritetaan yleisesti 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ä peruskuvaa samasta tuoteperheestä kuin isäntäjärjestelmä vähennämme fakeroot-tilan käytöstä konttien rakentamisessa aiheutuvien ongelmien määrää. Jos käytät peruskuvaa, 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 yrittää rakentaa kontti.

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 peruskuva 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 asennusten onnistumisen samalla, kun 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 sillä puolella, jolla aiot sitä käyttää. 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 konttia rakennettaessa. 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: 80 GB kirjautumissolmuilla ja töissä 20 GiB:stä useisiin teratavuihin varaustyypistä riippuen. Katso tarkat määrät kohdasta Roihun levyalueet. Lustren rinnakkaistiedostojärjestelmää ei voi (eikä pidä) käyttää väliaikaishakemistona.

Välimuistihakemisto

Apptainer tallentaa välimuistihakemistoon kerroksia ja blob-objekteja, kuten peruskuvia. Oletussijainti on kotihakemistossa ($HOME/.apptainer), jossa Roihussa on 15 GiB:n kiintiö, jonka yksi ainoa peruskuva voi jo 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. Kääntöpuolena on, että Lustre on paikallista levyä 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 ja anna sen kadota 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össä polkuun /tmp. Roihussa /tmp:n koko on kuitenkin rajallinen, joten bind mounttaamme paikallisen levyn ($TMPDIR) polkuun /tmp, jotta levytila ei lopu kesken, seuraavasti: --bind="$TMPDIR:/tmp".

SIF-kuvan rakentaminen olemassa olevasta Docker- tai OCI-kuvasta

Voimme hakea olemassa olevia konttikuvia 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-kuvan 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 interaktiivisessa kehittämisessä. Sandbox on luotava paikalliselle levylle ($TMPDIR), ei Lustren rinnakkaistiedostojärjestelmään.

Voimme alustaa sandboxin peruskuvasta seuraavasti:

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

Sen jälkeen voimme käynnistää sandboxissa shellin 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 peruskuvat

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

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

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-peruskuvat on siksi rakennettu x86_64:lle ja GPU-peruskuvat 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 peruskuva toimii vain, jos siitä on tarjolla rakennus käyttämällesi arkkitehtuurille.

Roihu-CPU:n peruskuvat ovat seuraavat:

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

Roihu-GPU:n peruskuvat 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-peruskontin rakentamisesta ja ajamisesta OSU micro benchmarks -ohjelmistolla ja Roihu-GPU-peruskontin rakentamisesta ja ajamisesta NCCL tests -ohjelmistolla.

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 on saatavilla konttikääreenä kontitettujen Pip- ja Conda-asennusten luomiseen kääreskripteillä. Jos Tykky on sinulle ennestään tuttu, voit jatkaa sen käyttöä, mutta suosittelemme konttien rakentamista ja ajamista suoraan, kuten edellisissä osioissa on kuvattu.