Skip to content

Commit 5a8e425

Browse files
bmcelveebmcelvee
committed
osdocs-227 accessing, securing, and exposing registry modules
1 parent 4162623 commit 5a8e425

7 files changed

+338
-2
lines changed

‎_topic_map.yml

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -149,6 +149,8 @@ Distros: openshift-*
149149
Topics:
150150
- Name: Registry options
151151
File: registry-options
152+
- Name: Accessing the registry
153+
File: accessing-the-registry
152154
---
153155
Name: Scalability and performance
154156
Dir: scalability_and_performance

‎modules/registry-accessing-directly.adoc

Lines changed: 125 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,125 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * assembly/registry
4+
5+
[id='registry-accessing-directly-{context}']
6+
= Accessing registry directly
7+
8+
You can access the registry directly to invoke `docker` commands. This allows
9+
you to push images to or pull them from the integrated registry directly using
10+
operations like `docker push` or `docker pull`. To do so, you must be logged in
11+
to the registry using the `docker login` command. The operations you can perform
12+
depend on your user permissions, as described in the following sections.
13+
14+
.Prerequisites
15+
16+
* For any direct access, you must have a regular user for your preferred identity
17+
provider.
18+
** A regular user can generate an access token required for logging in to
19+
the registry.
20+
** System users, such as *system:admin*, cannot obtain access tokens
21+
and, therefore, cannot access the registry directly.
22+
+
23+
For example, if you are using `HTPASSWD` authentication, you can create one
24+
using the following command:
25+
+
26+
----
27+
# htpasswd /etc/origin/openshift-htpasswd <user_name>
28+
----
29+
30+
* For pulling images, for example when using the `docker pull` command,
31+
the user must have the *registry-viewer* role. To add this role:
32+
+
33+
----
34+
$ oc policy add-role-to-user registry-viewer <user_name>
35+
----
36+
37+
* For writing or pushing images, for example when using the `docker push` command,
38+
the user must have the *registry-editor* role. To add this role:
39+
+
40+
----
41+
$ oc policy add-role-to-user registry-editor <user_name>
42+
----
43+
44+
.Procedure
45+
46+
. Log in to the registry directly:
47+
48+
.. Ensure you are logged in to {product-title} as a *regular user*:
49+
+
50+
----
51+
$ oc login
52+
----
53+
54+
.. Log in to the container image registry by using your access token:
55+
+
56+
----
57+
docker login -u openshift -p $(oc whoami -t) <registry_ip>:<port>
58+
----
59+
+
60+
[NOTE]
61+
====
62+
You can pass any value for the username, the token contains all necessary
63+
information. Passing a username that contains colons will result in a login
64+
failure.
65+
====
66+
+
67+
. Perform `docker pull` and `docker push` operations against your registry:
68+
+
69+
[IMPORTANT]
70+
====
71+
You can pull arbitrary images, but if you have the *system:registry* role
72+
added, you can only push images to the registry in your project.
73+
====
74+
+
75+
In the following examples, we use:
76+
+
77+
|====
78+
|Component |Value
79+
80+
|*<registry_ip>*
81+
|`172.30.124.220`
82+
83+
|*<port>*
84+
|`5000`
85+
86+
|*<project>*
87+
|`openshift`
88+
89+
|*<image>*
90+
|`busybox`
91+
92+
|*<tag>*
93+
| omitted (defaults to `latest`)
94+
|====
95+
96+
.. Pull an arbitrary image:
97+
+
98+
----
99+
$ docker pull docker.io/busybox
100+
----
101+
102+
.. Tag the new image with the form `<registry_ip>:<port>/<project>/<image>`.
103+
The project name *must* appear in this pull specification for {product-title} to
104+
correctly place and later access the image in the registry:
105+
+
106+
----
107+
$ docker tag docker.io/busybox 172.30.124.220:5000/openshift/busybox
108+
----
109+
+
110+
[NOTE]
111+
====
112+
Your regular user must have the *system:image-builder* role for the specified
113+
project, which allows the user to write or push an image. Otherwise, the `docker
114+
push` in the next step will fail. To test, you can create a new project to
115+
push the *busybox* image.
116+
====
117+
118+
.. Push the newly-tagged image to your registry:
119+
+
120+
----
121+
$ docker push 172.30.124.220:5000/openshift/busybox
122+
...
123+
cf2616975b4a: Image successfully pushed
124+
Digest: sha256:3662dd821983bc4326bee12caec61367e7fb6f6a3ee547cbaff98f77403cab55
125+
----

‎modules/registry-accessing-metrics.adoc

Lines changed: 84 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,84 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * assembly/registry
4+
5+
[id='registry-accessing-metrics-{context}']
6+
= Accessing registry metrics
7+
8+
The OpenShift Container Registry provides an endpoint for
9+
link:https://prometheus.io/docs/introduction/overview/[Prometheus metrics].
10+
Prometheus is a stand-alone, open source systems monitoring and alerting
11+
toolkit.
12+
13+
The metrics are exposed at the *_/extensions/v2/metrics_* path of the registry
14+
endpoint. However, this route must first be enabled; see
15+
Extended Registry Configuration for instructions.
16+
17+
// Recommended link to extended registry configuration assembly.
18+
19+
.Procedure
20+
21+
There are two ways in which you can access the metrics: running a metrics query
22+
or by using the cluster role.
23+
24+
*Metrics query*
25+
. Run a metrics query, for example:
26+
+
27+
[source, bash]
28+
----
29+
$ curl -s -u <user>:<secret> \ <1>
30+
http://172.30.30.30:5000/extensions/v2/metrics | grep openshift | head -n 10
31+
32+
# HELP openshift_build_info A metric with a constant '1' value labeled by major, minor, git commit & git version from which OpenShift was built.
33+
# TYPE openshift_build_info gauge
34+
openshift_build_info{gitCommit="67275e1",gitVersion="v3.6.0-alpha.1+67275e1-803",major="3",minor="6+"} 1
35+
# HELP openshift_registry_request_duration_seconds Request latency summary in microseconds for each operation
36+
# TYPE openshift_registry_request_duration_seconds summary
37+
openshift_registry_request_duration_seconds{name="test/origin-pod",operation="blobstore.create",quantile="0.5"} 0
38+
openshift_registry_request_duration_seconds{name="test/origin-pod",operation="blobstore.create",quantile="0.9"} 0
39+
openshift_registry_request_duration_seconds{name="test/origin-pod",operation="blobstore.create",quantile="0.99"} 0
40+
openshift_registry_request_duration_seconds_sum{name="test/origin-pod",operation="blobstore.create"} 0
41+
openshift_registry_request_duration_seconds_count{name="test/origin-pod",operation="blobstore.create"} 5
42+
----
43+
<1> `<user>` can be arbitrary, but `<secret>` must match the value specified in the
44+
registry configuration.
45+
46+
*Cluster role*
47+
. Create a cluster role if you do not already have one to access the metrics:
48+
+
49+
[source, bash]
50+
----
51+
$ cat <<EOF |
52+
apiVersion: rbac.authorization.k8s.io/v1
53+
kind: ClusterRole
54+
metadata:
55+
name: prometheus-scraper
56+
rules:
57+
- apiGroups:
58+
- image.openshift.io
59+
resources:
60+
- registry/metrics
61+
verbs:
62+
- get
63+
EOF
64+
oc create -f -
65+
----
66+
67+
. Add this role to a user, run the following command:
68+
+
69+
[source, bash]
70+
----
71+
$ oc adm policy add-cluster-role-to-user prometheus-scraper <username>
72+
----
73+
74+
. Access the metrics using cluster role. You still need to
75+
enable the endpoint, but you do not need to specify a `<secret>`. The part of
76+
the configuration file responsible for metrics should look like this:
77+
78+
----
79+
openshift:
80+
version: 1.0
81+
metrics:
82+
enabled: true
83+
...
84+
----

