From 80c25785e6436832dad19a362e1684ac2ee6bfa6 Mon Sep 17 00:00:00 2001 From: Vipin Balachandran 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 + `_. 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 -------------------