diff --git a/doc/source/images/cinder.png b/doc/source/images/cinder.png new file mode 100644 index 00000000000..ccf18ae8329 Binary files /dev/null and b/doc/source/images/cinder.png differ diff --git a/doc/source/index.rst b/doc/source/index.rst index 28f602979aa..5dc8d510a0a 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -15,11 +15,20 @@ License for the specific language governing permissions and limitations under the License. -=========================================== -Cinder, the OpenStack Block Storage Service -=========================================== +============================================== +OpenStack Block Storage (Cinder) documentation +============================================== -Cinder is an OpenStack project to provide "block storage as a service". +.. figure:: images/cinder.png + :alt: Cinder logo + :align: center + +What is Cinder? +--------------- + +Cinder is the OpenStack Block Storage service for providing volumes to Nova +virtual machines, Ironic bare metal hosts, containers and more. Some of the +goals of Cinder are to be/have: * **Component based architecture**: Quickly add new behaviors * **Highly available**: Scale to very serious workloads @@ -27,89 +36,126 @@ Cinder is an OpenStack project to provide "block storage as a service". * **Recoverable**: Failures should be easy to diagnose, debug, and rectify * **Open Standards**: Be a reference implementation for a community-driven api -This documentation is generated by the Sphinx toolkit and lives in the source -tree. Additional draft and project documentation on Cinder and other components -of OpenStack can be found on the `OpenStack wiki`_. Cloud administrators, refer -to `docs.openstack.org`_. +For end users +------------- -.. _`OpenStack wiki`: https://wiki.openstack.org/wiki/Main_Page -.. _`docs.openstack.org`: https://docs.openstack.org +As an end user of Cinder, you'll use Cinder to create and manage volumes using +the Horizon user interface, command line tools such as the +`python-cinderclient `_, +or by directly using the +`REST API `_. +Tools for using Cinder +~~~~~~~~~~~~~~~~~~~~~~ -Installation Guide -~~~~~~~~~~~~~~~~~~ +* `Horizon `_: + The official web UI for the OpenStack Project. +* `OpenStack Client `_: + The official CLI for OpenStack Projects. You should use this as your CLI for + most things, it includes not just nova commands but also commands for most of + the projects in OpenStack. +* `Cinder Client `_: + The **openstack** CLI is recommended, but there are some advanced features + and administrative commands that are not yet available there. For CLI access + to these commands, the **cinder** CLI can be used instead. + +Using the Cinder API +~~~~~~~~~~~~~~~~~~~~ + +All features of Cinder are exposed via a REST API that can be used to build +more complicated logic or automation with Cinder. This can be consumed directly +or via various SDKs. The following resources can help you get started consuming +the API directly. + +* `Cinder API `_ +* :doc:`Cinder microversion history ` + +For operators +------------- + +This section has details for deploying and maintaining Cinder services. + +Installing Cinder +~~~~~~~~~~~~~~~~~ + +Cinder can be configured standalone using the configuration setting +``auth_strategy = noauth``, but in most cases you will want to at least have +the `Keystone `_ Identity +service and other +`OpenStack services `_ installed. .. toctree:: - :maxdepth: 2 + :maxdepth: 1 Installation Guide Upgrade Process -Administration Guide -~~~~~~~~~~~~~~~~~~~~ +Administrating Cinder +~~~~~~~~~~~~~~~~~~~~~ + +Contents: .. toctree:: - :maxdepth: 2 + :maxdepth: 1 admin/index -Configuration Reference -~~~~~~~~~~~~~~~~~~~~~~~ +Reference +~~~~~~~~~ + +Contents: .. toctree:: - :maxdepth: 2 - - configuration/index - reference/support-matrix - drivers - -CLI Reference -~~~~~~~~~~~~~ - -Information on the commands available through Cinder's Command Line -Interface (CLI) can be found in this section of documentation. - -Full documentation on the python-cinderclient is in the -`python-cinderclient documentation`_. - -.. _`python-cinderclient documentation`: https://docs.openstack.org/python-cinderclient/latest - -.. toctree:: - :maxdepth: 2 + :maxdepth: 1 + configuration/index + reference/support-matrix + drivers cli/index -Contributor/Developer Docs -~~~~~~~~~~~~~~~~~~~~~~~~~~ +Additional resources +~~~~~~~~~~~~~~~~~~~~ + +* `Cinder release notes `_ + +For contributors +---------------- + +Contributions to Cinder are welcome. There can be a lot of background +information needed to get started. This section should help get you started. +Please feel free to also ask any questions in the **#openstack-cinder** IRC +channel. + +Getting started +~~~~~~~~~~~~~~~ + +* `OpenStack Contributor Guide `_ + +Contributing to Cinder +~~~~~~~~~~~~~~~~~~~~~~ + +Contents: .. toctree:: - :maxdepth: 2 + :maxdepth: 1 contributor/index + API Microversions +Additional reference +~~~~~~~~~~~~~~~~~~~~ -API Extensions -~~~~~~~~~~~~~~ - -Go to https://developer.openstack.org/api-ref/block-storage/ for information -about Cinder API extensions. - -:doc:`Block Storage v3 API Microversion History `: -The block storage v3 API evolves over time through -:doc:`API Microversions `. This -provides the history of all those changes. Consider it a "what's new" in the -block storage v3 API. - -Indices and tables -~~~~~~~~~~~~~~~~~~ - -* :ref:`genindex` -* :ref:`search` - -Glossary -~~~~~~~~ +Contents: .. toctree:: :maxdepth: 1 common/glossary.rst + +Indices and tables +~~~~~~~~~~~~~~~~~~ + +Contents: + +* :ref:`genindex` +* :ref:`search`