Improve documentation for pulling and pushing to oras repositories

[myoung3]

I was curious about using azure container registry for a project and tried to use, it but unfortunately the singularity documentation for authenticating with an oras repository is lacking. azure docs for pushing and pulling with singularity are similarly absent.

In particular, several areas for improvement:

• Should I use singularity remote to store azure keys? (I now know the answer to this is no--singularity remote is only for sylabs cloud, but I only found this through stumbling on another issue either here or in the original singularity github page). This should be clarified in the singularity remote help page.
• If singularity remote is not the correct way to authenticate for an oras repo (and azure specifically), how can I authenticate singularity push and singularity pull/singularity build? Do I need to install oras separately? If so, that should be spelled out.
• It would be great if you worked with Microsoft to get them add some examples with singularity in their help files.

https://azure.microsoft.com/en-us/blog/azure-container-registry-now-supports-singularity-image-format-containers/
https://docs.microsoft.com/en-us/azure/container-registry/container-registry-image-formats
https://sylabs.io/guides/3.7/user-guide/cli/singularity_pull.html?highlight=oras
https://sylabs.io/guides/3.7/user-guide/cli/singularity_push.html?highlight=oras

[dtrudg]

Hello, this would be appropriate for the docs repository

https://github.com/sylabs/singularity-userdocs

I will transfer the issue there.

Should I use singularity remote to store azure keys? (I now know the answer to this is no--singularity remote is only for sylabs cloud

This is actually not correct. Authentication to OCI registries (which are the targets of oras) can be handled through singularity remote login per the help message for singularity remote and the information at https://sylabs.io/guides/3.7/user-guide/endpoint.html?highlight=oras#managing-oci-registries

Singularity will supply the correct credentials for the registry based off of the hostname when using the following commands with a docker:// or oras:// URI:

I agree there is much room for improvement in the documentation here though. We would also gladly accept any contributions.

[myoung3]

Ok in that case I misunderstood your comment here: apptainer/singularity-userdocs#308 (comment):

The remote command is exclusively for Sylabs cloud services, i.e. the container library library:// URLs, remote builder, key store

I now see that the singularity help for singularity remote does mention OCI. I did try to use it to authenticate azure, but when I tried singularity remote add azureregistry myazureregistry.azurecr.io it directed me to

Generate an access token at https://myazureregistry.azurecr.io/auth/tokens, and paste it here.
Token entered will be hidden for security.
Access Token:

But https://myazureregistry.azurecr.io/auth/tokens does not exist (even after replacing myazureregistry with the actual registry name). And I couldn't figure out what access token to paste into the prompt, even after poking around the azure dashboard for my registry.

So unfortunately I don't feel equipped to contribute a documentation PR because I couldn't figure out how to get it working!

[dtrudg]

Ok in that case I misunderstood your comment here: apptainer/singularity-userdocs#308 (comment):

The remote command is exclusively for Sylabs cloud services, i.e. the container library library:// URLs, remote builder, key store

@myoung3 - the comment was accurate at the time it was posted. The ability to use singularity remote login to set OCI registry auth came in 3.7.0 at the end of 2020.

To login to an oci registry use a remote login to a docker:// or oras:// URI. Do not remote add it.

See the examples at: https://sylabs.io/guides/3.7/user-guide/endpoint.html?highlight=oras#managing-oci-registries (there are also links there to how to auth via env var)

The remote commands and terminology are confusing, unfortunately. A remote endpoint is a Sylabs Cloud instance, or a Singularity Enterprise installation that provides a bunch of services, not just a container library/registry. remote add is for adding the base URI of one of these, through which all the services provided will be discovered. You can't remote add an OCI registry as it doesn't supply the other services that make up a remote endpoint.

This confusion stems from it all being written when we did not support oras, and only the Sylabs Cloud / Enterprise were supported. I'm afraid other functionality hasn't always been bolted on in the most clear manner.

Sylabs is intending to restructure the handling of auth / remotes in SingularityCE 4.0 to make it much clearer. Unfortunately this will require breaking changes to the CLI, so it hasn't been tackled yet in the 3.x releases.

[myoung3]

Thanks, that all makes sense.

In that case I think it would be helpful to clarify the help files for singularity remote add and singularity remote login:

Currently remote add says:

Create a new singularity remote endpoint

Synopsis
The ‘remote add’ command allows you to create a new remote endpoint to be be used for singularity remote services. Authentication with a newly created endpoint will occur automatically.
https://sylabs.io/guides/3.8/user-guide/cli/singularity_remote_add.html

and remote login:

Log into a singularity remote endpoint, an OCI/Docker registry or a keyserver using credentials

Synopsis
The ‘remote login’ command allows you to set credentials for a specific endpoint, an OCI/Docker registry or a keyserver. This command can produce a link directing you to the token service you can use to generate a valid token. If no endpoint or registry is specified, it will try the default remote endpoint (SylabsCloud).

https://sylabs.io/guides/3.8/user-guide/cli/singularity_remote_login.html

I found this confusing because only the documentation for remote add says it allows you to "create" a new endpoint whereas login talks only about logging into an endpoint. I interpreted this incorrectly to mean that add needs to be run before login.
Additionally, if remote add is exclusively for sylabs cloud, then that could be explicitly described in the remote add help file, along with a suggestion to look at the help file for remote login for logging into OCI registries. Hope this helps.

[dtrudg]

In 4.0.0, OCI registry related auth has been split out of the remote command to a registry command, and documentation updated. This should hopefully clarify the procedures related to this issue.