ironic-lib(1)

IRONIC-LIB(1)

ironic-lib

IRONIC-LIB(1)

NAME

ironic-lib - ironic-lib 7.0.0

Ironic-lib is a library for use by projects under Bare Metal governance only. This documentation is intended for developer use only. If you are looking for documentation for deployers, please see the ironic documentation.

WELCOME TO IRONIC-LIB!

Overview

Metrics

Ironic-lib provides a pluggable metrics library as of the 2.0.0 release. Current provided backends are the default, 'noop', which discards all data, and 'statsd', which emits metrics to a statsd daemon over the network. The metrics backend to be used is configured via CONF.metrics.backend. How this configuration is set in practice may vary by project.

The typical usage of metrics is to initialize and cache a metrics logger, using the get_metrics_logger() method in ironic_lib.metrics_utils, then use that object to decorate functions or create context managers to gather metrics. The general convention is to provide the name of the module as the first argument to set it as the prefix, then set the actual metric name to the method name. For example:

from ironic_lib import metrics_utils
METRICS = metrics_utils.get_metrics_logger(__name__)
@METRICS.timer('my_simple_method')
def my_simple_method(arg, matey):


    pass
def my_complex_method(arg, matey):


    with METRICS.timer('complex_method_pt_1'):


        do_some_work()


    with METRICS.timer('complex_method_pt_2'):


        do_more_work()

There are three different kinds of metrics:

Timers measure how long the code in the decorated method or context manager takes to execute, and emits the value as a timer metric. These are useful for measuring performance of a given block of code.
Counters increment a counter each time a decorated method or context manager is executed. These are useful for counting the number of times a method is called, or the number of times an event occurs.
Gauges return the value of a decorated method as a metric. This is useful when you want to monitor the value returned by a method over time.

Additionally, metrics can be sent directly, rather than using a context manager or decorator, when appropriate. When used in this way, ironic-lib will simply emit the value provided as the requested metric type. For example:

from ironic_lib import metrics_utils
METRICS = metrics_utils.get_metrics_logger(__name__)
def my_node_failure_method(node):


    if node.failed:


        METRICS.send_counter(node.uuid, 1)

The provided statsd backend natively supports all three metric types. For more information about how statsd changes behavior based on the metric type, see statsd metric types

AUTOGENERATED API REFERENCE

ironic_lib

ironic_lib package

Subpackages

ironic_lib.common package

Submodules

ironic_lib.common.config module

class ironic_lib.common.config.Octal(min=None, max=None, type_name='integer value', choices=None): Bases: Integer

ironic_lib.common.i18n module

Module contents

ironic_lib.json_rpc package

Submodules

ironic_lib.json_rpc.client module

A simple JSON RPC client.

This client is compatible with any JSON RPC 2.0 implementation, including ours.

class ironic_lib.json_rpc.client.Client(serializer, version_cap=None): Bases: object
JSON RPC client with ironic exception handling.

allowed_exception_namespaces = ['ironic_lib.exception.', 'ironic.common.exception.', 'ironic_inspector.utils.']

can_send_version(version)

prepare(topic, version=None): Prepare the client to transmit a request.

Parameters

topic -- Topic which is being addressed. Typically this is the hostname of the remote json-rpc service.
version -- The RPC API version to utilize.

ironic_lib.json_rpc.server module

Implementation of JSON RPC for communication between API and conductors.

This module implementa a subset of JSON RPC 2.0 as defined in https://www.jsonrpc.org/specification. Main differences: * No support for batched requests. * No support for positional arguments passing. * No JSON RPC 1.0 fallback.

class ironic_lib.json_rpc.server.EmptyContext(src): Bases: object

request_id = None

to_dict()

exception ironic_lib.json_rpc.server.InvalidParams(message=None, **kwargs): Bases: JsonRpcError

code = -32602

exception ironic_lib.json_rpc.server.InvalidRequest(message=None, **kwargs): Bases: JsonRpcError

code = -32600

exception ironic_lib.json_rpc.server.JsonRpcError(message=None, **kwargs): Bases: IronicException

exception ironic_lib.json_rpc.server.MethodNotFound(message=None, **kwargs): Bases: JsonRpcError

code = -32601

exception ironic_lib.json_rpc.server.ParseError(message=None, **kwargs): Bases: JsonRpcError

code = -32700

class ironic_lib.json_rpc.server.WSGIService(manager, serializer, context_class=<class 'ironic_lib.json_rpc.server.EmptyContext'>): Bases: WSGIService
Provides ability to launch JSON RPC as a WSGI application.

Module contents

ironic_lib.json_rpc.auth_strategy()

ironic_lib.json_rpc.list_opts()

ironic_lib.json_rpc.register_opts(conf)

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.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 -- .INDENT 2.0

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 -- .INDENT 2.0

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

Index
Search Page

AUTHOR

Author name not set

COPYRIGHT

OpenStack Foundation

November 28, 2024

7.0.0