The ironic.conductor.rpcapi Module

Client side of the conductor RPC API.

class ironic.conductor.rpcapi.ConductorAPI(topic=None)[source]

Bases: object

Client side of the conductor RPC API.

API version history:

1.0 - Initial version.
Included get_node_power_status
1.1 - Added update_node and start_power_state_change.
1.2 - Added vendor_passthru.
1.3 - Rename start_power_state_change to change_node_power_state.
1.4 - Added do_node_deploy and do_node_tear_down.
1.5 - Added validate_driver_interfaces.
1.6 - change_node_power_state, do_node_deploy and do_node_tear_down
accept node id instead of node object.
1.7 - Added topic parameter to RPC methods.
1.8 - Added change_node_maintenance_mode.
1.9 - Added destroy_node.
1.10 - Remove get_node_power_state
1.11 - Added get_console_information, set_console_mode.
1.12 - validate_vendor_action, do_vendor_action replaced by single
vendor_passthru method.
1.13 - Added update_port.
1.14 - Added driver_vendor_passthru.
1.15 - Added rebuild parameter to do_node_deploy.
1.16 - Added get_driver_properties.
1.17 - Added set_boot_device, get_boot_device and
get_supported_boot_devices.
1.18 - Remove change_node_maintenance_mode.
1.19 - Change return value of vendor_passthru and
driver_vendor_passthru
1.20 - Added http_method parameter to vendor_passthru and
driver_vendor_passthru
1.21 - Added get_node_vendor_passthru_methods and
get_driver_vendor_passthru_methods
1.22 - Added configdrive parameter to do_node_deploy.
1.23 - Added do_provisioning_action
1.24 - Added inspect_hardware method
1.25 - Added destroy_port
1.26 - Added continue_node_clean
1.27 - Convert continue_node_clean to cast
1.28 - Change exceptions raised by destroy_node
1.29 - Change return value of vendor_passthru and
driver_vendor_passthru to a dictionary
1.30 - Added set_target_raid_config and
get_raid_logical_disk_properties
1.31 - Added Versioned Objects indirection API methods:
object_class_action_versions, object_action and
object_backport_versions
1.32 - Add do_node_clean
1.33 - Added update and destroy portgroup.
1.34 - Added heartbeat
1.35 - Added destroy_volume_connector and update_volume_connector
1.36 - Added create_node
1.37 - Added destroy_volume_target and update_volume_target
1.38 - Added vif_attach, vif_detach, vif_list
1.39 - Added timeout optional parameter to change_node_power_state
1.40 - Added inject_nmi
change_node_power_state(context, node_id, new_state, topic=None, timeout=None)[source]

Change a node’s power state.

Synchronously, acquire lock and start the conductor background task to change power state of a node.

Parameters:
  • context – request context.
  • node_id – node id or uuid.
  • new_state – one of ironic.common.states power state values
  • timeout – timeout (in seconds) positive integer (> 0) for any power state. None indicates to use default timeout.
  • topic – RPC topic. Defaults to self.topic.
Raises:

NoFreeConductorWorker when there is no free worker to start async task.
continue_node_clean(context, node_id, topic=None)[source]

Signal to conductor service to start the next cleaning action.

NOTE(JoshNang) this is an RPC cast, there will be no response or exception raised by the conductor for this RPC.

Parameters:
  • context – request context.
  • node_id – node id or uuid.
  • topic – RPC topic. Defaults to self.topic.
create_node(context, node_obj, topic=None)[source]

Synchronously, have a conductor validate and create a node.

Create the node’s information in the database and return a node object.

Parameters:
  • context – request context.
  • node_obj – a created (but not saved) node object.
  • topic – RPC topic. Defaults to self.topic.
Returns:

created node object.
Raises:

InterfaceNotFoundInEntrypoint if validation fails for any dynamic interfaces (e.g. network_interface).
Raises:

NoValidDefaultForInterface if no default can be calculated for some interfaces, and explicit values must be provided.
destroy_node(context, node_id, topic=None)[source]

Delete a node.

Parameters:
  • context – request context.
  • node_id – node id or uuid.
Raises:

