---
title: Accessing the registry
---

# Accessing the registry {#accessing-the-registry}

You can access a registry to view logs and metrics. You can also secure and expose the registry.

After you logged in to the registry by using the `podman login` command, you can push or pull images from the integrated registry directly by using `podman push` or `podman pull` commands. The commands that you can use depend on your user permissions.

## Prerequisites {#_prerequisites}

- You have access to the cluster as a user with the `cluster-admin` role.
- You must have configured an identity provider (IDP).
- For pulling images, for example when using the `podman pull` command, the user must have the `registry-viewer` role. To add this role, run the following command:

  ```terminal
  $ oc policy add-role-to-user registry-viewer <user_name>
  ```
- For writing or pushing images, such as using `podman push` command, complete the following steps:

  - Your account has the `registry-editor` role. To add this role, run the following command:

    ```terminal
    $ oc policy add-role-to-user registry-editor <user_name>
    ```
  - Your cluster must have an existing project where the images can be pushed to.

## Accessing the registry directly from the cluster {#registry-accessing-directly_accessing-the-registry}

You can access the registry from inside the cluster by using internal routes.

**Procedure**

1. Access the node by getting its name:

   ```terminal
   $ oc get nodes
   ```

   ```terminal
   $ oc debug nodes/<node_name>
   ```
2. To enable access to tools such as `oc` and `podman` on the node, change your root directory to `/host`. Successful output on running the commands states `Login Succeeded!`.

   ```terminal
   sh-4.2# chroot /host
   ```
3. Log in to the container image registry by using your access token:

   ```terminal
   sh-4.2# oc login -u kubeadmin -p <password_from_install_log> https://api-int.<cluster_name>.<base_domain>:6443
   ```

   ```terminal
   sh-4.2# podman login -u kubeadmin -p $(oc whoami -t) image-registry.openshift-image-registry.svc:5000
   ```

   > [!NOTE]
   > You can pass almost any value for the user name. The token contains all necessary information. Passing a user name that contains colons results in a login failure.
   >
   > The Image Registry Operator creates the route, such as `default-route-openshift-image-registry.<cluster_name>`.
4. Perform `podman pull` and `podman push` operations against your registry. The following example commands demonstrate these operations.

   1. Pull an arbitrary image:

      ```terminal
      sh-4.2# podman pull <name.io>/<image>
      ```

      > [!IMPORTANT]
      > You can pull arbitrary images, but if you have the **system:registry** role added, you can only push images to the registry in your project.
   2. Tag the new image with the form `<registry_ip>:<port>/<project>/<image>`. For example, `172.30.124.220:5000/openshift/image`. The project name must show in the pull specification for OpenShift Container Platform to correctly place and later access the image in the registry.

      ```terminal
      sh-4.2# podman tag <name.io>/<image> image-registry.openshift-image-registry.svc:5000/openshift/<image>
      ```

      > [!NOTE]
      > You must have the `system:image-builder` role for the specified project, which allows the user to write or push an image. Otherwise, the `podman push` in the next step will fail. To test, you can create a new project to push the image.
   3. Push the newly tagged image to your registry:

      ```terminal
      sh-4.2# podman push image-registry.openshift-image-registry.svc:5000/openshift/<image>
      ```

      > [!NOTE]
      > When pushing images to the internal registry, the repository name must use the `<project>/<name>` format. Using multiple project levels in the repository name results in an authentication error.

## Checking the status of the registry pods {#checking-the-status-of-registry-pods_accessing-the-registry}

As a cluster administrator,

you can list the image registry pods running in the `openshift-image-registry` project and check their status.

**Prerequisites**

- You have access to the cluster as a user with the `cluster-admin` role.

**Procedure**

- List the pods in the `openshift-image-registry` project and view their status. Example output provided for demonstrative purposes.

  ```terminal
  $ oc get pods -n openshift-image-registry
  ```

  ```terminal
  NAME READY STATUS RESTARTS AGE
  image-registry-79fb4469f6-llrln 1/1 Running 0 77m
  node-ca-hjksc 1/1 Running 0 73m
  node-ca-tftj6 1/1 Running 0 77m
  node-ca-wb6ht 1/1 Running 0 77m
  node-ca-zvt9q 1/1 Running 0 74m
  ```

## Viewing registry logs {#registry-viewing-logs_accessing-the-registry}

You can view the logs for the registry by using the `oc logs` command.

**Procedure**

- Use the `oc logs` command with deployments to view the logs for the container image registry. Example output provided for demonstrative purposes.

  ```terminal
  $ oc logs deployments/image-registry -n openshift-image-registry
  ```

  ```terminal
  2015-05-01T19:48:36.300593110Z time="2015-05-01T19:48:36Z" level=info msg="version=v2.0.0+unknown"
  2015-05-01T19:48:36.303294724Z time="2015-05-01T19:48:36Z" level=info msg="redis not configured" instance.id=9ed6c43d-23ee-453f-9a4b-031fea646002
  2015-05-01T19:48:36.303422845Z time="2015-05-01T19:48:36Z" level=info msg="using inmemory layerinfo cache" instance.id=9ed6c43d-23ee-453f-9a4b-031fea646002
  2015-05-01T19:48:36.303433991Z time="2015-05-01T19:48:36Z" level=info msg="Using OpenShift Auth handler"
  2015-05-01T19:48:36.303439084Z time="2015-05-01T19:48:36Z" level=info msg="listening on :5000" instance.id=9ed6c43d-23ee-453f-9a4b-031fea646002
  ```

## Accessing registry metrics {#registry-accessing-metrics_accessing-the-registry}

The OpenShift Container Registry provides an endpoint for [Prometheus metrics](https://prometheus.io/docs/introduction/overview/). Prometheus is a stand-alone, open source systems monitoring and alerting toolkit. The metrics get exposed at the ***/extensions/v2/metrics*** path of the registry endpoint. You can access the metrics by running a metrics query that includes a cluster role.

**Procedure**

1. Create a cluster role if you do not already have one to access the metrics:

   ```terminal
   $ cat <<EOF | oc create -f -
   apiVersion: rbac.authorization.k8s.io/v1
   kind: ClusterRole
   metadata:
     name: prometheus-scraper
   rules:
   - apiGroups:
     - image.openshift.io
     resources:
     - registry/metrics
     verbs:
     - get
   EOF
   ```
2. Add the cluster role to a user account by entering the following command:

   ```terminal
   $ oc adm policy add-cluster-role-to-user prometheus-scraper <username>
   ```
3. For the metrics query, get the user token.

   ```terminal
   openshift:
   $ oc whoami -t
   ```
4. Run a metrics query in node or inside a pod. The following example command and output demonstrate this task.

   ```terminal
   $ curl --insecure -s -u <user>:<secret> \ (1)
       https://image-registry.openshift-image-registry.svc:5000/extensions/v2/metrics | grep imageregistry | head -n 20
   ```

   - `<user>:<secret>`:  The `<user>` object can be arbitrary, but `<secret>` tag must use the user token.

     ```terminal
     # HELP imageregistry_build_info A metric with a constant '1' value labeled by major, minor, git commit & git version from which the image registry was built.
     # TYPE imageregistry_build_info gauge
     imageregistry_build_info{gitCommit="9f72191",gitVersion="v3.11.0+9f72191-135-dirty",major="3",minor="11+"} 1
     # HELP imageregistry_digest_cache_requests_total Total number of requests without scope to the digest cache.
     # TYPE imageregistry_digest_cache_requests_total counter
     imageregistry_digest_cache_requests_total{type="Hit"} 5
     imageregistry_digest_cache_requests_total{type="Miss"} 24
     # HELP imageregistry_digest_cache_scoped_requests_total Total number of scoped requests to the digest cache.
     # TYPE imageregistry_digest_cache_scoped_requests_total counter
     imageregistry_digest_cache_scoped_requests_total{type="Hit"} 33
     imageregistry_digest_cache_scoped_requests_total{type="Miss"} 44
     # HELP imageregistry_http_in_flight_requests A gauge of requests currently being served by the registry.
     # TYPE imageregistry_http_in_flight_requests gauge
     imageregistry_http_in_flight_requests 1
     # HELP imageregistry_http_request_duration_seconds A histogram of latencies for requests to the registry.
     # TYPE imageregistry_http_request_duration_seconds summary
     imageregistry_http_request_duration_seconds{method="get",quantile="0.5"} 0.01296087
     imageregistry_http_request_duration_seconds{method="get",quantile="0.9"} 0.014847248
     imageregistry_http_request_duration_seconds{method="get",quantile="0.99"} 0.015981195
     imageregistry_http_request_duration_seconds_sum{method="get"} 12.260727916000022
     ```

**Additional resources**
{._additional-resources}

- [Allowing pods to reference images across projects](/openshift-docs-markdown/openshift_images/managing_images/using-image-pull-secrets#images-allow-pods-to-reference-images-across-projects_using-image-pull-secrets)
- [Removing the kubeadmin user](/openshift-docs-markdown/authentication/remove-kubeadmin#removing-kubeadmin_removing-kubeadmin)
- [Understanding identity provider configuration](/openshift-docs-markdown/authentication/understanding-identity-provider#understanding-identity-provider_understanding-identity-provider)