The ironic.drivers.base Module

Abstract base classes for drivers.

class ironic.drivers.base.BareDriver

Bases: ironic.drivers.base.BaseDriver

A bare driver object which will have interfaces attached later.

Any composable interfaces should be added as class attributes of this class, as well as appended to core_interfaces or standard_interfaces here.

class ironic.drivers.base.BaseDriver

Bases: object

Base class for all drivers.

Defines the core, standardized, and vendor-specific interfaces for drivers. Any loadable driver must implement all core interfaces. Actual implementation may instantiate one or more classes, as long as the interfaces are appropriate.

get_properties()

Get the properties of the driver.

Returns:dictionary of <property name>:<property description> entries.

class ironic.drivers.base.BaseInterface

Bases: object

A base interface implementing common functions for Driver Interfaces.

execute_clean_step(task, step)

Execute the clean step on task.node.

A clean step must take a single positional argument: a TaskManager object. It may take one or more keyword variable arguments (for use with manual cleaning only.)

A step can be executed synchronously or asynchronously. A step should return None if the method has completed synchronously or states.CLEANWAIT if the step will continue to execute asynchronously. If the step executes asynchronously, it should issue a call to the ‘continue_node_clean’ RPC, so the conductor can begin the next clean step.

Parameters:

• task – A TaskManager object
• step – The clean step dictionary representing the step to execute

Returns:

None if this method has completed synchronously, or states.CLEANWAIT if the step will continue to execute asynchronously.

get_clean_steps(task)

Get a list of (enabled and disabled) clean steps for the interface.

This function will return all clean steps (both enabled and disabled) for the interface, in an unordered list.

Parameters:task – A TaskManager object, useful for interfaces overriding this function Raises NodeCleaningFailure:  if there is a problem getting the steps from the driver. For example, when a node (using an agent driver) has just been enrolled and the agent isn’t alive yet to be queried for the available clean steps. Returns:A list of clean step dictionaries

class ironic.drivers.base.BootInterface

Bases: object

Interface for boot-related actions.

clean_up_instance(task)

Cleans up the boot of instance.

This method cleans up the environment that was setup for booting the instance.

Parameters:task – a task from TaskManager. Returns:None

clean_up_ramdisk(task)

Cleans up the boot of ironic ramdisk.

This method cleans up the environment that was setup for booting the deploy ramdisk.

Parameters:task – a task from TaskManager. Returns:None

get_properties()

Return the properties of the interface.

Returns:dictionary of <property name>:<property description> entries.

prepare_instance(task)

Prepares the boot of instance.

This method prepares the boot of the instance after reading relevant information from the node’s database.

Parameters:task – a task from TaskManager. Returns:None

prepare_ramdisk(task, ramdisk_params)

Prepares the boot of Ironic ramdisk.

This method prepares the boot of the deploy ramdisk after reading relevant information from the node’s database.

Parameters:

• task – a task from TaskManager.
• ramdisk_params –

  the options to be passed to the ironic ramdisk. Different implementations might want to boot the ramdisk in different ways by passing parameters to them. For example,

  • When DIB ramdisk is booted to deploy a node, it takes the parameters iscsi_target_iqn, deployment_id, ironic_api_url, etc.
  • When Agent ramdisk is booted to deploy a node, it takes the parameters ipa-driver-name, ipa-api-url, root_device, etc.

  Other implementations can make use of ramdisk_params to pass such information. Different implementations of boot interface will have different ways of passing parameters to the ramdisk.

Returns:

None

validate(task)

Validate the driver-specific info for booting.

This method validates the driver-specific info for booting the ramdisk and instance on the node. If invalid, raises an exception; otherwise returns None.

Parameters:task – a task from TaskManager. Returns:None Raises:InvalidParameterValue Raises:MissingParameterValue

class ironic.drivers.base.ConsoleInterface

Bases: object

Interface for console-related actions.

get_console(task)

Get connection information about the console.

This method should return the necessary information for the client to access the console.

Parameters:task – a TaskManager instance containing the node to act on. Returns:the console connection information.

get_properties()

Return the properties of the interface.

Returns:dictionary of <property name>:<property description> entries.

start_console(task)

Start a remote console for the task’s node.

Parameters:task – a TaskManager instance containing the node to act on.

stop_console(task)

