Skip to content

Latest commit

 

History

History
215 lines (170 loc) · 8.42 KB

registry.rst

File metadata and controls

215 lines (170 loc) · 8.42 KB
Raw

OCI Image Registries

It is common for users of {Singularity} to use OCI registries as sources for their container images. Some registries require credentials to access certain images or even the registry itself. Previously, the only method in {Singularity} to supply credentials to registries was to supply credentials for each command or set environment variables to contain the credentials for a single registry. See :ref:`Authentication via Interactive Login <sec:docker_login>` and :ref:`Authentication via Environment Variables <sec:docker_envvars>`.

Starting with {Singularity} 4.0, users can supply credentials on a per-registry basis with the registry command.

Note

In versions of {Singularity} starting from 3.7 but before 4.0, the functionality described here was grouped together with :ref:`remote endpoint management<endpoint>` under the remote command group. Beginning with version 4.0, this functionality has been given its own top-level command group, registry.

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

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

$ singularity registry list

URI                  SECURE?
docker://docker.com  ✓

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

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

$ singularity registry login --username myuser docker://registry.example.com
Password / Token:
INFO:    Token stored in /home/myuser/.singularity/docker-config.json

$ singularity registry list

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

{Singularity} 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 start, instance run

Note

It is important for users to be aware that the registry login command will store the supplied credentials or tokens unencrypted in your 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/.singularity/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 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):

$ singularity 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 start, instance run), by passing them the same --authfile <path> flag:

$ singularity 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...
Singularity>

The same flag is also supported when using these commands in :ref:`OCI mode <oci_runtime>`:

$ singularity shell --oci --authfile ./myauthfile docker://preminger/private1:firsttry
INFO:    Converting OCI image to OCI-SIF format
INFO:    Squashing image to single layer
INFO:    Writing OCI-SIF image
INFO:    Cleaning up.
Singularity>

Note

If SINGULARITY_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 SINGULARITY_AUTHFILE variable, discussed below). See the :ref:`documentation of docker-related environment variables <sec:docker_envvars>` 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:

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

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

$ singularity registry logout --authfile ./myauthfile docker://docker.io
INFO:    Token removed from ./myauthfile
INFO:    Logout succeeded

$ singularity registry logout --authfile ./myauthfile docker://docker.io
WARNING: There is no existing login to registry "docker.io".
INFO:    Logout succeeded

SINGULARITY_AUTHFILE

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