From 80c25785e6436832dad19a362e1684ac2ee6bfa6 Mon Sep 17 00:00:00 2001
From: Vipin Balachandran <vbala@vmware.com>
Date: Thu, 18 Aug 2016 19:10:07 +0530
Subject: [PATCH] Driver documentation cleanup
Adding more details to volume driver interface documenation.
Change-Id: I79117625aa3b2d7adf57ddab7e5889bebb450176
---
cinder/interface/volume_driver.py | 13 +++++++++++--
cinder/interface/volume_management_driver.py | 19 +++++++++++++++----
.../volume_snapshotmanagement_driver.py | 13 ++++++++++---
doc/source/devref/drivers.rst | 13 +++++++------
4 files changed, 43 insertions(+), 15 deletions(-)
diff --git a/cinder/interface/volume_driver.py b/cinder/interface/volume_driver.py
index 05bd8f21a8b..564ec581b38 100644
--- a/cinder/interface/volume_driver.py
+++ b/cinder/interface/volume_driver.py
@@ -78,9 +78,18 @@ class VolumeDriverCore(base.CinderInterface):
string such as: "iSCSI", "FC", "nfs", "ceph", etc.
* total_capacity_gb
The total capacity in gigabytes (GiB) of the storage backend being
- used to store Cinder volumes.
+ used to store Cinder volumes. Use keyword 'unknown' if the backend
+ cannot report the value or 'infinite' if there is no upper limit.
+ But, it is recommended to report real values as the Cinder
+ scheduler assigns lowest weight to any storage backend reporting
+ 'unknown' or 'infinite'.
+
* free_capacity_gb
- The free capacity in gigabytes (GiB).
+ The free capacity in gigabytes (GiB). Use keyword 'unknown' if the
+ backend cannot report the value or 'infinite' if there is no upper
+ limit. But, it is recommended to report real values as the Cinder
+ scheduler assigns lowest weight to any storage backend reporting
+ 'unknown' or 'infinite'.
And the following optional fields:
diff --git a/cinder/interface/volume_management_driver.py b/cinder/interface/volume_management_driver.py
index 966cb50bcee..fac6074456e 100644
--- a/cinder/interface/volume_management_driver.py
+++ b/cinder/interface/volume_management_driver.py
@@ -53,8 +53,15 @@ class VolumeManagementDriver(base.CinderInterface):
ManageExistingVolumeTypeMismatch, specifying a reason for the failure.
:param volume: Cinder volume to manage
- :param existing_ref: Driver-specific information used to identify a
- volume
+ :param existing_ref: Dictionary with keys 'source-id', 'source-name'
+ with driver-specific values to identify a backend
+ storage object.
+ :raises: ManageExistingInvalidReference If the existing_ref doesn't
+ make sense, or doesn't refer to an existing backend storage
+ object.
+ :raises: ManageExistingVolumeTypeMismatch If there is a mismatch
+ between the volume type and the properties of the existing
+ backend storage object.
"""
def manage_existing_get_size(self, volume, existing_ref):
@@ -63,8 +70,12 @@ class VolumeManagementDriver(base.CinderInterface):
When calculating the size, round up to the next GB.
:param volume: Cinder volume to manage
- :param existing_ref: Driver-specific information used to identify a
- volume
+ :param existing_ref: Dictionary with keys 'source-id', 'source-name'
+ with driver-specific values to identify a backend
+ storage object.
+ :raises: ManageExistingInvalidReference If the existing_ref doesn't
+ make sense, or doesn't refer to an existing backend storage
+ object.
"""
def unmanage(self, volume):
diff --git a/cinder/interface/volume_snapshotmanagement_driver.py b/cinder/interface/volume_snapshotmanagement_driver.py
index 8bce8949cac..0eb3475d3eb 100644
--- a/cinder/interface/volume_snapshotmanagement_driver.py
+++ b/cinder/interface/volume_snapshotmanagement_driver.py
@@ -44,7 +44,9 @@ class VolumeSnapshotManagementDriver(base.CinderInterface):
backend storage object when required.
:param snapshot: The snapshot to manage.
- :param existing_ref: A reference to the existing snap.
+ :param existing_ref: Dictionary with keys 'source-id', 'source-name'
+ with driver-specific values to identify a backend
+ storage object.
:raises: ManageExistingInvalidReference If the existing_ref doesn't
make sense, or doesn't refer to an existing backend storage
object.
@@ -55,8 +57,13 @@ class VolumeSnapshotManagementDriver(base.CinderInterface):
When calculating the size, round up to the next GB.
- :param snapshot: The snapshot.
- :param existing_ref: A reference to the existing snap.
+ :param snapshot: The snapshot to manage.
+ :param existing_ref: Dictionary with keys 'source-id', 'source-name'
+ with driver-specific values to identify a backend
+ storage object.
+ :raises: ManageExistingInvalidReference If the existing_ref doesn't
+ make sense, or doesn't refer to an existing backend storage
+ object.
"""
def unmanage_snapshot(self, snapshot):
diff --git a/doc/source/devref/drivers.rst b/doc/source/devref/drivers.rst
index 8d548c3f1fc..d4698cbced1 100644
--- a/doc/source/devref/drivers.rst
+++ b/doc/source/devref/drivers.rst
@@ -28,9 +28,10 @@ There are some basic attributes that all drivers classes should have:
* VERSION: Driver version in string format. No naming convention is imposed,
although semantic versioning is recommended.
-* CI_WIKI_NAME: Must be the exact name of the ThirdPartySystems wiki page.
- This is used by our tooling system to associated jobs to drivers and
- track their CI reporting status correctly.
+* CI_WIKI_NAME: Must be the exact name of the `ThirdPartySystems wiki page
+ <https://wiki.openstack.org/wiki/ThirdPartySystems>`_. This is used by our
+ tooling system to associate jobs to drivers and track their CI reporting
+ status correctly.
The tooling system will also use the name and docstring of the driver class.
@@ -63,7 +64,6 @@ provided by a driver.
* driver_version
* free_capacity_gb
-* reserved_percentage
* storage_protocol
* total_capacity_gb
* vendor_name
@@ -71,8 +71,9 @@ provided by a driver.
**NOTE:** If the driver is unable to provide a value for free_capacity_gb or
total_capacity_gb, keywords can be provided instead. Please use 'unknown' if
-the array cannot report the value or 'infinite' if the array has no upper
-limit.
+the backend cannot report the value or 'infinite' if the backend has no upper
+limit. But, it is recommended to report real values as the Cinder scheduler
+assigns lowest weight to any storage backend reporting 'unknown' or 'infinite'.
Feature Enforcement
-------------------