Stop the remote console session for the task’s node.

Parameters:task – a TaskManager instance containing the node to act on.

validate(task)

Validate the driver-specific Node console info.

This method validates whether the ‘driver_info’ property of the supplied node contains the required information for this driver to provide console access to the Node. If invalid, raises an exception; otherwise returns None.

Parameters:task – a TaskManager instance containing the node to act on. Raises:InvalidParameterValue Raises:MissingParameterValue

class ironic.drivers.base.DeployInterface

Bases: ironic.drivers.base.BaseInterface

Interface for deploy-related actions.

clean_up(task)

Clean up the deployment environment for the task’s node.

If preparation of the deployment environment ahead of time is possible, this method should be implemented by the driver. It should erase anything cached by the prepare method.

If implemented, this method must be idempotent. It may be called multiple times for the same node on the same conductor, and it may be called by multiple conductors in parallel. Therefore, it must not require an exclusive lock.

This method is called before tear_down.

Parameters:task – a TaskManager instance containing the node to act on.

deploy(task)

Perform a deployment to the task’s node.

Perform the necessary work to deploy an image onto the specified node. This method will be called after prepare(), which may have already performed any preparatory steps, such as pre-caching some data for the node.

Parameters:task – a TaskManager instance containing the node to act on. Returns:status of the deploy. One of ironic.common.states.

get_properties()

Return the properties of the interface.

Returns:dictionary of <property name>:<property description> entries.

prepare(task)

Prepare the deployment environment for the task’s node.

If preparation of the deployment environment ahead of time is possible, this method should be implemented by the driver.

If implemented, this method must be idempotent. It may be called multiple times for the same node on the same conductor, and it may be called by multiple conductors in parallel. Therefore, it must not require an exclusive lock.

This method is called before deploy.

Parameters:task – a TaskManager instance containing the node to act on.

prepare_cleaning(task)

Prepare the node for cleaning tasks.

For example, nodes that use the Ironic Python Agent will need to boot the ramdisk in order to do in-band cleaning tasks.

If the function is asynchronous, the driver will need to handle settings node.driver_internal_info[‘clean_steps’] and node.clean_step, as they would be set in ironic.conductor.manager._do_node_clean, but cannot be set when this is asynchronous. After, the interface should make an RPC call to continue_node_cleaning to start cleaning.

NOTE(JoshNang) this should be moved to BootInterface when it gets implemented.

Parameters:task – a TaskManager instance containing the node to act on. Returns:If this function is going to be asynchronous, should return states.CLEANWAIT. Otherwise, should return None. The interface will need to call _get_cleaning_steps and then RPC to continue_node_cleaning

take_over(task)

Take over management of this task’s node from a dead conductor.

If conductors’ hosts maintain a static relationship to nodes, this method should be implemented by the driver to allow conductors to perform the necessary work during the remapping of nodes to conductors when a conductor joins or leaves the cluster.

For example, the PXE driver has an external dependency:

Neutron must forward DHCP BOOT requests to a conductor which has prepared the tftpboot environment for the given node. When a conductor goes offline, another conductor must change this setting in Neutron as part of remapping that node’s control to itself. This is performed within the takeover method.

Parameters:task – a TaskManager instance containing the node to act on.

tear_down(task)

Tear down a previous deployment on the task’s node.

Given a node that has been previously deployed to, do all cleanup and tear down necessary to “un-deploy” that node.

Parameters:task – a TaskManager instance containing the node to act on. Returns:status of the deploy. One of ironic.common.states.

tear_down_cleaning(task)

Tear down after cleaning is completed.

Given that cleaning is complete, do all cleanup and tear down necessary to allow the node to be deployed to again.

NOTE(JoshNang) this should be moved to BootInterface when it gets implemented.

Parameters:task – a TaskManager instance containing the node to act on.

validate(task)

Validate the driver-specific Node deployment info.

This method validates whether the ‘driver_info’ property of the task’s node contains the required information for this driver to deploy images to the node. If invalid, raises an exception; otherwise returns None.

Parameters:task – a TaskManager instance containing the node to act on. Raises:InvalidParameterValue Raises:MissingParameterValue

class ironic.drivers.base.InspectInterface

Bases: object

Interface for inspection-related actions.

get_properties()

Return the properties of the interface.

