BwUniCluster2.0/Containers

Introduction

To date, only few container runtime environments integrate well with HPC environments due to security concerns and differing assumptions in some areas.

For example native Docker environments require elevated privileges, which is not an option on shared HPC resources. Docker's "rootless mode" is also currently not supported on our HPC systems because it does not support necessary features such as cgroups resource controls, security profiles, overlay networks, furthermore GPU passthrough is difficult. Necessary subuid (newuidmap) and subgid (newgidmap) settings may impose security issues.

On bwUniCluster the container runtimes Enroot and Singularity/Apptainer are supported.

Further rootless container runtime environments (Podman, …) might be supported in the future, depending on how support for e.g. network interconnects, security features and HPC file systems develops.

ENROOT

Enroot enables you to run Docker containers on HPC systems. It is developed by NVIDIA. It is the recommended tool to use containers on bwUniCluster and integrates well with GPU usage and has basically no impact on performance. Enroot is available to all users by default.

Usage

Excellent documentation is provided on NVIDIA's github page. This documentation here therefore confines itself to simple examples to get to know the essential functionalities.

Using Docker containers with Enroot requires three steps:

• Importing an image
• Creating a container
• Starting a container

Optionally containers can also be exported and transferred.

Importing a container image

• enroot import docker://alpine
  This pulls the latest alpine image from dockerhub (default registry). You will obtain the file alpine.sqsh.

• enroot import docker://nvcr.io#nvidia/pytorch:21.04-py3
  This pulls the pytorch image version 21.04-py3 from NVIDIA's NGC registry. Please note that the NGC registry does not always contain the "latest" tag and instead requires the specification of a dedicated version. You will obtain the file nvidia+pytorch+21.04-py3.sqsh.

• enroot import docker://registry.scc.kit.edu#myProject/myImage:latest
  This pulls your latest image from the KIT registry. You obtain the file myImage.sqsh.

Creating a container

Create a container named "nvidia+pytorch+21.04-py3" by unpacking the .sqsh-file.

enroot create --name nvidia+pytorch+21.04-py3 nvidia+pytorch+21.04-py3.sqsh

"Creating" a container means that the squashed container image is unpacked inside $ENROOT_DATA_PATH/. By default this variable points to $HOME/.local/share/enroot/.

Starting a container

• Start the container nvidia+pytorch+21.04-py3 in read-write mode (--rw) and run bash inside the container.
  enroot start --rw nvidia+pytorch+21.04-py3 bash

• Start container in --rw-mode and get root access (--root) inside the container.
  enroot start --root --rw nvidia+pytorch+21.04-py3 bash
  You can now install software with root privileges, depending on the containerized Linux distribution e.g. with
  apt-get install … , apk add …, yum install …, pacman -S …

• Start container and mount (-m) a local directory to /work inside the container.
  enroot start -m <localDir>:/work --rw nvidia+pytorch+21.04-py3 bash

• Start container, mount a directory and start the application jupyter lab.
  enroot start -m <localDir>:/work --rw nvidia+pytorch+21.04-py3 jupyter lab

Exporting and transfering containers

If you intend to use Docker images which you built e.g. on your local desktop, and transfer them somewhere else, there are several possibilities to do so:

• enroot import --output myImage.sqsh dockerd://myImage
  Import an image from the locally running Docker daemon. Copy the .sqsh-file to bwUniCluster and import it with enroot import.

• enroot export --output myImage.sqsh myImage
  Export an existing enroot container. Copy the .sqsh-file to bwUniCluster and import it with enroot import.

• enroot bundle --output myImage.run myImage.sqsh
  Create a self extracting bundle from a container image. Copy the .run-file to bwUniCluster. You can run the self extracting image via ./myImage.run even if enroot is not installed!

Container management

You can list all containers on the system and additional information (--fancy parameter) with the enroot list command.

The unpacked images can be removed with the enroot remove command.

SLURM Integration

Enroot allows you to run containerized applications non-interactively, including MPI- and multi-node parallelism. The necessary Slurm integration is realized via the Pyxis plugin.

Create Container via enroot

• enroot import docker://ubuntu
• enroot create -n pyxis_ubuntu ubuntu.sqsh

Adding pyxis_ is a must for the pyxis plugin to work

Start via Slurm

Start existing Container:

• salloc -p dev_single -t 00:10:00 --container-name=ubuntu --container-mounts=/etc/slurm/task_prolog:/etc/slurm/task_prolog,/scratch:/scratch

Download and start Container via pyxis directly:

• salloc -p dev_single -t 00:10:00 --container-image=docker://ubuntu --container-name=ubuntu --container-mounts=/etc/slurm/task_prolog:/etc/slurm/task_prolog,/scratch:/scratch

In this case an enroot Container is created under ~./local/share/enroot/

Note: --container-mounts=/etc/slurm/task_prolog:/etc/slurm/task_prolog,/scratch:/scratch is needed for the plugin to work!! The Container name has to start with pyxis_ for the Plugin to work. When using the second Method this is done automatically. Furthermore when specifying the container name in your slurm Job the pyxis_ has to be omitted.

All options usable for pyxis can be found via srun --help under "Options provided by plugins:"

Notable Options:

• --container-mount-home Mounts the home directory into the container
• --container-writable Makes the container filesystem writable (otherwise only the mounted home is writebale)
• --container-remap-root Become root in your container. Allows installation of software via e.G apt(ubuntu)

FAQ

• How can I run JupyterLab in a container and connect to it?
  • Start an interactive session with or without GPUs. Notice the compute node ID the session is running on, and start a container with a running JupyterLab, e.g.:
    salloc -p gpu_4 --time=01:00:00 --gres=gpu:1
enroot start -m <localDir>:/work --rw nvidia+pytorch+21.04-py3 jupyter lab
  • Open a terminal on your desktop and create a SSH-tunnel to the running JupyterLab instance on the compute node. Insert the node ID, where the interactive session is running on:
    ssh -L8888:<computeNodeID>:8888 <yourAccount>@uc2.scc.kit.edu
  • Open a web browser and open the URL localhost:8888
  • Enter the token, which is visible in the output of the first terminal.
    Copy the string behind the token= and paste it into the input field in the browser.

• Are GPUs accessible from within a running container?
  Yes.
  Unlike Docker, Enroot does not need further command line options to enable GPU passthrough like --runtime=nvidia or --privileged.

• Is there something like enroot-compose?
  AFAIK no.
  Enroot is mainly intended for HPC workloads, not for operating multi-container applications. However, starting and running these applications separately is possible.

• Can I use workspaces to store containers?
  Yes.
  You can define the location of configuration files and storage with environment variables. The ENROOT_DATA_PATH variable should be set accordingly. Please refer to NVIDIA's documentation on runtime configuration.

Additional resources

Source code: https://github.com/NVIDIA/enroot

Documentation: https://github.com/NVIDIA/enroot/blob/master/doc

Additional information:

• FOSDEM 2020 talk + slides
• Slurm User Group Meeting 2019 talk

Singularity/Apptainer

Usage

Excellent documentation is provided on the Documentation&Examples page provided by Sylabs. This documentation here therefore confines itself to simple examples to get to know the essential functionalities.

Using Singularity/Apptainer usually involves two steps:

• Building a container image using singularity build

• Running a container image using singularity run or singularity exec

Building an image

• singularity build ubuntu.sif library://ubuntu
  This pulls the latest Ubuntu image from Singularity's Container Library and locally creates a container image file called ubuntu.sif.

• singularity build alpine.sif docker://alpine
  This pulls the latest alpine image from Dockerhub and locally creates a container image file called alpine.sif.

• singularity build pytorch-21.04-p3.sif docker://nvcr.io#nvidia/pytorch:21.04-py3
  This pulls the latest pytorch image from NVIDIA's NGC registry and locally creates a container image file called pytorch-21.04-p3.sif.

Running an image

• singularity shell ubuntu.sif
  Start a shell in the Ubuntu container.

• singularity run alpine.sif
  Start the container alpine.sif and run the default runscript provided by the image.

• singularity exec alpine.sif /bin/ls
  Start the container alpine.sif and run the /bin/ls command.

Container management

You can use the singularity search command to search for images on Singularity's Container Library.