cinder.volume.volume_utils module

Volume-related Utilities and helpers.

class TraceWrapperMetaclass(classname, bases, classDict)

Bases: type

Metaclass that wraps all methods of a class with trace_method.

This metaclass will cause every function inside of the class to be decorated with the trace_method decorator.

To use the metaclass you define a class like so: class MyClass(object, metaclass=utils.TraceWrapperMetaclass):

class TraceWrapperWithABCMetaclass(name, bases, namespace, **kwargs)

Bases: ABCMeta, TraceWrapperMetaclass

Metaclass that wraps all methods of a class with trace.

append_host(host: str | None, pool: str | None) → str | None

Encode pool into host info.

brick_attach_volume_encryptor(context: RequestContext, attach_info: dict, encryption: dict) → None

Attach encryption layer.

brick_detach_volume_encryptor(attach_info: dict, encryption: dict) → None

Detach encryption layer.

brick_get_connector(protocol: str, driver=None, use_multipath: bool = False, device_scan_attempts: int = 3, *args, **kwargs)

Wrapper to get a brick connector object.

This automatically populates the required protocol as well as the root_helper needed to execute commands.

brick_get_connector_properties(multipath: bool = False, enforce_multipath: bool = False)

Wrapper to automatically set root_helper in brick calls.

Parameters:

• multipath – A boolean indicating whether the connector can support multipath.

• enforce_multipath – If True, it raises exception when multipath=True is specified but multipathd is not running. If False, it falls back to multipath=False when multipathd is not running.

brick_get_encryptor(connection_info: dict, *args, **kwargs)

Wrapper to get a brick encryptor object.

check_already_managed_volume(vol_id: str | None)

Check cinder db for already managed volume.

Parameters:

vol_id – volume id parameter

Returns:

bool – return True, if db entry with specified volume id exists, otherwise return False

Raises:

ValueError if vol_id is not a valid uuid string

check_encryption_provider(volume: Volume, context: RequestContext) → dict

Check that this is a LUKS encryption provider.

Returns:

encryption dict

check_for_odirect_support(src: str, dest: str, flag: str = 'oflag=direct') → bool

check_image_metadata(image_meta: dict[str, str | int], vol_size: int) → None

Validates the image metadata.

clear_volume(volume_size: int, volume_path: str, volume_clear: str | None = None, volume_clear_size: int | None = None, volume_clear_ionice: str | None = None, throttle=None) → None

Unprovision old volumes to prevent data leaking between users.

clone_encryption_key(context: RequestContext, key_manager, encryption_key_id: str) → str

convert_config_string_to_dict(config_string: str) → dict

Convert config file replication string to a dict.

The only supported form is as follows: “{‘key-1’=’val-1’ ‘key-2’=’val-2’…}”

Parameters:

config_string – Properly formatted string to convert to dict.

Response:

dict of string values

copy_image_to_volume(driver, context: RequestContext, volume: Volume, image_meta: dict, image_location: str | tuple[str | None, Any], image_service, disable_sparse: bool = False) → None

Downloads Glance image to the specified volume.

copy_volume(src: str | ~typing.BinaryIO, dest: str | ~typing.BinaryIO, size_in_m: int, blocksize: str | int, sync=False, execute=<function execute>, ionice=None, throttle=None, sparse=False) → None

Copy data from the source volume to the destination volume.

The parameters ‘src’ and ‘dest’ are both typically of type str, which represents the path to each volume on the filesystem. Connectors can optionally return a volume handle of type RawIOBase for volumes that are not available on the local filesystem for open/close operations.

If either ‘src’ or ‘dest’ are not of type str, then they are assumed to be of type RawIOBase or any derivative that supports file operations such as read and write. In this case, the handles are treated as file handles instead of file paths and, at present moment, throttling is unavailable.

create_encryption_key(context: RequestContext, key_manager, volume_type_id: str) → str | None

delete_encryption_key(context: RequestContext, key_manager, encryption_key_id: str) → None

enable_bootable_flag(volume: Volume) → None

extract_availability_zones_from_volume_type(volume_type: VolumeType | dict) → list[str] | None

extract_host(host: str | None, level: str = 'backend', default_pool_name: bool = False) → str | None

Extract Host, Backend or Pool information from host string.

Parameters:

• host – String for host, which could include host@backend#pool info

• level – Indicate which level of information should be extracted from host string. Level can be ‘host’, ‘backend’ or ‘pool’, default value is ‘backend’

• default_pool_name – this flag specify what to do if level == ‘pool’ and there is no ‘pool’ info encoded in host string. default_pool_name=True will return DEFAULT_POOL_NAME, otherwise we return None. Default value of this parameter is False.

Returns:

expected information, string or None

Raises:

exception.InvalidVolume

For example:

host = ‘HostA@BackendB#PoolC’ ret = extract_host(host, ‘host’) # ret is ‘HostA’ ret = extract_host(host, ‘backend’) # ret is ‘HostA@BackendB’ ret = extract_host(host, ‘pool’) # ret is ‘PoolC’

host = ‘HostX@BackendY’ ret = extract_host(host, ‘pool’) # ret is None ret = extract_host(host, ‘pool’, True) # ret is ‘_pool0’

extract_id_from_snapshot_name(snap_name: str) → str | None

Return a snapshot’s ID from its name on the backend.

extract_id_from_volume_name(vol_name: str) → str | None