Returns:dictionary of <property name>:<property description> entries.

inspect_hardware(task)

Inspect hardware.

Inspect hardware to obtain the essential & additional hardware properties.

Parameters:task – a task from TaskManager. Raises:HardwareInspectionFailure, if unable to get essential hardware properties. Returns:resulting state of the inspection i.e. states.MANAGEABLE or None.

validate(task)

Validate the driver-specific inspection information.

If invalid, raises an exception; otherwise returns None.

Parameters:task – a task from TaskManager. Raises:InvalidParameterValue Raises:MissingParameterValue

class ironic.drivers.base.ManagementInterface

Bases: ironic.drivers.base.BaseInterface

Interface for management related actions.

get_boot_device(task)

Get the current boot device for a node.

Provides the current boot device of the node. Be aware that not all drivers support this.

Parameters:task – a task from TaskManager. Raises:MissingParameterValue if a required parameter is missing Returns:a dictionary containing:

boot_device:the boot device, one of ironic.common.boot_devices or None if it is unknown. persistent:Whether the boot device will persist to all future boots or not, None if it is unknown.

get_properties()

Return the properties of the interface.

Returns:dictionary of <property name>:<property description> entries.

get_sensors_data(task)

Get sensors data method.

Parameters:task – a TaskManager instance. Raises:FailedToGetSensorData when getting the sensor data fails. Raises:FailedToParseSensorData when parsing sensor data fails. Returns:returns a consistent format dict of sensor data grouped by sensor type, which can be processed by Ceilometer. eg,

{
  'Sensor Type 1': {
    'Sensor ID 1': {
      'Sensor Reading': 'current value',
      'key1': 'value1',
      'key2': 'value2'
    },
    'Sensor ID 2': {
      'Sensor Reading': 'current value',
      'key1': 'value1',
      'key2': 'value2'
    }
  },
  'Sensor Type 2': {
    'Sensor ID 3': {
      'Sensor Reading': 'current value',
      'key1': 'value1',
      'key2': 'value2'
    },
    'Sensor ID 4': {
      'Sensor Reading': 'current value',
      'key1': 'value1',
      'key2': 'value2'
    }
  }
}

get_supported_boot_devices(task)

Get a list of the supported boot devices.

Parameters:task – a task from TaskManager. Returns:A list with the supported boot devices defined in ironic.common.boot_devices.

set_boot_device(task, device, persistent=False)

Set the boot device for a node.

Set the boot device to use on next reboot of the node.

Parameters:

• task – a task from TaskManager.
• device – the boot device, one of ironic.common.boot_devices.
• persistent – Boolean value. True if the boot device will persist to all future boots, False if not. Default: False.

Raises:

InvalidParameterValue if an invalid boot device is specified.

Raises:

MissingParameterValue if a required parameter is missing

validate(task)

Validate the driver-specific management information.

If invalid, raises an exception; otherwise returns None.

Parameters:task – a task from TaskManager. Raises:InvalidParameterValue Raises:MissingParameterValue

class ironic.drivers.base.PowerInterface

Bases: ironic.drivers.base.BaseInterface

Interface for power-related actions.

get_power_state(task)

Return the power state of the task’s node.

Parameters:task – a TaskManager instance containing the node to act on. Raises:MissingParameterValue if a required parameter is missing. Returns:a power state. One of ironic.common.states.

get_properties()

Return the properties of the interface.

Returns:dictionary of <property name>:<property description> entries.

reboot(task)

Perform a hard reboot of the task’s node.

Drivers are expected to properly handle case when node is powered off by powering it on.

Parameters:task – a TaskManager instance containing the node to act on. Raises:MissingParameterValue if a required parameter is missing.

set_power_state(task, power_state)

Set the power state of the task’s node.

Parameters:

• task – a TaskManager instance containing the node to act on.
• power_state – Any power state from ironic.common.states.

Raises:

MissingParameterValue if a required parameter is missing.

validate(task)

Validate the driver-specific Node power info.

This method validates whether the ‘driver_info’ property of the supplied node contains the required information for this driver to manage the power state of the node. If invalid, raises an exception; otherwise, returns None.

Parameters:task – a TaskManager instance containing the node to act on. Raises:InvalidParameterValue Raises:MissingParameterValue

