ironic_lib package

Subpackages

• ironic_lib.common package
  • Submodules
  • ironic_lib.common.config module
    • Octal
  • ironic_lib.common.i18n module
  • Module contents
• ironic_lib.json_rpc package
  • Submodules
  • ironic_lib.json_rpc.client module
    • Client
      • Client.allowed_exception_namespaces
      • Client.can_send_version()
      • Client.prepare()
  • ironic_lib.json_rpc.server module
    • EmptyContext
      • EmptyContext.request_id
      • EmptyContext.to_dict()
    • InvalidParams
      • InvalidParams.code
    • InvalidRequest
      • InvalidRequest.code
    • JsonRpcError
    • MethodNotFound
      • MethodNotFound.code
    • ParseError
      • ParseError.code
    • WSGIService
  • Module contents
    • auth_strategy()
    • list_opts()
    • register_opts()

Submodules

ironic_lib.auth_basic module

class ironic_lib.auth_basic.BasicAuthMiddleware(app, auth_file)

Bases: object

Middleware which performs HTTP basic authentication on requests

format_exception(e)

ironic_lib.auth_basic.auth_entry(entry, password)

Compare a password with a single user auth file entry

Param:

entry: Line from auth user file to use for authentication

Param:

password: Password encoded as bytes

Returns:

A dictionary of WSGI environment values to append to the request

Raises:

Unauthorized, if the entry doesn’t match supplied password or if the entry is crypted with a method other than bcrypt

ironic_lib.auth_basic.authenticate(auth_file, username, password)

Finds username and password match in Apache style user auth file

The user auth file format is expected to comply with Apache documentation[1] however the bcrypt password digest is the only digest format supported.

[1] https://httpd.apache.org/docs/current/misc/password_encryptions.html

Param:

auth_file: Path to user auth file

Param:

username: Username to authenticate

Param:

password: Password encoded as bytes

Returns:

A dictionary of WSGI environment values to append to the request

Raises:

Unauthorized, if no file entries match supplied username/password

ironic_lib.auth_basic.parse_entry(entry)

Extrace the username and crypted password from a user auth file entry

Param:

entry: Line from auth user file to use for authentication

Returns:

a tuple of username and crypted password

Raises:

ConfigInvalid if the password is not in the supported bcrypt format

ironic_lib.auth_basic.parse_header(env)

Parse WSGI environment for Authorization header of type Basic

Param:

env: WSGI environment to get header from

Returns:

Token portion of the header value

Raises:

Unauthorized, if header is missing or if the type is not Basic

ironic_lib.auth_basic.parse_token(token)

Parse the token portion of the Authentication header value

Param:

token: Token value from basic authorization header

Returns:

tuple of username, password

Raises:

Unauthorized, if username and password could not be parsed for any reason

ironic_lib.auth_basic.unauthorized(message=None)

Raise an Unauthorized exception to prompt for basic authentication

Param:

message: Optional message for esception

Raises:

Unauthorized with WWW-Authenticate header set

ironic_lib.auth_basic.validate_auth_file(auth_file)

Read the auth user file and validate its correctness

Param:

auth_file: Path to user auth file

Raises:

ConfigInvalid on validation error

ironic_lib.capabilities module

Code for working with capabilities.

ironic_lib.capabilities.combine(capabilities_dict, skip_none=False)

Combine capabilities into the old format.

Parameters:

• capabilities_dict – Capabilities as a mapping.

• skip_none – If True, skips all items with value of None.

Returns:

Capabilities as a string key1:value1,key2:value2.

ironic_lib.capabilities.parse(capabilities, compat=True, skip_malformed=False)

Extract capabilities from provided object.

The capabilities value can either be a dict, or a json str, or a key1:value1,key2:value2 formatted string (if compat is True). If None, an empty dictionary is returned.

Parameters:

• capabilities – The capabilities value. Can either be a dict, or a json str, or a key1:value1,key2:value2 formatted string (if compat is True).

• compat – Whether to parse the old format key1:value1,key2:value2.

• skip_malformed – Whether to skip malformed items or raise ValueError.

Returns:

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

Raises:

TypeError if the capabilities are of invalid type.

Raises:

ValueError on a malformed capability if skip_malformed is False or on invalid JSON with compat is False.

ironic_lib.capabilities.update_and_combine(capabilities, new_values, skip_malformed=False, skip_none=False)

Parses capabilities, updated them with new values and re-combines.

Parameters:

• capabilities – The capabilities value. Can either be a dict, or a json str, or a key1:value1,key2:value2 formatted string (if compat is True).

• new_values – New values as a dictionary.

