apptainer-overlay

Create and manage writable overlay filesystems for containers.

TLDR

Attach a writable layer inside an existing SIF, so the image can be changed

$ apptainer overlay create --size [500] [path/to/image.sif]

Build a standalone overlay file that several images can share

$ apptainer overlay create --size [1024] [path/to/overlay.img]

Allocate it sparsely, taking disk space only as it fills

$ apptainer overlay create --size [1024] --sparse [path/to/overlay.img]

Lay it out for unprivileged fakeroot use

$ apptainer overlay create --fakeroot --size [1024] [path/to/overlay.img]

Pre-create a directory inside the overlay

$ apptainer overlay create --create-dir [/data] --size [1024] [path/to/overlay.img]

Run a container against an overlay file

$ apptainer run --overlay [path/to/overlay.img] [path/to/image.sif]

SYNOPSIS

apptainer overlay create [options] image

apptainer overlay manages EXT3 writable overlay filesystems for Apptainer containers. Overlays allow persistent writes on top of immutable SIF container images without modifying the original image.Overlays can be embedded directly into a SIF file or created as standalone image files that are attached at runtime. This enables persistent storage of modifications, logs, and user data while maintaining container immutability.

PARAMETERS

-s, --size size

Size of the EXT3 writable overlay in MiB (default: 64).

-S, --sparse

Create a sparse file instead of allocating full disk space.

-f, --fakeroot

Make the overlay layout usable by actions run with --fakeroot.

--create-dir path

Directory to create as part of the overlay layout (can be repeated).

INSTALL

sudo dnf install apptainer

sudo pacman -S apptainer

sudo apk add apptainer

sudo zypper install apptainer

brew install apptainer

nix profile install nixpkgs#apptainer

CAVEATS

Overlays require filesystem support for loop devices and EXT3. Sparse overlays save disk space but may cause performance issues with some workloads. Overlay size cannot be easily changed after creation.

RESOURCES

Source code · Homepage · Documentation