OpenStack Docs: cinder.volume.driver module

class BaseVD(execute=<function execute>, *args, **kwargs)¶

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, ET}, 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.

REPLICATION_FEATURE_CHECKERS = {'a/a': 'failover_completed', 'v2.1': 'failover_host'}¶

SUPPORTED = True¶

SUPPORTS_ACTIVE_ACTIVE = False¶

VERSION = 'N/A'¶

accept_transfer(context, volume, new_user, new_project)¶

after_volume_copy(context, src_vol, dest_vol, remote=None)¶

Driver-specific actions after copyvolume data.

This method will be called after _copy_volume_data during volume migration

backup_use_temp_snapshot()¶

Get the configured setting for backup from snapshot.

If an inheriting driver does not support this operation, the driver should override this method to return false and log a warning letting the administrator know they have configured something that cannot be done.

before_volume_copy(context, src_vol, dest_vol, remote=None)¶

Driver-specific actions before copyvolume data.

This method will be called before _copy_volume_data during volume migration

abstract check_for_setup_error()¶

classmethod clean_snapshot_file_locks(snapshot_id)¶

Clean up driver specific snapshot locks.

This method will be called when a snapshot has been removed from cinder or when we detect that the snapshot doesn’t exist.

There are 3 types of locks in Cinder:

Process locks: Don’t need cleanup
Node locks: Must use cinder.utils.synchronized_remove
Global locks: Must use cinder.coordination.synchronized_remove

When using method cinder.utils.synchronized_remove we must pass the exact lock name, whereas method cinder.coordination.synchronized_remove accepts a glob.

Refer to clean_volume_file_locks, api_clean_volume_file_locks, and clean_snapshot_file_locks in cinder.utils for examples.

classmethod clean_volume_file_locks(volume_id)¶

Clean up driver specific volume locks.

This method will be called when a volume has been removed from Cinder or when we detect that the volume doesn’t exist.

There are 3 types of locks in Cinder:

Process locks: Don’t need cleanup
Node locks: Must use cinder.utils.synchronized_remove
Global locks: Must use cinder.coordination.synchronized_remove

When using method cinder.utils.synchronized_remove we must pass the exact lock name, whereas method cinder.coordination.synchronized_remove accepts a glob.

Refer to clean_volume_file_locks, api_clean_volume_file_locks, and clean_snapshot_file_locks in cinder.utils for examples.

clear_download(context, volume)¶: Clean up after an interrupted image copy.

clone_image(context, volume, image_location, image_meta, image_service)¶

Create a volume efficiently from an existing image.

Refer to cinder.interface.volume_driver.VolumeDriverCore.clone_image for additional information.

copy_image_to_encrypted_volume(context, volume, image_service, image_id)¶

Fetch image from image_service and write to encrypted volume.

This attaches the encryptor layer when connecting to the volume.

copy_image_to_volume(context, volume, image_service, image_id)¶

Fetch image from image_service and write to unencrypted volume.

This does not attach an encryptor layer when connecting to the volume.

copy_volume_to_image(context, volume, image_service, image_meta)¶: Copy the volume to the specified image.

create_cloned_volume(volume, src_vref)¶

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.

abstract create_export(context, volume, connector)¶

Exports the volume.

Can optionally return a Dictionary of changes to the volume object to be persisted.

create_export_snapshot(context, snapshot, connector)¶

Exports the snapshot.

Can optionally return a Dictionary of changes to the snapshot object to be persisted.

create_group(context, group)¶

Creates a group.

Parameters:

context – the context of the caller.
group – the Group object of the group to be created.

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’.

create_group_from_src(context, group, volumes, group_snapshot=None, snapshots=None, source_group=None, source_vols=None)¶

Creates a group from source.

Parameters:

context – the context of the caller.
group – the Group object to be created.
volumes – a list of Volume objects in the group.
group_snapshot – the GroupSnapshot object as source.
snapshots – a list of Snapshot objects in group_snapshot.
source_group – the Group object as source.
source_vols – a list of Volume objects in the source_group.

Returns:

