A Note on Container URLs

Fuzzball locates and pulls containers for jobs based on URLs supplied in the Fuzzfile. The spec for these URLs is borrowed from Apptainer. A fully specified URL looks like one of the following:

[PROTOCOL]://<REGISTRY_HOST>/<NAMESPACE>/[REPOSITORY]:<TAG>

[PROTOCOL]://<REGISTRY_HOST>/<NAMESPACE>/[REPOSITORY]@sha256:<HASH>

Fuzzball will accept shorter versions of registry URLs and will try to supply sensible default values where appropriate. You can use the following information to help you specify URLs for your containers.

PROTOCOL * required

Fuzzball requires that you specify the protocol you will use to pull containers. Currently, two protocols are supported:

docker://: This protocol pulls containers in OCI format.
oras://: This protocol pulls containers in SIF format (using the OCI Registry As Storage or ORAS tool).

REGISTRY_HOST

This value tells Fuzzball where to obtain your container. If you use the docker:// protocol the values under unqualified-search-registries within /etc/containers/registries.conf (on the Fuzzball Substrate node) are searched in order. On Rocky 9, the default search order is ["registry.access.redhat.com", "registry.redhat.io", "docker.io"]. No default registry is supplied if you use the oras:// protocol.

Here are some example registry hosts that are commonly used:

docker.io: This default value will be supplied for you if you use the docker:// protocol and omit a registry.
nvcr.io: The NVIDIA container registry has a lot of HPC-specific containers many of which are optimized to use GPUs.
ghcr.io: The GitHub container registry is a popular place for users to host their containers.
us-west1-docker.pkg.dev: This is just an example showing how you might pull a container from a private registry on Google cloud. You can use any appropriate URL to pull from a private OCI registry.

NAMESPACE

OCI registries are organized by “namespaces”. In the case of common public registries like Docker Hub, these are usually the organization or user with the account who pushed the image. On some registries like Docker Hub there are special “official” images that can be pulled without supplying a namespace.

REPOSITORY * required

This is the name of the actual repository with the container image that you want to pull. Along with the protocol, this value is always require

TAG

You can use this value to specify the version of the container image that you want to access. If you omit this value, the “latest” tag will be pulled. Some images (like the official Rocky Linux image) do not have the tag “latest” and will error if you try to pull them without supplying a tag.

HASH

Instead of specifying a tag (which might be a moving target) you can pull your images by hash to help ensure that you always get a consistent container. The syntax @sha256:<HASH> allows you to do this. Pulling containers by hash is considered the best strategy for reproducibility.