GlusterFS: Full review and clean up

Signed-off-by: Jose A. Rivera <[email protected]>

Author: jarrpa

_snippets/glusterfs.adoc

@@ -0,0 +1,27 @@
+////
+How to use this file:
+
+* Use `include::_snippets/glusterfs.adoc[]` to enable the variables on a given
+  page.
+* When discussing the storage technology itself, just use "GlusterFS", e.g.
+  "GlusterFS volumes". It is incorrect to say, for example, "Red Hat Gluster
+  Storage volumes".
+* When discussing the base project or product, use `{gluster}`.
+* When discussing configurations of {gluster} that are managed by heketi, use
+  `{gluster-native}` if {gluster} is containerized and `{gluster-external}` if
+  it is not containerized.
+////
+:gluster: GlusterFS
+:gluster-native: Containerized GlusterFS
+:gluster-external: External GlusterFS
+:gluster-install-link: https://docs.gluster.org/en/latest/Install-Guide/Overview/
+:gluster-admin-link: https://docs.gluster.org/en/latest/Administrator%20Guide/overview/
+:gluster-role-link: https://github.com/openshift/openshift-ansible/tree/master/roles/openshift_storage_glusterfs
+ifdef::openshift-enterprise[]
+:gluster: Red Hat Gluster Storage
+:gluster-native: Container-Native Storage
+:gluster-external: Container-Ready Storage
+:gluster-install-link: https://access.redhat.com/documentation/en-us/red_hat_gluster_storage/3.3/html/installation_guide/
+:gluster-admin-link: https://access.redhat.com/documentation/en-us/red_hat_gluster_storage/3.3/html/administration_guide/
+:cns-link: https://access.redhat.com/documentation/en-us/red_hat_gluster_storage/3.3/html/container-native_storage_for_openshift_container_platform/
+endif::[]

_topic_map.yml

@@ -452,15 +452,11 @@ Topics:
     File: ceph_rbd_dynamic_example
   - Name: Complete Example Using GlusterFS
     File: gluster_example
-  - Name: Dynamic Provisioning Example Using Containerized GlusterFS
+  - Name: Complete Example Using GlusterFS for Dynamic Provisioning
     File: gluster_dynamic_example
-  - Name: Dynamic Provisioning Example Using Dedicated GlusterFS
-    File: dedicated_gluster_dynamic_example
-  - Name: Containerized Heketi for Managing Dedicated GlusterFS
-    File: containerized_heketi_with_dedicated_gluster
   - Name: Mounting Volumes To Privileged Pods
     File: privileged_pod_storage
-  - Name: Backing Docker Registry with GlusterFS Storage
+  - Name: Switching an Integrated OpenShift Container Registry to GlusterFS
     File: gluster_backed_registry
   - Name: Binding Persistent Volumes by Label
     File: binding_pv_by_label

install_config/install/advanced_install.adoc

@@ -14,10 +14,12 @@ endif::[]
 ifdef::openshift-origin[]
 :pb-prefix: ~/openshift-ansible/
 endif::[]
+include::_snippets/glusterfs.adoc[]
 
 toc::[]
 
 == Overview
+
 A reference configuration implemented using
 link:http://docs.ansible.com/ansible/[Ansible] playbooks is available as the _advanced
 installation_ method for installing a {product-title} cluster. Familiarity with Ansible is
@@ -842,11 +844,46 @@ openshift_cockpit_deployer_prefix='registry.example.com/openshift3/'
 openshift_cockpit_deployer_version='3.9.3'
 ----
 