class ironic.drivers.base.RAIDInterface

Bases: ironic.drivers.base.BaseInterface

create_configuration(task, create_root_volume=True, create_nonroot_volumes=True)

Creates RAID configuration on the given node.

This method creates a RAID configuration on the given node. It assumes that the target RAID configuration is already available in node.target_raid_config. Implementations of this interface are supposed to read the RAID configuration from node.target_raid_config. After the RAID configuration is done (either in this method OR in a call-back method), ironic.common.raid.update_raid_info() may be called to sync the node’s RAID-related information with the RAID configuration applied on the node.

Parameters:

• task – a TaskManager instance.
• create_root_volume – Setting this to False indicates not to create root volume that is specified in the node’s target_raid_config. Default value is True.
• create_nonroot_volumes – Setting this to False indicates not to create non-root volumes (all except the root volume) in the node’s target_raid_config. Default value is True.

Returns:

states.CLEANWAIT if RAID configuration is in progress asynchronously or None if it is complete.

delete_configuration(task)

Deletes RAID configuration on the given node.

This method deletes the RAID configuration on the give node. After RAID configuration is deleted, node.raid_config should be cleared by the implementation.

Parameters:task – a TaskManager instance. Returns:states.CLEANWAIT if deletion is in progress asynchronously or None if it is complete.

get_logical_disk_properties()

Get the properties that can be specified for logical disks.

This method returns a dictionary containing the properties that can be specified for logical disks and a textual description for them.

Returns:A dictionary containing properties that can be mentioned for logical disks and a textual description for them.

get_properties()

Return the properties of the interface.

Returns:dictionary of <property name>:<property description> entries.

validate(task)

Validates the RAID Interface.

This method validates the properties defined by Ironic for RAID configuration. Driver implementations of this interface can override this method for doing more validations (such as BMC’s credentials).

Parameters:task – a TaskManager instance. Raises:InvalidParameterValue, if the RAID configuration is invalid. Raises:MissingParameterValue, if some parameters are missing.

validate_raid_config(task, raid_config)

Validates the given RAID configuration.

This method validates the given RAID configuration. Driver implementations of this interface can override this method to support custom parameters for RAID configuration.

Parameters:

• task – a TaskManager instance.
• raid_config – The RAID configuration to validate.

Raises:

InvalidParameterValue, if the RAID configuration is invalid.

class ironic.drivers.base.RescueInterface

Bases: object

Interface for rescue-related actions.

get_properties()

Return the properties of the interface.

Returns:dictionary of <property name>:<property description> entries.

rescue(task)

Boot the task’s node into a rescue environment.

Parameters:task – a TaskManager instance containing the node to act on.

unrescue(task)

Tear down the rescue environment, and return to normal.

Parameters:task – a TaskManager instance containing the node to act on.

validate(task)

Validate the rescue info stored in the node’ properties.

If invalid, raises an exception; otherwise returns None.

Parameters:task – a TaskManager instance containing the node to act on. Raises:InvalidParameterValue Raises:MissingParameterValue

class ironic.drivers.base.VendorInterface

Bases: object

Interface for all vendor passthru functionality.

Additional vendor- or driver-specific capabilities should be implemented as a method in the class inheriting from this class and use the @passthru or @driver_passthru decorators.

Methods decorated with @driver_passthru should be short-lived because it is a blocking call.

driver_validate(method, **kwargs)

Validate driver-vendor-passthru actions.

If invalid, raises an exception; otherwise returns None.

Parameters:

• method – method to be validated
• kwargs – info for action.

Raises:

MissingParameterValue if kwargs does not contain certain parameter.

Raises:

InvalidParameterValue if parameter does not match.

get_properties()

Return the properties of the interface.

Returns:dictionary of <property name>:<property description> entries.

validate(task, method=None, **kwargs)

Validate vendor-specific actions.

If invalid, raises an exception; otherwise returns None.

Parameters:

• task – a task from TaskManager.
• method – method to be validated
• kwargs – info for action.

Raises:

UnsupportedDriverExtension if ‘method’ can not be mapped to the supported interfaces.

Raises:

InvalidParameterValue if kwargs does not contain ‘method’.

Raises:

MissingParameterValue

class ironic.drivers.base.VendorMetadata

Bases: tuple

VendorMetadata(method, metadata)