‎modules/registry-viewing-contents.adoc

Lines changed: 90 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,90 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * assembly/registry
4+
5+
[id='registry-viewing-contents-{context}']
6+
= Viewing the registry's contents
7+
8+
Tag and image metadata is stored in {product-title}, but the registry stores
9+
layer and signature data in a volume that is mounted into the registry container
10+
at *_/registry_*. As `oc exec` does not work on privileged containers, to view a
11+
registry's contents you must manually SSH into the node housing the registry
12+
pod's container, then run `docker exec` on the container itself.
13+
14+
.Procedure
15+
16+
. List the current pods to find the pod name of your container image registry:
17+
+
18+
----
19+
# oc get pods
20+
----
21+
+
22+
Then, use `oc describe` to find the host name for the node running the
23+
container:
24+
+
25+
----
26+
# oc describe pod <pod_name>
27+
----
28+
29+
. Log into the desired node:
30+
+
31+
----
32+
# ssh node.example.com
33+
----
34+
35+
. List the running containers from the default project on the node host and identify the container ID for
36+
the container image registry:
37+
+
38+
----
39+
# docker ps --filter=name=registry_docker-registry.*_default_
40+
----
41+
42+
. List the registry contents using the `oc rsh` command:
43+
+
44+
----
45+
# oc rsh dc/docker-registry find /registry
46+
/registry/docker
47+
/registry/docker/registry
48+
/registry/docker/registry/v2
49+
/registry/docker/registry/v2/blobs <1>
50+
/registry/docker/registry/v2/blobs/sha256
51+
/registry/docker/registry/v2/blobs/sha256/ed
52+
/registry/docker/registry/v2/blobs/sha256/ed/ede17b139a271d6b1331ca3d83c648c24f92cece5f89d95ac6c34ce751111810
53+
/registry/docker/registry/v2/blobs/sha256/ed/ede17b139a271d6b1331ca3d83c648c24f92cece5f89d95ac6c34ce751111810/data <2>
54+
/registry/docker/registry/v2/blobs/sha256/a3
55+
/registry/docker/registry/v2/blobs/sha256/a3/a3ed95caeb02ffe68cdd9fd84406680ae93d633cb16422d00e8a7c22955b46d4
56+
/registry/docker/registry/v2/blobs/sha256/a3/a3ed95caeb02ffe68cdd9fd84406680ae93d633cb16422d00e8a7c22955b46d4/data
57+
/registry/docker/registry/v2/blobs/sha256/f7
58+
/registry/docker/registry/v2/blobs/sha256/f7/f72a00a23f01987b42cb26f259582bb33502bdb0fcf5011e03c60577c4284845
59+
/registry/docker/registry/v2/blobs/sha256/f7/f72a00a23f01987b42cb26f259582bb33502bdb0fcf5011e03c60577c4284845/data
60+
/registry/docker/registry/v2/repositories <3>
61+
/registry/docker/registry/v2/repositories/p1
62+
/registry/docker/registry/v2/repositories/p1/pause <4>
63+
/registry/docker/registry/v2/repositories/p1/pause/_manifests
64+
/registry/docker/registry/v2/repositories/p1/pause/_manifests/revisions
65+
/registry/docker/registry/v2/repositories/p1/pause/_manifests/revisions/sha256
66+
/registry/docker/registry/v2/repositories/p1/pause/_manifests/revisions/sha256/e9a2ac6418981897b399d3709f1b4a6d2723cd38a4909215ce2752a5c068b1cf
67+
/registry/docker/registry/v2/repositories/p1/pause/_manifests/revisions/sha256/e9a2ac6418981897b399d3709f1b4a6d2723cd38a4909215ce2752a5c068b1cf/signatures <5>
68+
/registry/docker/registry/v2/repositories/p1/pause/_manifests/revisions/sha256/e9a2ac6418981897b399d3709f1b4a6d2723cd38a4909215ce2752a5c068b1cf/signatures/sha256
69+
/registry/docker/registry/v2/repositories/p1/pause/_manifests/revisions/sha256/e9a2ac6418981897b399d3709f1b4a6d2723cd38a4909215ce2752a5c068b1cf/signatures/sha256/ede17b139a271d6b1331ca3d83c648c24f92cece5f89d95ac6c34ce751111810
70+
/registry/docker/registry/v2/repositories/p1/pause/_manifests/revisions/sha256/e9a2ac6418981897b399d3709f1b4a6d2723cd38a4909215ce2752a5c068b1cf/signatures/sha256/ede17b139a271d6b1331ca3d83c648c24f92cece5f89d95ac6c34ce751111810/link <6>
71+
/registry/docker/registry/v2/repositories/p1/pause/_uploads <7>
72+
/registry/docker/registry/v2/repositories/p1/pause/_layers <8>
73+
/registry/docker/registry/v2/repositories/p1/pause/_layers/sha256
74+
/registry/docker/registry/v2/repositories/p1/pause/_layers/sha256/a3ed95caeb02ffe68cdd9fd84406680ae93d633cb16422d00e8a7c22955b46d4
75+
/registry/docker/registry/v2/repositories/p1/pause/_layers/sha256/a3ed95caeb02ffe68cdd9fd84406680ae93d633cb16422d00e8a7c22955b46d4/link <9>
76+
/registry/docker/registry/v2/repositories/p1/pause/_layers/sha256/f72a00a23f01987b42cb26f259582bb33502bdb0fcf5011e03c60577c4284845
77+
/registry/docker/registry/v2/repositories/p1/pause/_layers/sha256/f72a00a23f01987b42cb26f259582bb33502bdb0fcf5011e03c60577c4284845/link
78+
----
79+
<1> This directory stores all layers and signatures as blobs.
80+
<2> This file contains the blob's contents.
81+
<3> This directory stores all the image repositories.
82+
<4> This directory is for a single image repository *p1/pause*.
83+
<5> This directory contains signatures for a particular image manifest revision.
84+
<6> This file contains a reference back to a blob (which contains the signature
85+
data).
86+
<7> This directory contains any layers that are currently being uploaded and
87+
staged for the given repository.
88+
<8> This directory contains links to all the layers this repository references.
89+
<9> This file contains a reference to a specific layer that has been linked into
90+
this repository via an image.