+
+[[advanced-install-glusterfs-persistent-storage]]
+=== Configuring {gluster} Persistent Storage
+
+include::install_config/persistent_storage/topics/glusterfs_intro.adoc[]
+
+Additional information and examples, including the ones below, can be found at
+xref:../../install_config/persistent_storage/persistent_storage_glusterfs.adoc#install-config-persistent-storage-persistent-storage-glusterfs[Persistent Storage Using {gluster}].
+
+[[advanced-install-containerized-glusterfs-persistent-storage]]
+==== Configuring {gluster-native}
+
+[IMPORTANT]
+====
+See
+xref:../../install_config/install/prerequisites.adoc#prereq-containerized-glusterfs-considerations[{gluster-native} Considerations]
+for specific host preparations and prerequisites.
+====
+
+include::install_config/persistent_storage/topics/glusterfs_example_basic.adoc[]
+
+[[advanced-install-external-glusterfs-persistent-storage]]
+==== Configuring {gluster-external}
+
+include::install_config/persistent_storage/topics/glusterfs_example_basic_external.adoc[]
+
+[[advanced-install-registry]]
+=== Configuring an OpenShift Container Registry
+
+An integrated
+xref:../../architecture/infrastructure_components/image_registry.adoc#integrated-openshift-registry[OpenShift Container Registry]
+can be deployed using the advanced installer.
+
 [[advanced-install-registry-storage]]
 ==== Configuring Registry Storage
 
+If no registry storage options are used, the default OpenShift Container
+Registry is ephemeral and all data will be lost when the pod no longer exists.
 There are several options for enabling registry storage when using the advanced
-install:
+installer:
 
 [discrete]
 [[advanced-install-registry-storage-nfs-host-group]]
@@ -928,242 +965,25 @@ region endpoint parameter:
 openshift_hosted_registry_storage_s3_regionendpoint=https://myendpoint.example.com/
 ----
 
