From 6310829f73813a2c6485e8fb8fb90ebe1add5c71 Mon Sep 17 00:00:00 2001 From: Gorka Eguileor Date: Thu, 14 Jun 2018 20:47:24 +0200 Subject: [PATCH] Fix github README file Github doesn't support the "include" directive, so when we fixed the readme for the PyPi package we broke the github readme. Now it's only presenting the demo. To fix this we revert to having the whole readme in the README.rst file and in setup.py we hardcode the removal of the demo section. --- Makefile | 2 +- README.rst | 182 ++++++++++++++++++++++++++++++++++++++++++++- readme_postfix.rst | 105 -------------------------- readme_prefix.rst | 76 ------------------- setup.py | 9 ++- 5 files changed, 187 insertions(+), 187 deletions(-) delete mode 100644 readme_postfix.rst delete mode 100644 readme_prefix.rst diff --git a/Makefile b/Makefile index 4d77948..12af516 100644 --- a/Makefile +++ b/Makefile @@ -80,7 +80,7 @@ register: ## register package in pypi python setup.py register --repository pypi test-package: - python setup.py sdist + python setup.py check -r -s test-release: clean python setup.py sdist upload --repository pypitest diff --git a/README.rst b/README.rst index de95ccc..c882fe0 100644 --- a/README.rst +++ b/README.rst @@ -1,4 +1,78 @@ -.. include:: readme_prefix.rst +Cinder Library +=============================== + +.. image:: https://img.shields.io/pypi/v/cinderlib.svg + :target: https://pypi.python.org/pypi/cinderlib + +.. image:: https://readthedocs.org/projects/cinderlib/badge/?version=latest + :target: https://cinderlib.readthedocs.io/en/latest/?badge=latest + :alt: Documentation Status + +.. image:: https://img.shields.io/pypi/pyversions/cinderlib.svg + :target: https://pypi.python.org/pypi/cinderlib + +.. image:: https://img.shields.io/:license-apache-blue.svg + :target: http://www.apache.org/licenses/LICENSE-2.0 + + +Introduction +------------ + +Cinder Library is a Python library that allows using storage drivers outside of +Cinder. + +* Free software: Apache Software License 2.0 +* Documentation: https://cinderlib.readthedocs.io. + +This library is currently in Alpha stage and is primarily intended as a proof +of concept at this stage. While some drivers have been manually validated most +drivers have not, so there's a good chance that they could experience issues. + +When using this library one should be aware that this is in no way close to the +robustness or feature richness that the Cinder project provides, for detailed +information on the current limitations please refer to the documentation. + +Due to the limited access to Cinder backends and time constraints the list of +drivers that have been manually tested are (I'll try to test more): + +- LVM with LIO +- Dell EMC XtremIO +- Dell EMC VMAX +- Kaminario K2 +- Ceph/RBD +- NetApp SolidFire + +If you try the library with another storage array I would appreciate a note on +the library version, Cinder release, and results of your testing. + +Features +-------- + +* Use a Cinder driver without running a DBMS, Message broker, or Cinder + service. +* Using multiple simultaneous drivers on the same program. +* Basic operations support: + + - Create volume + - Delete volume + - Extend volume + - Clone volume + - Create snapshot + - Delete snapshot + - Create volume from snapshot + - Connect volume + - Disconnect volume + - Local attach + - Local detach + - Validate connector + +* Code should support multiple concurrent connections to a volume, though this + has not yet been tested. +* Metadata persistence plugin: + + - Stateless: Caller stores JSON serialization. + - Database: Metadata is stored in a database: MySQL, PostgreSQL, SQLite... + - Custom plugin: Metadata is stored in another metadata storage. Demo ---- @@ -9,4 +83,108 @@ Demo target="_blank"> -.. include:: readme_postfix.rst +Example +------- + +The following example uses CentOS 7 and the Cinder LVM driver, which should be +the easiest to setup and test. + +First you need to setup your system: + +.. code-block:: shell + + $ sudo yum install -y centos-release-openstack-pike + $ sudo yum install -y openstack-cinder targetcli python-pip + $ sudo pip install cinderlib + $ sudo dd if=/dev/zero of=cinder-volumes bs=1048576 seek=22527 count=1 + $ sudo lodevice=`losetup --show -f ./cinder-volumes` + $ sudo pvcreate $lodevice + $ sudo vgcreate cinder-volumes $lodevice + $ sudo vgscan --cache + +Then you need to run `python` with a passwordless sudo user (required to +control LVM and do the attach) and execute: + +.. code-block:: python + + import cinderlib as cl + from pprint import pprint as pp + + # We setup the library to setup the driver configuration when serializing + cl.setup(output_all_backend_info=True) + + # Initialize the LVM driver + lvm = cl.Backend(volume_driver='cinder.volume.drivers.lvm.LVMVolumeDriver', + volume_group='cinder-volumes', + iscsi_protocol='iscsi', + iscsi_helper='lioadm', + volume_backend_name='lvm_iscsi') + + # Show the LVM backend stats + pp(lvm.stats()) + + # Create a 1GB volume + vol = lvm.create_volume(1, name='lvm-vol') + + # Export, initialize, and do a local attach of the volume + attach = vol.attach() + + pp('Volume %s attached to %s' % (vol.id, attach.path)) + + # Snapshot it + snap = vol.create_snapshot('lvm-snap') + + # Show the JSON string + pp(vol.jsons) + + # Save the whole environment to a file + with open('cinderlib-test.txt', 'w') as f: + f.write(cl.dumps()) + + # Exit python + exit() + +Now we can check that the logical volume is there, exported, and attached to +our system: + +.. code-block:: shell + + # lvdisplay + # targetcli ls + # iscsiadm -m session + # lsblk + +And now let's run a new `python` interpreter and clean things up: + +.. code-block:: python + + import cinderlib as cl + + # Get the whole environment up + with open('cinderlib-test.txt') as f: + backends = cl.load(f.read(), save=True) + + # Get the volume reference we loaded from file and detach + vol = list(backends[0].volumes)[0] + vol.detach() + + # Get the snapshot and delete it + snap = list(vol.snapshots)[0] + snap.delete() + + # Finally delete the volume + vol.delete() + +We should confirm that the logical volume is no longer there, there's nothing +exported or attached to our system: + +.. code-block:: shell + + # lvdisplay + # targetcli ls + # iscsiadm -m session + # lsblk + +.. _GIGO: https://en.wikipedia.org/wiki/Garbage_in,_garbage_out +.. _official project documentation: https://readthedocs.org/projects/cinderlib/badge/?version=latest +.. _OpenStack's Cinder volume driver configuration documentation: https://docs.openstack.org/cinder/latest/configuration/block-storage/volume-drivers.html diff --git a/readme_postfix.rst b/readme_postfix.rst deleted file mode 100644 index 8801efb..0000000 --- a/readme_postfix.rst +++ /dev/null @@ -1,105 +0,0 @@ -Example -------- - -The following example uses CentOS 7 and the Cinder LVM driver, which should be -the easiest to setup and test. - -First you need to setup your system: - -.. code-block:: shell - - $ sudo yum install -y centos-release-openstack-pike - $ sudo yum install -y openstack-cinder targetcli python-pip - $ sudo pip install cinderlib - $ sudo dd if=/dev/zero of=cinder-volumes bs=1048576 seek=22527 count=1 - $ sudo lodevice=`losetup --show -f ./cinder-volumes` - $ sudo pvcreate $lodevice - $ sudo vgcreate cinder-volumes $lodevice - $ sudo vgscan --cache - -Then you need to run `python` with a passwordless sudo user (required to -control LVM and do the attach) and execute: - -.. code-block:: python - - import cinderlib as cl - from pprint import pprint as pp - - # We setup the library to setup the driver configuration when serializing - cl.setup(output_all_backend_info=True) - - # Initialize the LVM driver - lvm = cl.Backend(volume_driver='cinder.volume.drivers.lvm.LVMVolumeDriver', - volume_group='cinder-volumes', - iscsi_protocol='iscsi', - iscsi_helper='lioadm', - volume_backend_name='lvm_iscsi') - - # Show the LVM backend stats - pp(lvm.stats()) - - # Create a 1GB volume - vol = lvm.create_volume(1, name='lvm-vol') - - # Export, initialize, and do a local attach of the volume - attach = vol.attach() - - pp('Volume %s attached to %s' % (vol.id, attach.path)) - - # Snapshot it - snap = vol.create_snapshot('lvm-snap') - - # Show the JSON string - pp(vol.jsons) - - # Save the whole environment to a file - with open('cinderlib-test.txt', 'w') as f: - f.write(cl.dumps()) - - # Exit python - exit() - -Now we can check that the logical volume is there, exported, and attached to -our system: - -.. code-block:: shell - - # lvdisplay - # targetcli ls - # iscsiadm -m session - # lsblk - -And now let's run a new `python` interpreter and clean things up: - -.. code-block:: python - - import cinderlib as cl - - # Get the whole environment up - with open('cinderlib-test.txt') as f: - backends = cl.load(f.read(), save=True) - - # Get the volume reference we loaded from file and detach - vol = list(backends[0].volumes)[0] - vol.detach() - - # Get the snapshot and delete it - snap = list(vol.snapshots)[0] - snap.delete() - - # Finally delete the volume - vol.delete() - -We should confirm that the logical volume is no longer there, there's nothing -exported or attached to our system: - -.. code-block:: shell - - # lvdisplay - # targetcli ls - # iscsiadm -m session - # lsblk - -.. _GIGO: https://en.wikipedia.org/wiki/Garbage_in,_garbage_out -.. _official project documentation: https://readthedocs.org/projects/cinderlib/badge/?version=latest -.. _OpenStack's Cinder volume driver configuration documentation: https://docs.openstack.org/cinder/latest/configuration/block-storage/volume-drivers.html diff --git a/readme_prefix.rst b/readme_prefix.rst deleted file mode 100644 index 9aef146..0000000 --- a/readme_prefix.rst +++ /dev/null @@ -1,76 +0,0 @@ -Cinder Library -=============================== - -.. image:: https://img.shields.io/pypi/v/cinderlib.svg - :target: https://pypi.python.org/pypi/cinderlib - -.. image:: https://readthedocs.org/projects/cinderlib/badge/?version=latest - :target: https://cinderlib.readthedocs.io/en/latest/?badge=latest - :alt: Documentation Status - -.. image:: https://img.shields.io/pypi/pyversions/cinderlib.svg - :target: https://pypi.python.org/pypi/cinderlib - -.. image:: https://img.shields.io/:license-apache-blue.svg - :target: http://www.apache.org/licenses/LICENSE-2.0 - - -Introduction ------------- - -Cinder Library is a Python library that allows using storage drivers outside of -Cinder. - -* Free software: Apache Software License 2.0 -* Documentation: https://cinderlib.readthedocs.io. - -This library is currently in Alpha stage and is primarily intended as a proof -of concept at this stage. While some drivers have been manually validated most -drivers have not, so there's a good chance that they could experience issues. - -When using this library one should be aware that this is in no way close to the -robustness or feature richness that the Cinder project provides, for detailed -information on the current limitations please refer to the documentation. - -Due to the limited access to Cinder backends and time constraints the list of -drivers that have been manually tested are (I'll try to test more): - -- LVM with LIO -- Dell EMC XtremIO -- Dell EMC VMAX -- Kaminario K2 -- Ceph/RBD -- NetApp SolidFire - -If you try the library with another storage array I would appreciate a note on -the library version, Cinder release, and results of your testing. - -Features --------- - -* Use a Cinder driver without running a DBMS, Message broker, or Cinder - service. -* Using multiple simultaneous drivers on the same program. -* Basic operations support: - - - Create volume - - Delete volume - - Extend volume - - Clone volume - - Create snapshot - - Delete snapshot - - Create volume from snapshot - - Connect volume - - Disconnect volume - - Local attach - - Local detach - - Validate connector - -* Code should support multiple concurrent connections to a volume, though this - has not yet been tested. -* Metadata persistence plugin: - - - Stateless: Caller stores JSON serialization. - - Database: Metadata is stored in a database: MySQL, PostgreSQL, SQLite... - - Custom plugin: Metadata is stored in another metadata storage. - diff --git a/setup.py b/setup.py index 7bf31f9..24cc2e4 100644 --- a/setup.py +++ b/setup.py @@ -3,11 +3,14 @@ import setuptools -with open('readme_prefix.rst') as readme_file: +with open('README.rst') as readme_file: readme = readme_file.read() -with open('readme_postfix.rst') as readme_file: - readme += readme_file.read() +# Remove the demo for the PyPi package +start = readme.index('Demo\n----') +end = readme.index('Example\n-------') +readme = readme[:start] + readme[end:] + with open('HISTORY.rst') as history_file: history = history_file.read()