• skip_malformed – Whether to skip malformed items or raise ValueError.

• skip_none – If True, skips all items with value of None.

Returns:

Capabilities in the old format (key1:value1,key2:value2).

Raises:

TypeError if the capabilities are of invalid type.

Raises:

ValueError on a malformed capability if skip_malformed is False.

ironic_lib.exception module

Ironic base exception handling.

Includes decorator for re-raising Ironic-type exceptions.

SHOULD include dedicated exception logging.

exception ironic_lib.exception.BadRequest(message=None, **kwargs)

Bases: IronicException

code = 400

exception ironic_lib.exception.CatalogNotFound(message=None, **kwargs)

Bases: IronicException

exception ironic_lib.exception.ConfigInvalid(message=None, **kwargs)

Bases: IronicException

exception ironic_lib.exception.FileSystemNotSupported(message=None, **kwargs)

Bases: IronicException

exception ironic_lib.exception.InstanceDeployFailure(message=None, **kwargs)

Bases: IronicException

exception ironic_lib.exception.InvalidMetricConfig(message=None, **kwargs)

Bases: IronicException

exception ironic_lib.exception.IronicException(message=None, **kwargs)

Bases: Exception

Base Ironic Exception

To correctly use this class, inherit from it and define a ‘_msg_fmt’ property. That _msg_fmt will get printf’d with the keyword arguments provided to the constructor.

If you need to access the message from an exception you should use str(exc)

code = 500

headers = {}

safe = False

exception ironic_lib.exception.KeystoneFailure(message=None, **kwargs)

Bases: IronicException

exception ironic_lib.exception.KeystoneUnauthorized(message=None, **kwargs)

Bases: IronicException

exception ironic_lib.exception.MetricsNotSupported(message=None, **kwargs)

Bases: IronicException

exception ironic_lib.exception.ServiceLookupFailure(message=None, **kwargs)

Bases: IronicException

exception ironic_lib.exception.ServiceRegistrationFailure(message=None, **kwargs)

Bases: IronicException

exception ironic_lib.exception.Unauthorized(message=None, **kwargs)

Bases: IronicException

code = 401

headers = {'WWW-Authenticate': 'Basic realm="Baremetal API"'}

ironic_lib.exception.list_opts()

Entry point for oslo-config-generator.

ironic_lib.keystone module

Central place for handling Keystone authorization and service lookup.

ironic_lib.keystone.add_auth_opts(options, service_type=None)

Add auth options to sample config

As these are dynamically registered at runtime, this adds options for most used auth_plugins when generating sample config.

ironic_lib.keystone.get_adapter(group, **adapter_kwargs)

Loads adapter from options in a configuration file section.

The adapter_kwargs will be passed directly to keystoneauth1 Adapter and will override the values loaded from config. Consult keystoneauth1 docs for available adapter options.

Parameters:

group – name of the config section to load adapter options from

ironic_lib.keystone.get_auth(group, **auth_kwargs)

Loads auth plugin from options in a configuration file section.

The auth_kwargs will be passed directly to keystoneauth1 auth plugin and will override the values loaded from config. Note that the accepted kwargs will depend on auth plugin type as defined by [group]auth_type option. Consult keystoneauth1 docs for available auth plugins and their options.

Parameters:

group – name of the config section to load auth plugin options from

ironic_lib.keystone.get_endpoint(group, **adapter_kwargs)

Get an endpoint from an adapter.

The adapter_kwargs will be passed directly to keystoneauth1 Adapter and will override the values loaded from config. Consult keystoneauth1 docs for available adapter options.

Parameters:

group – name of the config section to load adapter options from

Raises:

CatalogNotFound if the endpoint is not found

ironic_lib.keystone.get_service_auth(context, endpoint, service_auth)

Create auth plugin wrapping both user and service auth.

When properly configured and using auth_token middleware, requests with valid service auth will not fail if the user token is expired.

Ideally we would use the plugin provided by auth_token middleware however this plugin isn’t serialized yet.

ironic_lib.keystone.get_session(group, **session_kwargs)

Loads session object from options in a configuration file section.

The session_kwargs will be passed directly to keystoneauth1 Session and will override the values loaded from config. Consult keystoneauth1 docs for available options.

Parameters:

group – name of the config section to load session options from

ironic_lib.keystone.ks_exceptions(f)

Wraps keystoneclient functions and centralizes exception handling.

ironic_lib.keystone.register_auth_opts(conf, group, service_type=None)

Register session- and auth-related options

Registers only basic auth options shared by all auth plugins. The rest are registered at runtime depending on auth plugin used.

ironic_lib.mdns module

Multicast DNS implementation for API discovery.

This implementation follows RFC 6763 as clarified by the API SIG guideline https://review.opendev.org/651222.

class ironic_lib.mdns.Zeroconf

Bases: object

Multicast DNS implementation client and server.

Uses threading internally, so there is no start method. It starts automatically on creation.

Warning

The underlying library does not yet support IPv6.

close()

Shut down mDNS and unregister services.

Note

If another server is running for the same services, it will re-register them immediately.

get_endpoint(service_type, skip_loopback=True, skip_link_local=False)

Get an endpoint and its properties from mDNS.

If the requested endpoint is already in the built-in server cache, and its TTL is not exceeded, the cached value is returned.

Parameters:

• service_type – OpenStack service type.

• skip_loopback – Whether to ignore loopback addresses.

• skip_link_local – Whether to ignore link local V6 addresses.

Returns:

tuple (endpoint URL, properties as a dict).

Raises:

ServiceLookupFailure if the service cannot be found.

register_service(service_type, endpoint, params=None)

Register a service.

This call announces the new services via multicast and instructs the built-in server to respond to queries about it.

Parameters:

• service_type – OpenStack service type, e.g. “baremetal”.

• endpoint – full endpoint to reach the service.

• params – optional properties as a dictionary.

Raises:

ServiceRegistrationFailure if the service cannot be registered, e.g. because of conflicts.

ironic_lib.mdns.get_endpoint(service_type)

Get an endpoint and its properties from mDNS.

If the requested endpoint is already in the built-in server cache, and its TTL is not exceeded, the cached value is returned.

Parameters:

service_type – OpenStack service type.

Returns:

tuple (endpoint URL, properties as a dict).

Raises:

ServiceLookupFailure if the service cannot be found.

ironic_lib.mdns.list_opts()

Entry point for oslo-config-generator.

ironic_lib.metrics module

class ironic_lib.metrics.Counter(metrics, name, sample_rate)

Bases: object

A counter decorator and context manager.

This metric type increments a counter every time the decorated method or context manager is executed. It is bound to this MetricLogger. For example:

from ironic_lib import metrics_utils

METRICS = metrics_utils.get_metrics_logger()

@METRICS.counter('foo')
def foo(bar, baz):
    print bar, baz

with METRICS.counter('foo'):
    do_something()

class ironic_lib.metrics.Gauge(metrics, name)

Bases: object

A gauge decorator.

This metric type returns the value of the decorated method as a metric every time the method is executed. It is bound to this MetricLogger. For example:

from ironic_lib import metrics_utils

METRICS = metrics_utils.get_metrics_logger()

@METRICS.gauge('foo')
def add_foo(bar, baz):
    return (bar + baz)

class ironic_lib.metrics.MetricLogger(prefix='', delimiter='.')

Bases: object

Abstract class representing a metrics logger.

A MetricLogger sends data to a backend (noop or statsd). The data can be a gauge, a counter, or a timer.

The data sent to the backend is composed of:

• a full metric name

• a numeric value

The format of the full metric name is:

_prefix<delim>name

where:

• _prefix: [global_prefix<delim>][uuid<delim>][host_name<delim>]prefix

• name: the name of this metric

• <delim>: the delimiter. Default is ‘.’

counter(name, sample_rate=None)

gauge(name)

get_metric_name(name)

Get the full metric name.

The format of the full metric name is:

_prefix<delim>name

where:

• _prefix: [global_prefix<delim>][uuid<delim>][host_name<delim>] prefix

• name: the name of this metric

• <delim>: the delimiter. Default is ‘.’

Parameters:

name – The metric name.

Returns:

The full metric name, with logger prefix, as a string.

get_metrics_data()

Return the metrics collection, if available.

send_counter(name, value, sample_rate=None)

Send counter metric data.

Counters are used to count how many times an event occurred. The backend will increment the counter ‘name’ by the value ‘value’.

Optionally, specify sample_rate in the interval [0.0, 1.0] to sample data probabilistically where:

P(send metric data) = sample_rate

If sample_rate is None, then always send metric data, but do not have the backend send sample rate information (if supported).

Parameters:

• name – Metric name

• value – Metric numeric value that will be sent to the backend

• sample_rate – Probabilistic rate at which the values will be sent. Value must be None or in the interval [0.0, 1.0].

send_gauge(name, value)

Send gauge metric data.

Gauges are simple values. The backend will set the value of gauge ‘name’ to ‘value’.

Parameters:

• name – Metric name

• value – Metric numeric value that will be sent to the backend

send_timer(name, value)

Send timer data.

Timers are used to measure how long it took to do something.

