From 88be92ee719baff6d5f2f7e7e073b118db2dc2e0 Mon Sep 17 00:00:00 2001
From: Alexandra Settle <a.settle@outlook.com>
Date: Mon, 26 Jun 2017 11:56:25 +0100
Subject: [PATCH] import installation guide pages from openstack-manuals

Change-Id: Id1ee4d52174b4a5e66c7d306e28b9c12a06d00e2
---
 doc/source/index.rst                          |   8 +
 .../install/cinder-backup-install-obs.rst     |  60 +++
 .../install/cinder-backup-install-rdo.rst     |  61 +++
 .../install/cinder-backup-install-ubuntu.rst  |  56 +++
 .../install/cinder-controller-install-obs.rst | 344 +++++++++++++++++
 .../install/cinder-controller-install-rdo.rst | 354 ++++++++++++++++++
 .../cinder-controller-install-ubuntu.rst      | 353 +++++++++++++++++
 .../install/cinder-storage-install-obs.rst    | 273 ++++++++++++++
 .../install/cinder-storage-install-rdo.rst    | 288 ++++++++++++++
 .../install/cinder-storage-install-ubuntu.rst | 275 ++++++++++++++
 doc/source/install/cinder-verify.rst          |  35 ++
 doc/source/install/index-obs.rst              |  23 ++
 doc/source/install/index-rdo.rst              |  23 ++
 doc/source/install/index-ubuntu.rst           |  23 ++
 doc/source/install/index.rst                  |  24 ++
 15 files changed, 2200 insertions(+)
 create mode 100644 doc/source/install/cinder-backup-install-obs.rst
 create mode 100644 doc/source/install/cinder-backup-install-rdo.rst
 create mode 100644 doc/source/install/cinder-backup-install-ubuntu.rst
 create mode 100644 doc/source/install/cinder-controller-install-obs.rst
 create mode 100644 doc/source/install/cinder-controller-install-rdo.rst
 create mode 100644 doc/source/install/cinder-controller-install-ubuntu.rst
 create mode 100644 doc/source/install/cinder-storage-install-obs.rst
 create mode 100644 doc/source/install/cinder-storage-install-rdo.rst
 create mode 100644 doc/source/install/cinder-storage-install-ubuntu.rst
 create mode 100644 doc/source/install/cinder-verify.rst
 create mode 100644 doc/source/install/index-obs.rst
 create mode 100644 doc/source/install/index-rdo.rst
 create mode 100644 doc/source/install/index-ubuntu.rst
 create mode 100644 doc/source/install/index.rst

