README clean up
Change-Id: I185c4a1317b4fc39cc51f7004315df7283ea1c94
diff --git a/README.rst b/README.rst
index fbdaaf9..5e1f645 100644
--- a/README.rst
+++ b/README.rst
@@ -1,18 +1,21 @@
-==============================
-Openstack Cinder Block Storage
-==============================
+=====
+Usage
+=====
-Cinder provides an infrastructure for managing volumes in OpenStack. It was
-originally a Nova component called nova-volume, but has become an independent
-project since the Folsom release.
+Cinder provides an infrastructure for managing volumes in OpenStack.
+Originally, this project was the Nova component called ``nova-volume``
+and starting from the Folsom OpenStack release it has become an independent
+project.
-Sample pillars
-==============
+This file provides the sample configurations for different use cases:
-New structure divides cinder-api,cinder-scheduler to role controller and
-cinder-volume to role volume.
+* Pillar sample of a basic Cinder configuration:
-.. code-block:: yaml
+ The pillar structure defines ``cinder-api`` and ``cinder-scheduler`` inside
+ the ``controller`` role and ``cinder-volume`` inside the to ``volume``
+ role.
+
+ .. code-block:: yaml
cinder:
controller:
@@ -116,10 +119,9 @@
barbican:
enabled: true
+* The CORS parameters enablement:
-Enable CORS parameters
-
-.. code-block:: yaml
+ .. code-block:: yaml
cinder:
controller:
@@ -131,95 +133,91 @@
allow_credentials: True
max_age: 86400
-Client-side RabbitMQ HA setup for controller
+* The client-side RabbitMQ HA setup for the controller:
-.. code-block:: yaml
+ .. code-block:: yaml
- cinder:
- controller:
- ....
- message_queue:
- engine: rabbitmq
- members:
- - host: 10.0.16.1
- - host: 10.0.16.2
- - host: 10.0.16.3
- user: openstack
- password: pwd
- virtual_host: '/openstack'
- ....
+ cinder:
+ controller:
+ ....
+ message_queue:
+ engine: rabbitmq
+ members:
+ - host: 10.0.16.1
+ - host: 10.0.16.2
+ - host: 10.0.16.3
+ user: openstack
+ password: pwd
+ virtual_host: '/openstack'
+ ....
-Client-side RabbitMQ HA setup for volume component
+* The client-side RabbitMQ HA setup for the volume component
-.. code-block:: yaml
+ .. code-block:: yaml
- cinder:
- volume:
- ....
- message_queue:
- engine: rabbitmq
- members:
- - host: 10.0.16.1
- - host: 10.0.16.2
- - host: 10.0.16.3
- user: openstack
- password: pwd
- virtual_host: '/openstack'
- ....
+ cinder:
+ volume:
+ ....
+ message_queue:
+ engine: rabbitmq
+ members:
+ - host: 10.0.16.1
+ - host: 10.0.16.2
+ - host: 10.0.16.3
+ user: openstack
+ password: pwd
+ virtual_host: '/openstack'
+ ....
-Configuring TLS communications
-------------------------------
+* Configuring TLS communications.
+ .. note:: By default, system-wide installed CA certs are used.
+ Therefore, the ``cacert_file`` and ``cacert`` parameters are
+ optional.
-**Note:** by default system wide installed CA certs are used, so ``cacert_file`` param is optional, as well as ``cacert``.
+ * RabbitMQ TLS:
+ .. code-block:: yaml
-- **RabbitMQ TLS**
+ cinder:
+ controller, volume:
+ message_queue:
+ port: 5671
+ ssl:
+ enabled: True
+ (optional) cacert: cert body if the cacert_file does not exists
+ (optional) cacert_file: /etc/openstack/rabbitmq-ca.pem
+ (optional) version: TLSv1_2
-.. code-block:: yaml
+ * MySQL TLS:
- cinder:
- controller, volume:
- message_queue:
- port: 5671
- ssl:
- enabled: True
- (optional) cacert: cert body if the cacert_file does not exists
- (optional) cacert_file: /etc/openstack/rabbitmq-ca.pem
- (optional) version: TLSv1_2
+ .. code-block:: yaml
+ cinder:
+ controller:
+ database:
+ ssl:
+ enabled: True
+ (optional) cacert: cert body if the cacert_file does not exists
+ (optional) cacert_file: /etc/openstack/mysql-ca.pem
-- **MySQL TLS**
+ * Openstack HTTPS API:
-.. code-block:: yaml
+ .. code-block:: yaml
- cinder:
- controller:
- database:
- ssl:
- enabled: True
- (optional) cacert: cert body if the cacert_file does not exists
- (optional) cacert_file: /etc/openstack/mysql-ca.pem
+ cinder:
+ controller, volume:
+ identity:
+ protocol: https
+ (optional) cacert_file: /etc/openstack/proxy.pem
+ glance:
+ protocol: https
+ (optional) cacert_file: /etc/openstack/proxy.pem
-- **Openstack HTTPS API**
+* Cinder setup with zeroing deleted volumes:
-.. code-block:: yaml
-
- cinder:
- controller, volume:
- identity:
- protocol: https
- (optional) cacert_file: /etc/openstack/proxy.pem
- glance:
- protocol: https
- (optional) cacert_file: /etc/openstack/proxy.pem
-
-
-
-Cinder setup with zeroing deleted volumes
-
-.. code-block:: yaml
+ .. code-block:: yaml
cinder:
controller:
@@ -227,9 +225,9 @@
wipe_method: zero
...
-Cinder setup with shreding deleted volumes
+* Cinder setup with shreding deleted volumes:
-.. code-block:: yaml
+ .. code-block:: yaml
cinder:
controller:
@@ -237,9 +235,9 @@
wipe_method: shred
...
-Configuration of policy.json file
+* Configuration of ``policy.json`` file:
-.. code-block:: yaml
+ .. code-block:: yaml
cinder:
controller:
@@ -249,9 +247,9 @@
# Add key without value to remove line from policy.json
'volume:extend':
-Default Cinder backend lvm_type setup
+* Default Cinder backend ``lvm_type`` setup:
-.. code-block:: yaml
+ .. code-block:: yaml
cinder:
volume:
@@ -260,10 +258,9 @@
# Type of LVM volumes to deploy; (default, thin, or auto). Auto defaults to thin if thin is supported.
lvm_type: auto
+* Default Cinder setup with iSCSI target:
-Default Cinder setup with iSCSI target
-
-.. code-block:: yaml
+ .. code-block:: yaml
cinder:
controller:
@@ -297,9 +294,9 @@
type_name: lvmdriver-1
volume_group: cinder-volume
-Cinder setup for IBM Storwize
+* Cinder setup for IBM Storwize:
-.. code-block:: yaml
+ .. code-block:: yaml
cinder:
volume:
@@ -339,10 +336,9 @@
multipath: true
pool: SAS15K
+* Cinder setup with NFS:
-Cinder setup with NFS
-
-.. code-block:: yaml
+ .. code-block:: yaml
cinder:
controller:
@@ -358,10 +354,9 @@
- 172.16.10.110:/var/nfs/cinder
options: rw,sync
+* Cinder setup with NetApp:
-Cinder setup with NetApp
-
-.. code-block:: yaml
+ .. code-block:: yaml
cinder:
controller:
@@ -390,10 +385,9 @@
nfs-common:
version: latest
+* Cinder setup with Hitachi VPS:
-Cinder setup with Hitachi VPS
-
-.. code-block:: yaml
+ .. code-block:: yaml
cinder:
controller:
@@ -405,9 +399,9 @@
engine: hitachi_vsp
connection: FC
-Cinder setup with Hitachi VPS with defined ldev range
+* Cinder setup with Hitachi VPS with defined ``ldev`` range:
-.. code-block:: yaml
+ .. code-block:: yaml
cinder:
controller:
@@ -420,30 +414,29 @@
connection: FC
ldev_range: 0-1000
-Cinder setup with CEPH
+* Cinder setup with Ceph:
-.. code-block:: yaml
+ .. code-block:: yaml
- cinder:
- controller:
- enabled: true
- backend:
- ceph_backend:
- type_name: standard-iops
- backend: ceph_backend
- pool: volumes
- engine: ceph
- user: cinder
- secret_uuid: da74ccb7-aa59-1721-a172-0006b1aa4e3e
- client_cinder_key: AQDOavlU6BsSJhAAnpFR906mvdgdfRqLHwu0Uw==
- report_discard_supported: True
+ cinder:
+ controller:
+ enabled: true
+ backend:
+ ceph_backend:
+ type_name: standard-iops
+ backend: ceph_backend
+ pool: volumes
+ engine: ceph
+ user: cinder
+ secret_uuid: da74ccb7-aa59-1721-a172-0006b1aa4e3e
+ client_cinder_key: AQDOavlU6BsSJhAAnpFR906mvdgdfRqLHwu0Uw==
+ report_discard_supported: True
-http://ceph.com/docs/master/rbd/rbd-openstack/
+ .. note:: `Ceph official documentation <http://ceph.com/docs/master/rbd/rbd-openstack/>`__
+* Cinder setup with HP3par:
-Cinder setup with HP3par
-
-.. code-block:: yaml
+ .. code-block:: yaml
cinder:
controller:
@@ -462,9 +455,9 @@
debug: True
snapcpg: OpenStackSNAPCPG
-Cinder setup with Fujitsu Eternus
+* Cinder setup with Fujitsu Eternus:
-.. code-block:: yaml
+ .. code-block:: yaml
cinder:
volume:
@@ -491,9 +484,9 @@
connection: FC/iSCSI
name: 10k_SAS
-Cinder setup with IBM GPFS filesystem
+* Cinder setup with IBM GPFS filesystem:
-.. code-block:: yaml
+ .. code-block:: yaml
cinder:
volume:
@@ -508,9 +501,9 @@
engine: gpfs
mount_point: '/mnt/gpfs-openstack/cinder/silver'
-Cinder setup with HP LeftHand
+* Cinder setup with HP LeftHand:
-.. code-block:: yaml
+ .. code-block:: yaml
cinder:
volume:
@@ -525,15 +518,15 @@
clustername: cluster1
iscsi_chap_enabled: false
-Extra parameters for HP LeftHand
+* Extra parameters for HP LeftHand:
-.. code-block:: yaml
+ .. code-block:: yaml
cinder type-key normal-storage set hplh:data_pl=r-10-2 hplh:provisioning=full
-Cinder setup with Solidfire
+* Cinder setup with Solidfire:
-.. code-block:: yaml
+ .. code-block:: yaml
cinder:
volume:
@@ -550,9 +543,9 @@
sf_api_port: 14443
host: ctl01
-Cinder setup with Block Device driver
+* Cinder setup with Block Device driver:
-.. code-block:: yaml
+ .. code-block:: yaml
cinder:
volume:
@@ -567,9 +560,9 @@
- sdc
- sdd
-Enable cinder-backup service for ceph
+* Enable cinder-backup service for ceph
-.. code-block:: yaml
+ .. code-block:: yaml
cinder:
controller:
@@ -597,9 +590,9 @@
ceph_chunk_size: 134217728
restore_discard_excess_bytes: false
-Enable auditing filter, ie: CADF
+* Auditing filter (CADF) enablement:
-.. code-block:: yaml
+ .. code-block:: yaml
cinder:
controller:
@@ -616,10 +609,9 @@
filter_factory: 'keystonemiddleware.audit:filter_factory'
map_file: '/etc/pycadf/cinder_api_audit_map.conf'
+* Cinder setup with custom availability zones:
-Cinder setup with custom availability zones:
-
-.. code-block:: yaml
+ .. code-block:: yaml
cinder:
controller:
@@ -630,10 +622,16 @@
default_availability_zone: my-default-zone
storage_availability_zone: my-custom-zone-name
+ The ``default_availability_zone`` is used when a volume has been created,
+ without specifying a zone in the ``create`` request as this zone must exist
+ in your configuration.
-Cinder setup with custom non-admin volume query filters:
+ The ``storage_availability_zone`` is an actual zone where the node belongs to
+ and must be specified per each node.
-.. code-block:: yaml
+* Cinder setup with custom non-admin volume query filters:
+
+ .. code-block:: yaml
cinder:
controller:
@@ -644,26 +642,25 @@
- availability_zone
- bootable
+* ``public_endpoint`` and ``osapi_volume_base_url``:
-public_endpoint and osapi_volume_base_url parameters:
-"public_endpoint" is used for configuring versions endpoint,
-"osapi_volume_base_URL" is used to present Cinder URL to users.
-They are useful when running Cinder under load balancer in SSL.
+ * ``public_endpoint``
+ Used for configuring versions endpoint
+ * ``osapi_volume_base_URL``
+ Used to present Cinder URL to users
-.. code-block:: yaml
+ These parameters can be useful when running Cinder under load balancer in
+ SSL.
+
+ .. code-block:: yaml
cinder:
controller:
public_endpoint_address: https://${_param:cluster_domain}:8776
-The default availability zone is used when a volume has been created, without specifying a zone in the create request. (this zone must exist in your configuration obviously)
-The storage availability zone is the actual zone where the node belongs to. Make sure to specify this per node.
-Check the documentation of OpenStack for more information
+* Client role definition:
-
-Client role
-
-.. code-block:: yaml
+ .. code-block:: yaml
cinder:
client:
@@ -684,38 +681,43 @@
key:
conn_speed: fibre-10G
-Enable Barbican integration
+* Barbican integration enablement:
-.. code-block:: yaml
+ .. code-block:: yaml
cinder:
controller:
barbican:
enabled: true
+* Keystone API version specification (v3 is default):
-Specify Keystone API version (v3 is default):
-
-.. code-block:: yaml
+ .. code-block:: yaml
cinder:
controller:
identity:
api_version: v2.0
-Enhanced logging with logging.conf
-----------------------------------
+**Enhanced logging with logging.conf**
-By default logging.conf is disabled.
+By default ``logging.conf`` is disabled.
+You can enable per-binary ``logging.conf`` by setting the following
+parameters:
-That is possible to enable per-binary logging.conf with new variables:
- * openstack_log_appender - set it to true to enable log_config_append for all OpenStack services;
- * openstack_fluentd_handler_enabled - set to true to enable FluentHandler for all Openstack services.
- * openstack_ossyslog_handler_enabled - set to true to enable OSSysLogHandler for all Openstack services.
+* ``openstack_log_appender``
+ Set to ``true`` to enable ``log_config_append`` for all OpenStack
+ services
-Only WatchedFileHandler, OSSysLogHandler and FluentHandler are available.
+* ``openstack_fluentd_handler_enabled``
+ Set to ``true`` to enable FluentHandler for all Openstack services
-Also it is possible to configure this with pillar:
+* ``openstack_ossyslog_handler_enabled``
+ Set to ``true`` to enable OSSysLogHandler for all Openstack services
+
+Only WatchedFileHandler, OSSysLogHandler, and FluentHandler are available.
+
+To configure this functionality with pillar:
.. code-block:: yaml
@@ -742,61 +744,27 @@
ossyslog:
enabled: true
-Documentation and Bugs
-============================
+**Documentation and bugs**
-To learn how to deploy OpenStack Salt, consult the documentation available
-online at:
+* http://salt-formulas.readthedocs.io/
+ Learn how to install and update salt-formulas
-https://wiki.openstack.org/wiki/OpenStackSalt
+* https://github.com/salt-formulas/salt-formula-cinder/issues
+ In the unfortunate event that bugs are discovered, report the issue to the
+ appropriate issue tracker. Use the Github issue tracker for a specific salt
+ formula
-In the unfortunate event that bugs are discovered, they should be reported to
-the appropriate bug tracker. If you obtained the software from a 3rd party
-operating system vendor, it is often wise to use their own bug tracker for
-reporting problems. In all other cases use the master OpenStack bug tracker,
-available at:
+* https://launchpad.net/salt-formulas
+ For feature requests, bug reports, or blueprints affecting the entire
+ ecosystem, use the Launchpad salt-formulas project
- http://bugs.launchpad.net/openstack-salt
+* https://launchpad.net/~salt-formulas-users
+ Join the salt-formulas-users team and subscribe to mailing list if required
-Developers wishing to work on the OpenStack Salt project should always base
-their work on the latest formulas code, available from the master GIT
-repository at:
+* https://github.com/salt-formulas/salt-formula-cinder
+ Develop the salt-formulas projects in the master branch and then submit pull
+ requests against a specific formula
- https://git.openstack.org/cgit/openstack/salt-formula-cinder
-
-Developers should also join the discussion on the IRC list, at:
-
- https://wiki.openstack.org/wiki/Meetings/openstack-salt
-
-Documentation and Bugs
-======================
-
-To learn how to install and update salt-formulas, consult the documentation
-available online at:
-
- http://salt-formulas.readthedocs.io/
-
-In the unfortunate event that bugs are discovered, they should be reported to
-the appropriate issue tracker. Use Github issue tracker for specific salt
-formula:
-
- https://github.com/salt-formulas/salt-formula-cinder/issues
-
-For feature requests, bug reports or blueprints affecting entire ecosystem,
-use Launchpad salt-formulas project:
-
- https://launchpad.net/salt-formulas
-
-You can also join salt-formulas-users team and subscribe to mailing list:
-
- https://launchpad.net/~salt-formulas-users
-
-Developers wishing to work on the salt-formulas projects should always base
-their work on master branch and submit pull request against specific formula.
-
- https://github.com/salt-formulas/salt-formula-cinder
-
-Any questions or feedback is always welcome so feel free to join our IRC
-channel:
-
- #salt-formulas @ irc.freenode.net
+* #salt-formulas @ irc.freenode.net
+ Use this IRC channel in case of any questions or feedback which is always
+ welcome