diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst index b7cc8ec88..3be845871 100644 --- a/CONTRIBUTING.rst +++ b/CONTRIBUTING.rst @@ -13,4 +13,4 @@ Pull requests submitted through GitHub will be ignored. Bugs should be filed on Launchpad, not GitHub: - https://bugs.launchpad.net/brick + https://bugs.launchpad.net/os-brick diff --git a/README.rst b/README.rst index 1fae2498e..613902dd4 100644 --- a/README.rst +++ b/README.rst @@ -5,11 +5,12 @@ brick OpenStack Cinder brick library for managing local volume attaches * Free software: Apache license -* Documentation: http://docs.openstack.org/developer/brick -* Source: http://git.openstack.org/cgit/openstack/brick +* Documentation: http://docs.openstack.org/developer/os-brick +* Source: http://git.openstack.org/cgit/openstack/os-brick * Bugs: http://bugs.launchpad.net/cinder Features -------- -* TODO +* Discovery of volumes being attached to a host for many transport protocols. +* Removal of volumes from a host. diff --git a/doc/source/api/index.rst b/doc/source/api/index.rst new file mode 100644 index 000000000..56d8d3c5e --- /dev/null +++ b/doc/source/api/index.rst @@ -0,0 +1,10 @@ +API Documentation +================= + +The **os-brick** package provides the ability to collect host initiator +information as well as discovery volumes and removal of volumes from a host. + +.. toctree:: + :maxdepth: 2 + + os_brick/index diff --git a/doc/source/api/os_brick/exception.rst b/doc/source/api/os_brick/exception.rst new file mode 100644 index 000000000..921cedc59 --- /dev/null +++ b/doc/source/api/os_brick/exception.rst @@ -0,0 +1,14 @@ +:mod:`exception` -- Exceptions +============================== + +.. automodule:: os_brick.exception + :synopsis: Exceptions generated by os-brick + + .. autoclass:: os_brick.exception.BrickException + .. autoclass:: os_brick.exception.NotFound + .. autoclass:: os_brick.exception.Invalid + .. autoclass:: os_brick.exception.InvalidParameterValue + .. autoclass:: os_brick.exception.NoFibreChannelHostsFound + .. autoclass:: os_brick.exception.NoFibreChannelVolumeDeviceFound + .. autoclass:: os_brick.exception.VolumeDeviceNotFound + .. autoclass:: os_brick.exception.ProtocolNotSupported diff --git a/doc/source/api/os_brick/index.rst b/doc/source/api/os_brick/index.rst new file mode 100644 index 000000000..762d13a1d --- /dev/null +++ b/doc/source/api/os_brick/index.rst @@ -0,0 +1,14 @@ +:mod:`os_brick` -- OpenStack Brick library +========================================== + +.. automodule:: os_brick + :synopsis: OpenStack Brick library + + +Sub-modules: + +.. toctree:: + :maxdepth: 2 + + initiator/index + exception diff --git a/doc/source/api/os_brick/initiator/connector.rst b/doc/source/api/os_brick/initiator/connector.rst new file mode 100644 index 000000000..90c0b6995 --- /dev/null +++ b/doc/source/api/os_brick/initiator/connector.rst @@ -0,0 +1,39 @@ +:mod:`connector` -- Connector +============================= + +.. automodule:: os_brick.initiator.connector + :synopsis: Connector module for os-brick + + .. autoclass:: os_brick.initiator.connector.InitiatorConnector + + .. automethod:: factory + + .. autoclass:: os_brick.initiator.connector.ISCSIConnector + + .. automethod:: connect_volume + .. automethod:: disconnect_volume + + .. autoclass:: os_brick.initiator.connector.ISERConnector + + .. automethod:: connect_volume + .. automethod:: disconnect_volume + + .. autoclass:: os_brick.initiator.connector.FibreChannelConnector + + .. automethod:: connect_volume + .. automethod:: disconnect_volume + + .. autoclass:: os_brick.initiator.connector.AoEConnector + + .. automethod:: connect_volume + .. automethod:: disconnect_volume + + .. autoclass:: os_brick.initiator.connector.LocalConnector + + .. automethod:: connect_volume + .. automethod:: disconnect_volume + + .. autoclass:: os_brick.initiator.connector.HuaweiStorHyperConnector + + .. automethod:: connect_volume + .. automethod:: disconnect_volume diff --git a/doc/source/api/os_brick/initiator/index.rst b/doc/source/api/os_brick/initiator/index.rst new file mode 100644 index 000000000..1921865f4 --- /dev/null +++ b/doc/source/api/os_brick/initiator/index.rst @@ -0,0 +1,13 @@ +:mod:`initiator` -- Initiator +============================= + +.. automodule:: os_brick.initiator + :synopsis: Initiator module + + +Sub-modules: + +.. toctree:: + :maxdepth: 2 + + connector diff --git a/doc/source/changelog.rst b/doc/source/changelog.rst new file mode 100644 index 000000000..b4e96ae39 --- /dev/null +++ b/doc/source/changelog.rst @@ -0,0 +1,6 @@ +os-brick Changelog history +========================== + +1.0.0 +----- +* First version of the library diff --git a/doc/source/conf.py b/doc/source/conf.py index b1f113ead..15a6a0f46 100755 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -37,8 +37,8 @@ source_suffix = '.rst' master_doc = 'index' # General information about the project. -project = u'brick' -copyright = u'2013, OpenStack Foundation' +project = u'os-brick' +copyright = u'2015, OpenStack Foundation' # If true, '()' will be appended to :func: etc. cross-reference text. add_function_parentheses = True diff --git a/doc/source/index.rst b/doc/source/index.rst index bfdeaeda5..2f224ee28 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -1,10 +1,10 @@ -Brick |release| Documenation -============================ +os-brick |release| Documenation +=============================== Overview -------- -**Brick** is a Python package containing classes that help -with volume discover and creation for local storage. +**os-brick** is a Python package containing classes that help +with volume discovery and removal from a host. :doc:`installation` Instructions on how to get the distribution. @@ -18,15 +18,15 @@ with volume discover and creation for local storage. Changes ------- -see the :doc:`changelog` for a full list of changes to **Brick**. +see the :doc:`changelog` for a full list of changes to **os-brick**. About This Documentation ------------------------ This documentation is generated using the `Sphinx `_ documentation generator. The source files for the documentation are located in the *doc/* directory of the -**Brick** distribution. To generate the docs locally run the -following command from the root directory of the **Brick** source. +**os-brick** distribution. To generate the docs locally run the +following command from the root directory of the **os-brick** source. .. code-block:: bash diff --git a/doc/source/installation.rst b/doc/source/installation.rst index 43fde847e..b7509d80b 100644 --- a/doc/source/installation.rst +++ b/doc/source/installation.rst @@ -4,9 +4,15 @@ Installation At the command line:: - $ pip install brick + $ pip install os-brick Or, if you have virtualenvwrapper installed:: - $ mkvirtualenv brick - $ pip install brick + $ mkvirtualenv os-brick + $ pip install os-brick + +Or, from source:: + + $ git clone https://github.com/openstack/os-brick + $ cd os-brick + $ python setup.py install diff --git a/doc/source/tutorial.rst b/doc/source/tutorial.rst new file mode 100644 index 000000000..140d6adc4 --- /dev/null +++ b/doc/source/tutorial.rst @@ -0,0 +1,36 @@ +Tutorial +======== + +This tutorial is intended as an introduction to working with +**os-brick**. + +Prerequisites +------------- +Before we start, make sure that you have the **os-brick** distribution +:doc:`installed `. In the Python shell, the following +should run without raising an exception: + +.. code-block:: bash + + >>> import os_brick + +Fetch all of the initiator information from the host +---------------------------------------------------- +An example of how to collect the initiator information that is needed +to export a volume to this host. + +.. code-block:: python + + from os_brick.initiator import connector + + # what helper do you want to use to get root access? + root_helper = "sudo" + # The ip address of the host you are running on + my_ip = "192.168.1.1" + # Do you want to support multipath connections? + multipath = True + # Do you want to enforce that multipath daemon is running? + enforce_multipath = False + initiator = connector.get_connector_properties(root_helper, my_ip, + multipath, + enforce_multipath) diff --git a/doc/source/usage.rst b/doc/source/usage.rst deleted file mode 100644 index 1912dfd19..000000000 --- a/doc/source/usage.rst +++ /dev/null @@ -1,7 +0,0 @@ -======== -Usage -======== - -To use brick in a project:: - - import brick diff --git a/os_brick/__init__.py b/os_brick/__init__.py index e69de29bb..2752a5c7f 100644 --- a/os_brick/__init__.py +++ b/os_brick/__init__.py @@ -0,0 +1,19 @@ +# 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. +""" +:mod:`os_brick` -- OpenStack host based volume management +========================================================= + +.. autmodule:: os_brick + :synopsis: OpenStack host based volume management. +.. moduleauthor:: Walter A. Boring IV +""" diff --git a/os_brick/initiator/__init__.py b/os_brick/initiator/__init__.py index e69de29bb..0f5c33a21 100644 --- a/os_brick/initiator/__init__.py +++ b/os_brick/initiator/__init__.py @@ -0,0 +1,21 @@ +# Copyright 2015 OpenStack Foundation +# All Rights Reserved. +# +# 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. +""" +Brick's Initiator module. + +The initator module contains the capabilities for discovering the initiator +information as well as discovering and removing volumes from a host. + +""" diff --git a/os_brick/initiator/connector.py b/os_brick/initiator/connector.py index aeb323520..8f6e2f898 100644 --- a/os_brick/initiator/connector.py +++ b/os_brick/initiator/connector.py @@ -12,6 +12,13 @@ # WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the # License for the specific language governing permissions and limitations # under the License. +""" Brick Connector objects for each supported transport protocol. + +.. module: connector + +The connectors here are responsible for discovering and removing volumes for +each of the supported transport protocols. +""" import copy import os