diff --git a/doc/source/index.rst b/doc/source/index.rst
index 84202b4987c..0dd94dd049f 100644
--- a/doc/source/index.rst
+++ b/doc/source/index.rst
@@ -34,6 +34,14 @@ be found on the `OpenStack wiki`_. Cloud administrators, refer to `docs.openstac
 .. _`docs.openstack.org`: http://docs.openstack.org
 
 
+Installing Cinder
+=================
+
+.. toctree::
+   :maxdepth: 2
+
+   install/index
+
 Developer Docs
 ==============
 
diff --git a/doc/source/install/cinder-backup-install-obs.rst b/doc/source/install/cinder-backup-install-obs.rst
new file mode 100644
index 00000000000..8aece5e116c
--- /dev/null
+++ b/doc/source/install/cinder-backup-install-obs.rst
@@ -0,0 +1,60 @@
+:orphan:
+
+Install and configure the backup service
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Optionally, install and configure the backup service. For simplicity,
+this configuration uses the Block Storage node and the Object Storage
+(swift) driver, thus depending on the
+`Object Storage service <https://docs.openstack.org/project-install-guide/object-storage/ocata/>`_.
+
+.. note::
+
+   You must :ref:`install and configure a storage node <cinder-storage>` prior
+   to installing and configuring the backup service.
+
+Install and configure components
+--------------------------------
+
+.. note::
+
+   Perform these steps on the Block Storage node.
+
+
+#. Install the packages:
+
+   .. code-block:: console
+
+      # zypper install openstack-cinder-backup
+
+#. Edit the ``/etc/cinder/cinder.conf`` file
+   and complete the following actions:
+
+   #. In the ``[DEFAULT]`` section, configure backup options:
+
+      .. path /etc/cinder/cinder.conf
+      .. code-block:: ini
+
+         [DEFAULT]
+         # ...
+         backup_driver = cinder.backup.drivers.swift
+         backup_swift_url = SWIFT_URL
+
+
+      Replace ``SWIFT_URL`` with the URL of the Object Storage service. The
+      URL can be found by showing the object-store API endpoints:
+
+      .. code-block:: console
+
+       $ openstack catalog show object-store
+
+Finalize installation
+---------------------
+
+Start the Block Storage backup service and configure it to
+start when the system boots:
+
+.. code-block:: console
+
+   # systemctl enable openstack-cinder-backup.service
+   # systemctl start openstack-cinder-backup.service
diff --git a/doc/source/install/cinder-backup-install-rdo.rst b/doc/source/install/cinder-backup-install-rdo.rst
new file mode 100644
index 00000000000..68826ccc427
--- /dev/null
+++ b/doc/source/install/cinder-backup-install-rdo.rst
@@ -0,0 +1,61 @@
+:orphan:
+
+Install and configure the backup service
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Optionally, install and configure the backup service. For simplicity,
+this configuration uses the Block Storage node and the Object Storage
+(swift) driver, thus depending on the
+`Object Storage service <https://docs.openstack.org/project-install-guide/object-storage/ocata/>`_.
+
+.. note::
+
+   You must :ref:`install and configure a storage node <cinder-storage>` prior
+   to installing and configuring the backup service.
+
+Install and configure components
+--------------------------------
+
+.. note::
+
+   Perform these steps on the Block Storage node.
+
+#. Install the packages:
+
+   .. code-block:: console
+
+      # yum install openstack-cinder
+
+
+#. Edit the ``/etc/cinder/cinder.conf`` file
+   and complete the following actions:
+
+   #. In the ``[DEFAULT]`` section, configure backup options:
+
+      .. path /etc/cinder/cinder.conf
+      .. code-block:: ini
+
+         [DEFAULT]
+         # ...
+         backup_driver = cinder.backup.drivers.swift
+         backup_swift_url = SWIFT_URL
+
+
+      Replace ``SWIFT_URL`` with the URL of the Object Storage service. The
+      URL can be found by showing the object-store API endpoints:
+
+      .. code-block:: console
+
+       $ openstack catalog show object-store
+
+
+Finalize installation
+---------------------
+
+Start the Block Storage backup service and configure it to
+start when the system boots:
+
+.. code-block:: console
+
+   # systemctl enable openstack-cinder-backup.service
+   # systemctl start openstack-cinder-backup.service
diff --git a/doc/source/install/cinder-backup-install-ubuntu.rst b/doc/source/install/cinder-backup-install-ubuntu.rst
new file mode 100644
index 00000000000..79a0932502c
--- /dev/null
+++ b/doc/source/install/cinder-backup-install-ubuntu.rst
@@ -0,0 +1,56 @@
+:orphan:
+
+Install and configure the backup service
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Optionally, install and configure the backup service. For simplicity,
+this configuration uses the Block Storage node and the Object Storage
+(swift) driver, thus depending on the
+`Object Storage service <https://docs.openstack.org/project-install-guide/object-storage/ocata/>`_.
+
+.. note::
+
+   You must :ref:`install and configure a storage node <cinder-storage>` prior
+   to installing and configuring the backup service.
+
+Install and configure components
+--------------------------------
+
+.. note::
+
+   Perform these steps on the Block Storage node.
+
+#. Install the packages:
+
+   .. code-block:: console
+
+     # apt install cinder-backup
+
+2. Edit the ``/etc/cinder/cinder.conf`` file
+   and complete the following actions:
+
+   * In the ``[DEFAULT]`` section, configure backup options:
+
+     .. path /etc/cinder/cinder.conf
+     .. code-block:: ini
+
+        [DEFAULT]
+        # ...
+        backup_driver = cinder.backup.drivers.swift
+        backup_swift_url = SWIFT_URL
+
+     Replace ``SWIFT_URL`` with the URL of the Object Storage service. The
+     URL can be found by showing the object-store API endpoints:
+
+     .. code-block:: console
+
+      $ openstack catalog show object-store
+
+Finalize installation
+---------------------
+
+Restart the Block Storage backup service:
+
+.. code-block:: console
+
+   # service cinder-backup restart
diff --git a/doc/source/install/cinder-controller-install-obs.rst b/doc/source/install/cinder-controller-install-obs.rst
new file mode 100644
index 00000000000..9df1615aee0
--- /dev/null
+++ b/doc/source/install/cinder-controller-install-obs.rst
@@ -0,0 +1,344 @@
+Install and configure controller node
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+This section describes how to install and configure the Block
+Storage service, code-named cinder, on the controller node. This
+service requires at least one additional storage node that provides
+volumes to instances.
+
+Prerequisites
+-------------
+
+Before you install and configure the Block Storage service, you
+must create a database, service credentials, and API endpoints.
+
+#. To create the database, complete these steps:
+
+   #.  Use the database access client to connect to the database
+       server as the ``root`` user:
+
+       .. code-block:: console
+
+          $ mysql -u root -p
+
+   #. Create the ``cinder`` database:
+
+      .. code-block:: console
+
+         MariaDB [(none)]> CREATE DATABASE cinder;
+
+   #. Grant proper access to the ``cinder`` database:
+
+      .. code-block:: console
+
+         MariaDB [(none)]> GRANT ALL PRIVILEGES ON cinder.* TO 'cinder'@'localhost' \
+           IDENTIFIED BY 'CINDER_DBPASS';
+         MariaDB [(none)]> GRANT ALL PRIVILEGES ON cinder.* TO 'cinder'@'%' \
+           IDENTIFIED BY 'CINDER_DBPASS';
+
+      Replace ``CINDER_DBPASS`` with a suitable password.
+
+   #. Exit the database access client.
+
+#. Source the ``admin`` credentials to gain access to admin-only
+   CLI commands:
+
+   .. code-block:: console
+
+      $ . admin-openrc
+
+#. To create the service credentials, complete these steps:
+
+   #. Create a ``cinder`` user:
+
+      .. code-block:: console
+
+         $ openstack user create --domain default --password-prompt cinder
+
+        User Password:
+        Repeat User Password:
+        +---------------------+----------------------------------+
+        | Field               | Value                            |
+        +---------------------+----------------------------------+
+        | domain_id           | default                          |
+        | enabled             | True                             |
+        | id                  | 9d7e33de3e1a498390353819bc7d245d |
+        | name                | cinder                           |
+        | options             | {}                               |
+        | password_expires_at | None                             |
+        +---------------------+----------------------------------+
+
+   #. Add the ``admin`` role to the ``cinder`` user:
+
+      .. code-block:: console
+
+         $ openstack role add --project service --user cinder admin
+
+     .. note::
+
+        This command provides no output.
+
+   #. Create the ``cinderv2`` and ``cinderv3`` service entities:
+
+      .. code-block:: console
+
+         $ openstack service create --name cinderv2 \
+          --description "OpenStack Block Storage" volumev2
+
+        +-------------+----------------------------------+
+        | Field       | Value                            |
+        +-------------+----------------------------------+
+        | description | OpenStack Block Storage          |
+        | enabled     | True                             |
+        | id          | eb9fd245bdbc414695952e93f29fe3ac |
+        | name        | cinderv2                         |
+        | type        | volumev2                         |
+        +-------------+----------------------------------+
+
+      .. code-block:: console
+
+         $ openstack service create --name cinderv3 \
+          --description "OpenStack Block Storage" volumev3
+
+        +-------------+----------------------------------+
+        | Field       | Value                            |
+        +-------------+----------------------------------+
+        | description | OpenStack Block Storage          |
+        | enabled     | True                             |
+        | id          | ab3bbbef780845a1a283490d281e7fda |
+        | name        | cinderv3                         |
+        | type        | volumev3                         |
+        +-------------+----------------------------------+
+
+.. note::
+
+      The Block Storage services require two service entities.
+
+#. Create the Block Storage service API endpoints:
+
+   .. code-block:: console
+
+      $ openstack endpoint create --region RegionOne \
+        volumev2 public http://controller:8776/v2/%\(project_id\)s
+
+      +--------------+------------------------------------------+
+      | Field        | Value                                    |
+      +--------------+------------------------------------------+
+      | enabled      | True                                     |
+      | id           | 513e73819e14460fb904163f41ef3759         |
+      | interface    | public                                   |
+      | region       | RegionOne                                |
+      | region_id    | RegionOne                                |
+      | service_id   | eb9fd245bdbc414695952e93f29fe3ac         |
+      | service_name | cinderv2                                 |
+      | service_type | volumev2                                 |
+      | url          | http://controller:8776/v2/%(project_id)s |
+      +--------------+------------------------------------------+
+
+      $ openstack endpoint create --region RegionOne \
+        volumev2 internal http://controller:8776/v2/%\(project_id\)s
+
+      +--------------+------------------------------------------+
+      | Field        | Value                                    |
+      +--------------+------------------------------------------+
+      | enabled      | True                                     |
+      | id           | 6436a8a23d014cfdb69c586eff146a32         |
+      | interface    | internal                                 |
+      | region       | RegionOne                                |
+      | region_id    | RegionOne                                |
+      | service_id   | eb9fd245bdbc414695952e93f29fe3ac         |
+      | service_name | cinderv2                                 |
+      | service_type | volumev2                                 |
+      | url          | http://controller:8776/v2/%(project_id)s |
+      +--------------+------------------------------------------+
+
+      $ openstack endpoint create --region RegionOne \
+        volumev2 admin http://controller:8776/v2/%\(project_id\)s
+
+      +--------------+------------------------------------------+
+      | Field        | Value                                    |
+      +--------------+------------------------------------------+
+      | enabled      | True                                     |
+      | id           | e652cf84dd334f359ae9b045a2c91d96         |
+      | interface    | admin                                    |
+      | region       | RegionOne                                |
+      | region_id    | RegionOne                                |
+      | service_id   | eb9fd245bdbc414695952e93f29fe3ac         |
+      | service_name | cinderv2                                 |
+      | service_type | volumev2                                 |
+      | url          | http://controller:8776/v2/%(project_id)s |
+      +--------------+------------------------------------------+
+
+   .. code-block:: console
+
+      $ openstack endpoint create --region RegionOne \
+        volumev3 public http://controller:8776/v3/%\(project_id\)s
+
+      +--------------+------------------------------------------+
+      | Field        | Value                                    |
+      +--------------+------------------------------------------+
+      | enabled      | True                                     |
+      | id           | 03fa2c90153546c295bf30ca86b1344b         |
+      | interface    | public                                   |
+      | region       | RegionOne                                |
+      | region_id    | RegionOne                                |
+      | service_id   | ab3bbbef780845a1a283490d281e7fda         |
+      | service_name | cinderv3                                 |
+      | service_type | volumev3                                 |
+      | url          | http://controller:8776/v3/%(project_id)s |
+      +--------------+------------------------------------------+
+
+      $ openstack endpoint create --region RegionOne \
+        volumev3 internal http://controller:8776/v3/%\(project_id\)s
+
+      +--------------+------------------------------------------+
+      | Field        | Value                                    |
+      +--------------+------------------------------------------+
+      | enabled      | True                                     |
+      | id           | 94f684395d1b41068c70e4ecb11364b2         |
+      | interface    | internal                                 |
+      | region       | RegionOne                                |
+      | region_id    | RegionOne                                |
+      | service_id   | ab3bbbef780845a1a283490d281e7fda         |
+      | service_name | cinderv3                                 |
+      | service_type | volumev3                                 |
+      | url          | http://controller:8776/v3/%(project_id)s |
+      +--------------+------------------------------------------+
+
+      $ openstack endpoint create --region RegionOne \
+        volumev3 admin http://controller:8776/v3/%\(project_id\)s
+
+      +--------------+------------------------------------------+
+      | Field        | Value                                    |
+      +--------------+------------------------------------------+
+      | enabled      | True                                     |
+      | id           | 4511c28a0f9840c78bacb25f10f62c98         |
+      | interface    | admin                                    |
+      | region       | RegionOne                                |
+      | region_id    | RegionOne                                |
+      | service_id   | ab3bbbef780845a1a283490d281e7fda         |
+      | service_name | cinderv3                                 |
+      | service_type | volumev3                                 |
+      | url          | http://controller:8776/v3/%(project_id)s |
+      +--------------+------------------------------------------+
+
+   .. note::
+
+      The Block Storage services require endpoints for each service
+      entity.
+
+Install and configure components
+--------------------------------
+
+
+#. Install the packages:
+
+   .. code-block:: console
+
+      # zypper install openstack-cinder-api openstack-cinder-scheduler
+
+#. Edit the ``/etc/cinder/cinder.conf`` file and complete the
+   following actions:
+
+   #. In the ``[database]`` section, configure database access:
+
+      .. path /etc/cinder/cinder.conf
+      .. code-block:: ini
+
+         [database]
+         # ...
+         connection = mysql+pymysql://cinder:CINDER_DBPASS@controller/cinder
+
+      Replace ``CINDER_DBPASS`` with the password you chose for the
+      Block Storage database.
+
+   #. In the ``[DEFAULT]`` section, configure ``RabbitMQ``
+      message queue access:
+
+      .. path /etc/cinder/cinder.conf
+      .. code-block:: ini
+
+         [DEFAULT]
+         # ...
+         transport_url = rabbit://openstack:RABBIT_PASS@controller
+
+      Replace ``RABBIT_PASS`` with the password you chose for the
+     ``openstack`` account in ``RabbitMQ``.
+
+  #. In the ``[DEFAULT]`` and ``[keystone_authtoken]`` sections,
+     configure Identity service access:
+
+     .. path /etc/cinder/cinder.conf
+     .. code-block:: ini
+
+        [DEFAULT]
+        # ...
+        auth_strategy = keystone
+
+        [keystone_authtoken]
+        # ...
+        auth_uri = http://controller:5000
+        auth_url = http://controller:35357
+        memcached_servers = controller:11211
+        auth_type = password
+        project_domain_name = default
+        user_domain_name = default
+        project_name = service
+        username = cinder
+        password = CINDER_PASS
+
+      Replace ``CINDER_PASS`` with the password you chose for
+      the ``cinder`` user in the Identity service.
+
+      .. note::
+
+         Comment out or remove any other options in the
+         ``[keystone_authtoken]`` section.
+
+   #. In the ``[DEFAULT]`` section, configure the ``my_ip`` option to
+      use the management interface IP address of the controller node:
+
+      .. path /etc/cinder/cinder.conf
+      .. code-block:: ini
+
+         [DEFAULT]
+         # ...
+         my_ip = 10.0.0.11
+
+#. In the ``[oslo_concurrency]`` section, configure the lock path:
+
+   .. path /etc/cinder/cinder.conf
+   .. code-block:: ini
+
+      [oslo_concurrency]
+      # ...
+      lock_path = /var/lib/cinder/tmp
+
+Configure Compute to use Block Storage
+--------------------------------------
+
+#. Edit the ``/etc/nova/nova.conf`` file and add the following
+   to it:
+
+   .. path /etc/nova/nova.conf
+   .. code-block:: ini
+
+      [cinder]
+      os_region_name = RegionOne
+
+Finalize installation
+---------------------
+
+#. Restart the Compute API service:
+
+   .. code-block:: console
+
+      # systemctl restart openstack-nova-api.service
+
+#. Start the Block Storage services and configure them to start when
+   the system boots:
+
+   .. code-block:: console
+
+      # systemctl enable openstack-cinder-api.service openstack-cinder-scheduler.service
+      # systemctl start openstack-cinder-api.service openstack-cinder-scheduler.service
diff --git a/doc/source/install/cinder-controller-install-rdo.rst b/doc/source/install/cinder-controller-install-rdo.rst
new file mode 100644
index 00000000000..2abd63f1805
--- /dev/null
+++ b/doc/source/install/cinder-controller-install-rdo.rst
@@ -0,0 +1,354 @@
+Install and configure controller node
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+This section describes how to install and configure the Block
+Storage service, code-named cinder, on the controller node. This
+service requires at least one additional storage node that provides
+volumes to instances.
+
+Prerequisites
+-------------
+
+Before you install and configure the Block Storage service, you
+must create a database, service credentials, and API endpoints.
+
+#. To create the database, complete these steps:
+
+   #. Use the database access client to connect to the database
+      server as the ``root`` user:
+
+      .. code-block:: console
+
+         $ mysql -u root -p
+
+   #. Create the ``cinder`` database:
+
+      .. code-block:: console
+
+         MariaDB [(none)]> CREATE DATABASE cinder;
+
+   #. Grant proper access to the ``cinder`` database:
+
+      .. code-block:: console
+
+         MariaDB [(none)]> GRANT ALL PRIVILEGES ON cinder.* TO 'cinder'@'localhost' \
+           IDENTIFIED BY 'CINDER_DBPASS';
+         MariaDB [(none)]> GRANT ALL PRIVILEGES ON cinder.* TO 'cinder'@'%' \
+           IDENTIFIED BY 'CINDER_DBPASS';
+
+      Replace ``CINDER_DBPASS`` with a suitable password.
+
+   #. Exit the database access client.
+
+#. Source the ``admin`` credentials to gain access to admin-only
+   CLI commands:
+
+   .. code-block:: console
+
+      $ . admin-openrc
+
+#. To create the service credentials, complete these steps:
+
+   #. Create a ``cinder`` user:
+
+      .. code-block:: console
+
+         $ openstack user create --domain default --password-prompt cinder
+
+        User Password:
+        Repeat User Password:
+        +---------------------+----------------------------------+
+        | Field               | Value                            |
+        +---------------------+----------------------------------+
+        | domain_id           | default                          |
+        | enabled             | True                             |
+        | id                  | 9d7e33de3e1a498390353819bc7d245d |
+        | name                | cinder                           |
+        | options             | {}                               |
+        | password_expires_at | None                             |
+        +---------------------+----------------------------------+
+
+   #. Add the ``admin`` role to the ``cinder`` user:
+
+      .. code-block:: console
+
+         $ openstack role add --project service --user cinder admin
+
+      .. note::
+
+         This command provides no output.
+
+   #. Create the ``cinderv2`` and ``cinderv3`` service entities:
+
+      .. code-block:: console
+
+         $ openstack service create --name cinderv2 \
+          --description "OpenStack Block Storage" volumev2
+
+        +-------------+----------------------------------+
+        | Field       | Value                            |
+        +-------------+----------------------------------+
+        | description | OpenStack Block Storage          |
+        | enabled     | True                             |
+        | id          | eb9fd245bdbc414695952e93f29fe3ac |
+        | name        | cinderv2                         |
+        | type        | volumev2                         |
+        +-------------+----------------------------------+
+
+      .. code-block:: console
+
+         $ openstack service create --name cinderv3 \
+          --description "OpenStack Block Storage" volumev3
+
+        +-------------+----------------------------------+
+        | Field       | Value                            |
+        +-------------+----------------------------------+
+        | description | OpenStack Block Storage          |
+        | enabled     | True                             |
+        | id          | ab3bbbef780845a1a283490d281e7fda |
+        | name        | cinderv3                         |
+        | type        | volumev3                         |
+        +-------------+----------------------------------+
+
+    .. note::
+
+       The Block Storage services require two service entities.
+
+#. Create the Block Storage service API endpoints:
+
+   .. code-block:: console
+
+      $ openstack endpoint create --region RegionOne \
+        volumev2 public http://controller:8776/v2/%\(project_id\)s
+
+      +--------------+------------------------------------------+
+      | Field        | Value                                    |
+      +--------------+------------------------------------------+
+      | enabled      | True                                     |
+      | id           | 513e73819e14460fb904163f41ef3759         |
+      | interface    | public                                   |
+      | region       | RegionOne                                |
+      | region_id    | RegionOne                                |
+      | service_id   | eb9fd245bdbc414695952e93f29fe3ac         |
+      | service_name | cinderv2                                 |
+      | service_type | volumev2                                 |
+      | url          | http://controller:8776/v2/%(project_id)s |
+      +--------------+------------------------------------------+
+
+      $ openstack endpoint create --region RegionOne \
+        volumev2 internal http://controller:8776/v2/%\(project_id\)s
+
+      +--------------+------------------------------------------+
+      | Field        | Value                                    |
+      +--------------+------------------------------------------+
+      | enabled      | True                                     |
+      | id           | 6436a8a23d014cfdb69c586eff146a32         |
+      | interface    | internal                                 |
+      | region       | RegionOne                                |
+      | region_id    | RegionOne                                |
+      | service_id   | eb9fd245bdbc414695952e93f29fe3ac         |
+      | service_name | cinderv2                                 |
+      | service_type | volumev2                                 |
+      | url          | http://controller:8776/v2/%(project_id)s |
+      +--------------+------------------------------------------+
+
+      $ openstack endpoint create --region RegionOne \
+        volumev2 admin http://controller:8776/v2/%\(project_id\)s
+
+      +--------------+------------------------------------------+
+      | Field        | Value                                    |
+      +--------------+------------------------------------------+
+      | enabled      | True                                     |
+      | id           | e652cf84dd334f359ae9b045a2c91d96         |
+      | interface    | admin                                    |
+      | region       | RegionOne                                |
+      | region_id    | RegionOne                                |
+      | service_id   | eb9fd245bdbc414695952e93f29fe3ac         |
+      | service_name | cinderv2                                 |
+      | service_type | volumev2                                 |
+      | url          | http://controller:8776/v2/%(project_id)s |
+      +--------------+------------------------------------------+
+
+   .. code-block:: console
+
+      $ openstack endpoint create --region RegionOne \
+        volumev3 public http://controller:8776/v3/%\(project_id\)s
+
+      +--------------+------------------------------------------+
+      | Field        | Value                                    |
+      +--------------+------------------------------------------+
+      | enabled      | True                                     |
+      | id           | 03fa2c90153546c295bf30ca86b1344b         |
+      | interface    | public                                   |
+      | region       | RegionOne                                |
+      | region_id    | RegionOne                                |
+      | service_id   | ab3bbbef780845a1a283490d281e7fda         |
+      | service_name | cinderv3                                 |
+      | service_type | volumev3                                 |
+      | url          | http://controller:8776/v3/%(project_id)s |
+      +--------------+------------------------------------------+
+
+      $ openstack endpoint create --region RegionOne \
+        volumev3 internal http://controller:8776/v3/%\(project_id\)s
+
+      +--------------+------------------------------------------+
+      | Field        | Value                                    |
+      +--------------+------------------------------------------+
+      | enabled      | True                                     |
+      | id           | 94f684395d1b41068c70e4ecb11364b2         |
+      | interface    | internal                                 |
+      | region       | RegionOne                                |
+      | region_id    | RegionOne                                |
+      | service_id   | ab3bbbef780845a1a283490d281e7fda         |
+      | service_name | cinderv3                                 |
+      | service_type | volumev3                                 |
+      | url          | http://controller:8776/v3/%(project_id)s |
+      +--------------+------------------------------------------+
+
+      $ openstack endpoint create --region RegionOne \
+        volumev3 admin http://controller:8776/v3/%\(project_id\)s
+
+      +--------------+------------------------------------------+
+      | Field        | Value                                    |
+      +--------------+------------------------------------------+
+      | enabled      | True                                     |
+      | id           | 4511c28a0f9840c78bacb25f10f62c98         |
+      | interface    | admin                                    |
+      | region       | RegionOne                                |
+      | region_id    | RegionOne                                |
+      | service_id   | ab3bbbef780845a1a283490d281e7fda         |
+      | service_name | cinderv3                                 |
+      | service_type | volumev3                                 |
+      | url          | http://controller:8776/v3/%(project_id)s |
+      +--------------+------------------------------------------+
+
+   .. note::
+
+      The Block Storage services require endpoints for each service
+      entity.
+
+Install and configure components
+--------------------------------
+
+#. Install the packages:
+
+   .. code-block:: console
+
+      # yum install openstack-cinder
+
+#. Edit the ``/etc/cinder/cinder.conf`` file and complete the
+   following actions:
+
+   #. In the ``[database]`` section, configure database access:
+
+     .. path /etc/cinder/cinder.conf
+     .. code-block:: ini
+
+        [database]
+        # ...
+        connection = mysql+pymysql://cinder:CINDER_DBPASS@controller/cinder
+
+     Replace ``CINDER_DBPASS`` with the password you chose for the
+     Block Storage database.
+
+   #. In the ``[DEFAULT]`` section, configure ``RabbitMQ``
+      message queue access:
+
+      .. path /etc/cinder/cinder.conf
+      .. code-block:: ini
+
+         [DEFAULT]
+         # ...
+         transport_url = rabbit://openstack:RABBIT_PASS@controller
+
+      Replace ``RABBIT_PASS`` with the password you chose for the
+      ``openstack`` account in ``RabbitMQ``.
+
+   #. In the ``[DEFAULT]`` and ``[keystone_authtoken]`` sections,
+      configure Identity service access:
+
+      .. path /etc/cinder/cinder.conf
+      .. code-block:: ini
+
+         [DEFAULT]
+         # ...
+         auth_strategy = keystone
+
+         [keystone_authtoken]
+         # ...
+         auth_uri = http://controller:5000
+         auth_url = http://controller:35357
+         memcached_servers = controller:11211
+         auth_type = password
+         project_domain_name = default
+         user_domain_name = default
+         project_name = service
+         username = cinder
+         password = CINDER_PASS
+
+      Replace ``CINDER_PASS`` with the password you chose for
+      the ``cinder`` user in the Identity service.
+
+      .. note::
+
+         Comment out or remove any other options in the
+         ``[keystone_authtoken]`` section.
+
+   #. In the ``[DEFAULT]`` section, configure the ``my_ip`` option to
+      use the management interface IP address of the controller node:
+
+      .. path /etc/cinder/cinder.conf
+      .. code-block:: ini
+
+         [DEFAULT]
+         # ...
+         my_ip = 10.0.0.11
+
+#. In the ``[oslo_concurrency]`` section, configure the lock path:
+
+   .. path /etc/cinder/cinder.conf
+   .. code-block:: ini
+
+      [oslo_concurrency]
+      # ...
+      lock_path = /var/lib/cinder/tmp
+
+#. Populate the Block Storage database:
+
+   .. code-block:: console
+
+      # su -s /bin/sh -c "cinder-manage db sync" cinder
+
+   .. note::
+
+      Ignore any deprecation messages in this output.
+
+Configure Compute to use Block Storage
+--------------------------------------
+
+#. Edit the ``/etc/nova/nova.conf`` file and add the following
+   to it:
+
+   .. path /etc/nova/nova.conf
+   .. code-block:: ini
+
+      [cinder]
+      os_region_name = RegionOne
+
+Finalize installation
+---------------------
+
+
+#. Restart the Compute API service:
+
+   .. code-block:: console
+
+      # systemctl restart openstack-nova-api.service
+
+#. Start the Block Storage services and configure them to start when
+   the system boots:
+
+   .. code-block:: console
+
+      # systemctl enable openstack-cinder-api.service openstack-cinder-scheduler.service
+      # systemctl start openstack-cinder-api.service openstack-cinder-scheduler.service
diff --git a/doc/source/install/cinder-controller-install-ubuntu.rst b/doc/source/install/cinder-controller-install-ubuntu.rst
new file mode 100644
index 00000000000..e6a384842ff
--- /dev/null
+++ b/doc/source/install/cinder-controller-install-ubuntu.rst
@@ -0,0 +1,353 @@
+Install and configure controller node
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+This section describes how to install and configure the Block
+Storage service, code-named cinder, on the controller node. This
+service requires at least one additional storage node that provides
+volumes to instances.
+
+Prerequisites
+-------------
+
+Before you install and configure the Block Storage service, you
+must create a database, service credentials, and API endpoints.
+
+#. To create the database, complete these steps:
+
+
+   #. Use the database access client to connect to the database
+      server as the ``root`` user:
+
+      .. code-block:: console
+
+         # mysql
+
+   #. Create the ``cinder`` database:
+
+     .. code-block:: console
+
+        MariaDB [(none)]> CREATE DATABASE cinder;
+
+   #. Grant proper access to the ``cinder`` database:
+
+     .. code-block:: console
+
+        MariaDB [(none)]> GRANT ALL PRIVILEGES ON cinder.* TO 'cinder'@'localhost' \
+          IDENTIFIED BY 'CINDER_DBPASS';
+        MariaDB [(none)]> GRANT ALL PRIVILEGES ON cinder.* TO 'cinder'@'%' \
+          IDENTIFIED BY 'CINDER_DBPASS';
+
+     Replace ``CINDER_DBPASS`` with a suitable password.
+
+   #. Exit the database access client.
+
+#. Source the ``admin`` credentials to gain access to admin-only
+   CLI commands:
+
+   .. code-block:: console
+
+      $ . admin-openrc
+
+#. To create the service credentials, complete these steps:
+
+   #. Create a ``cinder`` user:
+
+     .. code-block:: console
+
+        $ openstack user create --domain default --password-prompt cinder
+
+        User Password:
+        Repeat User Password:
+        +---------------------+----------------------------------+
+        | Field               | Value                            |
+        +---------------------+----------------------------------+
+        | domain_id           | default                          |
+        | enabled             | True                             |
+        | id                  | 9d7e33de3e1a498390353819bc7d245d |
+        | name                | cinder                           |
+        | options             | {}                               |
+        | password_expires_at | None                             |
+        +---------------------+----------------------------------+
+
+   #. Add the ``admin`` role to the ``cinder`` user:
+
+     .. code-block:: console
+
+        $ openstack role add --project service --user cinder admin
+
+     .. note::
+
+        This command provides no output.
+
+   #. Create the ``cinderv2`` and ``cinderv3`` service entities:
+
+     .. code-block:: console
+
+        $ openstack service create --name cinderv2 \
+          --description "OpenStack Block Storage" volumev2
+
+        +-------------+----------------------------------+
+        | Field       | Value                            |
+        +-------------+----------------------------------+
+        | description | OpenStack Block Storage          |
+        | enabled     | True                             |
+        | id          | eb9fd245bdbc414695952e93f29fe3ac |
+        | name        | cinderv2                         |
+        | type        | volumev2                         |
+        +-------------+----------------------------------+
+
+     .. code-block:: console
+
+        $ openstack service create --name cinderv3 \
+          --description "OpenStack Block Storage" volumev3
+
+        +-------------+----------------------------------+
+        | Field       | Value                            |
+        +-------------+----------------------------------+
+        | description | OpenStack Block Storage          |
+        | enabled     | True                             |
+        | id          | ab3bbbef780845a1a283490d281e7fda |
+        | name        | cinderv3                         |
+        | type        | volumev3                         |
+        +-------------+----------------------------------+
+
+   .. note::
+
+      The Block Storage services require two service entities.
+
+#. Create the Block Storage service API endpoints:
+
+   .. code-block:: console
+
+      $ openstack endpoint create --region RegionOne \
+        volumev2 public http://controller:8776/v2/%\(project_id\)s
+
+      +--------------+------------------------------------------+
+      | Field        | Value                                    |
+      +--------------+------------------------------------------+
+      | enabled      | True                                     |
+      | id           | 513e73819e14460fb904163f41ef3759         |
+      | interface    | public                                   |
+      | region       | RegionOne                                |
+      | region_id    | RegionOne                                |
+      | service_id   | eb9fd245bdbc414695952e93f29fe3ac         |
+      | service_name | cinderv2                                 |
+      | service_type | volumev2                                 |
+      | url          | http://controller:8776/v2/%(project_id)s |
+      +--------------+------------------------------------------+
+
+      $ openstack endpoint create --region RegionOne \
+        volumev2 internal http://controller:8776/v2/%\(project_id\)s
+
+      +--------------+------------------------------------------+
+      | Field        | Value                                    |
+      +--------------+------------------------------------------+
+      | enabled      | True                                     |
+      | id           | 6436a8a23d014cfdb69c586eff146a32         |
+      | interface    | internal                                 |
+      | region       | RegionOne                                |
+      | region_id    | RegionOne                                |
+      | service_id   | eb9fd245bdbc414695952e93f29fe3ac         |
+      | service_name | cinderv2                                 |
+      | service_type | volumev2                                 |
+      | url          | http://controller:8776/v2/%(project_id)s |
+      +--------------+------------------------------------------+
+
+      $ openstack endpoint create --region RegionOne \
+        volumev2 admin http://controller:8776/v2/%\(project_id\)s
+
+      +--------------+------------------------------------------+
+      | Field        | Value                                    |
+      +--------------+------------------------------------------+
+      | enabled      | True                                     |
+      | id           | e652cf84dd334f359ae9b045a2c91d96         |
+      | interface    | admin                                    |
+      | region       | RegionOne                                |
+      | region_id    | RegionOne                                |
+      | service_id   | eb9fd245bdbc414695952e93f29fe3ac         |
+      | service_name | cinderv2                                 |
+      | service_type | volumev2                                 |
+      | url          | http://controller:8776/v2/%(project_id)s |
+      +--------------+------------------------------------------+
+
+   .. code-block:: console
+
+      $ openstack endpoint create --region RegionOne \
+        volumev3 public http://controller:8776/v3/%\(project_id\)s
+
+      +--------------+------------------------------------------+
+      | Field        | Value                                    |
+      +--------------+------------------------------------------+
+      | enabled      | True                                     |
+      | id           | 03fa2c90153546c295bf30ca86b1344b         |
+      | interface    | public                                   |
+      | region       | RegionOne                                |
+      | region_id    | RegionOne                                |
+      | service_id   | ab3bbbef780845a1a283490d281e7fda         |
+      | service_name | cinderv3                                 |
+      | service_type | volumev3                                 |
+      | url          | http://controller:8776/v3/%(project_id)s |
+      +--------------+------------------------------------------+
+
+      $ openstack endpoint create --region RegionOne \
+        volumev3 internal http://controller:8776/v3/%\(project_id\)s
+
+      +--------------+------------------------------------------+
+      | Field        | Value                                    |
+      +--------------+------------------------------------------+
+      | enabled      | True                                     |
+      | id           | 94f684395d1b41068c70e4ecb11364b2         |
+      | interface    | internal                                 |
+      | region       | RegionOne                                |
+      | region_id    | RegionOne                                |
+      | service_id   | ab3bbbef780845a1a283490d281e7fda         |
+      | service_name | cinderv3                                 |
+      | service_type | volumev3                                 |
+      | url          | http://controller:8776/v3/%(project_id)s |
+      +--------------+------------------------------------------+
+
+      $ openstack endpoint create --region RegionOne \
+        volumev3 admin http://controller:8776/v3/%\(project_id\)s
+
+      +--------------+------------------------------------------+
+      | Field        | Value                                    |
+      +--------------+------------------------------------------+
+      | enabled      | True                                     |
+      | id           | 4511c28a0f9840c78bacb25f10f62c98         |
+      | interface    | admin                                    |
+      | region       | RegionOne                                |
+      | region_id    | RegionOne                                |
+      | service_id   | ab3bbbef780845a1a283490d281e7fda         |
+      | service_name | cinderv3                                 |
+      | service_type | volumev3                                 |
+      | url          | http://controller:8776/v3/%(project_id)s |
+      +--------------+------------------------------------------+
+
+   .. note::
+
+      The Block Storage services require endpoints for each service
+      entity.
+
+Install and configure components
+--------------------------------
+
+#. Install the packages:
+
+   .. code-block:: console
+
+      # apt install cinder-api cinder-scheduler
+
+#. Edit the ``/etc/cinder/cinder.conf`` file and complete the
+   following actions:
+
+   #. In the ``[database]`` section, configure database access:
+
+      .. path /etc/cinder/cinder.conf
+      .. code-block:: ini
+
+         [database]
+         # ...
+         connection = mysql+pymysql://cinder:CINDER_DBPASS@controller/cinder
+
+     Replace ``CINDER_DBPASS`` with the password you chose for the
+     Block Storage database.
+
+   #. In the ``[DEFAULT]`` section, configure ``RabbitMQ``
+      message queue access:
+
+     .. path /etc/cinder/cinder.conf
+     .. code-block:: ini
+
+        [DEFAULT]
+        # ...
+        transport_url = rabbit://openstack:RABBIT_PASS@controller
+
+     Replace ``RABBIT_PASS`` with the password you chose for the
+     ``openstack`` account in ``RabbitMQ``.
+
+   #. In the ``[DEFAULT]`` and ``[keystone_authtoken]`` sections,
+      configure Identity service access:
+
+      .. path /etc/cinder/cinder.conf
+      .. code-block:: ini
+
+         [DEFAULT]
+         # ...
+         auth_strategy = keystone
+
+         [keystone_authtoken]
+         # ...
+         auth_uri = http://controller:5000
+         auth_url = http://controller:35357
+         memcached_servers = controller:11211
+         auth_type = password
+         project_domain_name = default
+         user_domain_name = default
+         project_name = service
+         username = cinder
+         password = CINDER_PASS
+
+      Replace ``CINDER_PASS`` with the password you chose for
+      the ``cinder`` user in the Identity service.
+
+      .. note::
+
+         Comment out or remove any other options in the
+         ``[keystone_authtoken]`` section.
+
+   #. In the ``[DEFAULT]`` section, configure the ``my_ip`` option to
+      use the management interface IP address of the controller node:
+
+      .. path /etc/cinder/cinder.conf
+      .. code-block:: ini
+
+         [DEFAULT]
+         # ...
+         my_ip = 10.0.0.11
+
+#. In the ``[oslo_concurrency]`` section, configure the lock path:
+
+   .. path /etc/cinder/cinder.conf
+   .. code-block:: ini
+
+      [oslo_concurrency]
+      # ...
+      lock_path = /var/lib/cinder/tmp
+
+#. Populate the Block Storage database:
+
+   .. code-block:: console
+
+      # su -s /bin/sh -c "cinder-manage db sync" cinder
+
+   .. note::
+
+      Ignore any deprecation messages in this output.
+
+Configure Compute to use Block Storage
+--------------------------------------
+
+#. Edit the ``/etc/nova/nova.conf`` file and add the following
+   to it:
+
+   .. path /etc/nova/nova.conf
+   .. code-block:: ini
+
+      [cinder]
+      os_region_name = RegionOne
+
+Finalize installation
+---------------------
+
+#. Restart the Compute API service:
+
+   .. code-block:: console
+
+      # service nova-api restart
+
+#. Restart the Block Storage services:
+
+   .. code-block:: console
+
+      # service cinder-scheduler restart
+      # service apache2 restart
diff --git a/doc/source/install/cinder-storage-install-obs.rst b/doc/source/install/cinder-storage-install-obs.rst
new file mode 100644
index 00000000000..0bc9dbf83be
--- /dev/null
+++ b/doc/source/install/cinder-storage-install-obs.rst
@@ -0,0 +1,273 @@
+Install and configure a storage node
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Prerequisites
+-------------
+
+Before you install and configure the Block Storage service on the
+storage node, you must prepare the storage device.
+
+.. note::
+
+   Perform these steps on the storage node.
+
+#. Install the supporting utility packages.
+
+#. Install the LVM packages:
+
+  .. code-block:: console
+
+     # zypper install lvm2
+
+#. (Optional) If you intend to use non-raw image types such as QCOW2
+   and VMDK, install the QEMU package:
+
+   .. code-block:: console
+
+      # zypper install qemu
+
+    .. note::
+
+       Some distributions include LVM by default.
+
+#. Create the LVM physical volume ``/dev/sdb``:
+
+   .. code-block:: console
+
+      # pvcreate /dev/sdb
+
+      Physical volume "/dev/sdb" successfully created
+
+#. Create the LVM volume group ``cinder-volumes``:
+
+   .. code-block:: console
+
+      # vgcreate cinder-volumes /dev/sdb
+
+      Volume group "cinder-volumes" successfully created
+
+   The Block Storage service creates logical volumes in this volume group.
+
+#. Only instances can access Block Storage volumes. However, the
+   underlying operating system manages the devices associated with
+   the volumes. By default, the LVM volume scanning tool scans the
+   ``/dev`` directory for block storage devices that
+   contain volumes. If projects use LVM on their volumes, the scanning
+   tool detects these volumes and attempts to cache them which can cause
+   a variety of problems with both the underlying operating system
+   and project volumes. You must reconfigure LVM to scan only the devices
+   that contain the ``cinder-volumes`` volume group. Edit the
+   ``/etc/lvm/lvm.conf`` file and complete the following actions:
+
+   * In the ``devices`` section, add a filter that accepts the
+     ``/dev/sdb`` device and rejects all other devices:
+
+     .. path /etc/lvm/lvm.conf
+     .. code-block:: none
+
+        devices {
+        ...
+        filter = [ "a/sdb/", "r/.*/"]
+
+     .. end
+
+     Each item in the filter array begins with ``a`` for **accept** or
+     ``r`` for **reject** and includes a regular expression for the
+     device name. The array must end with ``r/.*/`` to reject any
+     remaining devices. You can use the :command:`vgs -vvvv` command
+     to test filters.
+
+     .. warning::
+
+        If your storage nodes use LVM on the operating system disk, you
+        must also add the associated device to the filter. For example,
+        if the ``/dev/sda`` device contains the operating system:
+
+        .. ignore_path /etc/lvm/lvm.conf
+        .. code-block:: ini
+
+           filter = [ "a/sda/", "a/sdb/", "r/.*/"]
+
+        .. end
+
+        Similarly, if your compute nodes use LVM on the operating
+        system disk, you must also modify the filter in the
+        ``/etc/lvm/lvm.conf`` file on those nodes to include only
+        the operating system disk. For example, if the ``/dev/sda``
+        device contains the operating system:
+
+        .. path /etc/openstack-dashboard/local_settings.py
+        .. code-block:: ini
+
+           filter = [ "a/sda/", "r/.*/"]
+
+        .. end
+
+Install and configure components
+--------------------------------
+
+#. Install the packages:
+
+   .. code-block:: console
+
+      # zypper install openstack-cinder-volume tgt
+
+#. Edit the ``/etc/cinder/cinder.conf`` file
+   and complete the following actions:
+
+   * In the ``[database]`` section, configure database access:
+
+     .. path /etc/cinder/cinder.conf
+     .. code-block:: ini
+
+        [database]
+        # ...
+        connection = mysql+pymysql://cinder:CINDER_DBPASS@controller/cinder
+
+     .. end
+
+     Replace ``CINDER_DBPASS`` with the password you chose for
+     the Block Storage database.
+
+   * In the ``[DEFAULT]`` section, configure ``RabbitMQ``
+     message queue access:
+
+     .. path /etc/cinder/cinder.conf
+     .. code-block:: ini
+
+        [DEFAULT]
+        # ...
+        transport_url = rabbit://openstack:RABBIT_PASS@controller
+
+     .. end
+
+     Replace ``RABBIT_PASS`` with the password you chose for
+     the ``openstack`` account in ``RabbitMQ``.
+
+   * In the ``[DEFAULT]`` and ``[keystone_authtoken]`` sections,
+     configure Identity service access:
+
+     .. path /etc/cinder/cinder.conf
+     .. code-block:: ini
+
+        [DEFAULT]
+        # ...
+        auth_strategy = keystone
+
+        [keystone_authtoken]
+        # ...
+        auth_uri = http://controller:5000
+        auth_url = http://controller:35357
+        memcached_servers = controller:11211
+        auth_type = password
+        project_domain_name = default
+        user_domain_name = default
+        project_name = service
+        username = cinder
+        password = CINDER_PASS
+
+     .. end
+
+     Replace ``CINDER_PASS`` with the password you chose for the
+     ``cinder`` user in the Identity service.
+
+     .. note::
+
+        Comment out or remove any other options in the
+        ``[keystone_authtoken]`` section.
+
+   * In the ``[DEFAULT]`` section, configure the ``my_ip`` option:
+
+     .. path /etc/cinder/cinder.conf
+     .. code-block:: ini
+
+        [DEFAULT]
+        # ...
+        my_ip = MANAGEMENT_INTERFACE_IP_ADDRESS
+
+     .. end
+
+     Replace ``MANAGEMENT_INTERFACE_IP_ADDRESS`` with the IP address
+     of the management network interface on your storage node,
+     typically 10.0.0.41 for the first node in the
+     :ref:`example architecture <overview-example-architectures>`.
+
+
+* In the ``[lvm]`` section, configure the LVM back end with the
+  LVM driver, ``cinder-volumes`` volume group, iSCSI protocol,
+  and appropriate iSCSI service:
+
+  .. path /etc/cinder/cinder.conf
+  .. code-block:: ini
+
+     [lvm]
+     # ...
+     volume_driver = cinder.volume.drivers.lvm.LVMVolumeDriver
+     volume_group = cinder-volumes
+     iscsi_protocol = iscsi
+     iscsi_helper = tgtadm
+
+  .. end
+
+
+
+   * In the ``[DEFAULT]`` section, enable the LVM back end:
+
+     .. path /etc/cinder/cinder.conf
+     .. code-block:: ini
+
+        [DEFAULT]
+        # ...
+        enabled_backends = lvm
+
+     .. end
+
+     .. note::
+
+        Back-end names are arbitrary. As an example, this guide
+        uses the name of the driver as the name of the back end.
+
+   * In the ``[DEFAULT]`` section, configure the location of the
+     Image service API:
+
+     .. path /etc/cinder/cinder.conf
+     .. code-block:: ini
+
+        [DEFAULT]
+        # ...
+        glance_api_servers = http://controller:9292
+
+     .. end
+
+   * In the ``[oslo_concurrency]`` section, configure the lock path:
+
+     .. path /etc/cinder/cinder.conf
+     .. code-block:: ini
+
+        [oslo_concurrency]
+        # ...
+        lock_path = /var/lib/cinder/tmp
+
+     .. end
+
+
+3. Create the ``/etc/tgt/conf.d/cinder.conf`` file
+   with the following data:
+
+   .. code-block:: shell
+
+      include /var/lib/cinder/volumes/*
+
+   .. end
+
+
+Finalize installation
+---------------------
+
+#. Start the Block Storage volume service including its dependencies
+   and configure them to start when the system boots:
+
+   .. code-block:: console
+
+      # systemctl enable openstack-cinder-volume.service tgtd.service
+      # systemctl start openstack-cinder-volume.service tgtd.service
diff --git a/doc/source/install/cinder-storage-install-rdo.rst b/doc/source/install/cinder-storage-install-rdo.rst
new file mode 100644
index 00000000000..0413d9cba89
--- /dev/null
+++ b/doc/source/install/cinder-storage-install-rdo.rst
@@ -0,0 +1,288 @@
+Install and configure a storage node
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Prerequisites
+-------------
+
+Before you install and configure the Block Storage service on the
+storage node, you must prepare the storage device.
+
+.. note::
+
+   Perform these steps on the storage node.
+
+#. Install the supporting utility packages:
+
+
+
+* Install the LVM packages:
+
+  .. code-block:: console
+
+     # yum install lvm2
+
+  .. end
+
+* Start the LVM metadata service and configure it to start when the
+  system boots:
+
+  .. code-block:: console
+
+     # systemctl enable lvm2-lvmetad.service
+     # systemctl start lvm2-lvmetad.service
+
+  .. end
+
+
+
+   .. note::
+
+      Some distributions include LVM by default.
+
+#. Create the LVM physical volume ``/dev/sdb``:
+
+   .. code-block:: console
+
+      # pvcreate /dev/sdb
+
+      Physical volume "/dev/sdb" successfully created
+
+   .. end
+
+#. Create the LVM volume group ``cinder-volumes``:
+
+   .. code-block:: console
+
+      # vgcreate cinder-volumes /dev/sdb
+
+      Volume group "cinder-volumes" successfully created
+
+   .. end
+
+   The Block Storage service creates logical volumes in this volume group.
+
+#. Only instances can access Block Storage volumes. However, the
+   underlying operating system manages the devices associated with
+   the volumes. By default, the LVM volume scanning tool scans the
+   ``/dev`` directory for block storage devices that
+   contain volumes. If projects use LVM on their volumes, the scanning
+   tool detects these volumes and attempts to cache them which can cause
+   a variety of problems with both the underlying operating system
+   and project volumes. You must reconfigure LVM to scan only the devices
+   that contain the ``cinder-volumes`` volume group. Edit the
+   ``/etc/lvm/lvm.conf`` file and complete the following actions:
+
+   * In the ``devices`` section, add a filter that accepts the
+     ``/dev/sdb`` device and rejects all other devices:
+
+     .. path /etc/lvm/lvm.conf
+     .. code-block:: none
+
+        devices {
+        ...
+        filter = [ "a/sdb/", "r/.*/"]
+
+     .. end
+
+     Each item in the filter array begins with ``a`` for **accept** or
+     ``r`` for **reject** and includes a regular expression for the
+     device name. The array must end with ``r/.*/`` to reject any
+     remaining devices. You can use the :command:`vgs -vvvv` command
+     to test filters.
+
+     .. warning::
+
+        If your storage nodes use LVM on the operating system disk, you
+        must also add the associated device to the filter. For example,
+        if the ``/dev/sda`` device contains the operating system:
+
+        .. ignore_path /etc/lvm/lvm.conf
+        .. code-block:: ini
+
+           filter = [ "a/sda/", "a/sdb/", "r/.*/"]
+
+        .. end
+
+        Similarly, if your compute nodes use LVM on the operating
+        system disk, you must also modify the filter in the
+        ``/etc/lvm/lvm.conf`` file on those nodes to include only
+        the operating system disk. For example, if the ``/dev/sda``
+        device contains the operating system:
+
+        .. path /etc/openstack-dashboard/local_settings.py
+        .. code-block:: ini
+
+           filter = [ "a/sda/", "r/.*/"]
+
+        .. end
+
+Install and configure components
+--------------------------------
+
+
+
+#. Install the packages:
+
+   .. code-block:: console
+
+      # yum install openstack-cinder targetcli python-keystone
+
+   .. end
+
+
+
+2. Edit the ``/etc/cinder/cinder.conf`` file
+   and complete the following actions:
+
+   * In the ``[database]`` section, configure database access:
+
+     .. path /etc/cinder/cinder.conf
+     .. code-block:: ini
+
+        [database]
+        # ...
+        connection = mysql+pymysql://cinder:CINDER_DBPASS@controller/cinder
+
+     .. end
+
+     Replace ``CINDER_DBPASS`` with the password you chose for
+     the Block Storage database.
+
+   * In the ``[DEFAULT]`` section, configure ``RabbitMQ``
+     message queue access:
+
+     .. path /etc/cinder/cinder.conf
+     .. code-block:: ini
+
+        [DEFAULT]
+        # ...
+        transport_url = rabbit://openstack:RABBIT_PASS@controller
+
+     .. end
+
+     Replace ``RABBIT_PASS`` with the password you chose for
+     the ``openstack`` account in ``RabbitMQ``.
+
+   * In the ``[DEFAULT]`` and ``[keystone_authtoken]`` sections,
+     configure Identity service access:
+
+     .. path /etc/cinder/cinder.conf
+     .. code-block:: ini
+
+        [DEFAULT]
+        # ...
+        auth_strategy = keystone
+
+        [keystone_authtoken]
+        # ...
+        auth_uri = http://controller:5000
+        auth_url = http://controller:35357
+        memcached_servers = controller:11211
+        auth_type = password
+        project_domain_name = default
+        user_domain_name = default
+        project_name = service
+        username = cinder
+        password = CINDER_PASS
+
+     .. end
+
+     Replace ``CINDER_PASS`` with the password you chose for the
+     ``cinder`` user in the Identity service.
+
+     .. note::
+
+        Comment out or remove any other options in the
+        ``[keystone_authtoken]`` section.
+
+   * In the ``[DEFAULT]`` section, configure the ``my_ip`` option:
+
+     .. path /etc/cinder/cinder.conf
+     .. code-block:: ini
+
+        [DEFAULT]
+        # ...
+        my_ip = MANAGEMENT_INTERFACE_IP_ADDRESS
+
+     .. end
+
+     Replace ``MANAGEMENT_INTERFACE_IP_ADDRESS`` with the IP address
+     of the management network interface on your storage node,
+     typically 10.0.0.41 for the first node in the
+     :ref:`example architecture <overview-example-architectures>`.
+
+
+
+* In the ``[lvm]`` section, configure the LVM back end with the
+  LVM driver, ``cinder-volumes`` volume group, iSCSI protocol,
+  and appropriate iSCSI service. If the ``[lvm]`` section does not exist,
+  create it:
+
+  .. path /etc/cinder/cinder.conf
+  .. code-block:: ini
+
+     [lvm]
+     volume_driver = cinder.volume.drivers.lvm.LVMVolumeDriver
+     volume_group = cinder-volumes
+     iscsi_protocol = iscsi
+     iscsi_helper = lioadm
+
+  .. end
+
+
+   * In the ``[DEFAULT]`` section, enable the LVM back end:
+
+     .. path /etc/cinder/cinder.conf
+     .. code-block:: ini
+
+        [DEFAULT]
+        # ...
+        enabled_backends = lvm
+
+     .. end
+
+     .. note::
+
+        Back-end names are arbitrary. As an example, this guide
+        uses the name of the driver as the name of the back end.
+
+   * In the ``[DEFAULT]`` section, configure the location of the
+     Image service API:
+
+     .. path /etc/cinder/cinder.conf
+     .. code-block:: ini
+
+        [DEFAULT]
+        # ...
+        glance_api_servers = http://controller:9292
+
+     .. end
+
+   * In the ``[oslo_concurrency]`` section, configure the lock path:
+
+     .. path /etc/cinder/cinder.conf
+     .. code-block:: ini
+
+        [oslo_concurrency]
+        # ...
+        lock_path = /var/lib/cinder/tmp
+
+     .. end
+
+
+Finalize installation
+---------------------
+
+
+
+* Start the Block Storage volume service including its dependencies
+  and configure them to start when the system boots:
+
+  .. code-block:: console
+
+     # systemctl enable openstack-cinder-volume.service target.service
+     # systemctl start openstack-cinder-volume.service target.service
+
+  .. end
+
+
diff --git a/doc/source/install/cinder-storage-install-ubuntu.rst b/doc/source/install/cinder-storage-install-ubuntu.rst
new file mode 100644
index 00000000000..7eaa5f27697
--- /dev/null
+++ b/doc/source/install/cinder-storage-install-ubuntu.rst
@@ -0,0 +1,275 @@
+Install and configure a storage node
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Prerequisites
+-------------
+
+Before you install and configure the Block Storage service on the
+storage node, you must prepare the storage device.
+
+.. note::
+
+   Perform these steps on the storage node.
+
+#. Install the supporting utility packages:
+
+
+
+
+.. code-block:: console
+
+   # apt install lvm2
+
+.. end
+
+
+   .. note::
+
+      Some distributions include LVM by default.
+
+#. Create the LVM physical volume ``/dev/sdb``:
+
+   .. code-block:: console
+
+      # pvcreate /dev/sdb
+
+      Physical volume "/dev/sdb" successfully created
+
+   .. end
+
+#. Create the LVM volume group ``cinder-volumes``:
+
+   .. code-block:: console
+
+      # vgcreate cinder-volumes /dev/sdb
+
+      Volume group "cinder-volumes" successfully created
+
+   .. end
+
+   The Block Storage service creates logical volumes in this volume group.
+
+#. Only instances can access Block Storage volumes. However, the
+   underlying operating system manages the devices associated with
+   the volumes. By default, the LVM volume scanning tool scans the
+   ``/dev`` directory for block storage devices that
+   contain volumes. If projects use LVM on their volumes, the scanning
+   tool detects these volumes and attempts to cache them which can cause
+   a variety of problems with both the underlying operating system
+   and project volumes. You must reconfigure LVM to scan only the devices
+   that contain the ``cinder-volumes`` volume group. Edit the
+   ``/etc/lvm/lvm.conf`` file and complete the following actions:
+
+   * In the ``devices`` section, add a filter that accepts the
+     ``/dev/sdb`` device and rejects all other devices:
+
+     .. path /etc/lvm/lvm.conf
+     .. code-block:: none
+
+        devices {
+        ...
+        filter = [ "a/sdb/", "r/.*/"]
+
+     .. end
+
+     Each item in the filter array begins with ``a`` for **accept** or
+     ``r`` for **reject** and includes a regular expression for the
+     device name. The array must end with ``r/.*/`` to reject any
+     remaining devices. You can use the :command:`vgs -vvvv` command
+     to test filters.
+
+     .. warning::
+
+        If your storage nodes use LVM on the operating system disk, you
+        must also add the associated device to the filter. For example,
+        if the ``/dev/sda`` device contains the operating system:
+
+        .. ignore_path /etc/lvm/lvm.conf
+        .. code-block:: ini
+
+           filter = [ "a/sda/", "a/sdb/", "r/.*/"]
+
+        .. end
+
+        Similarly, if your compute nodes use LVM on the operating
+        system disk, you must also modify the filter in the
+        ``/etc/lvm/lvm.conf`` file on those nodes to include only
+        the operating system disk. For example, if the ``/dev/sda``
+        device contains the operating system:
+
+        .. path /etc/openstack-dashboard/local_settings.py
+        .. code-block:: ini
+
+           filter = [ "a/sda/", "r/.*/"]
+
+        .. end
+
+Install and configure components
+--------------------------------
+
+
+
+
+#. Install the packages:
+
+   .. code-block:: console
+
+     # apt install cinder-volume
+
+   .. end
+
+
+2. Edit the ``/etc/cinder/cinder.conf`` file
+   and complete the following actions:
+
+   * In the ``[database]`` section, configure database access:
+
+     .. path /etc/cinder/cinder.conf
+     .. code-block:: ini
+
+        [database]
+        # ...
+        connection = mysql+pymysql://cinder:CINDER_DBPASS@controller/cinder
+
+     .. end
+
+     Replace ``CINDER_DBPASS`` with the password you chose for
+     the Block Storage database.
+
+   * In the ``[DEFAULT]`` section, configure ``RabbitMQ``
+     message queue access:
+
+     .. path /etc/cinder/cinder.conf
+     .. code-block:: ini
+
+        [DEFAULT]
+        # ...
+        transport_url = rabbit://openstack:RABBIT_PASS@controller
+
+     .. end
+
+     Replace ``RABBIT_PASS`` with the password you chose for
+     the ``openstack`` account in ``RabbitMQ``.
+
+   * In the ``[DEFAULT]`` and ``[keystone_authtoken]`` sections,
+     configure Identity service access:
+
+     .. path /etc/cinder/cinder.conf
+     .. code-block:: ini
+
+        [DEFAULT]
+        # ...
+        auth_strategy = keystone
+
+        [keystone_authtoken]
+        # ...
+        auth_uri = http://controller:5000
+        auth_url = http://controller:35357
+        memcached_servers = controller:11211
+        auth_type = password
+        project_domain_name = default
+        user_domain_name = default
+        project_name = service
+        username = cinder
+        password = CINDER_PASS
+
+     .. end
+
+     Replace ``CINDER_PASS`` with the password you chose for the
+     ``cinder`` user in the Identity service.
+
+     .. note::
+
+        Comment out or remove any other options in the
+        ``[keystone_authtoken]`` section.
+
+   * In the ``[DEFAULT]`` section, configure the ``my_ip`` option:
+
+     .. path /etc/cinder/cinder.conf
+     .. code-block:: ini
+
+        [DEFAULT]
+        # ...
+        my_ip = MANAGEMENT_INTERFACE_IP_ADDRESS
+
+     .. end
+
+     Replace ``MANAGEMENT_INTERFACE_IP_ADDRESS`` with the IP address
+     of the management network interface on your storage node,
+     typically 10.0.0.41 for the first node in the
+     :ref:`example architecture <overview-example-architectures>`.
+
+
+* In the ``[lvm]`` section, configure the LVM back end with the
+  LVM driver, ``cinder-volumes`` volume group, iSCSI protocol,
+  and appropriate iSCSI service:
+
+  .. path /etc/cinder/cinder.conf
+  .. code-block:: ini
+
+     [lvm]
+     # ...
+     volume_driver = cinder.volume.drivers.lvm.LVMVolumeDriver
+     volume_group = cinder-volumes
+     iscsi_protocol = iscsi
+     iscsi_helper = tgtadm
+
+  .. end
+
+
+
+   * In the ``[DEFAULT]`` section, enable the LVM back end:
+
+     .. path /etc/cinder/cinder.conf
+     .. code-block:: ini
+
+        [DEFAULT]
+        # ...
+        enabled_backends = lvm
+
+     .. end
+
+     .. note::
+
+        Back-end names are arbitrary. As an example, this guide
+        uses the name of the driver as the name of the back end.
+
+   * In the ``[DEFAULT]`` section, configure the location of the
+     Image service API:
+
+     .. path /etc/cinder/cinder.conf
+     .. code-block:: ini
+
+        [DEFAULT]
+        # ...
+        glance_api_servers = http://controller:9292
+
+     .. end
+
+   * In the ``[oslo_concurrency]`` section, configure the lock path:
+
+     .. path /etc/cinder/cinder.conf
+     .. code-block:: ini
+
+        [oslo_concurrency]
+        # ...
+        lock_path = /var/lib/cinder/tmp
+
+     .. end
+
+
+Finalize installation
+---------------------
+
+
+
+
+#. Restart the Block Storage volume service including its dependencies:
+
+   .. code-block:: console
+
+      # service tgt restart
+      # service cinder-volume restart
+
+   .. end
+
diff --git a/doc/source/install/cinder-verify.rst b/doc/source/install/cinder-verify.rst
new file mode 100644
index 00000000000..5b87ce83398
--- /dev/null
+++ b/doc/source/install/cinder-verify.rst
@@ -0,0 +1,35 @@
+.. _cinder-verify:
+
+Verify Cinder operation
+~~~~~~~~~~~~~~~~~~~~~~~
+
+Verify operation of the Block Storage service.
+
+.. note::
+
+   Perform these commands on the controller node.
+
+#. Source the ``admin`` credentials to gain access to
+   admin-only CLI commands:
+
+   .. code-block:: console
+
+      $ . admin-openrc
+
+   .. end
+
+#. List service components to verify successful launch of each process:
+
+   .. code-block:: console
+
+      $ openstack volume service list
+
+      +------------------+------------+------+---------+-------+----------------------------+
+      | Binary           | Host       | Zone | Status  | State | Updated_at                 |
+      +------------------+------------+------+---------+-------+----------------------------+
+      | cinder-scheduler | controller | nova | enabled | up    | 2016-09-30T02:27:41.000000 |
+      | cinder-volume    | block@lvm  | nova | enabled | up    | 2016-09-30T02:27:46.000000 |
+      +------------------+------------+------+---------+-------+----------------------------+
+
+
+   .. end
diff --git a/doc/source/install/index-obs.rst b/doc/source/install/index-obs.rst
new file mode 100644
index 00000000000..1ef7347241f
--- /dev/null
+++ b/doc/source/install/index-obs.rst
@@ -0,0 +1,23 @@
+===================================================================
+Cinder Installation Tutorial for openSUSE and SUSE Linux Enterprise
+===================================================================
+
+This section describes how to install and configure storage nodes
+for the Block Storage service. For simplicity, this configuration
+references one storage node with an empty local block storage device.
+The instructions use ``/dev/sdb``, but you can substitute a different
+value for your particular node.
+
+The service provisions logical volumes on this device using the
+:term:`LVM <Logical Volume Manager (LVM)>` driver and provides them
+to instances via :term:`iSCSI <iSCSI Qualified Name (IQN)>` transport.
+You can follow these instructions with minor modifications to horizontally
+scale your environment with additional storage nodes.
+
+.. toctree::
+   :maxdepth: 2
+
+   cinder-storage-install-obs.rst
+   cinder-controller-install-obs.rst
+   cinder-backup-install-obs.rst
+   cinder-verify.rst
diff --git a/doc/source/install/index-rdo.rst b/doc/source/install/index-rdo.rst
new file mode 100644
index 00000000000..9bbc27b4a06
--- /dev/null
+++ b/doc/source/install/index-rdo.rst
@@ -0,0 +1,23 @@
+======================================================================
+Cinder Installation Tutorial for Red Hat Enterprise Linux and CentOS
+======================================================================
+
+This section describes how to install and configure storage nodes
+for the Block Storage service. For simplicity, this configuration
+references one storage node with an empty local block storage device.
+The instructions use ``/dev/sdb``, but you can substitute a different
+value for your particular node.
+
+The service provisions logical volumes on this device using the
+:term:`LVM <Logical Volume Manager (LVM)>` driver and provides them
+to instances via :term:`iSCSI <iSCSI Qualified Name (IQN)>` transport.
+You can follow these instructions with minor modifications to horizontally
+scale your environment with additional storage nodes.
+
+.. toctree::
+   :maxdepth: 2
+
+   cinder-storage-install-rdo.rst
+   cinder-controller-install-rdo.rst
+   cinder-backup-install-rdo.rst
+   cinder-verify.rst
diff --git a/doc/source/install/index-ubuntu.rst b/doc/source/install/index-ubuntu.rst
new file mode 100644
index 00000000000..ca37c0232d0
--- /dev/null
+++ b/doc/source/install/index-ubuntu.rst
@@ -0,0 +1,23 @@
+=======================================
+Cinder Installation Tutorial for Ubuntu
+=======================================
+
+This section describes how to install and configure storage nodes
+for the Block Storage service. For simplicity, this configuration
+references one storage node with an empty local block storage device.
+The instructions use ``/dev/sdb``, but you can substitute a different
+value for your particular node.
+
+The service provisions logical volumes on this device using the
+:term:`LVM <Logical Volume Manager (LVM)>` driver and provides them
+to instances via :term:`iSCSI <iSCSI Qualified Name (IQN)>` transport.
+You can follow these instructions with minor modifications to horizontally
+scale your environment with additional storage nodes.
+
+.. toctree::
+   :maxdepth: 2
+
+   cinder-storage-install-ubuntu.rst
+   cinder-controller-install-ubuntu.rst
+   cinder-backup-install-ubuntu.rst
+   cinder-verify.rst
diff --git a/doc/source/install/index.rst b/doc/source/install/index.rst
new file mode 100644
index 00000000000..a93ae94f075
--- /dev/null
+++ b/doc/source/install/index.rst
@@ -0,0 +1,24 @@
+.. _cinder:
+
+============================
+Cinder Installation Tutorial
+============================
+
+The Block Storage service (cinder) provides block storage devices
+to guest instances. The method in which the storage is provisioned and
+consumed is determined by the Block Storage driver, or drivers
+in the case of a multi-backend configuration. There are a variety of
+drivers that are available: NAS/SAN, NFS, iSCSI, Ceph, and more.
+
+The Block Storage API and scheduler services typically run on the controller
+nodes. Depending upon the drivers used, the volume service can run
+on controller nodes, compute nodes, or standalone storage nodes.
+
+For more information, see the
+`Configuration Reference <https://docs.openstack.org/ocata/config-reference/block-storage/volume-drivers.html>`_.
+
+.. toctree::
+
+   index-obs
+   index-rdo
+   index-ubuntu
\ No newline at end of file