model_update, volumes_model_update

The source can be group_snapshot or a source_group.

param volumes is a list of objects retrieved from the db. 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.

create_group_snapshot(context, group_snapshot, snapshots)¶

Creates a group_snapshot.

Parameters:

context – the context of the caller.
group_snapshot – the GroupSnapshot object to be created.
snapshots – a list of Snapshot objects in the group_snapshot.

Returns:

model_update, snapshots_model_update

param snapshots is a list of Snapshot objects. 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 group_snapshot 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 group_snapshot 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 group_snapshot and all snapshots will be set to ‘available’ at the end of the manager function.

abstract create_volume(volume)¶

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>

create_volume_from_backup(volume, backup)¶

Creates a volume from a backup.

Can optionally return a Dictionary of changes to the volume object to be persisted.

Parameters:

volume – the volume object to be created.
backup – the backup object as source.

Returns:

volume_model_update

delete_group(context, group, volumes)¶

Deletes a group.

Parameters:

context – the context of the caller.
group – the Group object of the group to be deleted.
volumes – a list of Volume objects in the group.

Returns:

model_update, volumes_model_update

param volumes is a list of objects retrieved from the db. 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.

delete_group_snapshot(context, group_snapshot, snapshots)¶

Deletes a group_snapshot.

Parameters:

context – the context of the caller.
group_snapshot – the GroupSnapshot object to be deleted.
snapshots – a list of Snapshot objects in the group_snapshot.

Returns:

model_update, snapshots_model_update

param snapshots is a list of objects. It cannot be assigned to snapshots_model_update. snapshots_model_update is a list of 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 group_snapshot 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 group_snapshot 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 group_snapshot and all snapshots will be set to ‘deleted’ after the manager deletes them from db.

abstract delete_volume(volume)¶

Deletes a volume.

If volume_type extra specs includes ‘replication: <is> True’ then the driver needs to delete the volume replica too.

It is imperative that this operation ensures that the data from the deleted volume cannot leak into new volumes when they are created, as new volumes are likely to belong to a different tenant/project.

If the driver uses custom file locks they should be cleaned on success using cinder.utils.synchronized_remove

disable_replication(context, group, volumes)¶

Disables replication for a group and volumes in the group.

Parameters:

group – group object
volumes – list of volume objects in the group

Returns:

model_update - dict of group updates

Returns:

volume_model_updates - list of dicts of volume updates

do_setup(context)¶: Any initialization the volume driver does while starting.

enable_replication(context, group, volumes)¶

Enables replication for a group and volumes in the group.

Parameters:

group – group object
volumes – list of volume objects in the group

Returns:

model_update - dict of group updates

Returns:

volume_model_updates - list of dicts of volume updates

abstract ensure_export(context, volume)¶: Synchronously recreates an export for a volume.

extend_volume(volume, new_size)¶

failover(context, volumes, secondary_id=None, groups=None)¶

Like failover but for a host that is clustered.

Most of the time this will be the exact same behavior as failover_host, so if it’s not overwritten, it is assumed to be the case.

failover_completed(context, active_backend_id=None)¶: This method is called after failover for clustered backends.

failover_host(context, volumes, secondary_id=None, groups=None)¶

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:

context – security context
volumes – list of volume objects, in case the driver needs to take action on them in some way
secondary_id – Specifies rep target backend to fail over to
groups – replication groups

Returns:

ID of the backend that was failed-over to, model update for volumes, and model update for groups

failover_replication(context, group, volumes, secondary_backend_id=None)¶

Fails over replication for a group and volumes in the group.

Parameters:

group – group object
volumes – list of volume objects in the group
secondary_backend_id – backend_id of the secondary site

Returns:

model_update - dict of group updates

Returns:

volume_model_updates - list of dicts of volume updates

freeze_backend(context)¶

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_backup_device(context, backup)¶

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_default_filter_function()¶

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_default_goodness_function()¶

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

static get_driver_options()¶: Return the oslo_config options specific to the driver.

get_filter_function()¶

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_goodness_function()¶

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

get_pool(volume)¶

