Skip to content

Apptainer

Apptainer pulls the container images from configured container registries on all cluster nodes. The method used to retrieve an image depends on the system registry configuration and image availability.

Overview

Always start with the standard Apptainer pull command. Additional methods should only be used when required.

The general Apptainer pull command is the default command to pull container images:

Run on: compute node
apptainer pull \
  --name <image_name>.sif \
  --dir <image_directory> \
  --tmpdir <temporary_directory> \
  docker://<registry>/<repository>:<tag>

Note

  • --dir specifies the output directory for the final .sif image.
  • --tmpdir specifies the temporary working directory used during the pull.
  • Both directories should be located on an NFS-backed filesystem to avoid failures due to limited local disk space.

Prerequisites

  • Apptainer is installed on compute nodes.
  • NFS shared storage is configured (see Configure Mounts).
  • Verify Apptainer is installed:
Run on: compute node
apptainer --version

Procedure

Method 1: Standard Image Pull (Pulp-Integrated and Preferred)

  1. Create the directory used for both image storage and temporary files. This directory must be on an NFS-backed filesystem:

    Run on: compute node
    mkdir -p /hpc_tools/container_images

  2. Pull the image using the standard Apptainer workflow. This method automatically leverages Pulp when available and requires no changes to user behavior:

    Run on: compute node
    apptainer pull \
--name ubuntu_22.04.sif \
--dir /hpc_tools/container_images \
--tmpdir /hpc_tools/container_images \
docker://docker.io/library/ubuntu:22.04

Behavior: Registry mirror behavior is controlled by configuration files under /etc/containers/registries.conf.d/. When a Pulp registry mirror is configured and the image is present, the pull is transparently served from Pulp.

In environments where Pulp usage is required and the image is known to exist, the Pulp registry may be specified explicitly:

docker://<pulp-registry>/<namespace>/ubuntu:22.04

Replace <pulp-registry> and <namespace> with site-specific values.

Method 2: Pulling an Image Directly from the Internet (Exception Only)

Warning

  • Use this method only if: A Pulp registry mirror is configured, and The image is not available in Pulp or the mirror is unavailable.
  • Administrative privileges are required. Do not delete the configuration — disable it temporarily.

  1. Temporarily disable the container registry configuration that enforces mirroring to Pulp. This configuration is typically located under:

    /etc/containers/registries.conf.d/

  2. Pull the image directly from the public registry. Use the same NFS-backed directory for both image storage and temporary files:

    bash title="Run on: compute node" apptainer pull --disable-cache \ --name ubuntu_22.04.sif \ --dir /hpc_tools/container_images \ --tmpdir /hpc_tools/container_images \ docker://docker.io/library/ubuntu:22.04

Verification

  1. Verify the SIF image was downloaded successfully:

    Run on: compute node
    ls -lh /hpc_tools/container_images/ubuntu_22.04.sif
apptainer inspect /hpc_tools/container_images/ubuntu_22.04.sif

Note

After pulling directly from the internet, restore the registry mirror configuration so that future pulls again route through Pulp.

For detailed guidance on using Apptainer and NVIDIA HPC Benchmarks, refer to the Apptainer User Documentation.

Next Steps