OCI Image Registries

It is common for users of Apptainer to use OCI registries as sources for their container images. Some registries require credentials to access certain images or even the registry itself. One method is to supply credentials for each command or set environment variables to contain the credentials for a single registry. See Authentication via Interactive Login and Authentication via Environment Variables.

Alternatively, users can supply credentials on a per-registry basis with the registry command.

Users can login to an OCI registry with the registry login command by specifying a docker:// prefix to the registry hostname:

$ apptainer registry login --username myuser docker://docker.com
Password / Token:
INFO:    Token stored in /home/myuser/.docker/config.json
INFO:    Token stored in /home/myuser/.apptainer/remote.yaml

$ apptainer registry list

URI                  SECURE?
docker://docker.com  ✓

Apptainer will automatically supply the configured credentials when interacting with DockerHub. The checkmark in the SECURE? column indicates that Apptainer will use TLS when communicating with the registry.

A user can be logged-in to multiple OCI registries at the same time:

$ apptainer registry login --username myuser docker://registry.example.com
Password / Token:
INFO:    Token stored in /home/myuser/.apptainer/remote.yaml

$ apptainer registry list

URI                            SECURE?
docker://docker.com            ✓
docker://registry.example.com  ✓

Apptainer will supply the correct credentials for the registry based on the hostname used, whenever one of the following commands is used with a docker:// or oras:// URI:

pull, push, build, exec, shell, run, instance.

Note

It is important for users to be aware that the registry login command will store the supplied credentials or tokens unencrypted in their home directory, or in whatever file has been explicitly specified via the --authfile flag (discussed below).

The --authfile flag

By default, the registry login and registry logout subcommands store data in, and remove data from, the default credentials-storage file in the user’s $HOME/.docker/docker-config.json.

However, users might be interested in storing the credentials generated by registry login in a different file. Some example use cases:

  • A user wants to generate (and consume) registry credentials as part of a batch process. More than one of these batch processes may run in parallel, with potentially different credentials, and we therefore want each of them to store credentials in a different location.

  • One user (or an administrator) wants to create credential files that will then be transferred to, and consumed by, a different user.

The registry login and registry logout subcommands therefore support an --authfile <path> flag, which specifies a custom file location for credential information to be added to (by registry login) or removed from (by registry logout):

$ apptainer registry login -u myuser --authfile ./myauthfile docker://docker.io
Password / Token:
INFO:    Token stored in ./myauthfile

Once credentials have been added to a file, that file can be used in any of the commands discussed above (pull, push, build, exec, shell, run, instance.), by passing them the same --authfile <path> flag:

$ apptainer shell --authfile myauthfile docker://placeforstuff/private1:latest
INFO:    Converting OCI blobs to SIF format
INFO:    Starting build...
Getting image source signatures
Copying blob 7264a8db6415 done   |
Copying config 913cf3a39d done   |
Writing manifest to image destination
2023/09/28 13:15:46  info unpack layer: sha256:7264a8db6415046d36d16ba98b79778e18accee6ffa71850405994cffa9be7de
INFO:    Creating SIF file...
Apptainer>

Note

If APPTAINER_DOCKER_{USERNAME,PASSWORD} or DOCKER_{USERNAME,PASSWORD} environment variables are set, they will take precedence over anything specified with the --authfile flag (or anything specified with the APPTAINER_AUTHFILE variable, discussed below). See the documentation of docker-related environment variables for details.

Finally, note that logging in when the relevant credentials already exist, and logging out when the relevant credentials are already absent, are not considered errors:

$ apptainer registry login -u myuser --authfile ./myauthfile docker://docker.io
Password / Token:
INFO:    Token stored in ./myauthfile
$ apptainer registry login -u myuser --authfile ./myauthfile docker://docker.io
Password / Token:
INFO:    Token stored in ./myauthfile
$ apptainer registry logout --authfile ./myauthfile docker://docker.io
INFO:    Token removed from ./myauthfile
INFO:    Logout succeeded
$ apptainer registry logout --authfile ./myauthfile docker://docker.io
WARNING: There is no existing login to registry "docker.io".
INFO:    Logout succeeded

APPTAINER_AUTHFILE

In lieu of using the --authfile command-line flag, the same functionality may be accessed by setting the APPTAINER_AUTHFILE environment variable, both for the registry login / registry logout commands and for the pull, push, build, exec, shell, run, instance. set of commands.