Skip to content

Commit 5d7d803

Browse files
bmcelveebmcelvee
committed
osdocs-227 securing and exposing the registry
1 parent 1cc5e6e commit 5d7d803

9 files changed

+486
-48
lines changed

‎_topic_map.yml

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -157,6 +157,8 @@ Topics:
157157
File: registry-options
158158
- Name: Accessing the registry
159159
File: accessing-the-registry
160+
- Name: Securing and exposing the registry
161+
File: securing-exposing-registry
160162
---
161163
Name: Scalability and performance
162164
Dir: scalability_and_performance

‎modules/registry-accessing-directly.adoc

Lines changed: 11 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -5,10 +5,10 @@
55
[id='registry-accessing-directly-{context}']
66
= Accessing registry directly
77

8-
You can access the registry directly to invoke `docker` commands. This allows
8+
You can access the registry directly to invoke `podman` commands. This allows
99
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
10+
operations like `podman push` or `podman pull`. To do so, you must be logged in
11+
to the registry using the `oc registry login` command. The operations you can perform
1212
depend on your user permissions, as described in the following sections.
1313

1414
.Prerequisites
@@ -27,14 +27,14 @@ using the following command:
2727
# htpasswd /etc/origin/openshift-htpasswd <user_name>
2828
----
2929

30-
* For pulling images, for example when using the `docker pull` command,
30+
* For pulling images, for example when using the `podman pull` command,
3131
the user must have the *registry-viewer* role. To add this role:
3232
+
3333
----
3434
$ oc policy add-role-to-user registry-viewer <user_name>
3535
----
3636

37-
* For writing or pushing images, for example when using the `docker push` command,
37+
* For writing or pushing images, for example when using the `podman push` command,
3838
the user must have the *registry-editor* role. To add this role:
3939
+
4040
----
@@ -54,7 +54,7 @@ $ oc login
5454
.. Log in to the container image registry by using your access token:
5555
+
5656
----
57-
docker login -u openshift -p $(oc whoami -t) <registry_ip>:<port>
57+
podman login -u openshift -p $(oc whoami -t) <registry_ip>:<port>
5858
----
5959
+
6060
[NOTE]
@@ -64,7 +64,7 @@ information. Passing a username that contains colons will result in a login
6464
failure.
6565
====
6666
+
67-
. Perform `docker pull` and `docker push` operations against your registry:
67+
. Perform `podman pull` and `podman push` operations against your registry:
6868
+
6969
[IMPORTANT]
7070
====
@@ -96,29 +96,29 @@ In the following examples, we use:
9696
.. Pull an arbitrary image:
9797
+
9898
----
99-
$ docker pull docker.io/busybox
99+
$ podman pull podman.io/busybox
100100
----
101101

102102
.. Tag the new image with the form `<registry_ip>:<port>/<project>/<image>`.
103103
The project name *must* appear in this pull specification for {product-title} to
104104
correctly place and later access the image in the registry:
105105
+
106106
----
107-
$ docker tag docker.io/busybox 172.30.124.220:5000/openshift/busybox
107+
$ podman tag podman.io/busybox 172.30.124.220:5000/openshift/busybox
108108
----
109109
+
110110
[NOTE]
111111
====
112112
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
113+
project, which allows the user to write or push an image. Otherwise, the `podman
114114
push` in the next step will fail. To test, you can create a new project to
115115
push the *busybox* image.
116116
====
117117

118118
.. Push the newly-tagged image to your registry:
119119
+
120120
----
121-
$ docker push 172.30.124.220:5000/openshift/busybox
121+
$ podman push 172.30.124.220:5000/openshift/busybox
122122
...
123123
cf2616975b4a: Image successfully pushed
124124
Digest: sha256:3662dd821983bc4326bee12caec61367e7fb6f6a3ee547cbaff98f77403cab55

‎modules/registry-authentication-enabled-registry-overview.adoc

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -35,7 +35,7 @@ While it is possible to use this authentication method with {product-title}, it
3535
production deployments. Restrict this authentication method to
3636
stand-alone projects outside {product-title}.
3737