NodeLocked if node is locked by another conductor.
Raises:

NodeAssociated if the node contains an instance associated with it.
Raises:

InvalidState if the node is in the wrong provision state to perform deletion.
destroy_port(context, port, topic=None)[source]

Delete a port.

Parameters:
  • context – request context.
  • port – port object
  • topic – RPC topic. Defaults to self.topic.
Raises:

NodeLocked if node is locked by another conductor.
Raises:

NodeNotFound if the node associated with the port does not exist.
destroy_portgroup(context, portgroup, topic=None)[source]

Delete a portgroup.

Parameters:
  • context – request context.
  • portgroup – portgroup object
  • topic – RPC topic. Defaults to self.topic.
Raises:

NodeLocked if node is locked by another conductor.
Raises:

NodeNotFound if the node associated with the portgroup does not exist.
Raises:

PortgroupNotEmpty if portgroup is not empty
destroy_volume_connector(context, connector, topic=None)[source]

Delete a volume connector.

Delete the volume connector. The conductor will lock the related node during this operation.

Parameters:
  • context – request context
  • connector – volume connector object
  • topic – RPC topic. Defaults to self.topic.
Raises:

NodeLocked if node is locked by another conductor
Raises:

NodeNotFound if the node associated with the connector does not exist
Raises:

VolumeConnectorNotFound if the volume connector cannot be found
destroy_volume_target(context, target, topic=None)[source]

Delete a volume target.

Parameters:
  • context – request context
  • target – volume target object
  • topic – RPC topic. Defaults to self.topic.
Raises:

NodeLocked if node is locked by another conductor
Raises:

NodeNotFound if the node associated with the target does not exist
Raises:

VolumeTargetNotFound if the volume target cannot be found
do_node_clean(context, node_id, clean_steps, topic=None)[source]

Signal to conductor service to perform manual cleaning on a node.

Parameters:
  • context – request context.
  • node_id – node ID or UUID.
  • clean_steps – a list of clean step dictionaries.
  • topic – RPC topic. Defaults to self.topic.
Raises:

InvalidParameterValue if validation of power driver interface failed.
Raises:

InvalidStateRequested if cleaning can not be performed.
Raises:

NodeInMaintenance if node is in maintenance mode.
Raises:

NodeLocked if node is locked by another conductor.
Raises:

NoFreeConductorWorker when there is no free worker to start async task.
do_node_deploy(context, node_id, rebuild, configdrive, topic=None)[source]

Signal to conductor service to perform a deployment.

Parameters:
  • context – request context.
  • node_id – node id or uuid.
  • rebuild – True if this is a rebuild request.
  • configdrive – A gzipped and base64 encoded configdrive.
  • topic – RPC topic. Defaults to self.topic.
Raises:

InstanceDeployFailure
Raises:

InvalidParameterValue if validation fails
Raises:

MissingParameterValue if a required parameter is missing
Raises:

NoFreeConductorWorker when there is no free worker to start async task.

The node must already be configured and in the appropriate undeployed state before this method is called.

do_node_tear_down(context, node_id, topic=None)[source]

Signal to conductor service to tear down a deployment.

Parameters:
  • context – request context.
  • node_id – node id or uuid.
  • topic – RPC topic. Defaults to self.topic.
Raises:

InstanceDeployFailure
Raises:

InvalidParameterValue if validation fails
Raises:

MissingParameterValue if a required parameter is missing
Raises:

NoFreeConductorWorker when there is no free worker to start async task.

The node must already be configured and in the appropriate deployed state before this method is called.

do_provisioning_action(context, node_id, action, topic=None)[source]

Signal to conductor service to perform the given action on a node.

Parameters:
  • context – request context.
  • node_id – node id or uuid.
  • action – an action. One of ironic.common.states.VERBS
  • topic – RPC topic. Defaults to self.topic.
Raises:

InvalidParameterValue
Raises:

NoFreeConductorWorker when there is no free worker to start async task.
Raises:

InvalidStateRequested if the requested action can not be performed.

This encapsulates some provisioning actions in a single call.

driver_vendor_passthru(context, driver_name, driver_method, http_method, info, topic=None)[source]