-
-[[advanced-install-glusterfs-persistent-storage]]
-=== Configuring GlusterFS Persistent Storage
-
-GlusterFS can be configured to provide
-xref:../../architecture/additional_concepts/storage.adoc#architecture-additional-concepts-storage[peristent storage] and
-xref:../../install_config/storage_examples/gluster_dynamic_example.adoc#install-config-persistent-storage-dynamically-provisioning-pvs[dynamic provisioning] for {product-title}. It can be used both containerized within
-{product-title} and non-containerized on its own nodes.
-
-[[advanced-install-containerized-glusterfs-persistent-storage]]
-==== Configuring Containerized GlusterFS Persistent Storage
-
-ifdef::openshift-enterprise[]
-This option utilizes
-link:https://access.redhat.com/documentation/en-us/red_hat_gluster_storage/3.2/html/container-native_storage_for_openshift_container_platform/[Red Hat Container Native Storage (CNS)] for configuring containerized GlusterFS persistent storage in {product-title}.
-endif::[]
-ifdef::openshift-origin[]
-See link:https://github.com/gluster/gluster-kubernetes[Running Containerized GlusterFS in Kubernetes] for additional information on containerized storage
-using GlusterFS.
-endif::[]
-
-[IMPORTANT]
-====
-See
-xref:../../install_config/install/prerequisites.adoc#prereq-containerized-glusterfs-considerations[Containerized GlusterFS Considerations] for specific host preparations and prerequisites.
-====
-
-. In your inventory file, add `glusterfs` in the `[OSEv3:children]` section to
-enable the `[glusterfs]` group:
-+
-----
-[OSEv3:children]
-masters
-nodes
-glusterfs
-----
-
-. (Optional) Include any of the following role variables in the `[OSEv3:vars]`
-section you wish to change:
-+
-----
-[OSEv3:vars]
-openshift_storage_glusterfs_namespace=glusterfs <1>
-openshift_storage_glusterfs_name=storage <2>
-----
-<1> The project (namespace) to host the storage pods. Defaults to `glusterfs`.
-<2> A name to identify the GlusterFS cluster, which will be used in resource names.
-Defaults to `storage`.
-
-. Add a `[glusterfs]` section with entries for each storage node that will host
-the GlusterFS storage and include the `glusterfs_ip` and
-`glusterfs_devices` parameters in the form:
-+
-----
-<hostname_or_ip> glusterfs_ip=<ip_address> glusterfs_devices='[ "</path/to/device1/>", "</path/to/device2>", ... ]'
-----
-+
-For example:
-+
-----
-[glusterfs]
-192.168.10.11 glusterfs_ip=192.168.10.11 glusterfs_devices='[ "/dev/xvdc", "/dev/xvdd" ]'
-192.168.10.12 glusterfs_ip=192.168.10.12 glusterfs_devices='[ "/dev/xvdc", "/dev/xvdd" ]'
-192.168.10.13 glusterfs_ip=192.168.10.13 glusterfs_devices='[ "/dev/xvdc", "/dev/xvdd" ]'
-----
-+
-Set `glusterfs_devices` to a list of raw block devices that will be completely
-managed as part of a GlusterFS cluster. There must be at least one device
-listed. Each device must be bare, with no partitions or LVM PVs. Set
-`glusterfs_ip` to the IP address that will be used by pods to communicate with
-the GlusterFS node.
-
-. Add the hosts listed under `[glusterfs]` to the `[nodes]` group as well:
-+
-----
-[nodes]
-192.168.10.11
-192.168.10.12
-192.168.10.13
-----
-
-. After completing the cluster installation per
-xref:running-the-advanced-installation[Running the Advanced Installation], run
-the following from a master to verify the necessary objects were successfully
-created:
-
-.. Verfiy that the GlusterFS `StorageClass` was created:
-+
-----
-# oc get storageclass
-NAME                  TYPE
-glusterfs-storage     kubernetes.io/glusterfs
-----
-
-.. Verify that the route was created:
-+
-----
-# oc get routes
-NAME            HOST/PORT                                     PATH           SERVICES   PORT   TERMINATION   WILDCARD
-heketi-glusterfs-route  heketi-glusterfs-default.cloudapps.example.com  heketi-glusterfs <all>             None
-----
-+
-[NOTE]
-====
-The name for the route will be `heketi-glusterfs-route` unless the default
-`glusterfs` value was overridden using the `openshift_glusterfs_storage_name`
-variable in the inventory file.
-====
-
-.. Use `curl` to verify the route works correctly:
-+
-----
-# curl http://heketi-glusterfs-default.cloudapps.example.com/hello
-Hello from Heketi.
-----
-
-After successful installation, see
-link:https://access.redhat.com/documentation/en-us/red_hat_gluster_storage/3.2/html/container-native_storage_for_openshift_container_platform/chap-documentation-red_hat_gluster_storage_container_native_with_openshift_platform-gluster_pod_operations[Operations
-on a Red Hat Gluster Storage Pod in an OpenShift Environment] to learn how to
-check the status of the GlusterFS clusters.
-
-xref:../../install_config/storage_examples/gluster_dynamic_example.adoc#install-config-persistent-storage-dynamically-provisioning-pvs[Dynamic provisioning] of GlusterFS volumes can occur by
-xref:../../install_config/storage_examples/gluster_dynamic_example.adoc#create-a-pvc-ro-request-storage-for-your-application[creating a PVC to request storage].
-
-[[advanced-install-configuring-openshift-container-registry]]
-=== Configuring the OpenShift Container Registry
-
-Additional configuration options are available at installation time for the
-xref:../../architecture/infrastructure_components/image_registry.adoc#integrated-openshift-registry[OpenShift Container Registry].
-
-If no registry storage options are used, the default {product-title} registry is
-ephermal and all data will be lost if the pod no longer exists. {product-title}
-also supports a single node NFS-backed registry, but this option lacks
-redundancy and reliability compared with the GlusterFS-backed option.
-
-[[advanced-install-containerized-glusterfs-backed-registry]]
-==== Configuring a Containerized GlusterFS-Backed Registry
+[discrete]
+[[advanced-install-registry-storage-glusterfs]]
+===== Option E: {gluster-native}
 
 Similar to
-xref:advanced-install-containerized-glusterfs-persistent-storage[configuring containerized GlusterFS for persistent storage], GlusterFS storage can be
-configured and deployed for an OpenShift Container Registry during the initial
-installation of the cluster to offer redundant and more reliable storage for the
-registry.
+xref:advanced-install-containerized-glusterfs-persistent-storage[configuring {gluster-native}],
+{gluster} can be configured to provide storage for an OpenShift Container
+Registry during the initial installation of the cluster to offer redundant and
+reliable storage for the registry.
 
 [IMPORTANT]
 ====
 See
