Drivers for volumes.
Bases: object
Executes commands relating to Volumes.
Base Driver for Cinder Volume Control Path, This includes supported/required implementation for API calls. Also provides generic implementation of core features like cloning, copy_image_to_volume etc, this way drivers that inherit from this base class and don’t offer their own impl can fall back on a general solution here.
Key thing to keep in mind with this driver is that it’s intended that these drivers ONLY implement Control Path details (create, delete, extend...), while transport or data path related implementation should be a member object that we call a connector. The point here is that for example don’t allow the LVM driver to implement iSCSI methods, instead call whatever connector it has configured via conf file (iSCSI{LIO, TGT, IET}, FC, etc).
In the base class and for example the LVM driver we do this via a has-a relationship and just provide an interface to the specific connector methods. How you do this in your own driver is of course up to you.
Driver-specific actions after copyvolume data.
This method will be called after _copy_volume_data during volume migration
Callback for volume attached to instance or host.
Create a new backup from an existing volume.
Driver-specific actions before copyvolume data.
This method will be called before _copy_volume_data during volume migration
Clean up after an interrupted image copy.
Fetch the image from image_service and write it to the volume.
Copy the volume to the specified image.
Creates a clone of the specified volume.
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.
Exports the volume.
Can optionally return a Dictionary of changes to the volume object to be persisted.
Exports the snapshot.
Can optionally return a Dictionary of changes to the snapshot object to be persisted.
Creates a volume.
Can optionally return a Dictionary of changes to the volume object to be persisted.
If volume_type extra specs includes ‘capabilities:replication <is> True’ the driver needs to create a volume replica (secondary), and setup replication between the newly created volume and the secondary volume. Returned dictionary should include:
volume[‘replication_status’] = ‘copying’ volume[‘replication_extended_status’] = driver specific value volume[‘driver_data’] = driver specific value
Deletes a volume.
If volume_type extra specs includes ‘replication: <is> True’ then the driver needs to delete the volume replica too.
Callback for volume detached.
Any initialization the volume driver does while starting.
Synchronously recreates an export for a volume.
Failover a backend to a secondary replication target.
Instructs a replication capable/configured backend to failover to one of it’s secondary replication targets. host=None is an acceptable input, and leaves it to the driver to failover to the only configured target, or to choose a target on it’s own. All of the hosts volumes will be passed on to the driver in order for it to determine the replicated volumes on the host, if needed.
Response is a tuple, including the new target backend_id AND a lit of dictionaries with volume_id and updates. *Key things to consider (attaching failed-over volumes):
provider_location provider_auth provider_id replication_status
| Parameters: |
|
|---|
Notify the backend that it’s frozen.
We use set to prohibit the creation of any new resources on the backend, or any modifications to existing items on a backend. We set/enforce this by not allowing scheduling of new volumes to the specified backend, and checking at the api for modifications to resources and failing.
In most cases the driver may not need to do anything, but this provides a handle if they need it.
| Parameters: | context – security context |
|---|---|
| Response: | True|False |
Get a backup device from an existing volume.
The function returns a volume or snapshot to backup service, and then backup service attaches the device and does backup.
Get the default filter_function string.
Each driver could overwrite the method to return a well-known default string if it is available.
| Returns: | None |
|---|
Get the default goodness_function string.
Each driver could overwrite the method to return a well-known default string if it is available.
| Returns: | None |
|---|
Get filter_function string.
Returns either the string from the driver instance or global section in cinder.conf. If nothing is specified in cinder.conf, then try to find the default filter_function. When None is returned the scheduler will always pass the driver instance.
| Returns: | a filter_function string or None |
|---|
Get good_function string.
Returns either the string from the driver instance or global section in cinder.conf. If nothing is specified in cinder.conf, then try to find the default goodness_function. When None is returned the scheduler will give the lowest score to the driver instance.
| Returns: | a goodness_function string or None |
|---|
Return pool name where volume reside on.
| Parameters: | volume – The volume hosted by the the driver. |
|---|---|
| Returns: | name of the pool where given volume is in. |
Return prefixed property name
| Returns: | a prefixed property name string or None |
|---|
Old replication update method, deprecate.
Get the current version of this driver.
Return the current state of the volume service.
If ‘refresh’ is True, run the update first.
For replication the following state should be reported: replication = True (None or false disables replication)
Obtain backend volume stats and capabilities list.
This stores a dictionary which is consisted of two parts. First part includes static backend capabilities which are obtained by get_volume_stats(). Second part is properties, which includes parameters correspond to extra specs. This properties part is consisted of cinder standard capabilities and vendor unique properties.
Using this capabilities list, operator can manage/configure backend using key/value from capabilities without specific knowledge of backend.
Allow connection to connector and return connection info.
| Parameters: |
|
|---|
connected to. :param initiator_data (optional): A dictionary of driver_initiator_data objects with key-value pairs that have been saved for this initiator by a driver in previous initialize_connection calls. :returns conn_info: 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.
Allow connection to connector and return connection info.
| Parameters: |
|
|---|
connected to. :returns conn_info: 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.
Manage exiting stub.
This is for drivers that don’t implement manage_existing().
Migrate volume stub.
This is for drivers that don’t implement an enhanced version of this operation.
Removes an export for a volume.
Removes an export for a snapshot.
Restore an existing backup to a new or existing volume.
Determine if driver is running in Secure File Operations mode.
The Cinder Volume driver needs to query if this driver is running in a secure file operations mode. By default, it is False: any driver that does support secure file operations should override this method.
Disallow connection from connector.
Disallow connection from connector.
Notify the backend that it’s unfrozen/thawed.
Returns the backend to a normal state after a freeze operation.
In most cases the driver may not need to do anything, but this provides a handle if they need it.
| Parameters: | context – security context |
|---|---|
| Response: | True|False |
Unmanage stub.
This is for drivers that don’t implement unmanage().
Return model update for migrated volume.
Each driver implementing this method needs to be responsible for the values of _name_id and provider_location. If None is returned or either key is not set, it means the volume table does not need to change the value(s) for the key(s). The return format is {“_name_id”: value, “provider_location”: value}.
| Parameters: |
|
|---|---|
| Returns: | model_update to update DB with any needed changes |
Get provider info updates from driver.
| Parameters: |
|
|---|---|
| Returns: | tuple (volume_updates, snapshot_updates) |
where volume updates {‘id’: uuid, provider_id: <provider-id>} and snapshot updates {‘id’: uuid, provider_id: <provider-id>}
Fail if connector doesn’t contain all the data needed by driver.
Bases: object
Create a volume efficiently from an existing image.
image_location is a string whose format depends on the image service backend in use. The driver should use it to determine whether cloning is possible.
image_id is a string which represents id of the image. It can be used by the driver to introspect internal stores or registry to do an efficient image clone.
image_meta is a dictionary that includes ‘disk_format’ (e.g. raw, qcow2) and other image attributes that allow drivers to decide whether they can clone the image without first requiring conversion.
image_service is the reference of the image_service to use. Note that this is needed to be passed here for drivers that will want to fetch images from the image service directly.
Returns a dict of volume properties eg. provider_location, boolean indicating whether cloning occurred
Bases: object
Creates a cgsnapshot.
Creates a consistencygroup.
Deletes a cgsnapshot.
Deletes a consistency group.
Bases: cinder.volume.driver.ISCSIDriver
Logs calls instead of executing.
No setup necessary in fake mode.
Creates a clone of the specified volume.
Exports the volume.
Can optionally return a Dictionary of changes to the volume object to be persisted.
Exports the snapshot.
Can optionally return a Dictionary of changes to the snapshot object to be persisted.
Creates a snapshot.
Creates a volume from a snapshot.
Deletes a snapshot.
Deletes a volume.
Synchronously recreates an export for a volume.
Execute that simply logs the command.
Removes an export for a volume.
Removes an export for a snapshot.
Bases: cinder.volume.driver.FakeISCSIDriver
Logs calls instead of executing.
Execute that simply logs the command.
Bases: cinder.volume.driver.VolumeDriver
Executes commands relating to Fibre Channel volumes.
Get volume stats.
If ‘refresh’ is True, run update the stats first.
Initializes the connection and returns connection info.
The driver returns a driver_volume_type of ‘fibre_channel’. The target_wwn can be a single entry or a list of wwns that correspond to the list of remote wwn(s) that will export the volume. Example return values:
- {
‘driver_volume_type’: ‘fibre_channel’ ‘data’: {
‘target_discovered’: True, ‘target_lun’: 1, ‘target_wwn’: ‘1234567890123’, ‘discard’: False,}
}
or
- {
‘driver_volume_type’: ‘fibre_channel’ ‘data’: {
‘target_discovered’: True, ‘target_lun’: 1, ‘target_wwn’: [‘1234567890123’, ‘0987654321321’], ‘discard’: False,}
}
Fail if connector doesn’t contain all the data needed by driver.
Do a check on the connector and ensure that it has wwnns, wwpns.
Test for non-empty setting in connector.
Bases: cinder.volume.driver.VolumeDriver
Executes commands relating to ISCSI volumes.
We make use of model provider properties as follows:
Get volume stats.
If ‘refresh’ is True, run update the stats first.
Initializes the connection and returns connection info.
The iscsi driver returns a driver_volume_type of ‘iscsi’. The format of the driver data is defined in _get_iscsi_properties. Example return value:
{
'driver_volume_type': 'iscsi'
'data': {
'target_discovered': True,
'target_iqn': 'iqn.2010-10.org.openstack:volume-00000001',
'target_portal': '127.0.0.0.1:3260',
'volume_id': 1,
'discard': False,
}
}
If the backend driver supports multiple connections for multipath and for single path with failover, “target_portals”, “target_iqns”, “target_luns” are also populated:
{
'driver_volume_type': 'iscsi'
'data': {
'target_discovered': False,
'target_iqn': 'iqn.2010-10.org.openstack:volume1',
'target_iqns': ['iqn.2010-10.org.openstack:volume1',
'iqn.2010-10.org.openstack:volume1-2'],
'target_portal': '10.0.0.1:3260',
'target_portals': ['10.0.0.1:3260', '10.0.1.1:3260']
'target_lun': 1,
'target_luns': [1, 1],
'volume_id': 1,
'discard': False,
}
}
Bases: cinder.volume.driver.ISCSIDriver
Executes commands relating to ISER volumes.
We make use of model provider properties as follows:
Initializes the connection and returns connection info.
The iser driver returns a driver_volume_type of ‘iser’. The format of the driver data is defined in _get_iser_properties. Example return value:
{
'driver_volume_type': 'iser'
'data': {
'target_discovered': True,
'target_iqn':
'iqn.2010-10.org.iser.openstack:volume-00000001',
'target_portal': '127.0.0.0.1:3260',
'volume_id': 1,
}
}
Bases: object
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:
If the existing_ref doesn’t make sense, or doesn’t refer to an existing backend storage object, raise a ManageExistingInvalidReference exception.
Return size of snapshot to be managed by manage_existing.
When calculating the size, round up to the next GB.
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.
Bases: object
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: |
|
|---|
volume
Return size of volume to be managed by manage_existing.
When calculating the size, round up to the next GB.
| Parameters: |
|
|---|
volume
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 |
|---|
Bases: object
Migrate the volume to the specified host.
Returns a boolean indicating whether the migration occurred, as well as model_update.
| Parameters: |
|
|---|
Bases: object
Proxy Volume Driver to mark proxy drivers
If a driver uses a proxy class (e.g. by using __setattr__ and __getattr__) without directly inheriting from base volume driver this class can help marking them and retrieve the actual used driver object.
Bases: object
Creates a test replica clone of the specified replicated volume.
Create a clone of the replicated (secondary) volume.
Query the actual volume replication status from the driver.
Returns model_update for the volume. The driver is expected to update the following entries:
‘replication_status’ ‘replication_extended_status’ ‘replication_driver_data’
Possible ‘replication_status’ values (in model_update) are: ‘error’ - replication in error state ‘copying’ - replication copying data to secondary (inconsistent) ‘active’ - replication copying data to secondary (consistent) ‘active-stopped’ - replication data copy on hold (consistent) ‘inactive’ - replication data copy on hold (inconsistent) Values in ‘replication_extended_status’ and ‘replication_driver_data’ are managed by the driver.
| Parameters: |
|
|---|
Promote the replica to be the primary volume.
Following this command, replication between the volumes at the storage level should be stopped, the replica should be available to be attached, and the replication status should be in status ‘inactive’.
Returns model_update for the volume. The driver is expected to update the following entries:
‘replication_status’ ‘replication_extended_status’ ‘replication_driver_data’
Possible ‘replication_status’ values (in model_update) are: ‘error’ - replication in error state ‘inactive’ - replication data copy on hold (inconsistent) Values in ‘replication_extended_status’ and ‘replication_driver_data’ are managed by the driver.
| Parameters: |
|
|---|
Re-enable replication between the replica and primary volume.
This is used to re-enable/fix the replication between primary and secondary. One use is as part of the fail-back process, when you re-synchorize your old primary with the promoted volume (the old replica). Returns model_update for the volume to reflect the actions of the driver. The driver is expected to update the following entries:
‘replication_status’ ‘replication_extended_status’ ‘replication_driver_data’
Possible ‘replication_status’ values (in model_update) are: ‘error’ - replication in error state ‘copying’ - replication copying data to secondary (inconsistent) ‘active’ - replication copying data to secondary (consistent) ‘active-stopped’ - replication data copy on hold (consistent) ‘inactive’ - replication data copy on hold (inconsistent) Values in ‘replication_extended_status’ and ‘replication_driver_data’ are managed by the driver.
| Parameters: |
|
|---|
Bases: object
Creates a snapshot.
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.
Deletes a snapshot.
Bases: object
Accept the transfer of a volume for a new user/project.
Bases: cinder.volume.driver.ConsistencyGroupVD, cinder.volume.driver.TransferVD, cinder.volume.driver.ManageableVD, cinder.volume.driver.ExtendVD, cinder.volume.driver.CloneableImageVD, cinder.volume.driver.ManageableSnapshotsVD, cinder.volume.driver.SnapshotVD, cinder.volume.driver.ReplicaVD, cinder.volume.driver.LocalVD, cinder.volume.driver.MigrateVD, cinder.volume.driver.BaseVD
This class will be deprecated soon.
Please use the abstract classes above for new drivers.
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.
Return pool name where volume reside on.
| Parameters: | volume – The volume hosted by the the driver. |
|---|---|
| Returns: | name of the pool where given volume is in. |
Allow connection from connector for a snapshot.
Disallow connection from connector
Disallow connection from connector for a snapshot.
Unmanage the specified snapshot from Cinder management.
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’.