Definition File

Ein Defnition-File ist wie eine Bauanleitung zu verstehen für den Bau eines Containers. Immer absolute Pfade angeben bzw. Umgebungsvariablen benutzen!

Was ist ein Definition File?

Es legt fest:

• welches OS bzw. Container als Basis dient
• welche Pakete installiert werden sollen
• Umgebungsvariablen zur Laufzeit
• benötigte Files vom Host
• Metadaten und Beschreibung des Containers

Definition File eines Containers anzeigen

• wird beim Bau eines Singularity Containers in diesen gesichert
• So ist es möglich, sich das Definition File eines Containers anzeigen zu lassen:

$ singularity inspect -d CONTAINER.sif

Komponenten

• Header:
  • beschreibt KernOS bzw. Container mit Quelle
  • konfiguriert KernOS-Features
  • Linuxdistribution, genaue Version; Pakete, welche Teil der Installation sein müssen
• Sections:
  • optional
  • kann mehrere Instanzen vorhandener Sections enthalten
  • Befehle werden von /bin/sh interpretiert und akzeptieren /bin/sh Optionen
  • ausgeführt zur Buildtime oder Runtime

Header

• Bootstrap: Gibt den Bootstrap-Agent an der zum Erstellen des Kernsystems genutzt wird.

  • möglich: library, docker, shub, localimage, yum, debootstrap, arch, busybox, zypper (genaueres in Doku: https://www.sylabs.io/guides/3.2/user-guide.pdf)

  • Beispiel für einen Header:

Bootstrap: library
From: debian:7

oder

Bootstrap: library
From: ubuntu:18.04

• Jeder Bootstrap-Agent bringt seine eigenen Quellen und Funktionen mit sich. Eine kurze Übersicht der Quellen gibt es hier und eine ausführliche Beschreibung der Funktionen ist hier zu finden.

Sections

• Wenn ein Befehl fehlschlägt, wird der Build-Prozess gestoppt.
• Reihenfolge der Sections spielt keine Rolle
• Es gibt verschiedenste Sections: %setup, %files, %post, %runscript, %startscript, %test, %labels, %help

%setup

• Befehle, die außerhalb den Containers auf dem Host-System ausgeführt werden,

• werden ausgeführt, nachdem das KernOS den Container installiert worden ist,

• Filesystem des Containers kann durch Umgebungsvariable referenziert werden: $SINGULARITY_ROOTFS

• Beispiel:

%setup
 touch /file1
 touch${SINGULARITY_ROOTFS}/file2

• file1 wird auf dem Host erstellt (/)
• file2 wird im Container erstellt (/)

• Für das Kopieren von Files wird %files empfohlen, da %setup als einzige Section mit erweiterten Privilegien (Root) ausgeführt wird.

%files

• zum Kopieren von Dateien aus dem Host-System in den Container

• Jede Zeile besteht aus einem Paar von zwei Pfaden, welche den Quellpfad auf dem Host-System und den Zielpfad im Container angibt.
• Der Zielpfad ist optional und ist gleich dem Quellpfad, falls dieser weggelassen werden sollte.
• Beispiel:

%files
 /file1
 /file1 /opt

%environment

• Hier werden Umgebungsvariablen definiert, welche während der Runtime zur Verfügung stehen.

• Variablen, die hier definiert werden, stehen nicht während der Buildtime zur Verfügung (%post wäre hier die Wahl).

• Es gelten die selben Konventionen wie in den .baschrc oder .profile Files.
• Beispiel:

%environment
 export LISTEN_PORT=12345
 export LC_ALL=C

• Weitere Umgebungsvariablen können während der Runtime in %post definiert werden.

• %environment schreibt die Umgebungsvariablen in /.singularity.d/env/90-environment.sh

• In %post definierte Umgebungsvariablen landen in /.singularity.d/env/91-environment.sh.

• %post-Umgebungsvariablen haben Vorrang gegenüber %environment-Variablen während der Laufzeit.

%post

• Befehle werden ausgeführt, nachdem das KernOS installiert wurde.

• Hier werden Dateien heruntergeladen, neue Software und Libraries installiert, Config-Files erstellt, neue Verzeichnisse angelegt, usw.
• Beispiel:

%post
 apt-get update && apt-get install -y netcat
 NOW=`date`
 echo "export NOW=\"${NOW}\"" >> $SINGULARITY_ENVIRONMENT

• Um neue Umgebungsvariablen zu definieren, wird hier $SINGULARITY_ENVIRONMENT benutzt.

• %post-Umgebungsvariablen haben Vorrang gegenüber %environment-Variablen während der Laufzeit

%runscript

• Befehle werden zur Runtime ausgeführt (durch singularity run oder exec)

• Argumente, welche beim Start mitgegeben werden, werden hier genutzt
• Beispiel:

%runscript
 echo "Container was created $NOW"
 echo "Arguments received: $*"
 exec echo "$@"

• Konsolen-Output:

$ ./my_container.sif
Container was created Thu Dec  6 20:01:56 UTC 2018
Arguments received:

oder

$ ./my_container.sif this that and the other
Container was created Thu Dec  6 20:01:56 UTC 2018
Arguments received: this that and the other
this that and the other

%startscript

• Befehle werden ausgeführt, wenn instance start Befehl genutzt wird, welcher eine Container-Instanz startet.

• Beispiel:

%startscript
 nc -lp $LISTEN_PORT

• Container-Instanz lässt sich starten und stoppen mit:

$ singularity instance start my_container.sif instance1
$ lsof | grep LISTEN
$ singularity instance stop instance1

%test

• Befehle werden am Ende des Build-Prozesses ausgeführt.

• alternativ auch über den test-Befehl ausführbar
• Hier sollten Dinge wie BaseOS-Version, heruntergeladene Dateien und Softwarefunktionalität validiert werden.
• Beispiel:

%test
 grep -q NAME=\"U buntu\"/etc/os-release
 if[ $? -eq 0 ]; then
        echo "Container base is Ubuntu as expected."
 else
        echo "Container base is not Ubuntu."
 fi

• zum Überspringen des Testskripts beim Bauen eines Container den Parameter --notest benutzen: $ sudo singularity build --notest my_container.sif my_container.def

%labels

• Enthält Metadaten, welche in das File /.singularity.d/labels.json im Container abgespeichert werden.

• Jede Zeile besteht auch einem Name-Value-Paar.
• Beispiel:

%labels
 Author d@sylabs.io
 Version v0.0.1

• Metadaten eines Containers (%labels) abrufbar mit:

$ singularity inspect my_container.sif

%help

• enthält einen beliebigen Text, welcher mit dem "run-help Befehl" aufgerufen werden kann: $ singularity run-help my_container.sif

• Hier sollte eine Beschreibung des Containers, ähnlich einer Dokumentation, stehen.
• Gerade im Sinne der Reproduzierbarkeit können hier die Versionen der Softwarekomponenten angegeben werden.
• Es handelt sich also nur um einem Textbaustein, welcher keine weitere Funktion erfüllt, als als genau dieser angezeigt zu werden. Bei Änderungen des Containers sollte darauf geachtet werden, dass die $help-Section angepasst wird.
• Beispiel:

%help
 This is a demo container used to illustrate a def file that uses allsupported sections.

Zeitliche Einordnung der Komponenten

• Außen vor sind die für Metadaten zuständige Sections %help und %labels, da deren zeitliche Abfolge irrelevant sind.
• Unterteilung in Build-Prozess und Runtime:
• Build-Prozess:
  • Zuerst findet das Bootstrapping statt, also das Erstellen eines KernOS im Container.
  • Als nächstes wird das Skript der %setup-Section mit root-Rechten auf dem Host-System ausgeführt.
  • Anschließende Schritte beeinflussen nur noch den Container.
  • Schließlich wird der Build-Prozess mit den Skripten der %files- und %post-Section beendet, ab jetzt ohne erweiterte Privilegien.
  • An den Build-Prozess schließt das Skript der %test-Section an.
• Runtime:
  • Zuerst werden die Umgebungsvariablen durch die %environment-Section definiert.
  • Je nach Befehl wird das Skript der %runscript-Section (exec, run) oder das Skript der %startscript-Section (start) ausgeführt.

Beispiel für ein komplettes Definition-File

Bootstrap: library
From: ubuntu:18.04

%setup
touch /file1
touch${SINGULARITY_ROOTFS}/file2

%files
/file1
/file1 /opt

%environment
export LISTEN_PORT=12345
export LC_ALL=C

%post
apt-get update && apt-get install -y netcat
NOW=`date`echo "
export NOW=\"${NOW}\"" >> $SINGULARITY_ENVIRONMENT

%runscript
echo "Container was created $NOW"
echo "Arguments received: $*"exec echo "$@"

%startscript
nc -lp $LISTEN_PORT

%test
grep -q NAME=\"Ubuntu\"/etc/os-release
if[ $? -eq 0 ];then
echo "Container base is Ubuntu as expected."
else
echo "Container base is not Ubuntu."
fi

%labels
Author d@sylabs.io
Version v0.0.1

%help
This is a demo container used to illustrate a def file that uses allsupported sections.