38-
You can use `docker login` with your credentials, either username and password
38+
You can use `podman login` with your credentials, either username and password
3939
or authentication token, to access content on the new registry.
4040

4141
All image streams point to the new registry. Because the new registry requires

‎modules/registry-exposing-non-secure-registry-manually.adoc

Lines changed: 85 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,85 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * assembly/registry
4+
5+
[id='registry-exposing-non-secure-registry-manually-{context}']
6+
= Exposing a non-secure registry manually
7+
8+
Instead of securing the registry in order to expose the registry, you can simply
9+
expose a non-secure registry for non-production {product-title} environments.
10+
This allows you to have an external route to the registry without using SSL
11+
certificates.
12+
13+
[WARNING]
14+
====
15+
Only non-production environments should expose a non-secure registry to external access.
16+
====
17+
18+
.Procedure
19+
20+
To expose a non-secure registry:
21+
22+
. Expose the registry:
23+
+
24+
----
25+
# oc expose service podman-registry --hostname=<hostname> -n default
26+
----
27+
+
28+
This creates the following JSON file:
29+
+
30+
----
31+
apiVersion: v1
32+
kind: Route
33+
metadata:
34+
creationTimestamp: null
35+
labels:
36+
podman-registry: default
37+
name: podman-registry
38+
spec:
39+
host: registry.example.com
40+
port:
41+
targetPort: "5000"
42+
to:
43+
kind: Service
44+
name: podman-registry
45+
status: {}
46+
----
47+
. Verify that the route has been created successfully:
48+
+
49+
----
50+
# oc get route
51+
NAME HOST/PORT PATH SERVICE LABELS INSECURE POLICY TLS TERMINATION
52+
podman-registry registry.example.com podman-registry podman-registry=default
53+
----
54+
. Check the health of the registry:
55+
+
56+
----
57+
$ curl -v http://registry.example.com/healthz
58+
----
59+
+
60+
Expect an HTTP 200/OK message.
61+
+
62+
After exposing the registry, update your *_/etc/sysconfig/podman_* file by
63+
adding the port number to the `OPTIONS` entry. For example:
64+
+
65+
----
66+
OPTIONS='--selinux-enabled --insecure-registry=172.30.0.0/16 --insecure-registry registry.example.com:80'
67+
----
68+
+
69+
[IMPORTANT]
70+
====
71+
The options in the previous example should be added on the client from which you
72+
are trying to log in.
73+
74+
Also, ensure that Podman is running on the client.
75+
====
76+
77+
When logging in to the non-secured and exposed registry, make sure you specify the registry
78+
in the `podman login` command. For example:
79+
80+
----
81+
# podman login -e user@company.com \
82+
-u f83j5h6 \
83+
-p Ju1PeM47R0B92Lk3AZp-bWJSck2F7aGCiZ66aFGZrs2 \
84+
<host>
85+
----

‎modules/registry-exposing-secure-registry-manually.adoc

