Accessing the Registry

Viewing Logs

To view the logs for the container image registry, use the oc logs command with the deployment configuration:

  1. $ oc logs dc/docker-registry
  2. 2015-05-01T19:48:36.300593110Z time="2015-05-01T19:48:36Z" level=info msg="version=v2.0.0+unknown"
  3. 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
  4. 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
  5. 2015-05-01T19:48:36.303433991Z time="2015-05-01T19:48:36Z" level=info msg="Using OpenShift Auth handler"
  6. 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

File Storage

Tag and image metadata is stored in OKD, but the registry stores layer and signature data in a volume that is mounted into the registry container at /registry. As oc exec does not work on privileged containers, to view a registry’s contents you must manually SSH into the node housing the registry pod’s container, then run docker exec on the container itself:

  1. List the current pods to find the pod name of your container image registry:

    1. # oc get pods

    Then, use oc describe to find the host name for the node running the container:

    1. # oc describe pod <pod_name>

  2. Log into the desired node:

    1. # ssh node.example.com

  3. List the running containers from the default project on the node host and identify the container ID for the container image registry:

    1. # docker ps --filter=name=registry_docker-registry.*_default_

  4. List the registry contents using the oc rsh command:

    1. # oc rsh dc/docker-registry find /registry
    2. /registry/docker
    3. /registry/docker/registry
    4. /registry/docker/registry/v2
    5. /registry/docker/registry/v2/blobs (1)
    6. /registry/docker/registry/v2/blobs/sha256
    7. /registry/docker/registry/v2/blobs/sha256/ed
    8. /registry/docker/registry/v2/blobs/sha256/ed/ede17b139a271d6b1331ca3d83c648c24f92cece5f89d95ac6c34ce751111810
    9. /registry/docker/registry/v2/blobs/sha256/ed/ede17b139a271d6b1331ca3d83c648c24f92cece5f89d95ac6c34ce751111810/data (2)
    10. /registry/docker/registry/v2/blobs/sha256/a3
    11. /registry/docker/registry/v2/blobs/sha256/a3/a3ed95caeb02ffe68cdd9fd84406680ae93d633cb16422d00e8a7c22955b46d4
    12. /registry/docker/registry/v2/blobs/sha256/a3/a3ed95caeb02ffe68cdd9fd84406680ae93d633cb16422d00e8a7c22955b46d4/data
    13. /registry/docker/registry/v2/blobs/sha256/f7
    14. /registry/docker/registry/v2/blobs/sha256/f7/f72a00a23f01987b42cb26f259582bb33502bdb0fcf5011e03c60577c4284845
    15. /registry/docker/registry/v2/blobs/sha256/f7/f72a00a23f01987b42cb26f259582bb33502bdb0fcf5011e03c60577c4284845/data
    16. /registry/docker/registry/v2/repositories (3)
    17. /registry/docker/registry/v2/repositories/p1
    18. /registry/docker/registry/v2/repositories/p1/pause (4)
    19. /registry/docker/registry/v2/repositories/p1/pause/_manifests
    20. /registry/docker/registry/v2/repositories/p1/pause/_manifests/revisions
    21. /registry/docker/registry/v2/repositories/p1/pause/_manifests/revisions/sha256
    22. /registry/docker/registry/v2/repositories/p1/pause/_manifests/revisions/sha256/e9a2ac6418981897b399d3709f1b4a6d2723cd38a4909215ce2752a5c068b1cf
    23. /registry/docker/registry/v2/repositories/p1/pause/_manifests/revisions/sha256/e9a2ac6418981897b399d3709f1b4a6d2723cd38a4909215ce2752a5c068b1cf/signatures (5)
    24. /registry/docker/registry/v2/repositories/p1/pause/_manifests/revisions/sha256/e9a2ac6418981897b399d3709f1b4a6d2723cd38a4909215ce2752a5c068b1cf/signatures/sha256
    25. /registry/docker/registry/v2/repositories/p1/pause/_manifests/revisions/sha256/e9a2ac6418981897b399d3709f1b4a6d2723cd38a4909215ce2752a5c068b1cf/signatures/sha256/ede17b139a271d6b1331ca3d83c648c24f92cece5f89d95ac6c34ce751111810
    26. /registry/docker/registry/v2/repositories/p1/pause/_manifests/revisions/sha256/e9a2ac6418981897b399d3709f1b4a6d2723cd38a4909215ce2752a5c068b1cf/signatures/sha256/ede17b139a271d6b1331ca3d83c648c24f92cece5f89d95ac6c34ce751111810/link (6)
    27. /registry/docker/registry/v2/repositories/p1/pause/_uploads (7)
    28. /registry/docker/registry/v2/repositories/p1/pause/_layers (8)
    29. /registry/docker/registry/v2/repositories/p1/pause/_layers/sha256
    30. /registry/docker/registry/v2/repositories/p1/pause/_layers/sha256/a3ed95caeb02ffe68cdd9fd84406680ae93d633cb16422d00e8a7c22955b46d4
    31. /registry/docker/registry/v2/repositories/p1/pause/_layers/sha256/a3ed95caeb02ffe68cdd9fd84406680ae93d633cb16422d00e8a7c22955b46d4/link (9)
    32. /registry/docker/registry/v2/repositories/p1/pause/_layers/sha256/f72a00a23f01987b42cb26f259582bb33502bdb0fcf5011e03c60577c4284845
    33. /registry/docker/registry/v2/repositories/p1/pause/_layers/sha256/f72a00a23f01987b42cb26f259582bb33502bdb0fcf5011e03c60577c4284845/link
    1This directory stores all layers and signatures as blobs.
    2This file contains the blob’s contents.
    3This directory stores all the image repositories.
    4This directory is for a single image repository p1/pause.
    5This directory contains signatures for a particular image manifest revision.
    6This file contains a reference back to a blob (which contains the signature data).
    7This directory contains any layers that are currently being uploaded and staged for the given repository.
    8This directory contains links to all the layers this repository references.
    9This file contains a reference to a specific layer that has been linked into this repository via an image.

