Merge pull request #308 from EPCCed/container-reg

ECIR (Container Image Registry) Documentation

Author: agngrant

docs/images/registry/foundsbom.png

@@ -0,0 +1,31 @@
+# FAQ
+
+## Known Issues
+
+### Unauthorised error when logging into the registry from Docker
+
+If you have been logged in to the ECIR web UI for a long time (> 5 hours) and you attempt to login to the registry from Docker you may get an error of the form:
+
+```bash
+Error response from daemon: Get "https://registry.eidf.ac.uk/v2/": unauthorized:
+```
+
+This means the OAUTH token given to your account by the SAFE has expired, to rectify this you should logout from the ECIR web UI and then login again via the SAFE.
+
+You can check the status of your SAFE OAUTH token by visiting [safe.epcc.ed.ac.uk/TransitionServlet/Tokens/](https://safe.epcc.ed.ac.uk/TransitionServlet/Tokens/).
+
+### SBOM says no SBOM (A Missing SBOM)
+
+If you see an image you have uploaded to the registry have no attached SBOM after it has been scanned, like this:
+
+ ![NoSBOMOutputReport](../../images/registry/nosbom.png){: class="border-img"}
+   *Missing SBOM Output Report*
+
+Then you will have to click the folder icon next to the artifact name.
+
+This will open the information up for that artifact, like this:
+
+ ![FoundSBOMOutputReport](../../images/registry/foundsbom.png){: class="border-img"}
+   *Found SBOM Output Report*
+
+Some images when uploaded have additional elements packaged with them, and Harbor attaches the SBOM to the container image rather than the whole package.

docs/images/registry/nosbom.png

@@ -0,0 +1,45 @@
+# Overview
+
+EIDF Container Image Registry (ECIR) is an image registry for use in EIDF, EPCC and related services. ECIR uses [Harbor](https://goharbor.io) to provide services for image storage, vulnerability scanning and Software Bill of Materials (SBOM) generation.
+
+## Projects and Public Caches on ECIR
+
+ECIR provides projects with a private space on the service where a project can host multiple container image repositories.
+
+ECIR hosts public cache projects for commonly used images. If you use an image which is commonly pulled from public repositories, using a cache copy can reduce the impact on public services.
+
+Using ECIR for pulling and storing images should help with quick deployment and access control of images for projects. This will help reduce the overhead of EIDF Services pulling repeatedly from external registries.
+
+For information on what projects can use within an ECIR private space and Public Caches, see [ECIR Projects and Caches](./projects.md).
+
+## Working with ECIR
+
+For more information on how to work with ECIR, refer to [Working with ECIR](./working-with.md).
+
+## Features
+
+### Vulnerability scanning by Trivy
+
+All images in the ECIR will be scanned by [Trivy](https://trivy.dev/latest/) by default. A vulnerability report will be available shortly after push to the repositories for all new or updated images.
+
+The report will highlight fixable known issues.
+
+!!! Danger "Not Foolproof"
+
+    Just because Trivy indicates few or no vulnerabilities this does not mean the scanned image is free of security issues, Trivy can only scan for known issues and specific types of security problems.
+
+Projects can request that images with vulnerabilities above a set level are not deployable from the ECIR. This can be set on a project level and through a Helpdesk Request on the [EIDF Portal](https://portal.eidf.ac.uk/queries/submit).
+
+ ![TrivvyOuputReport](../../images/registry/trivvyoutput.png){: class="border-img"}
+   *Example Trivvy Output Report*
+
+### Software Bill of Materials (SBOM)
+
+SBOMs will be automatically generated on push to the ECIR and associated with an image. This will list what is in an image with its version and license information where possible. These can be downloaded for use in other tooling and distribution.
+
+ ![SBOMOutputReport](../../images/registry/sbomoutput.png){: class="border-img"}
+   *Example SBOM Output Report*
+
+## FAQ and Known Issues
+
+The FAQ and known issues can be found in the [ECIR FAQ](faq.md).

docs/images/registry/push.png

@@ -0,0 +1,112 @@
+# Projects
+
+## Projects within EIDF
+
+Every EIDF project can request that a ECIR project is created for them. An ECIR project is a namespace within the registry which contains repositories for container images private to users of that EIDF project.
+
+!!! important "ECIR Projects"
+
+    EIDF and other EPCC Projects can have ECIR Projects, all users in the owning project can access the ECIR project. The ECIR project is only for image storage and scanning. The owning project can have access to a wide range of other services.
+
+### Project Quota
+
+The default project quota for image storage will be 50 GiB.
+
+Quota increase requests should be submitted via the [EIDF Portal](https://portal.eidf.ac.uk/queries/submit).
+
+### Naming
+
+The root project name for each project will be their EIDF project number in the form:
+
+```bash
+eidfXXX
+```
+
+### Vulnerability Level Tolerance
+
+The default position of the ECIR is that all images can be deployed onto services, if a project would prefer to have a restriction on the vulnerabilities they are willing to tolerate in their projects, a request can be made to helpdesk to enforce a maximum level of vulnerability tolerance.
+
+Vulnerabilities are ranked:
+
+* Critical
+* High
+* Medium
+* Low
+
+Vulnerability scanning is provided via Trivy, more information about severity levels can be found on the [trivy documentation](https://trivy.dev/latest/docs/scanner/vulnerability/#severity-selection).
+
+### Permissions
+
+ECIR users have the [Harbor project maintainer role permissions](https://goharbor.io/docs/2.14.0/administration/managing-users/user-permissions-by-role/), this allows ECIR users to:
+
+* Create and delete repositories in their projects
+* Push and pull images from their projects
+* Initiate vulnerability and SBOM scans
+* View the results of scans
+* Edit the labels available to their projects
+
+ECIR Project maintainers **do not** have the permissions to:
+
+* Create new projects
+* Edit project configuration
+* Delete projects.
+
+## The Library and Public Caches
+
+ECIR provides a common library of standard images. ECIR provides cache projects for four major registries which allow images to be stored for 7 days after use in ECIR for convenient access.
+
+### The Library
+
+The Library is a public project containing ECIR copies of commonly used container images on the GPU Service. This will be updated over time to reflect use and updates on the service.
+
+To use an image from the Library, the image name should be preceded by `registry.eidf.ac.uk/library`, for example if an Ubuntu image with the tag `latest` were available in the Library it would be accessed with:
+
+```bash
+registry.eidf.ac.uk/library/ubuntu:latest
+```
+
+Use of images from the Library will not count towards project image storage on the ECIR.
+
+The Library will be updated as images are deprecated or updated and is read only for project users.
+
+Whilst users can use public registries to download images, ECIR aims to reduce request load on public systems and provide a local cache to speed up image access. This helps provide a consistent experience as though downloading from the source but with faster download times.
+
+Users can submit images to be added to the Library where they think these would be beneficial for many users or for images that are accessed frequently. These can be self built images or public images. These should be submit via the [EIDF helpdesk](https://portal.eidf.ac.uk/queries/submit) giving the image details, such as image source and tag(s), as well as justification for inclusion.
+
+### Public Caches
+
+Several main public registries can be routed through cache project proxies on ECIR. The cache projects mean that users can pull a public image from a public registry and the ECIR will store a copy of that image automatically. Cached images which are pulled in the following 7 day period will be retained, otherwise images not pulled for 7 days will be removed from the cache project.
+
+This is to reduce pressure on public registries from EIDF systems and to reduce the chance of the public services rate limiting.
+
+The services which have cache projects are:
+
+* Dockerhub [https://hub.docker.com](https://hub.docker.com) - Project docker-cache
+* GHCR [https://ghcr.io](https://ghcr.io) - Project ghcr-cache
+* Nvidia NGC Registry [https://nvcr.io](https://catalog.ngc.nvidia.com/) - Project nvidia-cache
+* Quay.io [https://quay.io](http://quay.io) - Project quay-cache
+
+To use a cache project, the ECIR address and the cache project name should be pre-pended to the name of the image, for example to pull the image, `nvidia/pytorch:25.05-py3` from the Nvidia (NVCR.io) registry, you would use:
+
+```bash
+registry.eidf.ac.uk/nvidia-cache/nvidia/pytorch:25.05-py3
+```
+
+For Docker, top level images can be referred to directly, such as:
+
+```bash
+registry.eidf.ac.uk/docker-cache/alpine:latest
+```
+
+Or if they are part of an organisation public repository:
+
+```bash
+registry.eidf.ac.uk/docker-cache/mcp/slack:latest
+```
+
+What to add in front of your image name:
+
+* Dockerhub: registry.eidf.ac.uk/docker-cache/
+* GHCR: registry.eidf.ac.uk/ghcr-cache/
+* Nvidia NGC Registry: registry.eidf.ac.uk/nvidia-cache/
+* Quay.io: registry.eidf.ac.uk/quay-cache/

docs/images/registry/sbomoutput.png

@@ -0,0 +1,206 @@
+# Working with ECIR
+
+## The Registry Interface and Accounts
+
+EIDF Users can access the registry through their SAFE account.
+
+The registry can be logged into at [https://registry.eidf.ac.uk](https://registry.eidf.ac.uk). If you are not logged into SAFE, the registry will redirect you to SAFE.
+
+User tokens can be accessed from the User Profile from the dropdown under your Username at the top right hand corner of the page. These will be needed to log into the registry from Docker and other container services.
+
+![UserProfile](../../images/registry/userprofile.png){: class="border-img"}
+   *Example User Profile*
+
+See the FAQ section ['Unauthorised' error when logging into the registry from Docker](./faq.md#unauthorised-error-when-logging-into-the-registry-from-docker) for help with token expiry and authorisation issues.
+
+## Push Commands
+
+In your project, there is a PUSH Command option which will give you the command templates for pushing to the Project repositories from different clients.
+
+![PushCommand](../../images/registry/push.png){: class="border-img"}
+   *Example Push Command*
+
+## Repositories
+
+Each repository in a project has a COPY PULL button option once an image/artifact has been selected for Docker and Podman.
+
+Clicking on a tag in a repository will open up the information on the artifact, this can include an overview of the image, vulnerability summary, SBOM and build history.
+
+## Using from the Command Line with Docker
+
+Important: Run these commands on a system that has Docker installed and has access to the ECIR.
+
+To login to the registry from a Docker client, you should use the following:
+
+```bash
+docker login registry.eidf.ac.uk
+```
+
+If you have previously done this and the credentials are valid, then it will confirm your login.
+
+If you have not logged in, the following prompt will appear:
+
+```bash
+Username:
+```
+
+You should enter the username (your SAFE preferred username) which appears in the User profile section of the Harbor, ECIR web interface.
+
+```bash
+Password:
+```
+
+You should copy the CLI Secret from the User Profile into this prompt.
+
+The following should appear, unless you are using a credential helper, which will remove the warning.
+
+```bash
+WARNING! Your password will be stored unencrypted in <home directory>/.docker/config.json.
+Configure a credential helper to remove this warning. See
+https://docs.docker.com/engine/reference/commandline/login/#credentials-store
+
+Login Succeeded
+```
+
+From your command line, you can now push and pull images to the registry.
+
+## Kubernetes/GPU Service Access
+
+To pull images from the registry, from private or authenticated projects, you will need to add a secret to the namespace you are using and reference it in your job definition. Note that user tokens have a limited validity period.
+
+If you are regularly using a repository from a project where you are sharing resources, it is recommended to create a robot account with limited read only privileges, this can be requested via a Helpdesk Request for your project.
+
+!!! important "Portal Management"
+
+    There will be new functionality soon added to the EIDF Portal to allow for project users to create read only robot accounts and for PI/Managers to create read/write robot accounts for use in CI/CD pipelines for image building.
+
+This is then treated like a normal user secret when you have the robot credentials.
+
+Secrets can be created in one of two ways, as detailed below, either directly via kubectl from your Docker config.json file, or by creating a YAML file.
+
+More details on Kubernetes secrets can be found in the [Kubernetes documentation](https://kubernetes.io/docs/concepts/configuration/secret/).
+
+### Secret Creation via Docker config.json
+
+!!! Tip
+    This section requires that you have logged into ECIR via Docker as described in *[Using from the command line with Docker](#using-from-the-command-line-with-docker)*. It also requires that kubectl is installed.
+
+Running the following command will create a secret `<secret-name>` in your project namespace. This can be used by Kubernetes to pull from your private repositories.
+
+The secret that is created will bundle together authentication information in the passed-in Docker config.json file.
+
+If you have logged in to other registries the bundled secret will include authentications from these registries e.g., DockerHub and the GitHub Container Registry. See the documentation for more details on [Kubernetes secret creation](https://kubernetes.io/docs/reference/kubectl/generated/kubectl_create/kubectl_create_secret_generic/).
+
+```bash
+kubectl create secret generic <secret-name> \
+    --from-file=.dockerconfigjson=<path/to/.docker/config.json> \
+    --type=kubernetes.io/dockerconfigjson -n <your namespace>
+```
+
+!!! warning
+    Usage of `~` to denote your home directory in the above command does not work.
+
+You can view details of the new secret by running:
+
+```bash
+kubectl describe secret <secret-name> -n <your namespace>
+```
+
+### Secret Creation via YAML
+
+Important: Run these commands on a system that has kubectl installed and has access to the ECIR.
+
+You do not need to be logged in to Docker to perform this setup, we manually encode our details and pass it to YAML.
+
+Encode your authorisation information into base64 for inclusion in the Kubernetes secret. The CLI Secret value is taken from your User profile in the registry web interface.
+
+![UserProfile](../../images/registry/userprofile.png){: class="border-img"}
+   *User Profile*
+
+```bash
+echo '{"auths":{"https://registry.eidf.ac.uk":{"username":"<your username>","password":"<your CLI Secret>"}}}' | base64
+```
+
+This will generate a string of characters, it may have line breaks on output, and for the next part, you can remove the line breaks and make it a single line.
+
+```bash
+eyJhdXRocyI6eyJodHRwczovL3JlZ2lzdHJ5LmVpZGYuYWMudWsiOnsidXNlcm5hbWUiOiJyb2Jv
+dCR0ZXN0X2xpYnJhcnkrZ3B1X2RlZmF1bHQiLCJwYXNzd29yZCI6InZrakRHRzNwSG9lTVc0bEtp
+THRTZGt3ZXdlcVlpRDFxc1RPT2cifX19Cg==
+```
+
+Create a YAML File with the following information:
+
+```bash
+apiVersion: v1
+kind: Secret
+metadata:
+  name: <secret-name>
+  namespace: <your project namespace>
+type: kubernetes.io/dockerconfigjson
+data:
+  .dockerconfigjson: >-
+     <the output from the encoding process>
+```
+
+For example:
+
+```bash
+apiVersion: v1
+kind: Secret
+metadata:
+  name: eidfreg
+  namespace: eidf000ns
+type: kubernetes.io/dockerconfigjson
+data:
+  .dockerconfigjson: >-
+    eyJhdXRocyI6eyJodHRwczovL3JlZ2lzdHJ5LmVpZGYuYWMudWsiOnsidXNlcm5hbWUiOiJyb2JvdCR0ZXN0X2xpYnJhcnkrZ3B1X2RlZmF1bHQiLCJwYXNzd29yZCI6InZrakRHRzNwSG9lTVc0bEtpTHRTZGt3ZXdlcVlpRDFxc1RPT2cifX19Cg==
+```
+
+To create the secret run:
+
+```bash
+kubectl apply -f <your filename> -n <your namespace>
+```
+
+### Using in a Job
+
+Use the image name from the pull command for the repository. For example, this could be `registry.eidf.ac.uk/nvidia-cache/nvidia/k8s/cuda-sample:nbody`, the ECIR cached version of the [NVIDIA sample](https://catalog.ngc.nvidia.com/orgs/nvidia/teams/k8s/containers/cuda-sample): `nvcr.io/nvidia/k8s/cuda-sample:nbody`.
+
+This is an example using an image and secret to access the registry. Replace the appropriate values with your own configuration.
+
+The below example will function without a secret as the image is in a public repository.
+
+``` yaml
+apiVersion: batch/v1
+kind: Job
+metadata:
+  generateName: jobtest-
+  labels:
+    kueue.x-k8s.io/queue-name: <project-namespace>-user-queue
+spec:
+  completions: 1
+  template:
+    metadata:
+      name: job-test
+    spec:
+      containers:
+        - name: cudasample
+          image: registry.eidf.ac.uk/nvidia-cache/nvidia/k8s/cuda-sample:nbody
+          args:
+            - '-benchmark'
+            - '-numbodies=512000'
+            - '-fp64'
+            - '-fullscreen'
+          resources:
+            requests:
+              cpu: 2
+              memory: 1Gi
+            limits:
+              cpu: 2
+              memory: 4Gi
+              nvidia.com/gpu: 1
+      restartPolicy: Never
+      imagePullSecrets:
+        - name: <secret-name>
+```