Storage Volumes, Disks

Todo

rework after iSCSI merge (see ‘Old Docs’) (todd or vish)

The cinder.volume.manager Module

Volume manager manages creating, attaching, detaching, and persistent storage.

Persistent storage volumes keep their state independent of instances. You can attach to an instance, terminate the instance, spawn a new instance (even one from a different image) and re-attach the volume with the same data intact.

Related Flags

volume_topic:What rpc topic to listen to (default: cinder-volume).
volume_manager:The module name of a class derived from manager.Manager (default: cinder.volume.manager.Manager).
volume_driver:Used by Manager. Defaults to cinder.volume.drivers.lvm.LVMISCSIDriver.
volume_group:Name of the group that will contain exported volumes (default: cinder-volumes)
num_shell_tries:
 Number of times to attempt to run commands (default: 3)
class VolumeManager(volume_driver=None, service_name=None, *args, **kwargs)

Bases: cinder.manager.SchedulerDependentManager

Manages attachable block storage devices.

RPC_API_VERSION = '1.16'
accept_transfer(context, volume_id, new_user, new_project)
attach_volume(context, volume_id, instance_uuid, host_name, mountpoint, mode)

Updates db to show volume is attached.

copy_volume_to_image(context, volume_id, image_meta)

Uploads the specified volume to Glance.

image_meta is a dictionary containing the following keys: ‘id’, ‘container_format’, ‘disk_format’

create_snapshot(context, volume_id, snapshot_id)

Creates and exports the snapshot.

create_volume(context, volume_id, request_spec=None, filter_properties=None, allow_reschedule=True, snapshot_id=None, image_id=None, source_volid=None)

Creates the volume.

delete_snapshot(inst, context, snapshot_id, **kwargs)
delete_volume(inst, context, volume_id, **kwargs)
detach_volume(inst, context, volume_id, **kwargs)
extend_volume(context, volume_id, new_size, reservations)
init_host()

Do any initialization that needs to be run if this is a standalone service.

initialize_connection(context, volume_id, connector)

Prepare volume for connection from host represented by connector.

This method calls the driver initialize_connection and returns it to the caller. The connector parameter is a dictionary with information about the host that will connect to the volume in the following format:

{
    'ip': ip,
    'initiator': initiator,
}

ip: the ip address of the connecting machine

initiator: the iscsi initiator name of the connecting machine. This can be None if the connecting machine does not support iscsi connections.

driver is responsible for doing any necessary security setup and returning a connection_info dictionary in the following format:

{
    'driver_volume_type': driver_volume_type,
    'data': data,
}
driver_volume_type: a string to identify the type of volume. This
can be used by the calling code to determine the strategy for connecting to the volume. This could be ‘iscsi’, ‘rbd’, ‘sheepdog’, etc.
data: this is the data that the calling code will use to connect
to the volume. Keep in mind that this will be serialized to json in various places, so it should not contain any non-json data types.
manage_existing(ctxt, volume_id, ref=None)
migrate_volume(ctxt, volume_id, host, force_host_copy=False, new_type_id=None)

Migrate the volume to the specified host (called on source host).

migrate_volume_completion(ctxt, volume_id, new_volume_id, error=False)
notification(context, event)
publish_service_capabilities(context)

Collect driver status and then publish.

retype(ctxt, volume_id, new_type_id, host, migration_policy='never', reservations=None)
target = <Target version=1.16>
terminate_connection(context, volume_id, connector, force=False)

Cleanup connection from host represented by connector.

The format of connector is the same as for initialize_connection.

locked_snapshot_operation(f)

Lock decorator for snapshot operations.

Takes a named lock prior to executing the operation. The lock is named with the operation executed and the id of the snapshot. This lock can then be used by other operations to avoid operation conflicts on shared snapshots.

Example use:

If a snapshot operation uses this decorator, it will block until the named lock is free. This is used to protect concurrent operations on the same snapshot e.g. delete SnapA while create volume VolA from SnapA is in progress.

locked_volume_operation(f)

Lock decorator for volume operations.

Takes a named lock prior to executing the operation. The lock is named with the operation executed and the id of the volume. This lock can then be used by other operations to avoid operation conflicts on shared volumes.

Example use:

If a volume operation uses this decorator, it will block until the named lock is free. This is used to protect concurrent operations on the same volume e.g. delete VolA while create volume VolB from VolA is in progress.

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_volume(volume)
static fake_execute(cmd, *_args, **_kwargs)

Execute that simply logs the command.

initialize_connection(volume, connector)
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’

}

}

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 0x7fa9e7a2d848>, *args, **kwargs)

Bases: object

Executes commands relating to Volumes.

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_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)

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

create_volume_from_snapshot(volume, snapshot)

Creates a volume from a snapshot.

delete_snapshot(snapshot)

Deletes a snapshot.

delete_volume(volume)

Deletes a volume.

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

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.
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 a boolean indicating whether the retype occurred.

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.

Tests

The volume_unittest Module

Old Docs

Cinder uses iSCSI to export storage volumes from multiple storage nodes. These iSCSI exports are attached (using libvirt) directly to running instances.

Cinder volumes are exported over the primary system VLAN (usually VLAN 1), and not over individual VLANs.

The underlying volumes by default are LVM logical volumes, created on demand within a single large volume group.

Table Of Contents

Previous topic

The Database Layer

Next topic

Authentication and Authorization

This Page