Accessing the Registry Directly

For advanced usage, you can access the registry directly to invoke docker commands. This allows you to push images to or pull them from the integrated registry directly using operations like docker push or docker pull. To do so, you must be logged in to the registry using the docker login command. The operations you can perform depend on your user permissions, as described in the following sections.

User Prerequisites

To access the registry directly, the user that you use must satisfy the following, depending on your intended usage:

  • For any direct access, you must have a regular user for your preferred identity provider. A regular user can generate an access token required for logging in to the registry. System users, such as system:admin, cannot obtain access tokens and, therefore, cannot access the registry directly.

    For example, if you are using HTPASSWD authentication, you can create one using the following command:

    1. # htpasswd /etc/origin/master/htpasswd <user_name>

  • For pulling images, for example when using the docker pull command, the user must have the registry-viewer role. To add this role:

    1. $ oc policy add-role-to-user registry-viewer <user_name>

  • For writing or pushing images, for example when using the docker push command, the user must have the registry-editor role. To add this role:

    1. $ oc policy add-role-to-user registry-editor <user_name>

For more information on user permissions, see Managing Role Bindings.

Logging in to the Registry

Ensure your user satisfies the prerequisites for accessing the registry directly.

To log in to the registry directly:

  1. Ensure you are logged in to OKD as a regular user:

    1. $ oc login

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

    1. docker login -u openshift -p $(oc whoami -t) <registry_ip>:<port>

You can pass any value for the username, the token contains all necessary information. Passing a username that contains colons will result in a login failure.

Pushing and Pulling Images

After logging in to the registry, you can perform docker pull and docker push operations against your registry.

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.

In the following examples, we use:

Component

Value

<registry_ip>

172.30.124.220

<port>

5000

<project>

openshift

<image>

busybox

<tag>

omitted (defaults to latest)

  1. Pull an arbitrary image:

    1. $ docker pull docker.io/busybox

  2. Tag the new image with the form <registry_ip>:<port>/<project>/<image>. The project name must appear in this pull specification for OKD to correctly place and later access the image in the registry.

    1. $ docker tag docker.io/busybox 172.30.124.220:5000/openshift/busybox

    Your regular user must have the system:image-builder role for the specified project, which allows the user to write or push an image. Otherwise, the docker push in the next step will fail. To test, you can create a new project to push the busybox image.

  3. Push the newly-tagged image to your registry:

    1. $ docker push 172.30.124.220:5000/openshift/busybox
    2. ...
    3. cf2616975b4a: Image successfully pushed
    4. Digest: sha256:3662dd821983bc4326bee12caec61367e7fb6f6a3ee547cbaff98f77403cab55

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 are exposed at the /extensions/v2/metrics path of the registry endpoint. However, this route must first be enabled; see Extended Registry Configuration for instructions.

The following is a simple example of a metrics query:

  1. $ curl -s -u <user>:<secret> \ (1)
  2.     http://172.30.30.30:5000/extensions/v2/metrics | grep openshift | head -n 10
  4. # HELP openshift_build_info A metric with a constant '1' value labeled by major, minor, git commit & git version from which OpenShift was built.
  5. # TYPE openshift_build_info gauge
  6. openshift_build_info{gitCommit="67275e1",gitVersion="v3.6.0-alpha.1+67275e1-803",major="3",minor="6+"} 1
  7. # HELP openshift_registry_request_duration_seconds Request latency summary in microseconds for each operation
  8. # TYPE openshift_registry_request_duration_seconds summary
  9. openshift_registry_request_duration_seconds{name="test/origin-pod",operation="blobstore.create",quantile="0.5"} 0
  10. openshift_registry_request_duration_seconds{name="test/origin-pod",operation="blobstore.create",quantile="0.9"} 0
  11. openshift_registry_request_duration_seconds{name="test/origin-pod",operation="blobstore.create",quantile="0.99"} 0
  12. openshift_registry_request_duration_seconds_sum{name="test/origin-pod",operation="blobstore.create"} 0
  13. openshift_registry_request_duration_seconds_count{name="test/origin-pod",operation="blobstore.create"} 5
1<user> can be arbitrary, but <secret> must match the value specified in the registry configuration.

Another method to access the metrics is to use a cluster role. You still need to enable the endpoint, but you do not need to specify a <secret>. The part of the configuration file responsible for metrics should look like this:

  1. openshift:
  2.   version: 1.0
  3.   metrics:
  4.     enabled: true
  5. ...

You must create a cluster role if you do not already have one to access the metrics:

  1. $ cat <<EOF |
  2. apiVersion: rbac.authorization.k8s.io/v1
  3. kind: ClusterRole
  4. metadata:
  5.   name: prometheus-scraper
  6. rules:
  7. - apiGroups:
  8.   - image.openshift.io
  9.   resources:
  10.   - registry/metrics
  11.   verbs:
  12.   - get
  13. EOF
  14. oc create -f -

To add this role to a user, run the following command:

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

See the upstream Prometheus documentation for more advanced queries and recommended visualizers.