cinder/doc/source/contributor/drivers_locking_examples.rst

orphan

Drivers Locking Examples

This document presents an incomplete list of locks being currently used in driver related code (main driver code, helper classes and method, etc.), to serve as a reference to other driver developers.

Note

Please keep in mind that Cinder drivers may support different deployment options. Some may only support running one backend on each node. Others may support running multiple backends in a single node. And some may even support Active-Active deployments. Therefore these references are not necessarily examples of how drivers achieve Active-Active.

LIO target

• Lock scope: Node.
• Critical section: Calls to cinder-rtstool CLI.
• Lock name: 'lioadm'.
• Where: _execute method.
• File: cinder/volume/targets/lio.py

NVMET target

• Lock scope: Node.
• Critical section: Creating or deleting NVMeOF targets operations.
• Lock name: 'nvmetcli'.
• Where: delete_nvmeof_target and create_nvmeof_target methods.
• File: cinder/volume/targets/nvmet.py.

HGST driver:

• Lock scope: Process.
• Critical section: Create volume operation.
• Lock name: 'hgst'devices'.
• Where: create_volume method.
• File: cinder/volume/drivers/hgst.py.

Solidfire driver:

• Lock scope: Process
• Critical section: Creating volume from an image, cloning volume, creating volume from a snapshot.
• Lock name: solidfire-{resource_id}.
• Where: locked_image_id_operation and locked_source_id_operation decorators.
• File: cinder/volume/drivers/solidfire.py.

Infinidat driver:

• Lock scope: Global.
• Critical section: Initialize and terminate connections operations.
• Lock name: infinidat-{management_address}-lock.
• Where: initialize_connection and terminate_connection methods.
• File: cinder/volume/drivers/infinidat.py.

Kaminario FC driver:

• Lock scope: Global.
• Critical section: Initialize and terminate connections operations.
• Lock name: kaminario-{san_ip}.
• Where: initialize_connection and terminate_connection methods.
• File: cinder/volume/drivers/kaminario/kaminario_fc.py

Kaminario iSCSI driver:

• Lock scope: Global.
• Critical section: Initialize and terminate connections operations.
• Lock name: kaminario-{san_ip}.
• Where: initialize_connection and terminate_connection methods.
• File: cinder/volume/drivers/kaminario/kaminario_iscsi.py

Dell Unity:

• Lock scope: Global.
• Critical section: Create or get a host on the backend.
• Lock name: {self.host}-{name}
• Where: create_host method.
• File: cinder/volume/drivers/dell_emc/unity/client.py

Dell Unity:

• Lock scope: Global.
• Critical section: Create host and attach.
• Lock name: {client.host}-{host_name}
• Where: _create_host_and_attach method.
• File: cinder/volume/drivers/dell_emc/unity/adapter.py

Dell Unity:

• Lock scope: Global.
• Critical section: Create host and attach as part of the initialize_connection process, and also detach and delete host as part of the terminate_connection process.
• Lock name: {client.host}-{host_name}
• Where: _create_host_and_attach and _detach_and_delete_host methods.
• File: cinder/volume/drivers/dell_emc/unity/adapter.py

Dothill:

• Lock scope: Global
• Critical section: Retrieving a session key from the array. Perform HTTP requests on the device.
• Lock name: {driver_name}-{array_name}
• Where: _get_session_key and _api_request methods.
• File: cinder/volume/drivers/dothill/dothill_client.py.

Dothill:

• Lock scope: Global
• Critical section: Mapping a volume as part of the initialize_connection process.
• Lock name: {driver_name}-{array_name}-map
• Where: map_volume method.
• File: cinder/volume/drivers/dothill/dothill_client.py.

Other files

Other files that also make use of the locking mechanisms, and can be useful as reference, are:

• cinder/volume/drivers/dell_emc/vmax/common.py
• cinder/volume/drivers/dell_emc/vmax/masking.py
• cinder/volume/drivers/dell_emc/vmax/provision.py
• cinder/volume/drivers/dell_emc/vmax/rest.py
• cinder/volume/drivers/dell_emc/vmax/utils.py
• cinder/volume/drivers/fujitsu/eternus_dx_common.py
• cinder/volume/drivers/hpe/hpe_3par_common.py
• cinder/volume/drivers/hpe/hpe_lefthand_iscsi.py
• cinder/volume/drivers/huawei/huawei_driver.py
• cinder/volume/drivers/huawei/rest_client.py
• cinder/volume/drivers/huawei/smartx.py
• cinder/volume/drivers/ibm/flashsystem_common.py
• cinder/volume/drivers/ibm/flashsystem_fc.py
• cinder/volume/drivers/ibm/flashsystem_iscsi.py
• cinder/volume/drivers/ibm/ibm_storage/ds8k_helper.py
• cinder/volume/drivers/ibm/ibm_storage/ds8k_proxy.py
• cinder/volume/drivers/ibm/ibm_storage/ds8k_replication.py
• cinder/volume/drivers/ibm/ibm_storage/xiv_proxy.py
• cinder/volume/drivers/ibm/storwize_svc/storwize_const.py
• cinder/volume/drivers/ibm/storwize_svc/storwize_svc_fc.py
• cinder/volume/drivers/ibm/storwize_svc/storwize_svc_iscsi.py
• cinder/volume/drivers/inspur/instorage/instorage_const.py
• cinder/volume/drivers/inspur/instorage/instorage_fc.py
• cinder/volume/drivers/inspur/instorage/instorage_iscsi.py
• cinder/volume/drivers/nec/cli.py
• cinder/volume/drivers/nec/volume_helper.py
• cinder/volume/drivers/netapp/dataontap/nfs_base.py

Notes on Driver Locking

From the volume manager flow, create_cloned_volume() happens to be called with a lock that prevents concurrent calls to clone from the same volume at the same time.

This is done by the cinder/volume/manager.py create_volume() code:

elif source_volid is not None:
    locked_action = "%s-%s" % (source_volid, 'delete_volume')

and subsequent COORDINATOR.get_lock() call.

This seems to have been intended to prevent a volume from being deleted while being used as the source of a volume clone, the fact that it prevents concurrent clone operations is a side effect.

This means that a driver that cannot correctly handle concurrent clone operations from the same volume will work for normal clone operations, but then fail when a clone operation is performed as part of cloning from the image-volume cache, or cloning from a Cinder backend of Glance. (See https://bugs.launchpad.net/cinder/+bug/1851512 for an example.)

It should be assumed that, at some point, this locking behavior will be changed to allow concurrent clone calls.