Return pool name where volume reside on.

Parameters:: volume – The volume hosted by the driver.
Returns:: name of the pool where given volume is in.

get_replication_error_status(context, groups)¶

Returns error info for replicated groups and its volumes.

Returns:: group_model_updates - list of dicts of group updates

if error happens. For example, a dict of a group can be as follows:

{'group_id': xxxx,
 'replication_status': fields.ReplicationStatus.ERROR}

Returns:: volume_model_updates - list of dicts of volume updates

if error happens. For example, a dict of a volume can be as follows:

{'volume_id': xxxx,
 'replication_status': fields.ReplicationStatus.ERROR}

get_version()¶: Get the current version of this driver.

get_volume_stats(refresh=False)¶

Get volume stats.

If ‘refresh’ is True, run update the stats first.

init_capabilities()¶

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.

abstract initialize_connection(volume, connector)¶

Allow connection to connector and return connection info.

..note::: Whether or not a volume is ‘cacheable’ for volume local cache on the hypervisor is normally configured in the volume-type extra-specs. Support may be disabled at the driver level, however, by returning “cacheable”: False in the conn_info. This will override any setting in the volume-type extra-specs.

Parameters:

volume – The volume to be attached
connector – Dictionary containing information about what is being connected to.

Returns conn_info:

A dictionary of connection information.

initialize_connection_snapshot(snapshot, connector, **kwargs)¶

Allow connection to connector and return connection info.

Parameters:

snapshot – The snapshot to be attached
connector – Dictionary containing information about what is being 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.

property initialized¶

manage_existing(volume, existing_ref)¶

Manage exiting stub.

This is for drivers that don’t implement manage_existing().

migrate_volume(context, volume, host)¶

Migrate volume stub.

This is for drivers that don’t implement an enhanced version of this operation.

abstract remove_export(context, volume)¶: Removes an export for a volume.

remove_export_snapshot(context, snapshot)¶: Removes an export for a snapshot.

retype(context, volume, new_type, diff, host)¶

secure_file_operations_enabled()¶

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.

set_initialized()¶

set_throttle()¶

snapshot_revert_use_temp_snapshot()¶

property supported¶

classmethod supports_replication_feature(feature)¶

Check if driver class supports replication features.

Feature is a string that must be one of:

v2.1
a/a

abstract terminate_connection(volume, connector, **kwargs)¶

Disallow connection from connector.

Parameters:

volume – The volume to be disconnected.
connector – A dictionary describing the connection with details about the initiator. Can be None.

terminate_connection_snapshot(snapshot, connector, **kwargs)¶: Disallow connection from connector.

thaw_backend(context)¶

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(volume)¶

Unmanage stub.

This is for drivers that don’t implement unmanage().

update_group(context, group, add_volumes=None, remove_volumes=None)¶

Updates a group.

Parameters:

context – the context of the caller.
group – the Group object of the group to be updated.
add_volumes – a list of Volume objects to be added.
remove_volumes – a list of Volume objects to be removed.

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 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’.

update_migrated_volume(ctxt, volume, new_volume, original_volume_status)¶

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:

volume – The original volume that was migrated to this backend
new_volume – The migration volume object that was created on this backend as part of the migration process
original_volume_status – The status of the original volume

Returns:

model_update to update DB with any needed changes

update_provider_info(volumes, snapshots)¶

Get provider info updates from driver.

Parameters:

volumes – List of Cinder volumes to check for updates
snapshots – List of Cinder snapshots to check for updates

Returns:

tuple (volume_updates, snapshot_updates)

where volume updates {‘id’: uuid, provider_id: <provider-id>} and snapshot updates {‘id’: uuid, provider_id: <provider-id>}

validate_connector(connector)¶: Fail if connector doesn’t contain all the data needed by driver.

static validate_connector_has_setting(connector, setting)¶

class CloneableImageVD¶

Bases: object

abstract clone_image(context, volume, image_location, image_meta, image_service)¶

Create a volume efficiently from an existing image.

Refer to cinder.interface.volume_driver.VolumeDriverCore.clone_image for additional information.

