<commit_before>[[install-config-storage-examples-gluster-backed-registry]]
= Backing Docker Registry with GlusterFS Storage
{product-author}
{product-version}
:data-uri:
:icons:
:experimental:
:toc: macro
:toc-title:
:prewrap:

toc::[]

== Overview

This topic reviews how to attach a GlusterFS persistent volume to the Docker
Registry.

It is assumed that the Docker registry service has already been started and the
Gluster volume has been created.

[[backing-docker-registry-with-glusterfs-storage-prerequisites]]
== Prerequisites

* The xref:../install/docker_registry.adoc#deploy-registry[docker-registry] was deployed *without*
configuring storage.
* A Gluster volume exists and *glusterfs-fuse* is installed on schedulable nodes.
* Definitions written for GlusterFS xref:../persistent_storage/persistent_storage_glusterfs.adoc#creating-gluster-endpoints[endpoints and service],
xref:../persistent_storage/persistent_storage_glusterfs.adoc#gfs-creating-persistent-volume[persistent volume (PV)],
and
xref:../../architecture/additional_concepts/storage.adoc#persistent-volume-claims[persistent volume claim (PVC)].
** For this guide, these will be:
*** *_gluster-endpoints-service.yaml_*
*** *_gluster-endpoints.yaml_*
*** *_gluster-pv.yaml_*
*** *_gluster-pvc.yaml_*
* A user with the
xref:../../admin_guide/manage_authorization_policy.adoc#managing-role-bindings[*cluster-admin*] role binding.
** For this guide, that user is *admin*.

[NOTE]
====
All `oc` commands are executed on the master node as the *admin* user.
====

[[create-gfs-pvc]]
== Create the Gluster Persistent Volume

First, make the Gluster volume available to the registry.

----
$ oc create -f gluster-endpoints-service.yaml
$ oc create -f gluster-endpoints.yaml
$ oc create -f gluster-pv.yaml
$ oc create -f gluster-pvc.yaml
----

Check to make sure the PV and PVC were created and bound successfully. The
expected output should resemble the following. Note that the PVC status is
*Bound*, indicating that it has bound to the PV.

----
$ oc get pv
NAME         LABELS    CAPACITY   ACCESSMODES   STATUS      CLAIM     REASON    AGE
gluster-pv   <none>    1Gi        RWX           Available                       37s
$ oc get pvc
NAME            LABELS    STATUS    VOLUME       CAPACITY   ACCESSMODES   AGE
gluster-claim   <none>    Bound     gluster-pv   1Gi        RWX           24s
----

[NOTE]
====
If either the PVC or PV failed to create or the PVC failed to bind, refer back
to the xref:../persistent_storage/persistent_storage_glusterfs.adoc#install-config-persistent-storage-persistent-storage-glusterfs[GlusterFS
Persistent Storage] guide. *Do not* proceed until they initialize and the PVC
status is *Bound*.
====

[[attach-pvc-to-reg]]
== Attach the PVC to the Docker Registry

Before moving forward, ensure that the *docker-registry* service is running.

----
$ oc get svc
NAME              CLUSTER_IP       EXTERNAL_IP   PORT(S)                 SELECTOR                  AGE
docker-registry   172.30.167.194   <none>        5000/TCP                docker-registry=default   18m
----

[NOTE]
====
If either the *docker-registry* service or its associated pod is not running,
refer back to the
xref:../install/docker_registry.adoc#deploy-registry[*docker-registry*] setup
instructions for troubleshooting before continuing.
====

Then, attach the PVC:

----
$ oc volume deploymentconfigs/docker-registry --add --name=v1 -t pvc \
     --claim-name=gluster-claim --overwrite
----

xref:../install/docker_registry.adoc#install-config-install-docker-registry[Deploying a Docker Registry] provides more
information on using the Docker registry.

[[backing-docker-registry-with-glusterfs-storage-issues]]
== Known Issues

[[backing-docker-registry-with-glusterfs-storage-pod-cannot-resolve]]
=== Pod Cannot Resolve the Volume Host

In non-production cases where the *dnsmasq* server is located on the same node
as the {product-title} master service, pods might not resolve to the host
machines when mounting the volume, causing errors in the
*docker-registry-1-deploy* pod. This can happen when *dnsmasq.service* fails to
start because of a collision with {product-title} DNS on port 53. To run the DNS
server on the master host, some configurations needs to be changed.