Parameters:

• m_name – Metric name

• m_value – Metric numeric value that will be sent to the backend

timer(name)

class ironic_lib.metrics.NoopMetricLogger(prefix='', delimiter='.')

Bases: MetricLogger

Noop metric logger that throws away all metric data.

class ironic_lib.metrics.Timer(metrics, name)

Bases: object

A timer decorator and context manager.

This metric type times the decorated method or code running inside the context manager, and emits the time as the metric value. It is bound to this MetricLogger. For example:

from ironic_lib import metrics_utils

METRICS = metrics_utils.get_metrics_logger()

@METRICS.timer('foo')
def foo(bar, baz):
    print bar, baz

with METRICS.timer('foo'):
    do_something()

ironic_lib.metrics_collector module

class ironic_lib.metrics_collector.DictCollectionMetricLogger(prefix, delimiter='.')

Bases: MetricLogger

Metric logger that collects internal counters.

COUNTER_TYPE = 'c'

GAUGE_TYPE = 'g'

TIMER_TYPE = 'ms'

get_metrics_data()

Return the metrics collection dictionary.

Returns:

Dictionary containing the keys and values of data stored via the metrics collection hooks. The values themselves are dictionaries which contain a type field, indicating if the statistic is a counter, gauge, or timer. A counter has a count field, a gauge value has a value field, and a ‘timer’ fiend las a ‘count’ and ‘sum’ fields. The multiple fields for for a timer type allows for additional statistics to be implied from the data once collected and compared over time.

ironic_lib.metrics_statsd module

class ironic_lib.metrics_statsd.StatsdMetricLogger(prefix, delimiter='.', host=None, port=None)

Bases: MetricLogger

Metric logger that reports data via the statsd protocol.

COUNTER_TYPE = 'c'

GAUGE_TYPE = 'g'

TIMER_TYPE = 'ms'

ironic_lib.metrics_statsd.list_opts()

Entry point for oslo-config-generator.

ironic_lib.metrics_utils module

ironic_lib.metrics_utils.get_metrics_logger(prefix='', backend=None, host=None, delimiter='.')

Return a metric logger with the specified prefix.

The format of the prefix is: [global_prefix<delim>][host_name<delim>]prefix where <delim> is the delimiter (default is ‘.’)

Parameters:

• prefix – Prefix for this metric logger. Value should be a string or None.

• backend – Backend to use for the metrics system. Possible values are ‘noop’ and ‘statsd’.

• host – Name of this node.

• delimiter – Delimiter to use for the metrics name.

Returns:

The new MetricLogger.

ironic_lib.metrics_utils.list_opts()

Entry point for oslo-config-generator.

ironic_lib.utils module

Utilities and helper functions.

ironic_lib.utils.dd(src, dst, *args)

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_lib.utils.execute(*cmd, use_standard_locale=False, log_stdout=True, **kwargs)

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_lib.utils.find_devices_by_hints(devices, root_device_hints)

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_lib.utils.get_route_source(dest, ignore_link_local=True)

Get the IP address to send packages to destination.

ironic_lib.utils.is_http_url(url)

ironic_lib.utils.list_opts()

Entry point for oslo-config-generator.

ironic_lib.utils.match_root_device_hints(devices, root_device_hints)

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_lib.utils.mkfs(fs, path, label=None)

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_lib.utils.mounted(source, dest=None, opts=None, fs_type=None, mount_attempts=1, umount_attempts=3)

A context manager for a temporary mount.

Parameters:

• source – A device to mount.

• dest – Mount destination. If not specified, a temporary directory will be created and removed afterwards. An existing destination is not removed.

• opts – Mount options (-o argument).

• fs_type – File system type (-t argument).

• mount_attempts – A number of attempts to mount the device.

• umount_attempts – A number of attempts to unmount the device.

Returns:

A generator yielding the destination.

ironic_lib.utils.parse_device_tags(output)

Parse tags from the lsblk/blkid output.

Parses format KEY=”VALUE” KEY2=”VALUE2”.

Returns:

a generator yielding dicts with information from each line.

ironic_lib.utils.parse_root_device_hints(root_device)

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_lib.utils.try_execute(*cmd, **kwargs)

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_lib.utils.unlink_without_raise(path)

ironic_lib.wsgi module

class ironic_lib.wsgi.WSGIService(name, app, conf)

Bases: ServiceBase

reset()

Reset server greenpool size to default.

Returns:

None

start()

Start serving this service using loaded configuration.

Returns:

None

stop()

Stop serving this API.

Returns:

None

wait()

Wait for the service to stop serving this API.

Returns:

None

Module contents