‎modules/registry-viewing-logs.adoc

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * assembly/registry
4+
5+
[id='registry-viewing-logs-{context}']
6+
= Viewing registry logs
7+
8+
You can view the logs for the registry by using the `oc logs` command.
9+
10+
.Procedure
11+
12+
. Use the `oc logs` command with the deployment configuration to view the logs
13+
for the container image registry:
14+
+
15+
----
16+
$ oc logs dc/docker-registry
17+
2015-05-01T19:48:36.300593110Z time="2015-05-01T19:48:36Z" level=info msg="version=v2.0.0+unknown"
18+
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
19+
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
20+
2015-05-01T19:48:36.303433991Z time="2015-05-01T19:48:36Z" level=info msg="Using OpenShift Auth handler"
21+
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
22+
----

‎registry/PLACEHOLDER

Lines changed: 0 additions & 2 deletions
This file was deleted.

‎registry/accessing-the-registry.adoc

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
:context: accessing-the-registry.adoc
2+
= Accessing the registry
3+
include::modules/common-attributes.adoc[]
4+
toc::[]
5+
6+
Use the following sections for instructions on accessing the registry, including
7+
viewing logs and metrics, as well as securing and exposing the registry.
8+
9+
include::modules/registry-accessing-directly.adoc[leveloffset=+1]
10+
11+
include::modules/registry-viewing-contents.adoc[leveloffset=+1]
12+
13+
include::modules/registry-viewing-logs.adoc[leveloffset=+1]
14+
15+
include::modules/registry-accessing-metrics.adoc[leveloffset=+1]

0 commit comments

Comments
 (0)