Pass vendor-specific calls which don’t specify a node to a driver.

Handles driver-level vendor passthru calls. These calls don’t require a node UUID and are executed on a random conductor with the specified driver. If the method mode is async the conductor will start background worker to perform vendor action.

Parameters:
  • context – request context.
  • driver_name – name of the driver on which to call the method.
  • driver_method – name of the vendor method, for use by the driver.
  • http_method – the HTTP method used for the request.
  • info – data to pass through to the driver.
  • topic – RPC topic. Defaults to self.topic.
Raises:

InvalidParameterValue for parameter errors.
Raises:

MissingParameterValue if a required parameter is missing
Raises:

UnsupportedDriverExtension if the driver doesn’t have a vendor interface, or if the vendor interface does not support the specified driver_method.
Raises:

DriverNotFound if the supplied driver is not loaded.
Raises:

NoFreeConductorWorker when there is no free worker to start async task.
Raises:

InterfaceNotFoundInEntrypoint if the default interface for a hardware type is invalid.
Raises:

NoValidDefaultForInterface if no default interface implementation can be found for this driver’s vendor interface.
Returns:

A dictionary containing:

return:The response of the invoked vendor method
async:Boolean value. Whether the method was invoked asynchronously (True) or synchronously (False). When invoked asynchronously the response will be always None.
attach:Boolean value. Whether to attach the response of the invoked vendor method to the HTTP response object (True) or return it in the response body (False).

get_boot_device(context, node_id, topic=None)[source]

Get the current boot device.

Returns the current boot device of a node.

Parameters:
  • context – request context.
  • node_id – node id or uuid.
Raises:

NodeLocked if node is locked by another conductor.
Raises:

UnsupportedDriverExtension if the node’s driver doesn’t support management.
Raises:

InvalidParameterValue when the wrong driver info is specified.
Raises:

MissingParameterValue if missing supplied info.
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_console_information(context, node_id, topic=None)[source]

Get connection information about the console.

Parameters:
  • context – request context.
  • node_id – node id or uuid.
  • topic – RPC topic. Defaults to self.topic.
Raises:

UnsupportedDriverExtension if the node’s driver doesn’t support console.
Raises:

InvalidParameterValue when the wrong driver info is specified.
Raises:

MissingParameterValue if a required parameter is missing
get_driver_properties(context, driver_name, topic=None)[source]

Get the properties of the driver.

Parameters:
  • context – request context.
  • driver_name – name of the driver.
  • topic – RPC topic. Defaults to self.topic.
Returns:

a dictionary with <property name>:<property description> entries.
Raises:

DriverNotFound.
get_driver_vendor_passthru_methods(context, driver_name, topic=None)[source]

Retrieve information about vendor methods of the given driver.

Parameters:
  • context – an admin context.
  • driver_name – name of the driver.
  • topic – RPC topic. Defaults to self.topic.
Raises:

UnsupportedDriverExtension if current driver does not have vendor interface.
Raises:

DriverNotFound if the supplied driver is not loaded.
Raises:

InterfaceNotFoundInEntrypoint if the default interface for a hardware type is invalid.
Raises:

NoValidDefaultForInterface if no default interface implementation can be found for this driver’s vendor interface.
Returns:

dictionary of <method name>:<method metadata> entries.
get_node_vendor_passthru_methods(context, node_id, topic=None)[source]

Retrieve information about vendor methods of the given node.

Parameters:
  • context – an admin context.
  • node_id – the id or uuid of a node.
  • topic – RPC topic. Defaults to self.topic.
Returns:

dictionary of <method name>:<method metadata> entries.
get_raid_logical_disk_properties(context, driver_name, topic=None)[source]

Get the logical disk properties for RAID configuration.

Gets the information about logical disk properties which can be specified in the input RAID configuration.

Parameters:
  • context – request context.
  • driver_name – name of the driver
  • topic – RPC topic. Defaults to self.topic.
Raises:

UnsupportedDriverExtension if the driver doesn’t support RAID configuration.
Raises:

InterfaceNotFoundInEntrypoint if the default interface for a hardware type is invalid.
Raises:

