Merge "Add document for volume providers"

doc/source/devref/cinder_provider.rst

@@ -0,0 +1,92 @@
+..
+    Licensed under the Apache License, Version 2.0 (the "License"); you may
+    not use this file except in compliance with the License. You may obtain
+    a copy of the License at
+
+        http://www.apache.org/licenses/LICENSE-2.0
+
+    Unless required by applicable law or agreed to in writing, software
+    distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+    WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+    License for the specific language governing permissions and limitations
+    under the License.
+
+
+Cinder provider
+===============
+
+Cinder volume provider enables Fuxi create volume from OpenStack Cinder and
+provides them to Docker containers.
+
+Cinder provider configuration setttings
+---------------------------------------
+
+The following parameters in `cinder` group need to be set:
+
+- `region_name` = <used to pick the URL from the service catalog>
+- `volume_connector` = <the way to connect or disconect volume. default
+     `osbrick`, only could chose from [osbrick, openstack]>
+- `fstype` = <the filesystem type for formatting connected block device.
+     default `ext4`>
+- `multiattach` = <the volume is enabled to attached to multi-host.
+     deafult `False`>
+
+.. note::
+
+    * If want to use keystone v3, please set authtoken configuration in group
+    `cinder` or other group with `auth_section` marking it.
+
+    * `multiattach` must be setting properly according to the enabled volume
+    driver backends in Cinder.
+
+
+Supported connectors
+--------------------
+- osbrick:   fuxi.connector.osbrickconnector.CinderConnector
+- openstack: fuxi.connector.cloudconnector.openstack.CinderConnector
+
+Connector osbrick
+-----------------
+osbrick connector uses OpenStack library package `os-brick`_ to manage the
+connection with Cinder volume.
+With this connector, `fuxi-server` could run in baremetal or VM normally.
+
+Requirements
+~~~~~~~~~~~~
+- Install related client for connecting Cinder volume.
+  eg: open-iscsi, nfs-common.
+- When iSCSI client used and `fuxi-server` is running in root user, must make
+  a link for executable file `/lib/udev/scsi_id`
+  ::
+
+    ln -s /lib/udev/scsi_id /usr/local/bin
+
+
+Connector openstack
+-------------------
+
+This connector is only supported when running the containers inside OpenStack
+Nova instances due to its usage of OpenStack Nova API 'connect' and 'disconnet'
+verbs.
+
+Usage
+-----
+
+The example for creating volume from Cinder with Docker volume command:
+
+::
+
+  docker volume create --driver fuxi --name <vol_name> \
+      --opt size=1 \
+      --opt fstype=ext4 \
+      --opt multiattach=true
+
+Use existing Cinder volume:
+
+::
+
+  docker volume create --driver fuxi --name test_vol \
+      --opt size=1 \
+      --opt volume_id=<volume_id>
+
+.. _os-brick: https://github.com/openstack/os-brick

doc/source/devref/index.rst

@@ -0,0 +1,28 @@
+..
+    Licensed under the Apache License, Version 2.0 (the "License"); you may
+    not use this file except in compliance with the License. You may obtain
+    a copy of the License at
+
+        http://www.apache.org/licenses/LICENSE-2.0
+
+    Unless required by applicable law or agreed to in writing, software
+    distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+    WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+    License for the specific language governing permissions and limitations
+    under the License.
+
+
+
+Developer Guide
+===============
+
+Volume providers
+----------------
+.. toctree::
+   :maxdepth: 2
+
+   cinder_provider
+   manila_provider
+
+* :ref:`genindex`
+* :ref:`search`

doc/source/devref/manila_provider.rst

