Using NERSC's `registry.nersc.gov`¶

NERSC's registry.nersc.gov is a private registry with OCI (Open Container Initiative) support. It can provide storage for both container images and OCI-compliant Helm charts. Users who wish to store images in the NERSC private registry are welcome to request access to registry.nersc.gov via filing a ticket at help.nersc.gov. Users who have completed Spin training may already have access. For any user who does not have access, logging into registry.nersc.gov will fail with "Invalid user name or password."

This registry is project-based, similar to our CFS and /global/common/software filesystems. This means that each top-level project namespace can be shared between all members of a project.

As a best practice, users should generally store images and/or Helm charts in their own namespace. In the project “musicians”, we suggest that each user create and use their own namespaces underneath, for example:

registry.nersc.gov/musicians

User santana should create their own namespace under their project musicians:

registry.nersc.gov/musicians/santana

Individual projects may also agree upon other project-wide namespaces, for example:

registry.nersc.gov/musicians/smooth
registry.nersc.gov/musicians/santana
registry.nersc.gov/musicians/robthomas

smooth, a directory where users santana and robthomas can share their collaboration materials, can be decided upon by users in the musicians project.

Creating an image or Helm chart with this name/tag pattern and pushing it to registry.nersc.gov will create the desired namespace under the musicians project. For example, the user may push a container image tagged as registry.nersc.gov/musicians/smooth/radio:edit or push a Helm chart to registry.nersc.gov/musicians/smooth/radio-chart:edit. Either of these two actions will create the smooth namespace on registry.nersc.gov.

If you have questions, please don’t hesitate to file a ticket at help.nersc.gov.

Interacting with the Registry for Container Images¶

To interact with NERSC's registry.nersc.gov for container images, you can use podman-hpc. The syntax of building, tagging, and pushing images are similar to other tools like docker and podman. Below are the steps to log in, build, tag, and push a container image using podman-hpc:

First, log in to the registry using podman-hpc:

podman-hpc login registry.nersc.gov

You will be prompted to enter your username and password. Ensure you have access rights; otherwise, the login will fail with "Invalid user name or password" as described above.

Using the NERSC Registry as a Pull-Through Cache¶

The NERSC Registry supports pull-through caching for public images in the following registries:

docker.io
gcr.io
ghcr.io
gitlab.io
hub.docker.com
nvcr.io
public.ecr.aws
quay.io

Utilizing the NERSC Registry to access images in public registries generally results in faster pull times and provides protection against outages and rate limiting.

Authentication Requirements¶

On Spin: You must select registry-nersc under Pull Secrets, as authentication is required even for public images.
On Perlmutter: Log in to the NERSC Registry using the instructions provided in the Login to the Registry section.

Pulling Images Through the Pull-Through Cache¶

To use an image from Docker Hub via the pull-through cache, simply prepend the NERSC Registry URL to the Docker Hub image name.

Default Repository Example: If you are using the image python:3, pull it from the NERSC Registry with the following command:

podman-hpc pull registry.nersc.gov/docker.io/library/python:3

Non-Default Repository Example: For images in a non-default repository, omit the library element. For instance, to pull nginxinc/nginx-unprivileged, use:

podman-hpc pull registry.nersc.gov/docker.io/nginxinc/nginx-unprivileged

Build a Container Image¶

For more details, please refer to this section on building-images with podman-hpc. In short, navigate to the directory containing your Containerfile or Dockerfile and run:

podman-hpc build -t registry.nersc.gov/<project>/<namespace>/<image-name>:<tag> .

Replace <project>, <namespace>, <image-name>, and <tag> with your specific project, namespace, image name, and desired tag.

Tag the Image¶

If you need to tag an existing image, use the following command:

podman-hpc tag <local-image-name>:<local-tag> registry.nersc.gov/<project>/<namespace>/<image-name>:<tag>

This command assigns a new tag to your local image, preparing it for pushing to the registry.

Push the Image¶

Finally, push your tagged image to the registry:

podman-hpc push registry.nersc.gov/<project>/<namespace>/<image-name>:<tag>

This uploads your image to the specified namespace within the registry.

Interacting with the Registry for Helm Charts¶

For instructions on pushing, and installing Helm charts, please refer to this section for using Helm Charts from an OCI registry.

Using NERSC's registry.nersc.gov¶