diff --git a/README.md b/README.md deleted file mode 100644 index 4d8966b..0000000 --- a/README.md +++ /dev/null @@ -1,86 +0,0 @@ -Team and repository tags -======================== - -[![Team and repository tags](https://governance.openstack.org/tc/badges/devstack-plugin-ceph.svg)](https://governance.openstack.org/tc/reference/tags/index.html) - -Devstack Ceph Plugin -==================== - -# Overview - -Devstack plugin to configure Ceph as the storage backend for openstack services - -As part of ```stack.sh```: - -* Installs Ceph (client and server) packages -* Creates a Ceph cluster for use with openstack services -* Configures Ceph as the storage backend for Cinder, Cinder Backup, Nova, - Manila (not by default), and Glance services -* (Optionally) Sets up & configures Rados gateway (aka rgw or radosgw) as a Swift endpoint with Keystone integration - * Set ```ENABLE_CEPH_RGW=True``` in your ```localrc``` -* Supports Ceph cluster running local or remote to openstack services - -As part of ```unstack.sh``` | ```clean.sh```: - -* Tears down the Ceph cluster and its related services - -This plugin also gets used to configure Ceph as the storage backend for the upstream Ceph CI job named ```gate-tempest-dsvm-full-devstack-plugin-ceph``` - - -# Usage - -* To get started quickly, just enable the plugin in your ```local.conf```: - - ```enable_plugin devstack-plugin-ceph https://opendev.org/openstack/devstack-plugin-ceph``` - - Run ```stack.sh``` in your devstack tree and boom! You're good to go. - -* Ceph is setup as the default storage backend for Cinder, Cinder Backup, - Glance and Nova services. You have the ability to control each of the - enabled services with the following configuration in your ```local.conf```: - - ``` - ENABLE_CEPH_CINDER=True # ceph backend for cinder - ENABLE_CEPH_GLANCE=True # store images in ceph - ENABLE_CEPH_C_BAK=True # backup volumes to ceph - ENABLE_CEPH_NOVA=True # allow nova to use ceph resources - ``` - - Change any of the above lines to ```False``` to disable that feature - specifically. - -* Ceph can be enabled as the storage backend for Manila with the following - setting in your ```local.conf```: - - ``` - ENABLE_CEPH_MANILA=True - ``` - - CephFS Native driver that supports native Ceph protocol is used by default. - To use CephFS NFS-Ganesha driver that supports NFS protocol add the setting: - - ``` - MANILA_CEPH_DRIVER=cephfsnfs - ``` - - Make sure that the manila plugin is enabled before devstack-plugin-ceph in - the ```local.conf``` file. - -* Then run ```stack.sh``` and wait for the _magic_ to happen :) - - -# Known Issues / Limitations - -* Rados Gateway with Keystone for Swift - works on Ubuntu only -* Tempest test failures when using RGW as swift endpoint -* Tempest fails due to verify-tempest-config erroring out, when using RGW as swift endpoint - * Patch sent @ https://review.openstack.org/#/c/264179/ -* Manila with CephFS - for Ubuntu, support only for Trusty Tahr (14.04 LTS) and beyond - -# TODOs - -* Fix Rados Gateway with Keystone for Swift on Fedora - -# Bugs - -* https://bugs.launchpad.net/devstack-plugin-ceph diff --git a/README.rst b/README.rst new file mode 100644 index 0000000..1b5a143 --- /dev/null +++ b/README.rst @@ -0,0 +1,97 @@ +Devstack Ceph Plugin +==================== + +.. image:: https://governance.openstack.org/tc/badges/devstack-plugin-ceph.svg + :target: https://governance.openstack.org/tc/reference/tags/index.html + +Overview +-------- + +Devstack plugin to configure Ceph as the storage backend for openstack +services + +As part of ``stack.sh``: + +- Installs Ceph (client and server) packages +- Creates a Ceph cluster for use with openstack services +- Configures Ceph as the storage backend for Cinder, Cinder Backup, + Nova, Manila (not by default), and Glance services +- (Optionally) Sets up & configures Rados gateway (aka rgw or radosgw) + as a Swift endpoint with Keystone integration +- Set ``ENABLE_CEPH_RGW=True`` in your ``localrc`` +- Supports Ceph cluster running local or remote to openstack services + +As part of ``unstack.sh`` \| ``clean.sh``: + +- Tears down the Ceph cluster and its related services + +This plugin also gets used to configure Ceph as the storage backend for +the upstream Ceph CI job named +``gate-tempest-dsvm-full-devstack-plugin-ceph`` + +Usage +----- + +- To get started quickly, just enable the plugin in your + ``local.conf``: + + ``enable_plugin devstack-plugin-ceph https://opendev.org/openstack/devstack-plugin-ceph`` + +Run ``stack.sh`` in your devstack tree and boom! You're good to go. + +- Ceph is setup as the default storage backend for Cinder, Cinder + Backup, Glance and Nova services. You have the ability to control + each of the enabled services with the following configuration in your + ``local.conf``: + + :: + + ENABLE_CEPH_CINDER=True # ceph backend for cinder + ENABLE_CEPH_GLANCE=True # store images in ceph + ENABLE_CEPH_C_BAK=True # backup volumes to ceph + ENABLE_CEPH_NOVA=True # allow nova to use ceph resources + +Change any of the above lines to ``False`` to disable that feature +specifically. + +- Ceph can be enabled as the storage backend for Manila with the + following setting in your ``local.conf``: + + :: + + ENABLE_CEPH_MANILA=True + +CephFS Native driver that supports native Ceph protocol is used by +default. To use CephFS NFS-Ganesha driver that supports NFS protocol add +the setting: + +:: + + MANILA_CEPH_DRIVER=cephfsnfs + +Make sure that the manila plugin is enabled before devstack-plugin-ceph +in the ``local.conf`` file. + +- Then run ``stack.sh`` and wait for the *magic* to happen :) + +Known Issues / Limitations +-------------------------- + +- Rados Gateway with Keystone for Swift - works on Ubuntu only +- Tempest test failures when using RGW as swift endpoint +- Tempest fails due to verify-tempest-config erroring out, when using + RGW as swift endpoint +- Patch sent @ https://review.openstack.org/#/c/264179/ +- Manila with CephFS - for Ubuntu, support only for Trusty Tahr (14.04 + LTS) and beyond + +TODOs +----- + +- Fix Rados Gateway with Keystone for Swift on Fedora + +Bugs +---- + +- https://bugs.launchpad.net/devstack-plugin-ceph + diff --git a/doc/requirements.txt b/doc/requirements.txt index e7219e8..6534033 100644 --- a/doc/requirements.txt +++ b/doc/requirements.txt @@ -3,3 +3,4 @@ # process, which may cause wedges in the gate later. openstackdocstheme>=2.2.1 # Apache-2.0 sphinx>=2.0.0,!=2.1.0 # BSD +sphinxcontrib-svg2pdfconverter>=0.1.0 # BSD diff --git a/doc/source/conf.py b/doc/source/conf.py index d0a3e6b..1f9ee53 100755 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -22,6 +22,7 @@ sys.path.insert(0, os.path.abspath('../..')) # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom ones. extensions = [ 'sphinx.ext.autodoc', + 'sphinxcontrib.rsvgconverter', #'sphinx.ext.intersphinx', 'openstackdocstheme' ] @@ -32,6 +33,7 @@ openstackdocs_bug_project = 'devstack-plugin-ceph' openstackdocs_bug_tag = '' openstackdocs_auto_version = False openstackdocs_auto_name = False +openstackdocs_pdf_link = True # autodoc generation is a bit aggressive and a nuisance when doing heavy # text edit cycles. @@ -72,10 +74,15 @@ htmlhelp_basename = '%sdoc' % project # [howto/manual]). latex_documents = [ ('index', - '%s.tex' % project, + 'doc-devstack-plugin-ceph.tex', u'%s Documentation' % project, u'OpenStack Foundation', 'manual'), ] # Example configuration for intersphinx: refer to the Python standard library. #intersphinx_mapping = {'http://docs.python.org/': None} + +latex_use_xindy = False +latex_elements = { + 'extraclassoptions': 'openany,oneside', +} diff --git a/doc/source/readme.rst b/doc/source/readme.rst index 7592303..a6210d3 100644 --- a/doc/source/readme.rst +++ b/doc/source/readme.rst @@ -1 +1 @@ -.. include:: ../../README.md +.. include:: ../../README.rst diff --git a/tox.ini b/tox.ini index e67c7e7..3975df9 100644 --- a/tox.ini +++ b/tox.ini @@ -32,3 +32,11 @@ commands = rm -rf doc/build sphinx-build -W -b html doc/source doc/build/html whitelist_externals = rm + +[testenv:pdf-docs] +deps = {[testenv:docs]deps} +whitelist_externals = + make +commands = + sphinx-build -W -b latex doc/source doc/build/pdf + make -C doc/build/pdf