1. Documentation
×

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

  • 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:

    $ 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:

      $ 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

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

Procedure

  1. Access the node by getting its name:

    $ oc get nodes
    $ 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!.

    sh-4.2# chroot /host

  3. Log in to the container image registry by using your access token:

    sh-4.2# oc login -u kubeadmin -p <password_from_install_log> https://api-int.<cluster_name>.<base_domain>:6443
    sh-4.2# podman login -u kubeadmin -p $(oc whoami -t) image-registry.openshift-image-registry.svc:5000

    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:

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

      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 OKD to correctly place and later access the image in the registry.

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

      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:

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

      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

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.

    $ oc get pods -n openshift-image-registry
    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

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.

    $ oc logs deployments/image-registry -n openshift-image-registry
    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

The OpenShift Container Registry provides an endpoint for Prometheus metrics. 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:

    $ 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:

    $ oc adm policy add-cluster-role-to-user prometheus-scraper <username>

  3. For the metrics query, get the user token.

    openshift:
$ oc whoami -t

  4. Run a metrics query in node or inside a pod. The following example command and output demonstrate this task.

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

      # 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