class FibreChannelDriver(*args, **kwargs)¶

Bases: VolumeDriver

Executes commands relating to Fibre Channel volumes.

initialize_connection(volume, connector)¶

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,
    }
}

validate_connector(connector)¶

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.

static validate_connector_has_setting(connector, setting)¶: Test for non-empty setting in connector.

class ISCSIDriver(*args, **kwargs)¶

Bases: VolumeDriver

Executes commands relating to ISCSI volumes.

We make use of model provider properties as follows:

provider_location: if present, contains the iSCSI target information in the same format as an ietadm discovery i.e. ‘<ip>:<port>,<portal> <target IQN>’
provider_auth: if present, contains a space-separated triple: ‘<auth method> <auth username> <auth password>’. CHAP is the only auth_method in use at the moment.

initialize_connection(volume, connector)¶

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,
    }
}

terminate_connection(volume, connector, **kwargs)¶

Disallow connection from connector

Parameters:

volume – The volume to be disconnected.
connector – A dictionary describing the connection with details about the initiator. Can be None.

validate_connector(connector)¶: Fail if connector doesn’t contain all the data needed by driver.

class ISERDriver(*args, **kwargs)¶

Bases: ISCSIDriver

Executes commands relating to ISER volumes.

We make use of model provider properties as follows:

provider_location: if present, contains the iSER target information in the same format as an ietadm discovery i.e. ‘<ip>:<port>,<portal> <target IQN>’
provider_auth: if present, contains a space-separated triple: ‘<auth method> <auth username> <auth password>’. CHAP is the only auth_method in use at the moment.

initialize_connection(volume, connector)¶

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,
    }
}

class ManageableSnapshotsVD¶

Bases: object

get_manageable_snapshots(cinder_snapshots, marker, limit, offset, sort_keys, sort_dirs)¶

List snapshots on the backend available for management by Cinder.

Returns a list of dictionaries, each specifying a snapshot in the host, with the following keys: - reference (dictionary): The reference for a snapshot, which can be passed to “manage_existing_snapshot”. - size (int): The size of the snapshot according to the storage backend, rounded up to the nearest GB. - safe_to_manage (boolean): Whether or not this snapshot is safe to manage according to the storage backend. For example, is the snapshot in use or invalid for any reason. - reason_not_safe (string): If safe_to_manage is False, the reason why. - cinder_id (string): If already managed, provide the Cinder ID. - extra_info (string): Any extra information to return to the user - source_reference (string): Similar to “reference”, but for the snapshot’s source volume.

Parameters:

cinder_snapshots – A list of snapshots in this host that Cinder currently manages, used to determine if a snapshot is manageable or not.
marker – The last item of the previous page; we return the next results after this value (after sorting)
limit – Maximum number of items to return
offset – Number of items to skip after marker
sort_keys – List of keys to sort results by (valid keys are ‘identifier’ and ‘size’)
sort_dirs – List of directions to sort by, corresponding to sort_keys (valid directions are ‘asc’ and ‘desc’)

manage_existing_snapshot(snapshot, existing_ref)¶

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:

Rename the backend storage object so that it matches the snapshot[‘name’] which is how drivers traditionally map between a cinder snapshot and the associated backend storage object.
Place some metadata on the snapshot, or somewhere in the backend, that allows other driver requests (e.g. delete) to locate the backend storage object when required.

If the existing_ref doesn’t make sense, or doesn’t refer to an existing backend storage object, raise a ManageExistingInvalidReference exception.

Parameters:

snapshot – Cinder volume snapshot to manage
existing_ref – Driver-specific information used to identify a volume snapshot

manage_existing_snapshot_get_size(snapshot, existing_ref)¶

Return size of snapshot to be managed by manage_existing.

When calculating the size, round up to the next GB.

Parameters:

snapshot – Cinder volume snapshot to manage
existing_ref – Driver-specific information used to identify a volume snapshot

Returns size:

Volume snapshot size in GiB (integer)

unmanage_snapshot(snapshot)¶

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 – Cinder volume snapshot to unmanage