NoValidDefaultForInterface if no default interface implementation can be found for this driver’s RAID interface.
Returns:

A dictionary containing the properties that can be mentioned for logical disks and a textual description for them.
get_supported_boot_devices(context, node_id, topic=None)[source]

Get the list of supported devices.

Returns the list of supported boot devices of a node.

Parameters:
  • context – request context.
  • node_id – node id or uuid.
Raises:

NodeLocked if node is locked by another conductor.
Raises:

UnsupportedDriverExtension if the node’s driver doesn’t support management.
Raises:

InvalidParameterValue when the wrong driver info is specified.
Raises:

MissingParameterValue if missing supplied info.
Returns:

A list with the supported boot devices defined in ironic.common.boot_devices.
get_topic_for(node)[source]

Get the RPC topic for the conductor service the node is mapped to.

Parameters:node – a node object.
Returns:an RPC topic string.
Raises:NoValidHost
get_topic_for_driver(driver_name)[source]

Get RPC topic name for a conductor supporting the given driver.

The topic is used to route messages to the conductor supporting the specified driver. A conductor is selected at random from the set of qualified conductors.

Parameters:driver_name – the name of the driver to route to.
Returns:an RPC topic string.
Raises:DriverNotFound
heartbeat(context, node_id, callback_url, topic=None)[source]

Process a node heartbeat.

Parameters:
  • context – request context.
  • node_id – node ID or UUID.
  • callback_url – URL to reach back to the ramdisk.
  • topic – RPC topic. Defaults to self.topic.
inject_nmi(context, node_id, topic=None)[source]

Inject NMI for a node.

Inject NMI (Non Maskable Interrupt) for a node immediately. Be aware that not all drivers support this.

Parameters:
  • context – request context.
  • node_id – node id or uuid.
Raises:

NodeLocked if node is locked by another conductor.
Raises:

UnsupportedDriverExtension if the node’s driver doesn’t support management or management.inject_nmi.
Raises:

InvalidParameterValue when the wrong driver info is specified or an invalid boot device is specified.
Raises:

MissingParameterValue if missing supplied info.
inspect_hardware(context, node_id, topic=None)[source]

Signals the conductor service to perform hardware introspection.

Parameters:
  • context – request context.
  • node_id – node id or uuid.
  • topic – RPC topic. Defaults to self.topic.
Raises:

NodeLocked if node is locked by another conductor.
Raises:

HardwareInspectionFailure
Raises:

NoFreeConductorWorker when there is no free worker to start async task.
Raises:

UnsupportedDriverExtension if the node’s driver doesn’t support inspection.
Raises:

InvalidStateRequested if ‘inspect’ is not a valid action to do in the current state.
object_action(context, objinst, objmethod, args, kwargs)[source]

Perform an action on a VersionedObject instance.

We want any conductor to handle this, so it is intentional that there is no topic argument for this method.

Parameters:
  • context – The context within which to perform the action
  • objinst – The object instance on which to perform the action
  • objmethod – The name of the action method to call
  • args – The positional arguments to the action method
  • kwargs – The keyword arguments to the action method
Raises:

NotImplementedError when an operator makes an error during upgrade
Returns:

A tuple with the updates made to the object and the result of the action method
object_backport_versions(context, objinst, object_versions)[source]

Perform a backport of an object instance.

The default behavior of the base VersionedObjectSerializer, upon receiving an object with a version newer than what is in the local registry, is to call this method to request a backport of the object.

We want any conductor to handle this, so it is intentional that there is no topic argument for this method.

Parameters:
  • context – The context within which to perform the backport
  • objinst – An instance of a VersionedObject to be backported
  • object_versions – A dict of {objname: version} mappings
Raises:

NotImplementedError when an operator makes an error during upgrade
Returns:

The downgraded instance of objinst
object_class_action_versions(context, objname, objmethod, object_versions, args, kwargs)[source]

Perform an action on a VersionedObject class.

We want any conductor to handle this, so it is intentional that there is no topic argument for this method.

