Add OpenStack-related documentation, incl. Cinder plugins

_build_cfg.yml

@@ -150,6 +150,8 @@ Topics:
     File: overview
   - Name: Master and Node Configuration
     File: master_node_configuration
+  - Name: Configuring with OpenStack
+    File: configuring_openstack
   - Name: Managing Nodes
     File: manage_nodes
   - Name: Routing from Edge Load Balancers
@@ -184,6 +186,8 @@ Topics:
         File: persistent_storage_nfs
       - Name: Using GlusterFS
         File: persistent_storage_glusterfs
+      - Name: Using OpenStack Cinder
+        File: persistent_storage_cinder
   - Name: IPtables
     File: iptables
   - Name: Native Container Routing

admin_guide/configuring_openstack.adoc

@@ -0,0 +1,75 @@
+= Configuring for OpenStack
+{product-author}
+{product-version}
+:data-uri:
+:icons:
+:experimental:
+:toc: macro
+:toc-title:
+
+toc::[]
+
+== Overview
+When deployed on
+link:https://www.openstack.org/[OpenStack], OpenShift can be configured to
+access OpenStack infrastructure and e.g. use
+link:https://access.redhat.com/documentation/en/red-hat-enterprise-linux-openstack-platform/version-7/red-hat-enterprise-linux-openstack-platform-7-architecture-guide/chapter-1-components#comp-cinder[OpenStack Cinder]
+volumes as persistent storage for application data.
+
+=== Cloud configuration
+As an administrator, create a *_/etc/cloud.conf_* file on all your OpenShift
+machines, both masters and nodes:
+
+----
+[Global]
+auth-url = <OS_AUTH_URL>
+username = <OS_USERNAME>
+password = <password>
+tenant-id = <OS_TENANT_ID>
+region = <OS_REGION_NAME>
+
+[LoadBalancer]
+subnet-id = <UUID of the load balancer subnet>
+----
+
+Consult your OpenStack administrators for values of the `*OS_*` variables,
+which are commonly used in OpenStack world.
+
+=== Master configuration
+
+Edit or
+link:master_node_configuration.html#creating-new-configuration-files[create]
+OpenShift master configuration file
+(*_/etc/openshift/master/master-config.yaml_* by default) and update content of
+`apiServerArguments` and `controllerArguments` sections:
+
+----
+kubernetesMasterConfig:
+  ...
+  apiServerArguments:
+    cloud-provider:
+      - "openstack"
+    cloud-config:
+      - "/etc/cloud.conf"
+  controllerArguments:
+    cloud-provider:
+      - "openstack"
+    cloud-config:
+      - "/etc/cloud.conf"
+----
+
+=== Node configuration
+
+Edit or
+link:master_node_configuration.html#creating-new-configuration-files[create]
+OpenShift node configuration file
+(*_/etc/openshift/node-<hostname>/node-config.yaml_* by default) and update
+content of `kubeletArguments` section:
+
+----
+kubeletArguments:
+  cloud-provider:
+    - "openstack"
+  cloud-config:
+    - "/etc/cloud.conf"
+----

admin_guide/persistent_storage/persistent_storage_cinder.adoc

@@ -0,0 +1,85 @@
+= Persistent Storage Using OpenStack Cinder volumes
+{product-author}
+{product-version}
+:data-uri:
+:icons:
+:experimental:
+:toc: macro
+:toc-title:
+:prewrap!:
+
+toc::[]
+
+== Overview
+You can provision your OpenShift cluster with
+link:../../architecture/additional_concepts/storage.html[persistent storage] using
+https://access.redhat.com/documentation/en/red-hat-enterprise-linux-openstack-platform/version-7/red-hat-enterprise-linux-openstack-platform-7-architecture-guide/chapter-1-components#comp-cinder[OpenStack Cinder].
+Some familiarity with Kubernetes and OpenStack is assumed.
+
+[NOTE]
+====
+OpenShift needs to be properly configured for OpenStack, see chapter
+link:../configuring_openstack.html[Configuring OpenShift on OpenStack]
+.
+====
+
+The Kubernetes link:../../dev_guide/persistent_volumes.html[persistent volume]
+framework allows administrators to provision a cluster with persistent storage
+and gives users a way to request those resources without having any knowledge of
+the underlying infrastructure.
+
+For a detailed example, see the guide for
+https://github.com/openshift/origin/tree/master/examples/wordpress[WordPress and
+MySQL using persistent volumes].
+
+[IMPORTANT]
+====
+High-availability of storage in the infrastructure is left to the underlying
+storage provider.
+====
+
+[[provisioning]]
+
+== Provisioning
+Storage must exist in the underlying infrastructure before it can be mounted as
+a volume in OpenShift. All that is required for Cinder is a Cinder volume ID and
+the `*PersistentVolume*` API.
+
+.Persistent Volume Object Definition
+====
+
+[source,yaml]
+----
+{
+  "apiVersion": "v1",
+  "kind": "PersistentVolume",
+  "metadata": {
+    "name": "pv0001"
+  },
+  "spec": {
+    "capacity": {
+        "storage": "5Gi"
+    },
+    "accessModes": [ "ReadWriteOnce" ],
+    "cinder": {
+        "fsType": "ext3",
+        "volumeID": "f37a03aa-6212-4c62-a805-9ce139fab180"
+    },
+  }
+}
+----
+====
+
+[[volume-format]]
+
+=== Volume Format
+Before OpenShift mounts the volume and passes it to a container, it checks that
+it contains a filesystem specified with `*fsType*` parameter. If the device is
+not formatted with the filesystem, all data from the device are erased and the
+device is automatically formatted with the given filesystem.
+
+This allows using unformatted Cinder volumes as persistent volumes, as OpenShift
+will format them before the first use. However, it can result in data loss if
+value of `*fsType*` parameter is changed after the volume was already formatted
+and provisioned with data.
+