-xref:../../install_config/install/prerequisites.adoc#prereq-containerized-glusterfs-considerations[Containerized
-GlusterFS Considerations] for specific host preparations and prerequisites.
+xref:../../install_config/install/prerequisites.adoc#prereq-containerized-glusterfs-considerations[{gluster-native} Considerations]
+for specific host preparations and prerequisites.
 ====
 
-Configuration of storage for an OpenShift Container Registry is very similar to
-configuration for GlusterFS persistent storage in that it can be either
-containerized or non-containerized. For this containerized method, the following
-exceptions and additions apply:
-
-. In your inventory file, add `glusterfs_registry` in the `[OSEv3:children]` section
-to enable the `[glusterfs_registry]` group:
-+
-----
-[OSEv3:children]
-masters
-nodes
-glusterfs_registry
-----
-
-. Add the following role variable in the `[OSEv3:vars]` section to enable the
-GlusterFS-backed registry, provided that the `glusterfs_registry` group name and
-the `[glusterfs_registry]` group exist:
-+
-----
-[OSEv3:vars]
-openshift_hosted_registry_storage_kind=glusterfs
-----
-
-. It is recommended to have at least three registry pods, so set the following
-role variable in the `[OSEv3:vars]` section:
-+
-----
-openshift_hosted_registry_replicas=3
-----
-
-. If you want to specify the volume size for the GlusterFS-backed registry, set
-the following role variable in `[OSEv3:vars]` section:
-+
-----
-openshift_hosted_registry_storage_volume_size=10Gi
-----
-+
-If unspecified, the volume size defaults to `5Gi`.
-
-. The installer will deploy the OpenShift Container Registry pods and associated
-routers on nodes containing the `region=infra` label. Add this label on at least
-one node entry in the `[nodes]` section, otherwise the registry deployment will
-fail. For example:
-+
-----
-[nodes]
-192.168.10.14 openshift_schedulable=True openshift_node_labels="{'region': 'infra'}"
-----
-
-. Add a `[glusterfs_registry]` section with entries for each storage node that
-will host the GlusterFS-backed registry and include the `glusterfs_ip` and
-`glusterfs_devices` parameters in the form:
-+
-----
-<hostname_or_ip> glusterfs_ip=<ip_address> glusterfs_devices='[ "</path/to/device1/>", "</path/to/device2>", ... ]'
-----
-+
-For example:
-+
-----
-[glusterfs_registry]
-192.168.10.14 glusterfs_ip=192.168.10.14 glusterfs_devices='[ "/dev/xvdc", "/dev/xvdd" ]'
-192.168.10.15 glusterfs_ip=192.168.10.15 glusterfs_devices='[ "/dev/xvdc", "/dev/xvdd" ]'
-192.168.10.16 glusterfs_ip=192.168.10.16 glusterfs_devices='[ "/dev/xvdc", "/dev/xvdd" ]'
-----
-+
-Set `glusterfs_devices` to a list of raw block devices that will be completely
-managed as part of a GlusterFS cluster. There must be at least one device
-listed. Each device must be bare, with no partitions or LVM PVs. Set
-`glusterfs_ip` to the IP address that will be used by pods to communicate with
-the GlusterFS node.
-
-. Add the hosts listed under `[glusterfs_registry]` to the `[nodes]` group as well:
-+
-----
-[nodes]
-192.168.10.14
-192.168.10.15
-192.168.10.16
-----
+include::install_config/persistent_storage/topics/glusterfs_example_registry.adoc[]
 
-After successful installation, see
-link:https://access.redhat.com/documentation/en-us/red_hat_gluster_storage/3.2/html/container-native_storage_for_openshift_container_platform/chap-documentation-red_hat_gluster_storage_container_native_with_openshift_platform-gluster_pod_operations[Operations on a Red Hat Gluster Storage Pod in an OpenShift Environment] to check the
-status of the GlusterFS clusters.
 
 [[advanced-install-configuring-global-proxy]]
 === Configuring Global Proxy Options