Parameters:
  • context – The context within which to perform the action
  • objname – The registry name of the object
  • objmethod – The name of the action method to call
  • object_versions – A dict of {objname: version} mappings
  • args – The positional arguments to the action method
  • kwargs – The keyword arguments to the action method
Raises:

NotImplementedError when an operator makes an error during upgrade
Returns:

The result of the action method, which may (or may not) be an instance of the implementing VersionedObject class.
set_boot_device(context, node_id, device, persistent=False, topic=None)[source]

Set the boot device for a node.

Set the boot device to use on next reboot of the node. Be aware that not all drivers support this.

Parameters:
  • context – request context.
  • node_id – node id or uuid.
  • device – the boot device, one of ironic.common.boot_devices.
  • persistent – Whether to set next-boot, or make the change permanent. Default: False.
Raises:

NodeLocked if node is locked by another conductor.
Raises:

UnsupportedDriverExtension if the node’s driver doesn’t support management.
Raises:

InvalidParameterValue when the wrong driver info is specified or an invalid boot device is specified.
Raises:

MissingParameterValue if missing supplied info.
set_console_mode(context, node_id, enabled, topic=None)[source]

Enable/Disable the console.

Parameters:
  • context – request context.
  • node_id – node id or uuid.
  • topic – RPC topic. Defaults to self.topic.
  • enabled – Boolean value; whether the console is enabled or disabled.
Raises:

UnsupportedDriverExtension if the node’s driver doesn’t support console.
Raises:

InvalidParameterValue when the wrong driver info is specified.
Raises:

MissingParameterValue if a required parameter is missing
Raises:

NoFreeConductorWorker when there is no free worker to start async task.
set_target_raid_config(context, node_id, target_raid_config, topic=None)[source]

Stores the target RAID configuration on the node.

Stores the target RAID configuration on node.target_raid_config

Parameters:
  • context – request context.
  • node_id – node id or uuid.
  • target_raid_config – Dictionary containing the target RAID configuration. It may be an empty dictionary as well.
  • topic – RPC topic. Defaults to self.topic.
Raises:

UnsupportedDriverExtension if the node’s driver doesn’t support RAID configuration.
Raises:

InvalidParameterValue, if validation of target raid config fails.
Raises:

MissingParameterValue, if some required parameters are missing.
Raises:

NodeLocked if node is locked by another conductor.
update_node(context, node_obj, topic=None)[source]

Synchronously, have a conductor update the node’s information.

Update the node’s information in the database and return a node object. The conductor will lock the node while it validates the supplied information. If driver_info is passed, it will be validated by the core drivers. If instance_uuid is passed, it will be set or unset only if the node is properly configured.

Note that power_state should not be passed via this method. Use change_node_power_state for initiating driver actions.

Parameters:
  • context – request context.
  • node_obj – a changed (but not saved) node object.
  • topic – RPC topic. Defaults to self.topic.
Returns:

updated node object, including all fields.
Raises:

NoValidDefaultForInterface if no default can be calculated for some interfaces, and explicit values must be provided.
update_port(context, port_obj, topic=None)[source]

Synchronously, have a conductor update the port’s information.

Update the port’s information in the database and return a port object. The conductor will lock related node and trigger specific driver actions if they are needed.

Parameters:
  • context – request context.
  • port_obj – a changed (but not saved) port object.
  • topic – RPC topic. Defaults to self.topic.
Returns:

updated port object, including all fields.
update_portgroup(context, portgroup_obj, topic=None)[source]

Synchronously, have a conductor update the portgroup’s information.

Update the portgroup’s information in the database and return a portgroup object. The conductor will lock related node and trigger specific driver actions if they are needed.

Parameters:
  • context – request context.
  • portgroup_obj – a changed (but not saved) portgroup object.
  • topic – RPC topic. Defaults to self.topic.
Returns:

updated portgroup object, including all fields.
update_volume_connector(context, connector, topic=None)[source]

Update the volume connector’s information.

Update the volume connector’s information in the database and return a volume connector object. The conductor will lock the related node during this operation.

Parameters:
  • context – request context
  • connector – a changed (but not saved) volume connector object
  • topic – RPC topic. Defaults to self.topic.
Raises:

InvalidParameterValue if the volume connector’s UUID is being changed
Raises:

NodeLocked if node is locked by another conductor
Raises:

NodeNotFound if the node associated with the connector does not exist
Raises:

VolumeConnectorNotFound if the volume connector cannot be found
Raises:

VolumeConnectorTypeAndIdAlreadyExists if another connector already exists with the same values for type and connector_id fields
Returns:

updated volume connector object, including all fields.
update_volume_target(context, target, topic=None)[source]

Update the volume target’s information.

Update the volume target’s information in the database and return a volume target object. The conductor will lock the related node during this operation.

Parameters:
  • context – request context
  • target – a changed (but not saved) volume target object
  • topic – RPC topic. Defaults to self.topic.
Raises:

InvalidParameterValue if the volume target’s UUID is being changed
Raises:

NodeLocked if the node is already locked
Raises:

NodeNotFound if the node associated with the volume target does not exist
Raises:

VolumeTargetNotFound if the volume target cannot be found
Raises:

VolumeTargetBootIndexAlreadyExists if a volume target already exists with the same node ID and boot index values
Returns:

updated volume target object, including all fields
validate_driver_interfaces(context, node_id, topic=None)[source]

Validate the core and standardized interfaces for drivers.

Parameters:
  • context – request context.
  • node_id – node id or uuid.
  • topic – RPC topic. Defaults to self.topic.
Returns:

a dictionary containing the results of each interface validation.
vendor_passthru(context, node_id, driver_method, http_method, info, topic=None)[source]

Receive requests for vendor-specific actions.

Synchronously validate driver specific info or get driver status, and if successful invokes the vendor method. If the method mode is async the conductor will start background worker to perform vendor action.

Parameters:
  • context – request context.
  • node_id – node id or uuid.
  • driver_method – name of method for driver.
  • http_method – the HTTP method used for the request.
  • info – info for node driver.
  • topic – RPC topic. Defaults to self.topic.
Raises:

InvalidParameterValue if supplied info is not valid.
Raises:

MissingParameterValue if a required parameter is missing
Raises:

UnsupportedDriverExtension if current driver does not have vendor interface.
Raises:

NoFreeConductorWorker when there is no free worker to start async task.
Raises:

NodeLocked if node is locked by another conductor.
Returns:

A dictionary containing:

return:The response of the invoked vendor method
async:Boolean value. Whether the method was invoked asynchronously (True) or synchronously (False). When invoked asynchronously the response will be always None.
attach:Boolean value. Whether to attach the response of the invoked vendor method to the HTTP response object (True) or return it in the response body (False).

vif_attach(context, node_id, vif_info, topic=None)[source]

Attach VIF to a node

Parameters:
  • context – request context.
  • node_id – node ID or UUID.
  • vif_info – a dictionary representing VIF object. It must have an ‘id’ key, whose value is a unique identifier for that VIF.
  • topic – RPC topic. Defaults to self.topic.
Raises:

NodeLocked, if node has an exclusive lock held on it
Raises:

NetworkError, if an error occurs during attaching the VIF.
Raises:

InvalidParameterValue, if a parameter that’s required for VIF attach is wrong/missing.
vif_detach(context, node_id, vif_id, topic=None)[source]

Detach VIF from a node

Parameters:
  • context – request context.
  • node_id – node ID or UUID.
  • vif_id – an ID of a VIF.
  • topic – RPC topic. Defaults to self.topic.
Raises:

NodeLocked, if node has an exclusive lock held on it
Raises:

NetworkError, if an error occurs during detaching the VIF.
Raises:

InvalidParameterValue, if a parameter that’s required for VIF detach is wrong/missing.
vif_list(context, node_id, topic=None)[source]

List attached VIFs for a node

Parameters:
  • context – request context.
  • node_id – node ID or UUID.
  • topic – RPC topic. Defaults to self.topic.
Returns:

List of VIF dictionaries, each dictionary will have an ‘id’ entry with the ID of the VIF.
Raises:

NetworkError, if an error occurs during listing the VIFs.
Raises:

InvalidParameterValue, if a parameter that’s required for VIF list is wrong/missing.