Merge pull request #10102 from miminar/registry-catalog

Registry catalog API call

Author: bmcelvee

dev_guide/managing_images.adoc

@@ -551,6 +551,36 @@ By default, all service accounts in a project have rights to pull any image in
 the same project, and the *builder* service account has rights to push any image
 in the same project.
 
+ifdef::openshift-origin,openshift-enterprise,openshift-dedicated,atomic-registry[]
+=== Listing repositories
+
+Listing of repositories (or rather ImageStream names) is supported via `/v2/_catalog` endpoint as
+documented
+link:https://github.com/docker/distribution/blob/master/docs/spec/api.md#listing-repositories[upstream].
+The only requirement is that the authenticated user must have `list` rights on the `imagestreams`
+in the whole cluster.
+
+Here is one example of granting a permission to list ImageStreams to a user:
+
+----
+$ oc adm policy add-cluster-role-to-user registry-viewer user
+----
+
+.A CLI example of listing repositories
+----
+$ oc login -u user
+$ curl -v -u unused:$(oc whoami -t) https://<registry_server>:<port>/v2/_catalog?n=100
+----
+
+[IMPORTANT]
+====
+This API call is very expensive for a high number of image streams in the cluster. We strongly
+recommend to use
+link:https://github.com/docker/distribution/blob/master/docs/spec/api.md#pagination[pagination]
+instead of listing all image streams.
+====
+endif::openshift-origin,openshift-enterprise,openshift-dedicated,atomic-registry[]
+
 ifdef::openshift-origin,openshift-online,openshift-enterprise,openshift-dedicated[]
 [[using-image-pull-secrets]]
 == Using Image Pull Secrets