class ManageableVD¶

Bases: object

get_manageable_volumes(cinder_volumes, marker, limit, offset, sort_keys, sort_dirs)¶

List volumes on the backend available for management by Cinder.

Returns a list of dictionaries, each specifying a volume in the host, with the following keys: - reference (dictionary): The reference for a volume, which can be passed to “manage_existing”. - size (int): The size of the volume according to the storage backend, rounded up to the nearest GB. - safe_to_manage (boolean): Whether or not this volume is safe to manage according to the storage backend. For example, is the volume in use or invalid for any reason. - reason_not_safe (string): If safe_to_manage is False, the reason why. - cinder_id (string): If already managed, provide the Cinder ID. - extra_info (string): Any extra information to return to the user

Parameters:

cinder_volumes – A list of volumes in this host that Cinder currently manages, used to determine if a volume is manageable or not.
marker – The last item of the previous page; we return the next results after this value (after sorting)
limit – Maximum number of items to return
offset – Number of items to skip after marker
sort_keys – List of keys to sort results by (valid keys are ‘identifier’ and ‘size’)
sort_dirs – List of directions to sort by, corresponding to sort_keys (valid directions are ‘asc’ and ‘desc’)

abstract manage_existing(volume, existing_ref)¶

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:

Rename the backend storage object so that it matches the, volume[‘name’] which is how drivers traditionally map between a cinder volume and the associated backend storage object.
Place some metadata on the volume, or somewhere in the backend, that allows other driver requests (e.g. delete, clone, attach, detach…) to locate the backend storage object when required.

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 – Cinder volume to manage
existing_ref – Driver-specific information used to identify a volume

abstract manage_existing_get_size(volume, existing_ref)¶

Return size of volume to be managed by manage_existing.

When calculating the size, round up to the next GB.

Parameters:

volume – Cinder volume to manage
existing_ref – Driver-specific information used to identify a volume

Returns size:

Volume size in GiB (integer)