@@ -0,0 +1,101 @@
+..
+    Licensed under the Apache License, Version 2.0 (the "License"); you may
+    not use this file except in compliance with the License. You may obtain
+    a copy of the License at
+
+        http://www.apache.org/licenses/LICENSE-2.0
+
+    Unless required by applicable law or agreed to in writing, software
+    distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+    WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+    License for the specific language governing permissions and limitations
+    under the License.
+
+Manila provider
+===============
+
+Manila volume provider enables Fuxi create share from OpenStack Manila and
+provides them to Docker containers.
+
+Requirements
+------------
+- Install the related client according the driver backends that Manila
+  used for mounting the remote filesystem.
+
+
+Manila provider configuration settings
+--------------------------------------
+
+The following parameters in `manila` group need to be set:
+
+- `region_name` = <used to pick the URL from the service catalog>
+
+The following configuration parameters are options:
+
+- `volume_connector` = osbrick
+- `share_proto` = <default share protocol used to grant access>
+- `proto_access_type_map` = <the mapping of protocol access
+     that manila enabled>
+- `access_to_for_cert` = <the value of key `access_to` when Manila use
+     `access_type` `CERT` to allow access for visitors>
+
+.. note::
+
+   If want to use keystone v3, please set authtoken configuration in group
+   `manila` or other group with `auth_section` marking it.
+
+
+Usage
+-----
+
+Set `volume_providers = manila` in group `DEFAULT` to use Manila volume
+provider.
+
+For different backends that manila enabled, we need to provide different
+parameter to create volume(share) from Manila.
+
+The following are some examples.
+
+- If using `generic` driver in Manila, `share_network` should be provided;
+
+::
+
+  docker volume create --driver fuxi --name <vol_name> \
+      --opt share_network=<share_network_id>
+
+- If using `glusterfs` driver in Manila, `share_type` should be provided;
+
+::
+
+  docker volume create --driver fuxi --name <volume_name> \
+      --opt share_type=<share_type_id>
+
+- If using `glusterfs_native` driver in Manila, `share_type` and `share_proto`
+    need be provided;
+
+::
+
+  docker volume create --driver fuxi --name <vol_name> \
+      --opt share_type=<share_type_id> \
+      --opt share_proto=glusterfs
+
+
+Using existing Manila share:
+
+::
+
+  docker volume create --driver fuxi --name <vol_name> \
+      --opt volume_id=<share_id>
+
+.. note::
+
+   The parameter `--opt volume_provider=manila` is needed, if you want
+   use Manila volume provider when multi volume providers are enabled and
+   `manila` is not the first one.
+
+References
+----------
+
+* `Manila share features support mapping`_
+
+.. _Manila share features support mapping: https://docs.openstack.org/developer/manila/devref/share_back_ends_feature_support_mapping.html

doc/source/index.rst

@@ -4,7 +4,7 @@
    contain the root `toctree` directive.
 
 Welcome to fuxi's documentation!
-========================================================
+================================
 
 Contents:
 
@@ -17,6 +17,14 @@ Contents:
    contributing
    reno.rst
 
+Developer Docs
+==============
+
+.. toctree::
+   :maxdepth: 1
+
+   devref/index
+
 Indices and tables
 ==================
 

doc/source/installation.rst

@@ -89,6 +89,7 @@ Then edit it.
 ::
 
     [nova]
+    region_name = REGION_NAME  # Region name of this node. This is used when picking the URL in the service catalog.
     auth_url = AUTH_URL # For example, it can be http://127.0.0.1:35357/v3/
     username = ADMIN_USER
     user_domain_name = Default

fuxi/volumeprovider/cinder.py

@@ -336,7 +336,7 @@ class Cinder(provider.Provider):
     def delete(self, docker_volume_name):
         cinder_volume, state = self._get_docker_volume(docker_volume_name)
         LOG.info(_LI("Get docker volume %(d_v)s %(vol)s with state %(st)s"),
-                 {'d_v': docker_volume_name, 'vol':  cinder_volume,
+                 {'d_v': docker_volume_name, 'vol': cinder_volume,
                   'st': state})
 
         if state == ATTACH_TO_THIS: