ironic.common.utils module

Utilities and helper functions.

ironic.common.utils.check_dir(directory_to_check=None, required_space=1)[source]

Check a directory is usable.

This function can be used by drivers to check that directories they need to write to are usable. This should be called from the drivers init function. This function checks that the directory exists and then calls check_dir_writable and check_dir_free_space. If directory_to_check is not provided the default is to use the temp directory.

Parameters:

  • directory_to_check – the directory to check.

  • required_space – amount of space to check for in MiB.

Raises:

PathNotFound if directory can not be found

Raises:

DirectoryNotWritable if user is unable to write to the directory

Raises:

InsufficientDiskSpace – if free space is < required space

ironic.common.utils.dd(src, dst, *args)[source]

Execute dd from src to dst.

Parameters:

  • src – the input file for dd command.

  • dst – the output file for dd command.

  • args – a tuple containing the arguments to be passed to dd command.

Raises:

processutils.ProcessExecutionError if it failed to run the process.

ironic.common.utils.execute(*cmd, use_standard_locale=False, log_stdout=True, **kwargs)[source]

Convenience wrapper around oslo’s execute() method.

Executes and logs results from a system command. See docs for oslo_concurrency.processutils.execute for usage.

Parameters:

  • cmd – positional arguments to pass to processutils.execute()

  • use_standard_locale – Defaults to False. If set to True, execute command with standard locale added to environment variables.

  • log_stdout – Defaults to True. If set to True, logs the output.

  • kwargs – keyword arguments to pass to processutils.execute()

Returns:

(stdout, stderr) from process execution

Raises:

UnknownArgumentError on receiving unknown arguments

Raises:

ProcessExecutionError

Raises:

OSError

ironic.common.utils.fast_track_enabled(node)[source]
ironic.common.utils.file_has_content(path, content, hash_algo='sha256')[source]

Checks that content of the file is the same as provided reference.

Parameters:

  • path – path to file

  • content – reference content to check against

  • hash_algo – hashing algo from hashlib to use, default is ‘sha256’

Returns:

True if the hash of reference content is the same as the hash of file’s content, False otherwise

ironic.common.utils.file_mime_type(path)[source]

Gets a mime type of the given file.

ironic.common.utils.find_devices_by_hints(devices, root_device_hints)[source]

Find all devices that match the root device hints.

Try to find devices that match the root device hints. In order for a device to be matched it needs to satisfy all the given hints.

Parameters:

  • devices –

    A list of dictionaries representing the devices

    containing one or more of the following keys:

    name:

    (String) The device name, e.g /dev/sda

    size:

    (Integer) Size of the device in bytes

    model:

    (String) Device model

    vendor:

    (String) Device vendor name

    serial:

    (String) Device serial number

    wwn:

    (String) Unique storage identifier

    wwn_with_extension:

    (String): Unique storage identifier with the vendor extension appended

    wwn_vendor_extension:

    (String): United vendor storage identifier

    rotational:

    (Boolean) Whether it’s a rotational device or not. Useful to distinguish HDDs (rotational) and SSDs (not rotational).

    hctl:

    (String): The SCSI address: Host, channel, target and lun. For example: ‘1:0:0:0’.

    by_path:

    (String): The alternative device name, e.g. /dev/disk/by-path/pci-0000:00

  • root_device_hints – A dictionary with the root device hints.

Raises:

ValueError, if some information is invalid.

Returns:

A generator with all matching devices as dictionaries.

ironic.common.utils.get_route_source(dest, ignore_link_local=True)[source]

Get the IP address to send packages to destination.

ironic.common.utils.get_updated_capabilities(current_capabilities, new_capabilities)[source]

Returns an updated capability string.

This method updates the original (or current) capabilities with the new capabilities. The original capabilities would typically be from a node’s properties[‘capabilities’]. From new_capabilities, any new capabilities are added, and existing capabilities may have their values updated. This updated capabilities string is returned.

Parameters:

  • current_capabilities – Current capability string

  • new_capabilities – the dictionary of capabilities to be updated.

Returns:

An updated capability string. with new_capabilities.

Raises:

ValueError, if current_capabilities is malformed or if new_capabilities is not a dictionary

ironic.common.utils.is_fips_enabled()[source]

Check if FIPS mode is enabled in the system.

ironic.common.utils.is_hostname_safe(hostname)[source]

Old check for valid logical node names.

Retained for compatibility with REST API < 1.10.

Nominally, checks that the supplied hostname conforms to:

In practice, this check has several shortcomings and errors that are more thoroughly documented in bug #1468508.

Parameters:

hostname – The hostname to be validated.

Returns:

True if valid. False if not.

ironic.common.utils.is_http_url(url)[source]
ironic.common.utils.is_ironic_using_sqlite()[source]

Return True if Ironic is configured to use SQLite

ironic.common.utils.is_loopback(hostname_or_ip)[source]

Check if the provided hostname or IP address is a loopback.

ironic.common.utils.is_memory_insufficient(raise_if_fail=False)[source]

Checks available system memory and holds the deployment process.

Evaluates the current system memory available, meaning can be allocated to a process by the kernel upon allocation request, and delays the execution until memory has been freed, or until it has timed out.

This method will issue a sleep, if the amount of available memory is insufficient. This is configured using the [DEFAULT]minimum_memory_wait_time and the [DEFAULT]minimum_memory_wait_retries.

Parameters:

raise_if_fail – Default False, but if set to true an InsufficientMemory exception is raised upon insufficient memory.

Returns:

True if the check has timed out. Otherwise None is returned.

Raises:

InsufficientMemory if the raise_if_fail parameter is set to True.

ironic.common.utils.is_regex_string_in_file(path, string)[source]
ironic.common.utils.is_valid_datapath_id(datapath_id)[source]

Verify the format of an OpenFlow datapath_id.

Check if a datapath_id is valid and contains 16 hexadecimal digits. Datapath ID format: the lower 48-bits are for a MAC address, while the upper 16-bits are implementer-defined.

Parameters:

datapath_id – OpenFlow datapath_id to be validated.

Returns:

True if valid. False if not.

ironic.common.utils.is_valid_logical_name(hostname)[source]

Determine if a logical name is valid.

The logical name may only consist of RFC3986 unreserved characters:

ALPHA / DIGIT / “-” / “.” / “_” / “~”

ironic.common.utils.is_valid_no_proxy(no_proxy)[source]

Check no_proxy validity

Check if no_proxy value that will be written to environment variable by ironic-python-agent is valid.

Parameters:

no_proxy – the value that requires validity check. Expected to be a comma-separated list of host names, IP addresses and domain names (with optional :port).

Returns:

True if no_proxy is valid, False otherwise.

ironic.common.utils.match_root_device_hints(devices, root_device_hints)[source]

Try to find a device that matches the root device hints.

Try to find a device that matches the root device hints. In order for a device to be matched it needs to satisfy all the given hints.

Parameters:

  • devices –

    A list of dictionaries representing the devices

    containing one or more of the following keys:

    name:

    (String) The device name, e.g /dev/sda

    size:

    (Integer) Size of the device in bytes

    model:

    (String) Device model

    vendor:

    (String) Device vendor name

    serial:

    (String) Device serial number

    wwn:

    (String) Unique storage identifier

    wwn_with_extension:

    (String): Unique storage identifier with the vendor extension appended

    wwn_vendor_extension:

    (String): United vendor storage identifier

    rotational:

    (Boolean) Whether it’s a rotational device or not. Useful to distinguish HDDs (rotational) and SSDs (not rotational).

    hctl:

    (String): The SCSI address: Host, channel, target and lun. For example: ‘1:0:0:0’.

    by_path:

    (String): The alternative device name, e.g. /dev/disk/by-path/pci-0000:00

  • root_device_hints – A dictionary with the root device hints.

Raises:

ValueError, if some information is invalid.

Returns:

The first device to match all the hints or None.

ironic.common.utils.mkfs(fs, path, label=None)[source]

Format a file or block device

Parameters:

  • fs – Filesystem type (examples include ‘swap’, ‘ext3’, ‘ext4’ ‘btrfs’, etc.)

  • path – Path to file or block device to format

  • label – Volume label to use

ironic.common.utils.parse_instance_info_capabilities(node)[source]

Parse the instance_info capabilities.

One way of having these capabilities set is via Nova, where the capabilities are defined in the Flavor extra_spec and passed to Ironic by the Nova Ironic driver.

NOTE: Although our API fully supports JSON fields, to maintain the backward compatibility with Juno the Nova Ironic driver is sending it as a string.

Parameters:

node – a single Node.

