The cinder.volume.driver Module

Drivers for volumes.

class FakeISCSIDriver(*args, **kwargs)

Bases: cinder.volume.driver.ISCSIDriver

Logs calls instead of executing.

check_for_setup_error()

No setup necessary in fake mode.

create_cloned_volume(volume, src_vref)

Creates a clone of the specified volume.

create_export(context, volume)

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

create_snapshot(snapshot)

Creates a snapshot.

create_volume(volume)
create_volume_from_snapshot(volume, snapshot)

Creates a volume from a snapshot.

delete_snapshot(snapshot)

Deletes a snapshot.

delete_volume(volume)

Deletes a volume.

ensure_export(context, volume)

Synchronously recreates an export for a volume.

static fake_execute(cmd, *_args, **_kwargs)

Execute that simply logs the command.

initialize_connection(volume, connector)
local_path(volume)
remove_export(context, volume)

Removes an export for a volume.

terminate_connection(volume, connector, **kwargs)
class FakeISERDriver(*args, **kwargs)

Bases: cinder.volume.driver.FakeISCSIDriver

Logs calls instead of executing.

static fake_execute(cmd, *_args, **_kwargs)

Execute that simply logs the command.

initialize_connection(volume, connector)
class FibreChannelDriver(*args, **kwargs)

Bases: cinder.volume.driver.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’, ‘access_mode’: ‘rw’

}

}

or

{

‘driver_volume_type’: ‘fibre_channel’ ‘data’: {

‘target_discovered’: True, ‘target_lun’: 1, ‘target_wwn’: [‘1234567890123’, ‘0987654321321’], ‘access_mode’: ‘rw’

}

}

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: cinder.volume.driver.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.
get_target_helper(db)
get_volume_stats(refresh=False)

Get volume stats.

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

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,
        'access_mode': 'rw'
    }
}
terminate_connection(volume, connector, **kwargs)
validate_connector(connector)
class ISERDriver(*args, **kwargs)

Bases: cinder.volume.driver.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.
get_target_helper(db)
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 VolumeDriver(execute=<function execute at 0x2602488>, *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 configued 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.

VERSION = 'N/A'
accept_transfer(context, volume, new_user, new_project)

Accept the transfer of a volume for a new user/project.

attach_volume(context, volume, instance_uuid, host_name, mountpoint)

Callback for volume attached to instance or host.

backup_volume(context, backup, backup_service)

Create a new backup from an existing volume.

check_for_setup_error()
clear_download(context, volume)

Clean up after an interrupted image copy.

clone_image(volume, image_location, image_id, image_meta)

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.

Returns a dict of volume properties eg. provider_location, boolean indicating whether cloning occurred

copy_image_to_volume(context, volume, image_service, image_id)

Fetch the image from image_service and write it to the volume.

copy_volume_data(context, src_vol, dest_vol, remote=None)

Copy data from src_vol to dest_vol.

copy_volume_to_image(context, volume, image_service, image_meta)

Copy the volume to the specified image.

create_cgsnapshot(context, cgsnapshot)

Creates a cgsnapshot.

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.

create_consistencygroup(context, group)

Creates a consistencygroup.

create_export(context, volume)

Exports the volume.

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

create_replica_test_volume(volume, src_vref)

Creates a test replica clone of the specified replicated volume.

Create a clone of the replicated (secondary) volume.

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)

Deletes a cgsnapshot.

delete_consistencygroup(context, group)

Deletes a consistency group.

delete_snapshot(snapshot)

Deletes a snapshot.

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.

detach_volume(context, volume)

Callback for volume detached.

do_setup(context)

Any initialization the volume driver does while starting.

ensure_export(context, volume)

Synchronously recreates an export for a volume.

extend_volume(volume, new_size)
get_pool(volume)

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.
get_replication_status(context, 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:
  • context – Context
  • volume – A dictionary describing the volume
get_version()

Get the current version of this driver.

get_volume_stats(refresh=False)

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_support = True (None or false disables replication)

initialize_connection(volume, connector)

Allow connection to connector and return connection info.

initialized
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:

  1. 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.
  2. 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.

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.

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:
  • ctxt – 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.
promote_replica(context, volume)

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:
  • context – Context
  • volume – A dictionary describing the volume
reenable_replication(context, volume)

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:
  • context – Context
  • volume – A dictionary describing the volume
remove_export(context, volume)

Removes an export for a volume.

restore_backup(context, backup, volume, backup_service)

Restore an existing backup to a new or existing volume.

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

Convert the volume to be of the new type.

Returns either: A boolean indicating whether the retype occurred, or A tuple (retyped, model_update) where retyped is a boolean indicating if the retype occurred, and the model_update includes changes for the volume db. if diff[‘extra_specs’] includes ‘replication’ then:

if (‘True’, _ ) then replication should be disabled:
Volume replica should be deleted volume[‘replication_status’] should be changed to ‘disabled’ volume[‘replication_extended_status’] = None volume[‘replication_driver_data’] = None
if (_, ‘True’) then replication should be enabled:
Volume replica (secondary) should be created, and replication should be setup between the volume and the newly created replica volume[‘replication_status’] = ‘copying’ volume[‘replication_extended_status’] = driver specific value volume[‘replication_driver_data’] = driver specific value
Parameters:
  • ctxt – Context
  • volume – A dictionary describing the volume to migrate
  • new_type – A dictionary describing the volume type to convert to
  • diff – A dictionary with the difference between the two types
  • 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.
set_execute(execute)
set_initialized()
terminate_connection(volume, connector, **kwargs)

Disallow connection from connector

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.

validate_connector(connector)

Fail if connector doesn’t contain all the data needed by driver.

static validate_connector_has_setting(connector, setting)

Previous topic

The cinder.volume.configuration Module

Next topic

The cinder.volume.drivers.block_device Module

This Page