generate_password(length: int = 16, symbolgroups: tuple[str, ...] = ('23456789', 'ABCDEFGHJKLMNPQRSTUVWXYZ', 'abcdefghijkmnopqrstuvwxyz')) → str

Generate a random password from the supplied symbol groups.

At least one symbol from each group will be included. Unpredictable results if length is less than the number of symbol groups.

Believed to be reasonably secure (with a reasonable password length!)

generate_username(length: int = 20, symbolgroups: tuple[str, ...] = ('23456789', 'ABCDEFGHJKLMNPQRSTUVWXYZ', 'abcdefghijkmnopqrstuvwxyz')) → str

get_all_physical_volumes(vg_name=None) → list

get_all_volume_groups(vg_name=None) → list

get_backend_configuration(backend_name, backend_opts=None)

Get a configuration object for a specific backend.

get_base_image_ref(volume: Volume)

get_max_over_subscription_ratio(str_value: str | float, supports_auto: bool = False) → str | float

Get the max_over_subscription_ratio from a string

As some drivers need to do some calculations with the value and we are now receiving a string value in the conf, this converts the value to float when appropriate.

Parameters:

• str_value – Configuration object

• supports_auto – Tell if the calling driver supports auto MOSR.

Response:

value of mosr

get_volume_image_metadata(image_id: str, image_meta: dict[str, Any]) → dict

group_get_by_id(group_id)

hosts_are_equivalent(host_1: str, host_2: str) → bool

image_conversion_dir() → str

is_all_zero(chunk: bytes) → bool

Return true if the chunk of bytes is all zeroes.

is_boolean_str(str: str | None) → bool

is_group_a_cg_snapshot_type(group_or_snap) → bool

is_group_a_type(group: Group, key: str) → bool

is_multiattach_spec(extra_specs: dict) → bool

is_replicated_spec(extra_specs: dict) → bool

log_unsupported_driver_warning(driver)

Annoy the log about unsupported drivers.

matching_backend_name(src_volume_type, volume_type) → bool

notify_about_backup_usage(context: RequestContext, backup: Backup, event_suffix: str, extra_usage_info: dict | None = None, host: str | None = None) → None

notify_about_capacity_usage(context: RequestContext, capacity: dict, suffix: str, extra_usage_info: dict | None = None, host: str | None = None) → None

notify_about_cgsnapshot_usage(context: RequestContext, cgsnapshot: CGSnapshot, event_suffix: str, extra_usage_info: dict | None = None, host: str | None = None) → None

notify_about_consistencygroup_usage(context: RequestContext, group: Group, event_suffix: str, extra_usage_info: dict | None = None, host: str | None = None) → None

notify_about_group_snapshot_usage(context: RequestContext, group_snapshot: GroupSnapshot, event_suffix: str, extra_usage_info=None, host: str | None = None) → None

notify_about_group_usage(context: RequestContext, group: Group, event_suffix: str, extra_usage_info: dict | None = None, host: str | None = None) → None

notify_about_snapshot_usage(context: RequestContext, snapshot: Snapshot, event_suffix: str, extra_usage_info: dict | None = None, host: str | None = None) → None

notify_about_volume_usage(context: RequestContext, volume: Volume, event_suffix: str, extra_usage_info: dict | None = None, host: str | None = None) → None

null_safe_str(s: str | None) → str

paginate_entries_list(entries: list[dict], marker: dict | str | None, limit: int, offset: int | None, sort_keys: list[str], sort_dirs: list[str]) → list

Paginate a list of entries.

Parameters:

entries – list of dictionaries

Marker:

The last element previously returned

Limit:

The maximum number of items to return

Offset:

The number of items to skip from the marker or from the first element.

Sort_keys:

A list of keys in the dictionaries to sort by

Sort_dirs:

A list of sort directions, where each is either ‘asc’ or ‘dec’

require_driver_initialized(driver)

Verifies if driver is initialized

If the driver is not initialized, an exception will be raised.

Params driver:

The driver instance.

Raises:

exception.DriverNotInitialized

resolve_hostname(hostname: str) → str

Resolves host name to IP address.

Resolves a host name (my.data.point.com) to an IP address (10.12.143.11). This routine also works if the data passed in hostname is already an IP. In this case, the same IP address will be returned.

Parameters:

hostname – Host name to resolve.

Returns:

IP Address for Host name.

sanitize_host(host: str) → str

Ensure IPv6 addresses are enclosed in [] for iSCSI portals.

sanitize_hostname(hostname) → str

Return a hostname which conforms to RFC-952 and RFC-1123 specs.

setup_tracing(trace_flags)

Set global variables for each trace flag.

Sets variables TRACE_METHOD and TRACE_API, which represent whether to log methods or api traces.

Parameters:

trace_flags – a list of strings

supports_thin_provisioning() → bool

trace(*dec_args, **dec_kwargs)

Trace calls to the decorated function.

This decorator should always be defined as the outermost decorator so it is defined last. This is important so it does not interfere with other decorators.

Using this decorator on a function will cause its execution to be logged at DEBUG level with arguments, return values, and exceptions.

Returns:

a function decorator

trace_api(*dec_args, **dec_kwargs)

Decorates a function if TRACE_API is true.

trace_method(f)

Decorates a function if TRACE_METHOD is true.

update_backup_error(backup, err: str, status='error') → None

upload_volume(context: RequestContext, image_service, image_meta, volume_path, volume: Volume, volume_format: str = 'raw', run_as_root: bool = True, compress: bool = True, volume_fd=None) → None