In *_/etc/dnsmasq.conf_*, add:

====
----
# Reverse DNS record for master
host-record=master.example.com,<master-IP>
# Wildcard DNS for {product-title} Applications - Points to Router
address=/apps.example.com/<master-IP>
# Forward .local queries to SkyDNS
server=/local/127.0.0.1#8053
# Forward reverse queries for service network to SkyDNS.
# This is for default {product-title} SDN - change as needed.
server=/17.30.172.in-addr.arpa/127.0.0.1#8053
----
====

With these settings, *dnsmasq* will pull from the *_/etc/hosts_* file on the
master node.

Add the appropriate host names and IPs for all necessary hosts.

In *_master-config.yaml_*, change `*bindAddress*` to:
====
----
dnsConfig:
 bindAddress: 127.0.0.1:8053
----
====

When pods are created, they receive a copy of *_/etc/resolv.conf_*, which
typically contains only the master DNS server so they can resolve external DNS
requests. To enable internal DNS resolution, insert the *dnsmasq* server at the
top of the server list. This way, *dnsmasq* will attempt to resolve requests
internally first.

In *_/etc/resolv.conf_* all scheduled nodes:

====
----
nameserver 192.168.1.100  <1>
nameserver 192.168.1.1    <2>
----
<1> Add the internal DNS server.
<2> Pre-existing external DNS server.
====

Once the configurations are changed, restart the {product-title} master and
*dnsmasq* services.

ifdef::openshift-enterprise[]
----
$ oc systemctl restart atomic-openshift-master
$ oc systemctl restart dnsmasq
----
endif::openshift-enterprise[]
ifdef::openshift-origin[]
----
$ oc systemctl restart origin-master
$ oc systemctl restart dnsmasq
----
endif::openshift-origin[]<commit_msg>Fixed {product-title} instances in code blocks and removed oc from systemctl commands<commit_after>[[install-config-storage-examples-gluster-backed-registry]]
= Backing Docker Registry with GlusterFS Storage
{product-author}
{product-version}
:data-uri:
:icons:
:experimental:
:toc: macro
:toc-title:
:prewrap:

toc::[]

== Overview

This topic reviews how to attach a GlusterFS persistent volume to the Docker
Registry.

It is assumed that the Docker registry service has already been started and the
Gluster volume has been created.

[[backing-docker-registry-with-glusterfs-storage-prerequisites]]
== Prerequisites

* The xref:../install/docker_registry.adoc#deploy-registry[docker-registry] was deployed *without*
configuring storage.
* A Gluster volume exists and *glusterfs-fuse* is installed on schedulable nodes.
* Definitions written for GlusterFS xref:../persistent_storage/persistent_storage_glusterfs.adoc#creating-gluster-endpoints[endpoints and service],
xref:../persistent_storage/persistent_storage_glusterfs.adoc#gfs-creating-persistent-volume[persistent volume (PV)],
and
xref:../../architecture/additional_concepts/storage.adoc#persistent-volume-claims[persistent volume claim (PVC)].
** For this guide, these will be:
*** *_gluster-endpoints-service.yaml_*
*** *_gluster-endpoints.yaml_*
*** *_gluster-pv.yaml_*
*** *_gluster-pvc.yaml_*
* A user with the
xref:../../admin_guide/manage_authorization_policy.adoc#managing-role-bindings[*cluster-admin*] role binding.
** For this guide, that user is *admin*.

[NOTE]
====
All `oc` commands are executed on the master node as the *admin* user.
====

[[create-gfs-pvc]]
== Create the Gluster Persistent Volume

First, make the Gluster volume available to the registry.

----
$ oc create -f gluster-endpoints-service.yaml
$ oc create -f gluster-endpoints.yaml
$ oc create -f gluster-pv.yaml
$ oc create -f gluster-pvc.yaml
----

Check to make sure the PV and PVC were created and bound successfully. The
expected output should resemble the following. Note that the PVC status is
*Bound*, indicating that it has bound to the PV.

----
$ oc get pv
NAME         LABELS    CAPACITY   ACCESSMODES   STATUS      CLAIM     REASON    AGE
gluster-pv   <none>    1Gi        RWX           Available                       37s
$ oc get pvc
NAME            LABELS    STATUS    VOLUME       CAPACITY   ACCESSMODES   AGE
gluster-claim   <none>    Bound     gluster-pv   1Gi        RWX           24s
----

[NOTE]
====
If either the PVC or PV failed to create or the PVC failed to bind, refer back
to the xref:../persistent_storage/persistent_storage_glusterfs.adoc#install-config-persistent-storage-persistent-storage-glusterfs[GlusterFS
Persistent Storage] guide. *Do not* proceed until they initialize and the PVC
status is *Bound*.
====

[[attach-pvc-to-reg]]
== Attach the PVC to the Docker Registry

Before moving forward, ensure that the *docker-registry* service is running.

----
$ oc get svc
NAME              CLUSTER_IP       EXTERNAL_IP   PORT(S)                 SELECTOR                  AGE
docker-registry   172.30.167.194   <none>        5000/TCP                docker-registry=default   18m
----

[NOTE]
====
If either the *docker-registry* service or its associated pod is not running,
refer back to the
xref:../install/docker_registry.adoc#deploy-registry[*docker-registry*] setup
instructions for troubleshooting before continuing.
====

Then, attach the PVC:

----
$ oc volume deploymentconfigs/docker-registry --add --name=v1 -t pvc \
     --claim-name=gluster-claim --overwrite
----

xref:../install/docker_registry.adoc#install-config-install-docker-registry[Deploying a Docker Registry] provides more
information on using the Docker registry.

[[backing-docker-registry-with-glusterfs-storage-issues]]
== Known Issues

[[backing-docker-registry-with-glusterfs-storage-pod-cannot-resolve]]
=== Pod Cannot Resolve the Volume Host

In non-production cases where the *dnsmasq* server is located on the same node
as the {product-title} master service, pods might not resolve to the host
machines when mounting the volume, causing errors in the
*docker-registry-1-deploy* pod. This can happen when *dnsmasq.service* fails to
start because of a collision with {product-title} DNS on port 53. To run the DNS
server on the master host, some configurations needs to be changed.

In *_/etc/dnsmasq.conf_*, add:

====
----
# Reverse DNS record for master
host-record=master.example.com,<master-IP>
# Wildcard DNS for OpenShift Applications - Points to Router
address=/apps.example.com/<master-IP>
# Forward .local queries to SkyDNS
server=/local/127.0.0.1#8053
# Forward reverse queries for service network to SkyDNS.
# This is for default OpenShift SDN - change as needed.
server=/17.30.172.in-addr.arpa/127.0.0.1#8053
----
====

With these settings, *dnsmasq* will pull from the *_/etc/hosts_* file on the
master node.

Add the appropriate host names and IPs for all necessary hosts.

In *_master-config.yaml_*, change `*bindAddress*` to:
====
----
dnsConfig:
 bindAddress: 127.0.0.1:8053
----
====

When pods are created, they receive a copy of *_/etc/resolv.conf_*, which
typically contains only the master DNS server so they can resolve external DNS
requests. To enable internal DNS resolution, insert the *dnsmasq* server at the
top of the server list. This way, *dnsmasq* will attempt to resolve requests
internally first.

In *_/etc/resolv.conf_* all scheduled nodes:

====
----
nameserver 192.168.1.100  <1>
nameserver 192.168.1.1    <2>
----
<1> Add the internal DNS server.
<2> Pre-existing external DNS server.
====

Once the configurations are changed, restart the {product-title} master and
*dnsmasq* services.

ifdef::openshift-enterprise[]
----
$ systemctl restart atomic-openshift-master
$ systemctl restart dnsmasq
----
endif::openshift-enterprise[]
ifdef::openshift-origin[]
----
$ systemctl restart origin-master
$ systemctl restart dnsmasq
----
endif::openshift-origin[]
{'fraction_non_alphanumeric': 0.11044549443131961, 'fraction_numerical': 0.01451231859601755, 'mean_word_length': 3.7621534752912815, 'pattern_counts': {'":': 0, '<': 21, '<?xml version=': 0, '>': 21, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 12, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '935329', 'n_tokens_mistral': 3877, 'n_tokens_neox': 3538, 'n_words': 1210}