Cinder exposes an API to users to interact with different storage backend solutions. The following are standards across all drivers for Cinder services to properly interact with a driver.
There are some basic attributes that all drivers classes should have:
The tooling system will also use the name and docstring of the driver class.
Minimum features are enforced to avoid having a grid of what features are supported by which drivers and which releases. Cinder Core requires that all drivers implement the following minimum features.
Volume stats are used by the different schedulers for the drivers to provide a report on their current state of the backend. The following should be 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 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’.
All concrete driver implementations should use the cinder.interface.volumedriver decorator on the driver class:
@interface.volumedriver
class LVMVolumeDriver(driver.VolumeDriver):
This will register the driver and allow automated compliance tests to run against and verify the compliance of the driver against the required interface to support the Core Functionality listed above.
Running tox -e compliance will verify all registered drivers comply to this interface. This can be used during development to perform self checks along the way. Any missing method calls will be identified by the compliance tests.
The details for the required volume driver interfaces can be found in the cinder/interface/volume_*_driver.py source.
The LVM driver is our reference for all new driver implementations. The information below can provide additional documentation for the methods that volume drivers need to implement.
The methods documented below are the minimum required interface for a volume driver to support. All methods from this interface must be implemented in order to be an official Cinder volume driver.
Core backend volume driver interface.
All backend drivers should support this interface as a bare minimum.
Core backend driver required interface.
Lets the driver know Nova has attached the volume to an instance.
| Parameters: |
|
|---|
Validate there are no issues with the driver configuration.
Called after do_setup(). Driver initialization can occur there or in this call, but must be complete by the time this returns.
If this method raises an exception, the driver will be left in an “uninitialized” state by the volume manager, which means that it will not be sent requests for volume operations.
This method typically checks things like whether the configured credentials can be used to log in the storage backend, and whether any external dependencies are present and working.
| Raises: | VolumeBackendAPIException in case of setup error. |
|---|
Clone an image to a volume.
| Parameters: |
|
|---|---|
| Returns: | Model updates. |
Fetch the image from image_service and write it to the volume.
| Parameters: |
|
|---|---|
| Returns: | Model updates. |
Copy the volume to the specified image.
| Parameters: |
|
|---|---|
| Returns: | Model updates. |
Create a new volume on the backend.
This method is responsible only for storage allocation on the backend. It should not export a LUN or actually make this storage available for use, this is done in a later call.
# TODO(smcginnis) - Add example data structure of volume object. :param volume: Volume object containing specifics to create. :returns: (Optional) dict of database updates for the new volume. :raises: VolumeBackendAPIException if creation failed.
Delete a volume from the backend.
If the driver can talk to the backend and detects that the volume is no longer present, this call should succeed and allow Cinder to complete the process of deleting the volume.
| Parameters: | volume – The volume to delete. |
|---|---|
| Raises: | VolumeIsBusy if the volume is still attached or has snapshots. VolumeBackendAPIException on error. |
Detach volume from an instance.
| Parameters: |
|
|---|
Any initialization the volume driver needs to do while starting.
Called once by the manager after the driver is loaded. Can be used to set up clients, check licenses, set up protocol specific helpers, etc.
| Parameters: | context – The admin context. |
|---|
Extend the size of a volume.
| Parameters: |
|
|---|
Collects volume backend stats.
The get_volume_stats method is used by the volume manager to collect information from the driver instance related to information about the driver, available and used space, and driver/backend capabilities.
It returns a dict with the following required fields:
This is an identifier for the backend taken from cinder.conf. Useful when using multi-backend.
Vendor/author of the driver who serves as the contact for the driver’s development and support.
The driver version is logged at cinder-volume startup and is useful for tying volume service logs to a specific release of the code. There are currently no rules for how or when this is updated, but it tends to follow typical major.minor.revision ideas.
The protocol used to connect to the storage, this should be a short string such as: “iSCSI”, “FC”, “nfs”, “ceph”, etc.
The total capacity in gigabytes (GiB) of the storage backend being 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’.
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:
Percentage of backend capacity which is not used by the scheduler.
Driver-specific information used by the driver and storage backend to correlate Cinder volumes and backend LUNs/files.
Whether the backend supports quality of service.
The total provisioned capacity on the storage backend, in gigabytes (GiB), including space consumed by any user other than Cinder itself.
The maximum amount a backend can be over subscribed.
Whether the backend is capable of allocating thinly provisioned volumes.
Whether the backend is capable of allocating thick provisioned volumes. (Typically True.)
Total number of volumes on the storage backend. This can be used in custom driver filter functions.
A custom function used by the scheduler to determine whether a volume should be allocated to this backend or not. Example:
capabilities.total_volumes < 10
Similar to filter_function, but used to weigh multiple volume backends. Example:
capabilities.capacity_utilization < 0.6 ? 100 : 25
Whether the backend supports multiattach or not. Defaults to False.
Whether copies performed by the volume manager for operations such as migration should attempt to preserve sparseness.
The returned dict may also contain a list, “pools”, which has a similar dict for each pool being used with the backend.
| Parameters: | refresh – Whether to discard any cached values and force a full refresh of stats. |
|---|---|
| Returns: | dict of appropriate values (see above). |
Allow connection to connector and return connection info.
| Parameters: |
|
|---|---|
| Returns: | A dictionary of connection information. This can optionally include a “initiator_updates” field. |
The “initiator_updates” field must be a dictionary containing a “set_values” and/or “remove_values” field. The “set_values” field must be a dictionary of key-value pairs to be set/updated in the db. The “remove_values” field must be a list of keys, previously set with “set_values”, that will be deleted from the db.
May be called multiple times to get connection information after a volume has already been attached.
Remove access to a volume.
| Parameters: |
|
|---|
Another required interface for a volume driver to be fully compatible is the ability to create and manage snapshots. Due to legacy constraints, this interface is not included in the base driver interface above.
Work is being done to address those legacy issues. Once that is complete, this interface will be merged with the base driver interface.
Snapshot capable volume driver interface.
Interface for drivers that support snapshots.
TODO(smcginnis) Merge into VolumeDriverBase once NFS driver supports snapshots.
Creates a snapshot.
| Parameters: | snapshot – Information for the snapshot to be created. |
|---|
Creates a volume from a snapshot.
If volume_type extra specs includes ‘replication: <is> True’ the driver needs to create a volume replica (secondary), and setup replication between the newly created volume and the secondary volume.
An optional larger size for the new snapshot can be specified. Drivers should check this value and create or expand the new volume to match.
| Parameters: |
|
|---|---|
| Returns: | A dict of database updates for the new volume. |
Deletes a snapshot.
| Parameters: | snapshot – The snapshot to delete. |
|---|
An optional feature a volume backend can support is the ability to manage existing volumes or unmanage volumes - keep the volume on the storage backend but no longer manage it through Cinder.
To support this functionality, volume drivers must implement these methods:
Manage/unmanage existing volume driver interface.
Interface for drivers that support managing existing volumes.
Brings an existing backend storage object under Cinder management.
existing_ref is passed straight through from the API request’s manage_existing_ref value, and it is up to the driver how this should be interpreted. It should be sufficient to identify a storage object that the driver should somehow associate with the newly-created cinder volume structure.
There are two ways to do this:
If the existing_ref doesn’t make sense, or doesn’t refer to an existing backend storage object, raise a ManageExistingInvalidReference exception.
The volume may have a volume_type, and the driver can inspect that and compare against the properties of the referenced backend storage object. If they are incompatible, raise a ManageExistingVolumeTypeMismatch, specifying a reason for the failure.
| Parameters: |
|
|---|---|
| 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. |
Return size of volume to be managed by manage_existing.
When calculating the size, round up to the next GB.
| Parameters: |
|
|---|---|
| Raises: | ManageExistingInvalidReference If the existing_ref doesn’t make sense, or doesn’t refer to an existing backend storage object. |
Removes the specified volume from Cinder management.
Does not delete the underlying backend storage object.
For most drivers, this will not need to do anything. However, some drivers might use this call as an opportunity to clean up any Cinder-specific configuration that they have associated with the backend storage object.
| Parameters: | volume – Cinder volume to unmanage |
|---|
In addition to the ability to manage and unmanage volumes, Cinder backend drivers may also support managing and unmanaging volume snapshots. These additional methods must be implemented to support these operations.
Manage/unmanage existing volume snapshots driver interface.
Interface for drivers that support managing existing snapshots.
Brings an existing backend storage object under Cinder management.
existing_ref is passed straight through from the API request’s manage_existing_ref value, and it is up to the driver how this should be interpreted. It should be sufficient to identify a storage object that the driver should somehow associate with the newly-created cinder snapshot structure.
There are two ways to do this:
| Parameters: |
|
|---|---|
| Raises: | ManageExistingInvalidReference If the existing_ref doesn’t make sense, or doesn’t refer to an existing backend storage object. |
Return size of snapshot to be managed by manage_existing.
When calculating the size, round up to the next GB.
| Parameters: |
|
|---|---|
| Raises: | ManageExistingInvalidReference If the existing_ref doesn’t make sense, or doesn’t refer to an existing backend storage object. |
Removes the specified snapshot from Cinder management.
Does not delete the underlying backend storage object.
For most drivers, this will not need to do anything. However, some drivers might use this call as an opportunity to clean up any Cinder-specific configuration that they have associated with the backend storage object.
| Parameters: | snapshot – The snapshot to unmanage. |
|---|
Some storage backends support the ability to group volumes and create write consistent snapshots across the group. In order to support these operations, the following interface must be implemented by the driver.
Consistency group volume driver interface.
Interface for drivers that support consistency groups.
Creates a cgsnapshot.
| Parameters: |
|
|---|---|
| Returns: | model_update, snapshots_model_update |
param snapshots is retrieved directly from the db. It is a list of cinder.db.sqlalchemy.models.Snapshot to be precise. It cannot be assigned to snapshots_model_update. snapshots_model_update is a list of dictionaries. It has to be built by the driver. An entry will be in this format: {‘id’: xxx, ‘status’: xxx, ......}. model_update will be in this format: {‘status’: xxx, ......}.
The driver should populate snapshots_model_update and model_update and return them.
The manager will check snapshots_model_update and update db accordingly for each snapshot. If the driver successfully deleted some snapshots but failed to delete others, it should set statuses of the snapshots accordingly so that the manager can update db correctly.
If the status in any entry of snapshots_model_update is ‘error’, the status in model_update will be set to the same if it is not already ‘error’.
If the status in model_update is ‘error’, the manager will raise an exception and the status of cgsnapshot will be set to ‘error’ in the db. If snapshots_model_update is not returned by the driver, the manager will set the status of every snapshot to ‘error’ in the except block.
If the driver raises an exception during the operation, it will be caught by the try-except block in the manager and the statuses of cgsnapshot and all snapshots will be set to ‘error’.
For a successful operation, the driver can either build the model_update and snapshots_model_update and return them or return None, None. The statuses of cgsnapshot and all snapshots will be set to ‘available’ at the end of the manager function.
Creates a consistencygroup.
| Parameters: |
|
|---|---|
| Returns: | model_update |
model_update will be in this format: {‘status’: xxx, ......}.
If the status in model_update is ‘error’, the manager will throw an exception and it will be caught in the try-except block in the manager. If the driver throws an exception, the manager will also catch it in the try-except block. The group status in the db will be changed to ‘error’.
For a successful operation, the driver can either build the model_update and return it or return None. The group status will be set to ‘available’.
Creates a consistencygroup from source.
| Parameters: |
|
|---|---|
| Returns: | model_update, volumes_model_update |
The source can be cgsnapshot or a source cg.
param volumes is retrieved directly from the db. It is a list of cinder.db.sqlalchemy.models.Volume to be precise. It cannot be assigned to volumes_model_update. volumes_model_update is a list of dictionaries. It has to be built by the driver. An entry will be in this format: {‘id’: xxx, ‘status’: xxx, ......}. model_update will be in this format: {‘status’: xxx, ......}.
To be consistent with other volume operations, the manager will assume the operation is successful if no exception is thrown by the driver. For a successful operation, the driver can either build the model_update and volumes_model_update and return them or return None, None.
Deletes a cgsnapshot.
| Parameters: |
|
|---|---|
| Returns: | model_update, snapshots_model_update |
param snapshots is retrieved directly from the db. It is a list of cinder.db.sqlalchemy.models.Snapshot to be precise. It cannot be assigned to snapshots_model_update. snapshots_model_update is a list of dictionaries. It has to be built by the driver. An entry will be in this format: {‘id’: xxx, ‘status’: xxx, ......}. model_update will be in this format: {‘status’: xxx, ......}.
The driver should populate snapshots_model_update and model_update and return them.
The manager will check snapshots_model_update and update db accordingly for each snapshot. If the driver successfully deleted some snapshots but failed to delete others, it should set statuses of the snapshots accordingly so that the manager can update db correctly.
If the status in any entry of snapshots_model_update is ‘error_deleting’ or ‘error’, the status in model_update will be set to the same if it is not already ‘error_deleting’ or ‘error’.
If the status in model_update is ‘error_deleting’ or ‘error’, the manager will raise an exception and the status of cgsnapshot will be set to ‘error’ in the db. If snapshots_model_update is not returned by the driver, the manager will set the status of every snapshot to ‘error’ in the except block.
If the driver raises an exception during the operation, it will be caught by the try-except block in the manager and the statuses of cgsnapshot and all snapshots will be set to ‘error’.
For a successful operation, the driver can either build the model_update and snapshots_model_update and return them or return None, None. The statuses of cgsnapshot and all snapshots will be set to ‘deleted’ after the manager deletes them from db.
Deletes a consistency group.
| Parameters: |
|
|---|---|
| Returns: | model_update, volumes_model_update |
param volumes is retrieved directly from the db. It is a list of cinder.db.sqlalchemy.models.Volume to be precise. It cannot be assigned to volumes_model_update. volumes_model_update is a list of dictionaries. It has to be built by the driver. An entry will be in this format: {‘id’: xxx, ‘status’: xxx, ......}. model_update will be in this format: {‘status’: xxx, ......}.
The driver should populate volumes_model_update and model_update and return them.
The manager will check volumes_model_update and update db accordingly for each volume. If the driver successfully deleted some volumes but failed to delete others, it should set statuses of the volumes accordingly so that the manager can update db correctly.
If the status in any entry of volumes_model_update is ‘error_deleting’ or ‘error’, the status in model_update will be set to the same if it is not already ‘error_deleting’ or ‘error’.
If the status in model_update is ‘error_deleting’ or ‘error’, the manager will raise an exception and the status of the group will be set to ‘error’ in the db. If volumes_model_update is not returned by the driver, the manager will set the status of every volume in the group to ‘error’ in the except block.
If the driver raises an exception during the operation, it will be caught by the try-except block in the manager. The statuses of the group and all volumes in it will be set to ‘error’.
For a successful operation, the driver can either build the model_update and volumes_model_update and return them or return None, None. The statuses of the group and all volumes will be set to ‘deleted’ after the manager deletes them from db.
Updates a consistency group.
| Parameters: |
|
|---|---|
| Returns: | model_update, add_volumes_update, remove_volumes_update |
model_update is a dictionary that the driver wants the manager to update upon a successful return. If None is returned, the manager will set the status to ‘available’.
add_volumes_update and remove_volumes_update are lists of dictionaries that the driver wants the manager to update upon a successful return. Note that each entry requires a {‘id’: xxx} so that the correct volume entry can be updated. If None is returned, the volume will remain its original status. Also note that you cannot directly assign add_volumes to add_volumes_update as add_volumes is a list of cinder.db.sqlalchemy.models.Volume objects and cannot be used for db update directly. Same with remove_volumes.
If the driver throws an exception, the status of the group as well as those of the volumes to be added/removed will be set to ‘error’.