diff --git a/doc/source/devref/cinder_provider.rst b/doc/source/devref/cinder_provider.rst new file mode 100644 index 0000000..8747863 --- /dev/null +++ b/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` = +- `volume_connector` = +- `fstype` = +- `multiattach` = + +.. 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 \ + --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= + +.. _os-brick: https://github.com/openstack/os-brick diff --git a/doc/source/devref/index.rst b/doc/source/devref/index.rst new file mode 100644 index 0000000..37dc939 --- /dev/null +++ b/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` \ No newline at end of file diff --git a/doc/source/devref/manila_provider.rst b/doc/source/devref/manila_provider.rst new file mode 100644 index 0000000..32c0249 --- /dev/null +++ b/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` = + +The following configuration parameters are options: + +- `volume_connector` = osbrick +- `share_proto` = +- `proto_access_type_map` = +- `access_to_for_cert` = + +.. 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 \ + --opt share_network= + +- If using `glusterfs` driver in Manila, `share_type` should be provided; + +:: + + docker volume create --driver fuxi --name \ + --opt share_type= + +- If using `glusterfs_native` driver in Manila, `share_type` and `share_proto` + need be provided; + +:: + + docker volume create --driver fuxi --name \ + --opt share_type= \ + --opt share_proto=glusterfs + + +Using existing Manila share: + +:: + + docker volume create --driver fuxi --name \ + --opt volume_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 diff --git a/doc/source/index.rst b/doc/source/index.rst index 7c804f0..57a04fc 100644 --- a/doc/source/index.rst +++ b/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 ================== diff --git a/doc/source/installation.rst b/doc/source/installation.rst index 5a406c9..42c6077 100644 --- a/doc/source/installation.rst +++ b/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 diff --git a/fuxi/volumeprovider/cinder.py b/fuxi/volumeprovider/cinder.py index 7e359d4..64254ab 100644 --- a/fuxi/volumeprovider/cinder.py +++ b/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: