Quickstart: Running Containers with Apptainer
In this quickstart, we will pull a container image from Docker Hub onto Vista, try to use the container image, and run a GPU-enabled container on a compute node. We will cover pulling images, the shell and exec commands, the --nv flag for GPU access, and running a container inside a Slurm job script.
A working knowledge of Linux and the Vista environment is sufficient. This quickstart introduces how to run containers, not how to create or build a container image.
Apptainer is a container runtime like Docker or Singularity, and it is available on Vista as a module. Before you begin, make sure you can log into Vista, navigate the file system, and submit Slurm jobs (see Vista Quickstart: Log In and Submit a Slurm Job).
Note that Apptainer commands do not run on the login node, so we need to perform the following steps in an interactive session on a compute node with a GPU. Start an interactive session on a gh-dev compute node with idev:
Replace myproject with your project allocation name. If you only have one allocation on Vista, the -A option may be omitted.
Once the session starts, you will be on a compute node with a GPU. Load the Apptainer module and go to $SCRATCH:
Container images are pulled from registries and converted into a single Singularity Image Format (.sif) file. When an image is pulled, it is saved to the current working directory. The container is portable and you can copy it between systems just like any other file. To pull an example image from Docker Hub:
After this command, we see the file alpine_latest.sif in your current directory:
Vista's Grace CPUs use the aarch64 (arm64) architecture, so the image you pull must also be built for the arm64 architecture. Images on registries can be multi-architecture and resolve to the correct build automatically, as alpine did above. But it is always important to check before pulling an image whether it includes an arm64 build, since an image built only for amd64 cannot run on Vista. For example, the TensorFlow container is only amd64:
The pull command will succeed and the image is downloaded into the directory, but the image will not run in the Vista environment.
As we have just previewed, the shell command opens an interactive shell inside the container. Notice that the prompt changes to Apptainer>, indicating that you are now inside the container's environment:
Inside the container, your home, work, and scratch directories are all still available. This is specific to Vista, where Apptainer is configured to bind these file systems automatically. By default, Apptainer only mounts your home directory and current working directory. Listing the current directory shows your own files:
Type exit to leave the container and return to the compute node environment:
When you only need to run a single command, exec runs it directly in the container without opening an interactive shell:
To use the GPU, pull a container that is configured to run a CUDA-enabled application. NVIDIA's NGC catalog provides a PyTorch container built for the arm64 architecture, which matches Vista's Grace CPUs. This image is large, so the pull may take several minutes:
By default, a container has no access to the host's GPU. Running a command like nvidia-smi without the --nv flag would fail because the NVIDIA driver and tools are not present inside the container:
Adding the --nv flag when running the Apptainer command tells Apptainer to bind the host's NVIDIA driver and libraries into the container. The command nvidia-smi now shows the H200 GPU on the node:
You can also confirm that PyTorch detects the GPU:
If this command prints True, then the GPU is also detected by PyTorch.
For non-interactive sessions, run the container from a Slurm batch script instead of an interactive session. The container command is the same as we have described, with loading the module and adding apptainer ...: