cinder.utils module¶
Utilities and helper functions for all Cinder code.
This file is for utilities useful in all of Cinder, including cinder-manage, the api service, the scheduler, etc.
Code related to volume drivers and connecting to volumes should be placed in volume_utils instead.
- class ComparableMixin¶
Bases:
object
- class DoNothing¶
Bases:
str
Class that literrally does nothing.
We inherit from str in case it’s called with json.dumps.
- class Semaphore(limit)¶
Bases:
object
Custom semaphore to workaround eventlet issues with multiprocessing.
- api_clean_volume_file_locks(volume_id)¶
- as_int(obj: int | float | str, quiet: bool = True) int ¶
- build_or_str(elements: None | str | Iterable[str], str_format: str | None = None) str ¶
Builds a string of elements joined by ‘or’.
Will join strings with the ‘or’ word and if a str_format is provided it will be used to format the resulted joined string. If there are no elements an empty string will be returned.
- Parameters:
elements (String or iterable of strings.) – Elements we want to join.
str_format (String.) – String to use to format the response.
- calculate_capacity_factors(total_capacity: float, free_capacity: float, provisioned_capacity: float, thin_provisioning_support: bool, max_over_subscription_ratio: float, reserved_percentage: int, thin: bool) dict ¶
Create the various capacity factors of the a particular backend.
Based off of definition of terms cinder-specs/specs/queens/provisioning-improvements.html Description of factors calculated where units of gb are Gibibytes. reserved_capacity - The amount of space reserved from the total_capacity as reported by the backend. total_reserved_available_capacity - The total capacity minus reserved capacity total_available_capacity - The total capacity available to cinder calculated from total_reserved_available_capacity (for thick) OR for thin total_reserved_available_capacity max_over_subscription_ratio calculated_free_capacity - total_available_capacity - provisioned_capacity virtual_free_capacity - The calculated free capacity available to cinder to allocate new storage. For thin: calculated_free_capacity For thick: the reported free_capacity can be less than the calculated capacity, so we use free_capacity - reserved_capacity.
free_percent - the percentage of the virtual_free_capacity and total_available_capacity is left over provisioned_ratio - The ratio of provisioned storage to total_available_capacity
- Parameters:
total_capacity (float) – The reported total capacity in the backend.
free_capacity (float) – The free space/capacity as reported by the backend.
provisioned_capacity (float) – as reported by backend or volume manager from allocated_capacity_gb
thin_provisioning_support (bool) – Is thin provisioning supported?
max_over_subscription_ratio (float) – as reported by the backend
reserved_percentage (int, 0-100) – the % amount to reserve as unavailable. 0-100
thin (bool) – calculate based on thin provisioning if enabled by thin_provisioning_support
- Returns:
A dictionary of all of the capacity factors.
- Return type:
dict
- calculate_max_over_subscription_ratio(capability: dict, global_max_over_subscription_ratio: float) float ¶
- calculate_virtual_free_capacity(total_capacity: float, free_capacity: float, provisioned_capacity: float, thin_provisioning_support: bool, max_over_subscription_ratio: float, reserved_percentage: int, thin: bool) float ¶
Calculate the virtual free capacity based on multiple factors.
- Parameters:
total_capacity – total_capacity_gb of a host_state or pool.
free_capacity – free_capacity_gb of a host_state or pool.
provisioned_capacity – provisioned_capacity_gb of a host_state or pool.
thin_provisioning_support – thin_provisioning_support of a host_state or a pool.
max_over_subscription_ratio – max_over_subscription_ratio of a host_state or a pool
reserved_percentage – reserved_percentage of a host_state or a pool.
thin – whether volume to be provisioned is thin
- Returns:
the calculated virtual free capacity.
- check_exclusive_options(**kwargs: dict | str | bool | None) None ¶
Checks that only one of the provided options is actually not-none.
Iterates over all the kwargs passed in and checks that only one of said arguments is not-none, if more than one is not-none then an exception will be raised with the names of those arguments who were not-none.
- check_metadata_properties(metadata: dict[str, str] | None) None ¶
Checks that the volume metadata properties are valid.
- check_ssh_injection(cmd_list: list[str]) None ¶
- check_string_length(value: str, name: str, min_length: int = 0, max_length: int | None = None, allow_all_spaces: bool = True) None ¶
Check the length of specified string.
- Parameters:
value – the value of the string
name – the name of the string
min_length – the min_length of the string
max_length – the max_length of the string
- clean_snapshot_file_locks(snapshot_id, driver)¶
- clean_volume_file_locks(volume_id, driver)¶
Remove file locks used by Cinder.
This doesn’t take care of driver locks, those should be handled in driver’s delete_volume method.
- convert_str(text: str | bytes) str ¶
Convert to native string.
Convert bytes and Unicode strings to native strings:
convert to bytes on Python 2: encode Unicode using encodeutils.safe_encode()
convert to Unicode on Python 3: decode bytes from UTF-8
- create_ordereddict(adict: dict) OrderedDict ¶
Given a dict, return a sorted OrderedDict.
- execute(*cmd: str, **kwargs: bool | str) tuple[str, str] ¶
Convenience wrapper around oslo’s execute() method.
- get_blkdev_major_minor(path: str, lookup_for_file: bool = True) str | None ¶
Get ‘major:minor’ number of block device.
Get the device’s ‘major:minor’ number of a block device to control I/O ratelimit of the specified path. If lookup_for_file is True and the path is a regular file, lookup a disk device which the file lies on and returns the result for the device.
- get_bool_param(param_string: str, params: dict, default: bool = False) bool ¶
- get_file_gid(path: str) int ¶
This primarily exists to make unit testing easier.
- get_file_mode(path: str) int ¶
This primarily exists to make unit testing easier.
- get_file_size(path: str) int ¶
Returns the file size.
- get_log_levels(prefix: str) dict ¶
- get_log_method(level_string: str) int ¶
- get_root_helper() str ¶
- if_notifications_enabled(f: Callable) Callable ¶
Calls decorated method only if notifications are enabled.
- is_blk_device(dev: str) bool ¶
- last_completed_audit_period(unit: str | None = None) tuple[datetime | timedelta, datetime | timedelta] ¶
This method gives you the most recently completed audit period.
- arguments:
- units: string, one of ‘hour’, ‘day’, ‘month’, ‘year’
Periods normally begin at the beginning (UTC) of the period unit (So a ‘day’ period begins at midnight UTC, a ‘month’ unit on the 1st, a ‘year’ on Jan, 1) unit string may be appended with an optional offset like so: ‘day@18’ This will begin the period at 18:00 UTC. ‘month@15’ starts a monthly period on the 15th, and year@3 begins a yearly one on March 1st.
- returns: 2 tuple of datetimes (begin, end)
The begin timestamp of this audit period is the same as the end of the previous.
- limit_operations(func: Callable) Callable ¶
Decorator to limit the number of concurrent operations.
This method decorator expects to have a _semaphore attribute holding an initialized semaphore in the self instance object.
We can get the appropriate semaphore with the semaphore_factory method.
- make_dev_path(dev: str, partition: str | None = None, base: str = '/dev') str ¶
Return a path to a particular device.
>>> make_dev_path('xvdc') /dev/xvdc
>>> make_dev_path('xvdc', 1) /dev/xvdc1
- monkey_patch() None ¶
Patches decorators for all functions in a specified module.
If the CONF.monkey_patch set as True, this function patches a decorator for all functions in specified modules.
You can set decorators for each modules using CONF.monkey_patch_modules. The format is “Module path:Decorator function”. Example: ‘cinder.api.ec2.cloud:’ cinder.openstack.common.notifier.api.notify_decorator’
Parameters of the decorator are as follows. (See cinder.openstack.common.notifier.api.notify_decorator)
- Parameters:
name – name of the function
function – object of the function
- notifications_enabled(conf)¶
Check if oslo notifications are enabled.
- paths_normcase_equal(path_a: str, path_b: str) bool ¶
- retry(retry_param: None | ~typing.Type[Exception] | tuple[~typing.Type[Exception], ...] | int | tuple[int, ...], interval: float = 1, retries: int = 3, backoff_rate: float = 2, wait_random: bool = False, retry=<class 'tenacity.retry.retry_if_exception_type'>) Callable ¶
- class retry_if_exit_code(codes)¶
Bases:
retry_if_exception
Retry on ProcessExecutionError specific exit codes.
- robust_file_write(directory: str, filename: str, data: str) None ¶
Robust file write.
Use “write to temp file and rename” model for writing the persistence file.
- Parameters:
directory – Target directory to create a file.
filename – File name to store specified data.
data – String data.
- semaphore_factory(limit: int, concurrent_processes: int) Semaphore | Semaphore ¶
Get a semaphore to limit concurrent operations.
The semaphore depends on the limit we want to set and the concurrent processes that need to be limited.
- service_expired_time(with_timezone: bool | None = False) datetime ¶
- set_log_levels(prefix: str, level_string: str) None ¶
- tempdir(**kwargs) Iterator[str] ¶
- temporary_chown(path: str, owner_uid: int | None = None) Iterator[None] ¶
Temporarily chown a path.
- Params owner_uid:
UID of temporary owner (defaults to current user)
- validate_dictionary_string_length(specs: dict) None ¶
Check the length of each key and value of dictionary.