Lines changed: 130 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,130 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * assembly/registry
4+
5+
[id='registry-exposing-secure-registry-manually-{context}']
6+
= Exposing a secure registry manually
7+
8+
Instead of logging in to the {product-title} registry from within the
9+
{product-title} cluster, you can gain external access to it by first securing
10+
the registry and then exposing it with a route. This allows you to log in to the
11+
registry from outside the cluster using the route address, and to tag and push
12+
images using the route host.
13+
14+
.Prerequisites:
15+
16+
* The following prerequisites are automatically preformed:
17+
** Deploy the registry.
18+
** Secure the registry.
19+
** Deploy a router.
20+
21+
.Procedure
22+
23+
. Verify whether a passthrough route exists, the route should have been created by
24+
default for the registry during the initial cluster installation:
25+
+
26+
----
27+
$ oc get route/pod-registry -o yaml
28+
apiVersion: v1
29+
kind: Route
30+
metadata:
31+
name: podman-registry
32+
spec:
33+
host: <host> <1>
34+
to:
35+
kind: Service
36+
name: podman-registry <2>
37+
tls:
38+
termination: passthrough <3>
39+
----
40+
<1> The host for your route. You must be able to resolve this name externally by
41+
DNS to the router's IP address.
42+
<2> The service name for your registry.
43+
<3> Specifies this route as a passthrough route.
44+
+
45+
[NOTE]
46+
====
47+
Re-encrypt routes are also supported for exposing the secure registry.
48+
====
49+
50+
.. If it does not exist, create the route with the `oc create route passthrough`
51+
command, specifying the registry as the route’s service. By default, the name of
52+
the created route is the same as the service name:
53+
54+
... Get the *podman-registry* service details:
55+
+
56+
----
57+
$ oc get svc
58+
NAME CLUSTER_IP EXTERNAL_IP PORT(S) SELECTOR AGE
59+
podman-registry 172.30.69.167 <none> 5000/TCP podman-registry=default 4h
60+
kubernetes 172.30.0.1 <none> 443/TCP,53/UDP,53/TCP <none> 4h
61+
router 172.30.172.132 <none> 80/TCP router=router 4h
62+
----
63+
64+
... Create the route:
65+
+
66+
----
67+
$ oc create route passthrough \
68+
--service=podman-registry \//<1>
69+
--hostname=<host>
70+
route "podman-registry" created <2>
71+
----
72+
<1> Specifies the registry as the route's service.
73+
<2> The route name is identical to the service name.
74+
75+
. Trust the certificates being used for the registry on your host
76+
system to allow the host to push and pull images. The certificates referenced
77+
were created when you secured your registry:
78+
+
79+
----
80+
$ sudo mkdir -p /etc/podman/certs.d/<host>
81+
$ sudo cp <ca_certificate_file> /etc/podman/certs.d/<host>
82+
$ sudo systemctl restart podman
83+
----
84+
85+
. Log in to the registry using the information from securing the registry.
86+
However, this time point to the host name used in the route rather than your
87+
service IP. When logging in to a secured and exposed registry, make sure you
88+
specify the registry in the `podman login` command:
89+
+
90+
----
91+
# podman login -e user@company.com \
92+
-u f83j5h6 \
93+
-p Ju1PeM47R0B92Lk3AZp-bWJSck2F7aGCiZ66aFGZrs2 \
94+
<host>
95+
----
96+
97+
. You can now tag and push images using the route host. For example, to tag and
98+
push a `busybox` image in a project called `test`:
99+
+
100+
----
101+
$ oc get imagestreams -n test
102+
NAME PODMAN REPO TAGS UPDATED
103+
104+
$ podman pull busybox
105+
$ podman tag busybox <host>/test/busybox
106+
$ podman push <host>/test/busybox
107+
The push refers to a repository [<host>/test/busybox] (len: 1)
108+
8c2e06607696: Image already exists
109+
6ce2e90b0bc7: Image successfully pushed
110+
cf2616975b4a: Image successfully pushed
111+
Digest: sha256:6c7e676d76921031532d7d9c0394d0da7c2906f4cb4c049904c4031147d8ca31
112+
113+
$ podman pull <host>/test/busybox
114+
latest: Pulling from <host>/test/busybox
115+
cf2616975b4a: Already exists
116+
6ce2e90b0bc7: Already exists
117+
8c2e06607696: Already exists
118+
Digest: sha256:6c7e676d76921031532d7d9c0394d0da7c2906f4cb4c049904c4031147d8ca31
119+
Status: Image is up to date for <host>/test/busybox:latest
120+
121+
$ oc get imagestreams -n test
122+
NAME PODMAN REPO TAGS UPDATED
123+
busybox 172.30.11.215:5000/test/busybox latest 2 seconds ago
124+
----
125+
+
126+
[NOTE]
127+
====
128+
Your image streams will have the IP address and port of the registry service,
129+
not the route name and port. See `oc get imagestreams` for details.
130+
====

0 commit comments

Comments
 (0)