# openstack.baremetal.v1.Node

## The Node Class

The `Node` class inherits from `Resource`.

class openstack.baremetal.v1.node.Node(_synchronized=False, connection=None, **attrs)

  The base resource

  Parameters:

    - _synchronized (bool) – This is not intended to be used directly. See `new()` and `existing()`.

    - connection (openstack.connection.Connection) – Reference to the Connection being used. Defaults to None to allow Resource objects to be used without an active Connection, such as in unit tests. Use of `self._connection` in Resource code should protect itself with a check for None.

  resources_key = 'nodes'

    Plural form of key for resource.

  base_path = '/nodes'

    The base part of the URI for this resource.

  allow_create = True

    Allow create operation for this resource.

  allow_fetch = True

    Allow get operation for this resource.

  allow_commit = True

    Allow update operation for this resource.

  allow_delete = True

    Allow delete operation for this resource.

  allow_list = True

    Allow list operation for this resource.

  allow_patch = True

    Allow patch operation for this resource.

  commit_method = 'PATCH'

    Method for committing a resource (PUT, PATCH, POST)

  commit_jsonpatch = True

    Whether commit uses JSON patch format.

  allocation_id

    The UUID of the allocation associated with this node. Added in API microversion 1.52.

  owner

    A string or UUID of the tenant who owns the baremetal node. Added in API microversion 1.50.

  boot_mode

    The current boot mode state (uefi/bios). Added in API microversion 1.75.

  chassis_id

    The UUID of the chassis associated wit this node. Can be empty or None.

  clean_step

    The current clean step.

  conductor_group

    Conductor group this node is managed by. Added in API microversion 1.46.

  created_at

    Timestamp at which the node was last updated.

  deploy_step

    The current deploy step. Added in API microversion 1.44.

  description

    The description of the node. Added in API microversion 1.51.

  driver

    The name of the driver.

  driver_info

    All the metadata required by the driver to manage this node. List of fields varies between drivers, and can be retrieved from the `openstack.baremetal.v1.driver.Driver` resource.

  driver_internal_info

    Internal metadata set and stored by node’s driver. This is read-only.

  extra

    A set of one or more arbitrary metadata key and value pairs.

  fault

    Fault type that caused the node to enter maintenance mode. Introduced in API microversion 1.42.

  id

    The UUID of the node resource.

  instance_info

    Information used to customize the deployed image, e.g. size of root partition, config drive in the form of base64 encoded string and other metadata.

  instance_id

    UUID of the nova instance associated with this node.

  is_automated_clean_enabled

    Override enabling of automated cleaning. Added in API microversion 1.47.

  is_console_enabled

    Whether console access is enabled on this node.

  is_maintenance

    Whether node is currently in “maintenance mode”. Nodes put into maintenance mode are removed from the available resource pool.

  is_retired

    Whether the node is marked for retirement. Added in API microversion 1.61.

  is_secure_boot

    Whether the node is currently booted with secure boot turned on. Added in API microversion 1.75.

  last_error

    Any error from the most recent transaction that started but failed to finish.

  lessee

    Field indicating if the node is leased to a specific project. Added in API version 1.65

  links

    A list of relative links, including self and bookmark links.

  maintenance_reason

    user settable description of the reason why the node was placed into maintenance mode.

  name

    Human readable identifier for the node. May be undefined. Certain words are reserved. Added in API microversion 1.5

  parent_node

    The node which serves as the parent_node for this node. Added in API version 1.83

  ports

    Links to the collection of ports on this node.

  port_groups

    Links to the collection of portgroups on this node. Available since API microversion 1.24.

  power_state

    The current power state. Usually “power on” or “power off”, but may be “None” if service is unable to determine the power state.

  properties

    Physical characteristics of the node. Content populated by the service during inspection.

  provision_state

    The current provisioning state of the node.

  retired_reason

    The reason why the node is marked for retirement. Added in API microversion 1.61.

  raid_config

    The current RAID configuration of the node.

  reservation

    The name of an service conductor host which is holding a lock on this node, if a lock is held.

  resource_class

    A string to be used by external schedulers to identify this node as a unit of a specific type of resource. Added in API microversion 1.21.

  service_step

    A string representing the current service step being executed upon. Added in API microversion 1.89.

  runbook

    A string representing the uuid or logical name of a runbook as an alternative to providing `clean_steps` or `service_steps`. Added in API microversion 1.92.

  shard

    A string indicating the shard this node belongs to. Added in API microversion 1,82.

  states

    Links to the collection of states.

  target_provision_state

    The requested state if a provisioning action has been requested. For example, `AVAILABLE`, `DEPLOYING`, `DEPLOYWAIT`, `DEPLOYING`, `ACTIVE` etc.

  target_power_state

    The requested state during a state transition.

  target_raid_config

    The requested RAID configuration of the node which will be applied when the node next transitions through the CLEANING state.

  traits

    Traits of the node. Introduced in API microversion 1.37.

  updated_at

    Timestamp at which the node was last updated.

  bios_interface

    BIOS interface to use when setting BIOS properties of the node. Introduced in API microversion 1.40.

  boot_interface

    Boot interface to use when configuring boot of the node. Introduced in API microversion 1.31.

  console_interface

    Console interface to use when working with serial console. Introduced in API microversion 1.31.

  deploy_interface

    Deploy interface to use when deploying the node. Introduced in API microversion 1.31.

  firmware_interface

    Firmware interface to be used when managing the node. Introduced in API microversion 1.86

  inspect_interface

    Inspect interface to use when inspecting the node. Introduced in API microversion 1.31.

  management_interface

    Management interface to use for management actions on the node. Introduced in API microversion 1.31.

  network_interface

    Network interface provider to use when plumbing the network connections for this node. Introduced in API microversion 1.20.

  power_interface

    Power interface to use for power actions on the node. Introduced in API microversion 1.31.

  raid_interface

    RAID interface to use for configuring RAID on the node. Introduced in API microversion 1.31.

  rescue_interface

    Rescue interface to use for rescuing of the node. Introduced in API microversion 1.38.

  storage_interface

    Storage interface to use when attaching remote storage. Introduced in API microversion 1.33.

  vendor_interface

    Vendor interface to use for vendor-specific actions on the node. Introduced in API microversion 1.31.

  create(session, *args, **kwargs)

    Create a remote resource based on this instance.

    The overridden version is capable of handling the populated `provision_state` field of one of three values: `enroll`, `manageable` or `available`. If not provided, the server default is used (`enroll` in newer versions of Ironic).

    This call does not cause a node to go through automated cleaning. If you need it, use `provision_state=manageable` followed by a call to `set_provision_state()`.

    Note that Bare Metal API 1.4 is required for `manageable` and 1.11 is required for `enroll`.

    Warning

    Using `provision_state=available` is only possible with API versions 1.1 to 1.10 and thus is incompatible with setting any fields that appeared after 1.11.

    Parameters:

      session (`Adapter`) – The session to use for making this request.

    Returns:

      This `Resource` instance.

    Raises:

      ValueError if the Node’s `provision_state` is not one of `None`, `enroll`, `manageable` or `available`.

    Raises:

      `NotSupported` if the `provision_state` cannot be reached with any API version supported by the server.

  commit(session, *args, **kwargs)

    Commit the state of the instance to the remote resource.

    Parameters:

      session (`Adapter`) – The session to use for making this request.

    Returns:

      This `Node` instance.

  set_provision_state(session, target, config_drive=None, clean_steps=None, rescue_password=None, wait=False, timeout=None, deploy_steps=None, service_steps=None, runbook=None)

    Run an action modifying this node’s provision state.

    This call is asynchronous, it will return success as soon as the Bare Metal service acknowledges the request.

    Parameters:

      - session (`Adapter`) – The session to use for making this request.

      - target – Provisioning action, e.g. `active`, `provide`. See the Bare Metal service documentation for available actions.

      - config_drive – Config drive to pass to the node, only valid for `active` and ``rebuild` targets. You can use functions from `openstack.baremetal.configdrive` to build it.

      - clean_steps – Clean steps to execute, only valid for `clean` target.

      - rescue_password – Password for the rescue operation, only valid for `rescue` target.

      - wait – Whether to wait for the target state to be reached.

      - timeout – Timeout (in seconds) to wait for the target state to be reached. If `None`, wait without timeout.

      - deploy_steps – Deploy steps to execute, only valid for `active` and `rebuild` target.

      - service_steps – Service steps to execute, only valid for `service` target.

      - runbook – UUID or logical name of a runbook.

    Returns:

      This `Node` instance.

    Raises:

      ValueError if `config_drive`, `clean_steps`, `deploy_steps` or `rescue_password` are provided with an invalid `target`.

    Raises:

      `ResourceFailure` if the node reaches an error state while waiting for the state.

    Raises:

      `ResourceTimeout` if timeout is reached while waiting for the state.

  wait_for_power_state(session, expected_state, timeout=None)

    Wait for the node to reach the expected power state.

    Parameters:

      - session (`Adapter`) – The session to use for making this request.

      - expected_state – The expected power state to reach.

      - timeout – If `wait` is set to `True`, specifies how much (in seconds) to wait for the expected state to be reached. The value of `None` (the default) means no client-side timeout.

    Returns:

      This `Node` instance.

    Raises:

      `ResourceTimeout` on timeout.

  wait_for_provision_state(session, expected_state, timeout=None, abort_on_failed_state=True)

    Wait for the node to reach the expected state.

    Parameters:

      - session (`Adapter`) – The session to use for making this request.

      - expected_state – The expected provisioning state to reach.

      - timeout – If `wait` is set to `True`, specifies how much (in seconds) to wait for the expected state to be reached. The value of `None` (the default) means no client-side timeout.

      - abort_on_failed_state – If `True` (the default), abort waiting if the node reaches a failure state which does not match the expected one. Note that the failure state for `enroll` -> `manageable` transition is `enroll` again.

    Returns:

      This `Node` instance.

    Raises:

      `ResourceFailure` if the node reaches an error state and `abort_on_failed_state` is `True`.

    Raises:

      `ResourceTimeout` on timeout.

  wait_for_reservation(session, timeout=None)

    Wait for a lock on the node to be released.

    Bare metal nodes in ironic have a reservation lock that is used to represent that a conductor has locked the node while performing some sort of action, such as changing configuration as a result of a machine state change.

    This lock can occur during power syncronization, and prevents updates to objects attached to the node, such as ports.

    Note that nothing prevents a conductor from acquiring the lock again after this call returns, so it should be treated as best effort.

    Returns immediately if there is no reservation on the node.

    Parameters:

      - session (`Adapter`) – The session to use for making this request.

      - timeout – How much (in seconds) to wait for the lock to be released. The value of `None` (the default) means no timeout.

    Returns:

      This `Node` instance.

  inject_nmi(session)

    Inject NMI.

    Parameters:

      session – The session to use for making this request.

    Returns:

      None

  set_power_state(session, target, wait=False, timeout=None)

    Run an action modifying this node’s power state.

    This call is asynchronous, it will return success as soon as the Bare Metal service acknowledges the request.

    Parameters:

      - session (`Adapter`) – The session to use for making this request.

      - target – Target power state, as a `PowerAction` or a string.

      - wait – Whether to wait for the expected power state to be reached.

      - timeout – Timeout (in seconds) to wait for the target state to be reached. If `None`, wait without timeout.

  attach_vmedia(session, device_type, image_url, image_download_source=None, retry_on_conflict=True)

    Attach virtual media device to a node.

    Parameters:

      - session (`Adapter`) – The session to use for making this request.

      - device_type – The type of virtual media device.

      - image_url – The URL of the image to attach.

      - image_download_source – The source of the image download.

      - retry_on_conflict – Whether to retry HTTP CONFLICT errors. This can happen when either the virtual media is already used on a node or the node is locked. Since the latter happens more often, the default value is True.

    Returns:

      `None`

    Raises:

      `NotSupported` if the server does not support the VMEDIA API.

  detach_vmedia(session, device_types=None)

    Detach virtual media from a node

    Parameters:

      - session (`Adapter`) – The session to use for making this request.

      - device_types – A list with the types of virtual media devices to detach.

    Returns:

      `True` if the virtual media was detached, otherwise `False`.

    Raises:

      `NotSupported` if the server does not support the VMEDIA API

  attach_vif(session, vif_id, retry_on_conflict=True, *, port_id=None, port_group_id=None)

    Attach a VIF to the node.

    The exact form of the VIF ID depends on the network interface used by the node. In the most common case it is a Network service port (NOT a Bare Metal port) ID. A VIF can only be attached to one node at a time.

    Parameters:

      - session (`Adapter`) – The session to use for making this request.

      - vif_id – Backend-specific VIF ID.

      - retry_on_conflict – Whether to retry HTTP CONFLICT errors. This can happen when either the VIF is already used on a node or the node is locked. Since the latter happens more often, the default value is True.

      - port_id – The UUID of the port to attach the VIF to. Only one of port_id or port_group_id can be provided.

      - port_group_id – The UUID of the portgroup to attach to. Only one of port_group_id or port_id can be provided.

    Returns:

      None

    Raises:

      `NotSupported` if the server does not support the VIF API.

    Raises:

      `InvalidRequest` if both port_id and port_group_id are provided.

  detach_vif(session, vif_id, ignore_missing=True)

    Detach a VIF from the node.

    The exact form of the VIF ID depends on the network interface used by the node. In the most common case it is a Network service port (NOT a Bare Metal port) ID.

    Parameters:

      - session (`Adapter`) – The session to use for making this request.

      - vif_id (string) – Backend-specific VIF ID.

      - ignore_missing (bool) – When set to `False` `NotFoundException` will be raised when the VIF does not exist. Otherwise, `False` is returned.

    Returns:

      `True` if the VIF was detached, otherwise `False`.

    Raises:

      `NotSupported` if the server does not support the VIF API.

  list_vifs(session)

    List IDs of VIFs attached to the node.

    The exact form of the VIF ID depends on the network interface used by the node. In the most common case it is a Network service port (NOT a Bare Metal port) ID.

    Parameters:

      session (`Adapter`) – The session to use for making this request.

    Returns:

      List of VIF IDs as strings.

    Raises:

      `NotSupported` if the server does not support the VIF API.

  validate(session, required=('boot', 'deploy', 'power'))

    Validate required information on the node.

    Parameters:

      - session (`Adapter`) – The session to use for making this request.

      - required – List of interfaces that are required to pass validation. The default value is the list of minimum required interfaces for provisioning.

    Returns:

      dict mapping interface names to `ValidationResult` objects.

    Raises:

      `ValidationException` if validation fails for a required interface.

  set_maintenance(session, reason=None)

    Enable maintenance mode on the node.

    Parameters:

      - session (`Adapter`) – The session to use for making this request.

      - reason – Optional reason for maintenance.

    Returns:

      This `Node` instance.

  unset_maintenance(session)

    Disable maintenance mode on the node.

    Parameters:

      session (`Adapter`) – The session to use for making this request.

    Returns:

      This `Node` instance.

  get_boot_device(session)

    Get node boot device.

    Parameters:

      session – The session to use for making this request.

    Returns:

      The HTTP response.

  set_boot_device(session, boot_device, persistent=False)

    Set node boot device

    Parameters:

      - session – The session to use for making this request.

      - boot_device – Boot device to assign to the node.

      - persistent – If the boot device change is maintained after node reboot

    Returns:

      `None`

  get_supported_boot_devices(session)

    Get supported boot devices for the node.

    Parameters:

      session – The session to use for making this request.

    Returns:

      The HTTP response.

  set_boot_mode(session, target)

    Make a request to change node’s boot mode

    This call is asynchronous, it will return success as soon as the Bare Metal service acknowledges the request.

    Parameters:

      - session – The session to use for making this request.

      - target – Boot mode to set for node, one of either ‘uefi’/’bios’.

    Returns:

      `None`

    Raises:

      ValueError if `target` is not one of ‘uefi or ‘bios’.

  set_secure_boot(session, target)

    Make a request to change node’s secure boot state

    This call is asynchronous, it will return success as soon as the Bare Metal service acknowledges the request.

    Parameters:

      - session – The session to use for making this request.

      - target (bool) – Boolean indicating secure boot state to set. True/False corresponding to ‘on’/’off’ respectively.

    Returns:

      `None`

    Raises:

      ValueError if `target` is not boolean.

  add_trait(session, trait)

    Add a trait to the node.

    Parameters:

      - session – The session to use for making this request.

      - trait – The trait to add to the node.

    Returns:

      `None`

  remove_trait(session, trait, ignore_missing=True)

    Remove a trait from the node.

    Parameters:

      - session – The session to use for making this request.

      - trait – The trait to remove from the node.

      - ignore_missing (bool) – When set to `False` `NotFoundException` will be raised when the trait does not exist. Otherwise, `False` is returned.

    Returns bool:

      True on success removing the trait. False when the trait does not exist already.

  set_traits(session, traits)

    Set traits for the node.

    Removes any existing traits and adds the traits passed in to this method.

    Parameters:

      - session – The session to use for making this request.

      - traits – list of traits to add to the node.

    Returns:

      `None`

  call_vendor_passthru(session, verb, method, body=None)

    Call a vendor passthru method.

    Parameters:

      - session – The session to use for making this request.

      - verb – The HTTP verb, one of GET, SET, POST, DELETE.

      - method – The method to call using vendor_passthru.

      - body – The JSON body in the HTTP call.

    Returns:

      The HTTP response.

  list_vendor_passthru(session)

    List vendor passthru methods for the node.

    Parameters:

      session – The session to use for making this request.

    Returns:

      The HTTP response.

  get_console(session)

    Get the node console.

    Parameters:

      session – The session to use for making this request.

    Returns:

      The HTTP response.

  set_console_mode(session, enabled)

    Set the node console mode.

    Parameters:

      - session – The session to use for making this request.

      - enabled – Whether the console should be enabled or not.

    Returns:

      `None`

  get_node_inventory(session, node_id)

    Get a node’s inventory.

    Parameters:

      - session – The session to use for making this request.

      - node_id – DEPRECATED The ID of the node.

    Returns:

      The HTTP response.

  list_firmware(session)

    List firmware components associated with the node.

    Parameters:

      session – The session to use for making this request.

    Returns:

      The HTTP response.

  patch(session, patch=None, prepend_key=True, has_body=True, retry_on_conflict=None, base_path=None, *, microversion=None, reset_interfaces=None)

    Patch the remote resource.

    Allows modifying the resource by providing a list of JSON patches to apply to it. The patches can use both the original (server-side) and SDK field names.

    Parameters:

      - session (`Adapter`) – The session to use for making this request.

      - patch – Additional JSON patch as a list or one patch item. If provided, it is applied on top of any changes to the current resource.

      - prepend_key – A boolean indicating whether the resource_key should be prepended in a resource update request. Default to True.

      - retry_on_conflict (bool) – Whether to enable retries on HTTP CONFLICT (409). Value of `None` leaves the Adapter defaults.

      - base_path (str) – Base part of the URI for modifying resources, if different from `base_path`.

      - microversion (str) – API version to override the negotiated one.

    Returns:

      This `Resource` instance.

    Raises:

      `MethodNotSupported` if `Resource.allow_patch` is not set to `True`.

### The PowerAction Class

The `PowerAction` enumeration represents known power actions.

class openstack.baremetal.v1.node.PowerAction(*values)

  Mapping from an action to a target power state.

  POWER_ON = 'power on'

    Power on the node.

  POWER_OFF = 'power off'

    Power off the node (using hard power off).

  REBOOT = 'rebooting'

    Reboot the node (using hard power off).

  SOFT_POWER_OFF = 'soft power off'

    Power off the node using soft power off.

  SOFT_REBOOT = 'soft rebooting'

    Reboot the node using soft power off.

### The ValidationResult Class

The `ValidationResult` class represents the result of a validation.

class openstack.baremetal.v1.node.ValidationResult(result, reason)

  Result of a single interface validation.

  Variables:

    - result – Result of a validation, `True` for success, `False` for failure, `None` for unsupported interface.

    - reason – If `result` is `False` or `None`, explanation of the result.

### The WaitResult Class

The `WaitResult` class represents the result of waiting for several nodes.

class openstack.baremetal.v1.node.WaitResult(success, failure, timeout)

  A named tuple representing a result of waiting for several nodes.

  Each component is a list of `Node` objects:

  Variables:

    - ~.success – a list of `Node` objects that reached the state.

    - ~.timeout – a list of `Node` objects that reached timeout.

    - ~.failure – a list of `Node` objects that hit a failure.

  Create new instance of WaitResult(success, failure, timeout)

this page last updated: 2026-01-16 23:06:19

Except where otherwise noted, this document is licensed under Creative Commons Attribution 3.0 License. See all OpenStack Legal Documents.