Raises:

InvalidParameterValue if the capabilities string is not a dictionary or is malformed.

Returns:

A dictionary with the capabilities if found, otherwise an empty dictionary.

ironic.common.utils.parse_kernel_params(params)[source]

Parse kernel parameters into a dictionary.

None is used as a value for parameters that are not in the key=value format.

Parameters:

params – kernel parameters as a space-delimited string.

ironic.common.utils.parse_root_device_hints(root_device)[source]

Parse the root_device property of a node.

Parses and validates the root_device property of a node. These are hints for how a node’s root device is created. The ‘size’ hint should be a positive integer. The ‘rotational’ hint should be a Boolean value.

Parameters:

root_device – the root_device dictionary from the node’s property.

Returns:

a dictionary with the root device hints parsed or None if there are no hints.

Raises:

ValueError, if some information is invalid.

ironic.common.utils.pop_node_nested_field(node, collection, field, default=None)[source]

Pop a value from a dictionary field of a node.

Parameters:

  • node – Node object.

  • collection – Name of the field with the dictionary.

  • field – Nested field name.

  • default – The default value to return.

Returns:

The removed value or the default.

ironic.common.utils.remove_large_keys(var)[source]

Remove specific keys from the var, recursing into dicts and lists.

ironic.common.utils.render_template(template, params, is_file=True, strict=False)[source]

Renders Jinja2 template file with given parameters.

Parameters:

  • template – full path to the Jinja2 template file

  • params – dictionary with parameters to use when rendering

  • is_file – whether template is file or string with template itself

  • strict – Enable strict template rendering. Default is False

Returns:

Rendered template

Raises:

jinja2.exceptions.UndefinedError

ironic.common.utils.rmtree_without_raise(path)[source]
ironic.common.utils.safe_rstrip(value, chars=None)[source]

Removes trailing characters from a string if that does not make it empty

Parameters:

  • value – A string value that will be stripped.

  • chars – Characters to remove.

Returns:

Stripped value.

ironic.common.utils.set_node_nested_field(node, collection, field, value)[source]

Set a value in a dictionary field of a node.

Parameters:

  • node – Node object.

  • collection – Name of the field with the dictionary.

  • field – Nested field name.

  • value – New value.

ironic.common.utils.stop_after_retries(option, group=None)[source]

A tenacity retry helper that stops after retries specified in conf.

ironic.common.utils.tempdir(**kwargs)[source]
ironic.common.utils.try_execute(*cmd, **kwargs)[source]

The same as execute but returns None on error.

Executes and logs results from a system command. See docs for oslo_concurrency.processutils.execute for usage.

Instead of raising an exception on failure, this method simply returns None in case of failure.

Parameters:

  • cmd – positional arguments to pass to processutils.execute()

  • kwargs – keyword arguments to pass to processutils.execute()

Raises:

UnknownArgumentError on receiving unknown arguments

Returns:

tuple of (stdout, stderr) or None in some error cases

ironic.common.utils.unix_file_modification_datetime(file_name)[source]
ironic.common.utils.validate_and_normalize_datapath_id(datapath_id)[source]

Validate an OpenFlow datapath_id and return normalized form.

Checks whether the supplied OpenFlow datapath_id is formally correct and normalize it to all lower case.

Parameters:

datapath_id – OpenFlow datapath_id to be validated and normalized.

Returns:

Normalized and validated OpenFlow datapath_id.

Raises:

InvalidDatapathID If an OpenFlow datapath_id is not valid.

ironic.common.utils.validate_and_normalize_mac(address)[source]

Validate a MAC address and return normalized form.

Checks whether the supplied MAC address is formally correct and normalize it to all lower case.

Parameters:

address – MAC address to be validated and normalized.

Returns:

Normalized and validated MAC address.

Raises:

InvalidMAC If the MAC address is not valid.

ironic.common.utils.validate_conductor_group(conductor_group)[source]
ironic.common.utils.validate_network_port(port, port_name='Port')[source]

Validates the given port.

Parameters:

  • port – TCP/UDP port.

  • port_name – Name of the port.

Returns:

An integer port number.

Raises:

InvalidParameterValue, if the port is invalid.

ironic.common.utils.wrap_ipv6(ip)[source]

Wrap the address in square brackets if it’s an IPv6 address.

ironic.common.utils.write_to_file(path, contents, permission=None)[source]