abstract unmanage(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

class MigrateVD¶

Bases: object

abstract migrate_volume(context, volume, host)¶

Migrate the volume to the specified host.

Returns a boolean indicating whether the migration occurred, as well as model_update.

Parameters:

context – Context
volume – A dictionary describing the volume to migrate
host – A dictionary describing the host to migrate to, where host[‘host’] is its name, and host[‘capabilities’] is a dictionary of its reported capabilities.

class ProxyVD¶

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.

class VolumeDriver(execute=<function execute>, *args, **kwargs)¶

Bases: ManageableVD, CloneableImageVD, ManageableSnapshotsVD, MigrateVD, BaseVD

accept_transfer(context, volume, new_user, new_project)¶

check_for_setup_error()¶

clear_download(context, volume)¶: Clean up after an interrupted image copy.

clone_image(context, volume, image_location, image_meta, image_service)¶

Create a volume efficiently from an existing image.

Refer to cinder.interface.volume_driver.VolumeDriverCore.clone_image for additional information.

create_cgsnapshot(context, cgsnapshot, snapshots)¶

Creates a cgsnapshot.

Parameters:

context – the context of the caller.
cgsnapshot – the dictionary of the cgsnapshot to be created.
snapshots – a list of snapshot dictionaries in the cgsnapshot.

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.

create_consistencygroup(context, group)¶

Creates a consistencygroup.

Parameters:

context – the context of the caller.
group – the dictionary of the consistency group to be created.

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’.

create_consistencygroup_from_src(context, group, volumes, cgsnapshot=None, snapshots=None, source_cg=None, source_vols=None)¶

Creates a consistencygroup from source.

Parameters:

context – the context of the caller.
group – the dictionary of the consistency group to be created.
volumes – a list of volume dictionaries in the group.
cgsnapshot – the dictionary of the cgsnapshot as source.
snapshots – a list of snapshot dictionaries in the cgsnapshot.
source_cg – the dictionary of a consistency group as source.
source_vols – a list of volume dictionaries in the source_cg.

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.

create_export(context, volume, connector)¶

Exports the volume.

Can optionally return a Dictionary of changes to the volume object to be persisted.

create_export_snapshot(context, snapshot, connector)¶

Exports the snapshot.

Can optionally return a Dictionary of changes to the snapshot object to be persisted.

create_snapshot(snapshot)¶: Creates a snapshot.

create_volume(volume)¶

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>

create_volume_from_snapshot(volume, 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.

delete_cgsnapshot(context, cgsnapshot, snapshots)¶

Deletes a cgsnapshot.

Parameters:

context – the context of the caller.
cgsnapshot – the dictionary of the cgsnapshot to be deleted.
snapshots – a list of snapshot dictionaries in the cgsnapshot.

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.

delete_consistencygroup(context, group, volumes)¶

Deletes a consistency group.

Parameters:

context – the context of the caller.
group – the dictionary of the consistency group to be deleted.
volumes – a list of volume dictionaries in the group.

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.

delete_snapshot(snapshot)¶

Deletes a snapshot.

If the driver uses custom file locks they should be cleaned on success using cinder.utils.synchronized_remove

delete_volume(volume)¶

Deletes a volume.

If volume_type extra specs includes ‘replication: <is> True’ then the driver needs to delete the volume replica too.

It is imperative that this operation ensures that the data from the deleted volume cannot leak into new volumes when they are created, as new volumes are likely to belong to a different tenant/project.

If the driver uses custom file locks they should be cleaned on success using cinder.utils.synchronized_remove

ensure_export(context, volume)¶: Synchronously recreates an export for a volume.

extend_volume(volume, new_size)¶

get_manageable_snapshots(cinder_snapshots, marker, limit, offset, sort_keys, sort_dirs)¶

List snapshots on the backend available for management by Cinder.

Returns a list of dictionaries, each specifying a snapshot in the host, with the following keys: - reference (dictionary): The reference for a snapshot, which can be passed to “manage_existing_snapshot”. - size (int): The size of the snapshot according to the storage backend, rounded up to the nearest GB. - safe_to_manage (boolean): Whether or not this snapshot is safe to manage according to the storage backend. For example, is the snapshot in use or invalid for any reason. - reason_not_safe (string): If safe_to_manage is False, the reason why. - cinder_id (string): If already managed, provide the Cinder ID. - extra_info (string): Any extra information to return to the user - source_reference (string): Similar to “reference”, but for the snapshot’s source volume.

Parameters:

cinder_snapshots – A list of snapshots in this host that Cinder currently manages, used to determine if a snapshot is manageable or not.
marker – The last item of the previous page; we return the next results after this value (after sorting)
limit – Maximum number of items to return
offset – Number of items to skip after marker
sort_keys – List of keys to sort results by (valid keys are ‘identifier’ and ‘size’)
sort_dirs – List of directions to sort by, corresponding to sort_keys (valid directions are ‘asc’ and ‘desc’)

get_manageable_volumes(cinder_volumes, marker, limit, offset, sort_keys, sort_dirs)¶

List volumes on the backend available for management by Cinder.

Returns a list of dictionaries, each specifying a volume in the host, with the following keys: - reference (dictionary): The reference for a volume, which can be passed to “manage_existing”. - size (int): The size of the volume according to the storage backend, rounded up to the nearest GB. - safe_to_manage (boolean): Whether or not this volume is safe to manage according to the storage backend. For example, is the volume in use or invalid for any reason. - reason_not_safe (string): If safe_to_manage is False, the reason why. - cinder_id (string): If already managed, provide the Cinder ID. - extra_info (string): Any extra information to return to the user

Parameters:

cinder_volumes – A list of volumes in this host that Cinder currently manages, used to determine if a volume is manageable or not.
marker – The last item of the previous page; we return the next results after this value (after sorting)
limit – Maximum number of items to return
offset – Number of items to skip after marker
sort_keys – List of keys to sort results by (valid keys are ‘identifier’ and ‘size’)
sort_dirs – List of directions to sort by, corresponding to sort_keys (valid directions are ‘asc’ and ‘desc’)

get_pool(volume)¶

Return pool name where volume reside on.

Parameters:: volume – The volume hosted by the driver.
Returns:: name of the pool where given volume is in.

initialize_connection(volume, connector, **kwargs)¶

Allow connection to connector and return connection info.

..note::: Whether or not a volume is ‘cacheable’ for volume local cache on the hypervisor is normally configured in the volume-type extra-specs. Support may be disabled at the driver level, however, by returning “cacheable”: False in the conn_info. This will override any setting in the volume-type extra-specs.

Parameters:

volume – The volume to be attached
connector – Dictionary containing information about what is being connected to.

Returns conn_info:

A dictionary of connection information.

initialize_connection_snapshot(snapshot, connector, **kwargs)¶: Allow connection from connector for a snapshot.

local_path(volume)¶

manage_existing(volume, existing_ref)¶

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:

Rename the backend storage object so that it matches the, volume[‘name’] which is how drivers traditionally map between a cinder volume and the associated backend storage object.
Place some metadata on the volume, or somewhere in the backend, that allows other driver requests (e.g. delete, clone, attach, detach…) to locate the backend storage object when required.

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 – Cinder volume to manage
existing_ref – Driver-specific information used to identify a volume

manage_existing_get_size(volume, existing_ref)¶

Return size of volume to be managed by manage_existing.

When calculating the size, round up to the next GB.

Parameters:

volume – Cinder volume to manage
existing_ref – Driver-specific information used to identify a volume

Returns size:

Volume size in GiB (integer)

manage_existing_snapshot(snapshot, existing_ref)¶

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:

Rename the backend storage object so that it matches the snapshot[‘name’] which is how drivers traditionally map between a cinder snapshot and the associated backend storage object.
Place some metadata on the snapshot, or somewhere in the backend, that allows other driver requests (e.g. delete) to locate the backend storage object when required.

If the existing_ref doesn’t make sense, or doesn’t refer to an existing backend storage object, raise a ManageExistingInvalidReference exception.

Parameters:

snapshot – Cinder volume snapshot to manage
existing_ref – Driver-specific information used to identify a volume snapshot

manage_existing_snapshot_get_size(snapshot, existing_ref)¶

Return size of snapshot to be managed by manage_existing.

When calculating the size, round up to the next GB.

Parameters:

snapshot – Cinder volume snapshot to manage
existing_ref – Driver-specific information used to identify a volume snapshot

Returns size:

Volume snapshot size in GiB (integer)

migrate_volume(context, volume, host)¶

Migrate the volume to the specified host.

Returns a boolean indicating whether the migration occurred, as well as model_update.

Parameters:

context – Context
volume – A dictionary describing the volume to migrate
host – A dictionary describing the host to migrate to, where host[‘host’] is its name, and host[‘capabilities’] is a dictionary of its reported capabilities.

remove_export(context, volume)¶: Removes an export for a volume.

remove_export_snapshot(context, snapshot)¶: Removes an export for a snapshot.

retype(context, volume, new_type, diff, host)¶

revert_to_snapshot(context, volume, snapshot)¶

Revert volume to snapshot.

Note: the revert process should not change the volume’s current size, that means if the driver shrank the volume during the process, it should extend the volume internally.

terminate_connection(volume, connector, **kwargs)¶

Disallow connection from connector

Parameters:

volume – The volume to be disconnected.
connector – A dictionary describing the connection with details about the initiator. Can be None.

terminate_connection_snapshot(snapshot, connector, **kwargs)¶: Disallow connection from connector for a snapshot.

unmanage(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

unmanage_snapshot(snapshot)¶: Unmanage the specified snapshot from Cinder management.

update_consistencygroup(context, group, add_volumes=None, remove_volumes=None)¶

Updates a consistency group.

Parameters:

context – the context of the caller.
group – the dictionary of the consistency group to be updated.
add_volumes – a list of volume dictionaries to be added.
remove_volumes – a list of volume dictionaries to be removed.

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’.

cinder.volume.driver module

cinder.volume.driver module¶

cinder

Page Contents