Chapter 4. Accessing the registry
Use the following sections for instructions on accessing the registry, including viewing logs and metrics, as well as securing and exposing the registry.
You can access the registry directly to invoke podman commands. This allows you to push images to or pull them from the integrated registry directly using operations like podman push or podman pull. To do so, you must be logged in to the registry using the podman login command. The operations you can perform depend on your user permissions, as described in the following sections.
4.1. Prerequisites
-
You have access to the cluster as a user with the
cluster-adminrole. - You must have configured an identity provider (IDP).
For pulling images, for example when using the
podman pullcommand, the user must have theregistry-viewerrole. To add this role, run the following command:$ oc policy add-role-to-user registry-viewer <user_name>
For writing or pushing images, for example when using the
podman pushcommand:The user must have the
registry-editorrole. 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.
4.2. Accessing the registry directly from the cluster
You can access the registry from inside the cluster.
Procedure
Access the registry from the cluster by using internal routes:
Access the node by getting the node’s name:
$ oc get nodes
$ oc debug nodes/<node_name>
To enable access to tools such as
ocandpodmanon the node, change your root directory to/host:sh-4.2# chroot /host
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 should see a message confirming login, such as:
Login Succeeded!
NoteYou can pass any value for the user name; the token contains all necessary information. Passing a user name that contains colons will result in a login failure.
Since the Image Registry Operator creates the route, it will likely be similar to
default-route-openshift-image-registry.<cluster_name>.Perform
podman pullandpodman pushoperations against your registry:ImportantYou 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, use:
Component Value <registry_ip>
172.30.124.220<port>
5000<project>
openshift<image>
image<tag>
omitted (defaults to
latest)Pull an arbitrary image:
sh-4.2# podman pull <name.io>/<image>
Tag the new image with the form
<registry_ip>:<port>/<project>/<image>. The project name must appear in this pull specification for OpenShift Container Platform 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>
NoteYou must have the
system:image-builderrole for the specified project, which allows the user to write or push an image. Otherwise, thepodman pushin the next step will fail. To test, you can create a new project to push the image.Push the newly tagged image to your registry:
sh-4.2# podman push image-registry.openshift-image-registry.svc:5000/openshift/<image>
NoteWhen 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.
4.3. 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-adminrole.
Procedure
List the pods in the
openshift-image-registryproject and view their status:$ oc get pods -n openshift-image-registry
Example output
NAME READY STATUS RESTARTS AGE cluster-image-registry-operator-764bd7f846-qqtpb 1/1 Running 0 78m 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
4.4. Viewing registry logs
You can view the logs for the registry by using the oc logs command.
Procedure
Use the
oc logscommand with deployments to view the logs for the container image registry:$ oc logs deployments/image-registry -n openshift-image-registry
Example output
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
4.5. 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.
Procedure
You can access the metrics by running a metrics query using a cluster role.
Cluster role
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
Add this role to a user, run the following command:
$ oc adm policy add-cluster-role-to-user prometheus-scraper <username>
Metrics query
Get the user token.
openshift: $ oc whoami -t
Run a metrics query in node or inside a pod, for example:
$ curl --insecure -s -u <user>:<secret> \ 1 https://image-registry.openshift-image-registry.svc:5000/extensions/v2/metrics | grep imageregistry | head -n 20Example output
# 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- 1
- The
<user>object can be arbitrary, but<secret>tag must use the user token.
4.6. Additional resources
- For more information on allowing pods in a project to reference images in another project, see Allowing pods to reference images across projects.
-
A
kubeadmincan access the registry until deleted. See Removing the kubeadmin user for more information. - For more information on configuring an identity provider, see Understanding identity provider configuration.
