Bare Metal API

API versions

Concepts

In order to bring new features to users over time, the Ironic API supports versioning. There are two kinds of versions in Ironic.

  • ‘’major versions’’, which have dedicated urls.

  • ‘’microversions’’, which can be requested through the use of the X-OpenStack-Ironic-API-Version header.

The Version APIs work differently from other APIs as they do not require authentication.

Beginning with the Kilo release, all API requests support the X-OpenStack-Ironic-API-Version header. This header SHOULD be supplied with every request; in the absence of this header, each request is treated as though coming from an older pre-Kilo client. This was done to preserve backwards compatibility as we introduced new features in the server.

If you try to use a feature with an API version older than when that feature was introduced the ironic service will respond as would before that feature existed. For example if a new API URL was added, and you try to make a request with an older API version, then you will get a Not Found (404) error, or if a new field was added to an existing API and you request an older API version then you will get an Invalid Parameter response.

GET
/

List API versions

This fetches all the information about all known major API versions in the deployment. Links to more specific information will be provided for each major API version, as well as information about supported min and max microversions.

Normal response codes: 200

Request

Response Example

Name

In

Type

Description

description

body

string

Descriptive text about the Ironic service.

versions

body

array

Array of information about currently supported versions.

version

body

string

Versioning of this API response, eg. “1.22”.

id

body

string

Major API version, eg, “v1”

links

body

array

A list of relative links. Includes the self and bookmark links.

min_version

header

string

Minimum API microversion supported by this endpoint, eg. “1.1”

{
  "default_version": {
    "id": "v1",
    "links": [
      {
        "href": "http://127.0.0.1:6385/v1/",
        "rel": "self"
      }
    ],
    "min_version": "1.1",
    "status": "CURRENT",
    "version": "1.37"
  },
  "description": "Ironic is an OpenStack project which enables the provision and management of baremetal machines.",
  "name": "OpenStack Ironic API",
  "versions": [
    {
      "id": "v1",
      "links": [
        {
          "href": "http://127.0.0.1:6385/v1/",
          "rel": "self"
        }
      ],
      "min_version": "1.1",
      "status": "CURRENT",
      "version": "1.37"
    }
  ]
}
GET
/v1/

Show v1 API

Show all the resources within the Ironic v1 API.

Normal response codes: 200

Request

Response Example

Name

In

Type

Description

id

body

string

Major API version, eg, “v1”

links

body

array

A list of relative links. Includes the self and bookmark links.

openstack-request-id (Optional)

header

string

A unique ID for tracking the request. The request ID associated with the request appears in the log lines for that request. By default, the middleware configuration ensures that the request ID appears in the log files.

x-openstack-ironic-api-version

header

string

Specific API microversion used to generate this response.

x-openstack-ironic-api-min-version

header

string

Minimum API microversion supported by this endpoint, eg. “1.1”

x-openstack-ironic-api-max-version

header

string

Maximum API microversion supported by this endpoint, eg. “1.22”

{
  "chassis": [
    {
      "href": "http://127.0.0.1:6385/v1/chassis/",
      "rel": "self"
    },
    {
      "href": "http://127.0.0.1:6385/chassis/",
      "rel": "bookmark"
    }
  ],
  "drivers": [
    {
      "href": "http://127.0.0.1:6385/v1/drivers/",
      "rel": "self"
    },
    {
      "href": "http://127.0.0.1:6385/drivers/",
      "rel": "bookmark"
    }
  ],
  "heartbeat": [
    {
      "href": "http://127.0.0.1:6385/v1/heartbeat/",
      "rel": "self"
    },
    {
      "href": "http://127.0.0.1:6385/heartbeat/",
      "rel": "bookmark"
    }
  ],
  "id": "v1",
  "links": [
    {
      "href": "http://127.0.0.1:6385/v1/",
      "rel": "self"
    },
    {
      "href": "https://docs.openstack.org/ironic/latest/contributor/webapi.html",
      "rel": "describedby",
      "type": "text/html"
    }
  ],
  "lookup": [
    {
      "href": "http://127.0.0.1:6385/v1/lookup/",
      "rel": "self"
    },
    {
      "href": "http://127.0.0.1:6385/lookup/",
      "rel": "bookmark"
    }
  ],
  "media_types": [
    {
      "base": "application/json",
      "type": "application/vnd.openstack.ironic.v1+json"
    }
  ],
  "nodes": [
    {
      "href": "http://127.0.0.1:6385/v1/nodes/",
      "rel": "self"
    },
    {
      "href": "http://127.0.0.1:6385/nodes/",
      "rel": "bookmark"
    }
  ],
  "portgroups": [
    {
      "href": "http://127.0.0.1:6385/v1/portgroups/",
      "rel": "self"
    },
    {
      "href": "http://127.0.0.1:6385/portgroups/",
      "rel": "bookmark"
    }
  ],
  "ports": [
    {
      "href": "http://127.0.0.1:6385/v1/ports/",
      "rel": "self"
    },
    {
      "href": "http://127.0.0.1:6385/ports/",
      "rel": "bookmark"
    }
  ],
  "volume": [
    {
      "href": "http://127.0.0.1:6385/v1/volume/",
      "rel": "self"
    },
    {
      "href": "http://127.0.0.1:6385/volume/",
      "rel": "bookmark"
    }
  ]
}

Nodes (nodes)

List, Searching, Creating, Updating, and Deleting of bare metal Node resources are done through the /v1/nodes resource. There are also several sub-resources, which allow further actions to be performed on a bare metal Node.

A Node is the canonical representation of a discretely allocatable server, capable of running an Operating System. Each Node must be associated with a driver; this informs Ironic what protocol to use when managing the Node.

Changed in version 1.6: A Node may be referenced both by its UUID and by a unique human-readable “name” in any request. Throughout this documentation, this is referred to as the node_ident. Responses clearly indicate whether a given field is a uuid or a name.

Depending on the Roles assigned to the authenticated OpenStack User, and upon the configuration of the Bare Metal service, API responses may change. For example, the default value of the “show_password” settings cause all API responses to mask passwords within driver_info with the literal string “******”.

POST
/v1/nodes

Create Node

Creates a new Node resource.

This method requires that a driver be supplied in the request body. Most subresources of a Node (eg, properties, driver_info, etc) may be supplied when the Node is created, or the resource may be updated later.

New in version 1.2: Added available state name, which replaced None as the status of an unprovisioned Node. All clients should be updated to use the new available state name. Nodes in the available state may have workloads provisioned on them; they are “available” for use.

New in version 1.5: Introduced the name field.

New in version 1.7: Introduced the clean_step field.

Changed in version 1.11: The default initial state of newly-created Nodes from available to enroll. This provides users a workflow to verify the manageability of a Node and perform necessary operational functions (eg, building a RAID array) before making the Node available for provisioning.

New in version 1.12: Introduced support for the raid_config and target_raid_config fields.

New in version 1.20: Introduced the network_interface field. If this field is not supplied when creating the Node, the default value will be used.

New in version 1.21: Introduced the resource_class field, which may be used to store a resource designation for the proposed OpenStack Placement Engine. This field has no effect within Ironic.

New in version 1.31: Introduced the boot_interface, deploy_interface, management_interface, power_interface, inspect_interface, console_interface, vendor_interface and raid_interface fields. If any of these fields are not supplied when creating the Node, their default value will be used.

Changed in version 1.31: If the specified driver is a dynamic driver, then all the interfaces (boot_interface, deploy_interface, etc.) will be set to the default interface for that driver unless another enabled interface is specified in the creation request.

New in version 1.33: Introduced the storage_interface field. If this field is not supplied when creating the Node, the default value will be used.

New in version 1.38: Introduced the rescue_interface field. If this field is not supplied when creating the Node, the default value will be used.

New in version 1.44: Introduced the deploy_step field.

New in version 1.46: Introduced the conductor_group field.

New in version 1.50: Introduced the owner field.

New in version 1.51: Introduced the description field.

New in version 1.52: Introduced the allocation_uuid field.

New in version 1.65: Introduced the lessee field.

New in version 1.82: Introduced the shard field.

Normal response codes: 201

Error codes: 400,403,406

Request

Name

In

Type

Description

boot_interface (Optional)

body

string

The boot interface for a Node, e.g. “pxe”.

conductor_group (Optional)

body

string

The conductor group for a node. Case-insensitive string up to 255 characters, containing a-z, 0-9, _, -, and ..

console_interface (Optional)

body

string

The console interface for a node, e.g. “no-console”.

deploy_interface (Optional)

body

string

The deploy interface for a node, e.g. “iscsi”.

driver_info (Optional)

body

JSON

All the metadata required by the driver to manage this Node. List of fields varies between drivers, and can be retrieved from the /v1/drivers/<DRIVER_NAME>/properties resource.

driver

body

string

The name of the driver used to manage this Node.

extra (Optional)

body

object

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

inspect_interface (Optional)

body

string

The interface used for node inspection, e.g. “no-inspect”.

management_interface (Optional)

body

string

Interface for out-of-band node management, e.g. “ipmitool”.

name (Optional)

body

string

Human-readable identifier for the Node resource. May be undefined. Certain words are reserved.

network_interface (Optional)

body

string

Which Network Interface provider to use when plumbing the network connections for this Node.

power_interface (Optional)

body

string

Interface used for performing power actions on the node, e.g. “ipmitool”.

properties (Optional)

body

JSON

Physical characteristics of this Node. Populated during inspection, if performed. Can be edited via the REST API at any time.

raid_interface (Optional)

body

string

Interface used for configuring RAID on this node, e.g. “no-raid”.

rescue_interface (Optional)

body

string

The interface used for node rescue, e.g. “no-rescue”.

resource_class (Optional)

body

string

A string which can be used by external schedulers to identify this Node as a unit of a specific type of resource.

storage_interface (Optional)

body

string

Interface used for attaching and detaching volumes on this node, e.g. “cinder”.

uuid (Optional)

body

string

The UUID for the resource.

vendor_interface (Optional)

body

string

Interface for vendor-specific functionality on this node, e.g. “no-vendor”.

owner (Optional)

body

string

A string or UUID of the tenant who owns the object.

description (Optional)

body

string

Informational text about this node.

lessee (Optional)

body

string

A string or UUID of the tenant who is leasing the object.

shard (Optional)

body

string

A string indicating the shard this node belongs to.

automated_clean (Optional)

body

boolean

Indicates whether the node will perform automated clean or not.

bios_interface (Optional)

body

string

The bios interface to be used for this node.

chassis_uuid (Optional)

body

string

UUID of the chassis associated with this Node. May be empty or None.

instance_info (Optional)

body

JSON

Information used to customize the deployed image. May include root partition size, a base 64 encoded config drive, and other metadata. Note that this field is erased automatically when the instance is deleted (this is done by requesting the Node provision state be changed to DELETED).

instance_uuid (Optional)

body

string

UUID of the Nova instance associated with this Node.

maintenance (Optional)

body

boolean

Whether or not this Node is currently in “maintenance mode”. Setting a Node into maintenance mode removes it from the available resource pool and halts some internal automation. This can happen manually (eg, via an API request) or automatically when Ironic detects a hardware fault that prevents communication with the machine.

maintenance_reason (Optional)

body

string

User-settable description of the reason why this Node was placed into maintenance mode

network_data (Optional)

body

JSON

Static network configuration in the OpenStack network data format to use during deployment and cleaning. Requires a specially crafted ramdisk, see DHCP-less documentation.

parent_node (Optional)

body

string

An optional UUID which can be used to denote the “parent” baremetal node.

protected (Optional)

body

boolean

Whether the node is protected from undeploying, rebuilding and deletion.

protected_reason (Optional)

body

string

The reason the node is marked as protected.

retired (Optional)

body

boolean

Whether the node is retired and can hence no longer be provided, i.e. move from manageable to available, and will end up in manageable after cleaning (rather than available).

retired_reason (Optional)

body

string

The reason the node is marked as retired.

Example Node creation request with a dynamic driver:

{
    "name": "test_node_dynamic",
    "driver": "ipmi",
    "driver_info": {
        "ipmi_username": "ADMIN",
        "ipmi_password": "password"
    },
    "power_interface": "ipmitool",
    "resource_class": "bm-large"
}

Response

The response will contain the complete Node record, with the supplied data, and any defaults added for non-specified fields. Most fields default to “null” or “”.

The list and example below are representative of the response as of API microversion 1.81.

Name

In

Type

Description

uuid

body

string

The UUID for the resource.

name (Optional)

body

string

Human-readable identifier for the Node resource. May be undefined. Certain words are reserved.

power_state

body

string

The current power state of this Node. Usually, “power on” or “power off”, but may be “None” if Ironic is unable to determine the power state (eg, due to hardware failure).

target_power_state

body

string

If a power state transition has been requested, this field represents the requested (ie, “target”) state, either “power on” or “power off”.

provision_state

body

string

The current provisioning state of this Node.

target_provision_state

body

string

If a provisioning action has been requested, this field represents the requested (ie, “target”) state. Note that a Node may go through several states during its transition to this target state. For instance, when requesting an instance be deployed to an AVAILABLE Node, the Node may go through the following state change progression: AVAILABLE -> DEPLOYING -> DEPLOYWAIT -> DEPLOYING -> ACTIVE

maintenance

body

boolean

Whether or not this Node is currently in “maintenance mode”. Setting a Node into maintenance mode removes it from the available resource pool and halts some internal automation. This can happen manually (eg, via an API request) or automatically when Ironic detects a hardware fault that prevents communication with the machine.

maintenance_reason (Optional)

body

string

User-settable description of the reason why this Node was placed into maintenance mode

fault (Optional)

body

string

The fault indicates the active fault detected by ironic, typically the Node is in “maintenance mode”. None means no fault has been detected by ironic. “power failure” indicates ironic failed to retrieve power state from this node. There are other possible types, e.g., “clean failure” and “rescue abort failure”.

last_error

body

string

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

reservation

body

string

The name of an Ironic Conductor host which is holding a lock on this node, if a lock is held. Usually “null”, but this field can be useful for debugging.

driver

body

string

The name of the driver.

driver_info

body

JSON

All the metadata required by the driver to manage this Node. List of fields varies between drivers, and can be retrieved from the /v1/drivers/<DRIVER_NAME>/properties resource.

driver_internal_info (Optional)

body

JSON

Internal metadata set and stored by the Node’s driver. This field is read-only.

properties

body

JSON

Physical characteristics of this Node. Populated by ironic-inspector during inspection. May be edited via the REST API at any time.

instance_info

body

JSON

Information used to customize the deployed image. May include root partition size, a base 64 encoded config drive, and other metadata. Note that this field is erased automatically when the instance is deleted (this is done by requesting the Node provision state be changed to DELETED).

instance_uuid

body

string

UUID of the Nova instance associated with this Node.

chassis_uuid

body

string

UUID of the chassis associated with this Node. May be empty or None.

extra

body

object

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

console_enabled

body

boolean

Indicates whether console access is enabled or disabled on this node.

raid_config (Optional)

body

JSON

Represents the current RAID configuration of the node. Introduced with the cleaning feature.

target_raid_config

body

JSON

Represents the requested RAID configuration of the node, which will be applied when the Node next transitions through the CLEANING state. Introduced with the cleaning feature.

clean_step (Optional)

body

string

The current clean step. Introduced with the cleaning feature.

deploy_step (Optional)

body

string

The current deploy step.

links

body

array

A list of relative links. Includes the self and bookmark links.

ports

body

array

Links to the collection of ports on this node

portgroups

body

array

Links to the collection of portgroups on this node.

states

body

array

Links to the collection of states. Note that this resource is also used to request state transitions.

resource_class

body

string

A string which can be used by external schedulers to identify this Node as a unit of a specific type of resource. For more details, see: https://docs.openstack.org/ironic/latest/install/configure-nova-flavors.html

boot_interface

body

string

The boot interface for a Node, e.g. “pxe”.

console_interface

body

string

The console interface for a node, e.g. “no-console”.

deploy_interface

body

string

The deploy interface for a node, e.g. “iscsi”.

inspect_interface

body

string

The interface used for node inspection, e.g. “no-inspect”.

management_interface

body

string

Interface for out-of-band node management, e.g. “ipmitool”.

network_interface

body

string

Which Network Interface provider to use when plumbing the network connections for this Node.

power_interface

body

string

Interface used for performing power actions on the node, e.g. “ipmitool”.

raid_interface

body

string

Interface used for configuring RAID on this node, e.g. “no-raid”.

rescue_interface

body

string

The interface used for node rescue, e.g. “no-rescue”.

storage_interface

body

string

Interface used for attaching and detaching volumes on this node, e.g. “cinder”.

traits

body

array

List of traits for this node.

vendor_interface

body

string

Interface for vendor-specific functionality on this node, e.g. “no-vendor”.

volume

body

array

Links to the volume resources.

conductor_group

body

string

The conductor group for a node. Case-insensitive string up to 255 characters, containing a-z, 0-9, _, -, and ..

parent_node (Optional)

body

string

An optional UUID which can be used to denote the “parent” baremetal node.

protected (Optional)

body

boolean

Whether the node is protected from undeploying, rebuilding and deletion.

protected_reason (Optional)

body

string

The reason the node is marked as protected.

conductor (Optional)

body

string

The conductor currently servicing a node. This field is read-only.

owner (Optional)

body

string

A string or UUID of the tenant who owns the object.

lessee (Optional)

body

string

A string or UUID of the tenant who is leasing the object.

shard (Optional)

body

string

A string indicating the shard this node belongs to.

description

body

string

Informational text about this node.

allocation_uuid

body

string

The UUID of the allocation associated with the node. If not null, will be the same as instance_uuid (the opposite is not always true). Unlike instance_uuid, this field is read-only. Please use the Allocation API to remove allocations.

automated_clean

body

boolean

Indicates whether the node will perform automated clean or not.

bios_interface

body

string

The bios interface to be used for this node.

network_data (Optional)

body

JSON

Static network configuration in the OpenStack network data format to use during deployment and cleaning. Requires a specially crafted ramdisk, see DHCP-less documentation.

retired (Optional)

body

boolean

Whether the node is retired and can hence no longer be provided, i.e. move from manageable to available, and will end up in manageable after cleaning (rather than available).

retired_reason (Optional)

body

string

The reason the node is marked as retired.

Example JSON representation of a Node:

{
  "allocation_uuid": null,
  "boot_interface": null,
  "chassis_uuid": null,
  "clean_step": {},
  "conductor_group": "group-1",
  "console_enabled": false,
  "console_interface": null,
  "created_at": "2016-08-18T22:28:48.643434+11:11",
  "deploy_interface": null,
  "deploy_step": {},
  "description": null,
  "driver": "agent_ipmitool",
  "driver_info": {
    "ipmi_password": "******",
    "ipmi_username": "ADMIN"
  },
  "driver_internal_info": {},
  "extra": {},
  "inspect_interface": null,
  "inspection_finished_at": null,
  "inspection_started_at": null,
  "instance_info": {},
  "instance_uuid": null,
  "last_error": null,
  "lessee": null,
  "links": [
    {
      "href": "http://127.0.0.1:6385/v1/nodes/6d85703a-565d-469a-96ce-30b6de53079d",
      "rel": "self"
    },
    {
      "href": "http://127.0.0.1:6385/nodes/6d85703a-565d-469a-96ce-30b6de53079d",
      "rel": "bookmark"
    }
  ],
  "maintenance": false,
  "maintenance_reason": null,
  "management_interface": null,
  "name": "test_node_classic",
  "network_data": {},
  "network_interface": "flat",
  "owner": null,
  "portgroups": [
    {
      "href": "http://127.0.0.1:6385/v1/nodes/6d85703a-565d-469a-96ce-30b6de53079d/portgroups",
      "rel": "self"
    },
    {
      "href": "http://127.0.0.1:6385/nodes/6d85703a-565d-469a-96ce-30b6de53079d/portgroups",
      "rel": "bookmark"
    }
  ],
  "ports": [
    {
      "href": "http://127.0.0.1:6385/v1/nodes/6d85703a-565d-469a-96ce-30b6de53079d/ports",
      "rel": "self"
    },
    {
      "href": "http://127.0.0.1:6385/nodes/6d85703a-565d-469a-96ce-30b6de53079d/ports",
      "rel": "bookmark"
    }
  ],
  "power_interface": null,
  "power_state": null,
  "properties": {},
  "protected": false,
  "protected_reason": null,
  "provision_state": "enroll",
  "provision_updated_at": null,
  "raid_config": {},
  "raid_interface": null,
  "rescue_interface": null,
  "reservation": null,
  "resource_class": "bm-large",
  "retired": false,
  "retired_reason": null,
  "states": [
    {
      "href": "http://127.0.0.1:6385/v1/nodes/6d85703a-565d-469a-96ce-30b6de53079d/states",
      "rel": "self"
    },
    {
      "href": "http://127.0.0.1:6385/nodes/6d85703a-565d-469a-96ce-30b6de53079d/states",
      "rel": "bookmark"
    }
  ],
  "storage_interface": "noop",
  "target_power_state": null,
  "target_provision_state": null,
  "target_raid_config": {},
  "traits": [],
  "updated_at": null,
  "uuid": "6d85703a-565d-469a-96ce-30b6de53079d",
  "vendor_interface": null,
  "volume": [
    {
      "href": "http://127.0.0.1:6385/v1/nodes/6d85703a-565d-469a-96ce-30b6de53079d/volume",
      "rel": "self"
    },
    {
      "href": "http://127.0.0.1:6385/nodes/6d85703a-565d-469a-96ce-30b6de53079d/volume",
      "rel": "bookmark"
    }
  ]
}
GET
/v1/nodes

List Nodes

Return a list of bare metal Nodes, with some useful information about each Node. Some filtering is possible by passing in flags with the request.

By default, this query will return the name, uuid, instance uuid, power state, provision state, and maintenance setting for each Node.

New in version 1.8: Added the fields Request parameter. When specified, this causes the content of the Response to include only the specified fields, rather than the default set.

New in version 1.9: Added the provision_state Request parameter, allowing the list of returned Nodes to be filtered by their current state.

New in version 1.16: Added the driver Request parameter, allowing the list of returned Nodes to be filtered by their driver name.

New in version 1.21: Added the resource_class Request parameter, allowing the list of returned Nodes to be filtered by this field.

New in version 1.42: Introduced the fault field.

New in version 1.43: Added the detail boolean request parameter. When specified True this causes the response to include complete details about each node, as shown in the “List Nodes Detailed” section below.

New in version 1.46: Introduced the conductor_group request parameter, to allow filtering the list of returned nodes by conductor group.

New in version 1.49: Introduced the conductor request parameter, to allow filtering the list of returned nodes by conductor.

New in version 1.50: Introduced the owner field.

New in version 1.51: Introduced the description field.

New in version 1.65: Introduced the lessee field.

New in version 1.82: Introduced the shard field. Introduced the sharded request parameter.

New in version 1.83: Introduced the parent_node field and query parameter to identify matching nodes. Introduced the include_children parameter which allows for all child nodes to be enumerated, which are normally hidden as child nodes are not normally intended for direct consumption by end users.

Normal response codes: 200

Error codes: 400,403,406

Request

Name

In

Type

Description

instance_uuid (Optional)

query

string

Filter the list of returned nodes, and only return the node with this specific instance UUID, or an empty set if not found.

maintenance (Optional)

query

boolean

Filter the list of returned nodes and only return those with maintenance set to True or False.

associated (Optional)

query

boolean

Filter the list of returned nodes and only return those which are, or are not, associated with an instance_uuid.

provision_state (Optional)

query

string

Filter the list of returned nodes, and only return those with the specified provision_state.

driver (Optional)

query

string

Filter the list of returned nodes, and only return those with the specified driver.

resource_class (Optional)

query

string

Filter the list of returned nodes, and only return the ones with the specified resource class.

conductor_group (Optional)

query

string

Filter the list of returned nodes, and only return those with the specified conductor_group. Case-insensitive string up to 255 characters, containing a-z, 0-9, _, -, and ..

conductor (Optional)

query

string

Filter the list of returned nodes, and only return those with the specified conductor.

fault (Optional)

query

string

Filter the list of returned nodes, and only return those with the specified fault. Possible values are determined by faults supported by ironic, e.g., power failure, clean failure or rescue abort failure.

owner (Optional)

body

string

A string or UUID of the tenant who owns the object.

lessee (Optional)

body

string

A string or UUID of the tenant who is leasing the object.

shard (Optional)

body

array

Filter the list of returned Nodes, and only return the ones associated with nodes in this specific shard(s), or an empty set if not found.

sharded (Optional)

body

boolean

When true, filter the list of returned Nodes, and only return the ones with a non-null shard value. When false, the inverse filter is performed.

description_contains (Optional)

query

string

Filter the list of returned nodes, and only return those containing substring specified by description_contains.

fields (Optional)

query

array

One or more fields to be returned in the response.

For example, the following request returns only the uuid and name fields for each node:

GET /v1/nodes?fields=uuid,name

limit (Optional)

query

integer

Requests a page size of items. Returns a number of items up to a limit value. Use the limit parameter to make an initial limited request and use the ID of the last-seen item from the response as the marker parameter value in a subsequent limited request. This value cannot be larger than the max_limit option in the [api] section of the configuration. If it is higher than max_limit, only max-limit resources will be returned.

marker (Optional)

query

string

The ID of the last-seen item. Use the limit parameter to make an initial limited request and use the ID of the last-seen item from the response as the marker parameter value in a subsequent limited request.

sort_dir (Optional)

query

string

Sorts the response by the requested sort direction. A valid value is asc (ascending) or desc (descending). Default is asc. You can specify multiple pairs of sort key and sort direction query parameters. If you omit the sort direction in a pair, the API uses the natural sorting direction of the server attribute that is provided as the sort_key.

sort_key (Optional)

query

string

Sorts the response by this attribute value. Default is id. You can specify multiple pairs of sort key and sort direction query parameters. If you omit the sort direction in a pair, the API uses the natural sorting direction of the server attribute that is provided as the sort_key.

detail (Optional)

query

boolean

Whether to show detailed information about the resource. This cannot be set to True if fields parameter is specified.

parent_node (Optional)

body

string

An optional UUID which can be used to denote the “parent” baremetal node.

include_children (Optional)

query

boolean

Whether to show child nodes in the node list, which are normally hidden.

Response

Name

In

Type

Description

uuid

body

string

The UUID for the resource.

name (Optional)

body

string

Human-readable identifier for the Node resource. May be undefined. Certain words are reserved.

instance_uuid

body

string

UUID of the Nova instance associated with this Node.

power_state

body

string

The current power state of this Node. Usually, “power on” or “power off”, but may be “None” if Ironic is unable to determine the power state (eg, due to hardware failure).

provision_state

body

string

The current provisioning state of this Node.

maintenance

body

boolean

Whether or not this Node is currently in “maintenance mode”. Setting a Node into maintenance mode removes it from the available resource pool and halts some internal automation. This can happen manually (eg, via an API request) or automatically when Ironic detects a hardware fault that prevents communication with the machine.

links

body

array

A list of relative links. Includes the self and bookmark links.

Example list of Nodes:

{
  "nodes": [
    {
      "instance_uuid": null,
      "links": [
        {
          "href": "http://127.0.0.1:6385/v1/nodes/6d85703a-565d-469a-96ce-30b6de53079d",
          "rel": "self"
        },
        {
          "href": "http://127.0.0.1:6385/nodes/6d85703a-565d-469a-96ce-30b6de53079d",
          "rel": "bookmark"
        }
      ],
      "maintenance": false,
      "name": "test_node_classic",
      "power_state": "power off",
      "provision_state": "available",
      "uuid": "6d85703a-565d-469a-96ce-30b6de53079d"
    },
    {
      "instance_uuid": null,
      "links": [
        {
          "href": "http://127.0.0.1:6385/v1/nodes/2b045129-a906-46af-bc1a-092b294b3428",
          "rel": "self"
        },
        {
          "href": "http://127.0.0.1:6385/nodes/2b045129-a906-46af-bc1a-092b294b3428",
          "rel": "bookmark"
        }
      ],
      "maintenance": false,
      "name": "test_node_dynamic",
      "power_state": null,
      "provision_state": "enroll",
      "uuid": "2b045129-a906-46af-bc1a-092b294b3428"
    }
  ]
}
GET
/v1/nodes/detail

List Nodes Detailed

Deprecated since version Use: ?detail=True query string instead.

Return a list of bare metal Nodes with complete details. Some filtering is possible by passing in flags with the request.

This method is particularly useful to locate the Node associated to a given Nova instance, eg. with a request to v1/nodes/detail?instance_uuid={NOVA INSTANCE UUID}

New in version 1.37: Introduced the traits field.

New in version 1.38: Introduced the rescue_interface field.

New in version 1.42: Introduced the fault field.

New in version 1.46: Introduced the conductor_group field.

New in version 1.48: Introduced the protected and protected_reason fields.

New in version 1.49: Introduced the conductor request parameter and conductor field.

New in version 1.50: Introduced the owner field.

New in version 1.51: Introduced the description field.

New in version 1.52: Introduced the allocation_uuid field.

New in version 1.65: Introduced the lessee field.

New in version 1.82: Introduced the shard field. Introduced the sharded request parameter.

Normal response codes: 200

Error codes: 400,403,406

Request

Name

In

Type

Description

instance_uuid (Optional)

query

string

Filter the list of returned nodes, and only return the node with this specific instance UUID, or an empty set if not found.

maintenance (Optional)

query

boolean

Filter the list of returned nodes and only return those with maintenance set to True or False.

fault (Optional)

query

string

Filter the list of returned nodes, and only return those with the specified fault. Possible values are determined by faults supported by ironic, e.g., power failure, clean failure or rescue abort failure.

associated (Optional)

query

boolean

Filter the list of returned nodes and only return those which are, or are not, associated with an instance_uuid.

provision_state (Optional)

query

string

Filter the list of returned nodes, and only return those with the specified provision_state.

driver (Optional)

query

string

Filter the list of returned nodes, and only return those with the specified driver.

resource_class (Optional)

query

string

Filter the list of returned nodes, and only return the ones with the specified resource class.

conductor_group (Optional)

query

string

Filter the list of returned nodes, and only return those with the specified conductor_group. Case-insensitive string up to 255 characters, containing a-z, 0-9, _, -, and ..

conductor (Optional)

query

string

Filter the list of returned nodes, and only return those with the specified conductor.

owner (Optional)

body

string

A string or UUID of the tenant who owns the object.

lessee (Optional)

body

string

A string or UUID of the tenant who is leasing the object.

shard (Optional)

body

array

Filter the list of returned Nodes, and only return the ones associated with nodes in this specific shard(s), or an empty set if not found.

sharded (Optional)

body

boolean

When true, filter the list of returned Nodes, and only return the ones with a non-null shard value. When false, the inverse filter is performed.

description_contains (Optional)

query

string

Filter the list of returned nodes, and only return those containing substring specified by description_contains.

limit (Optional)

query

integer

Requests a page size of items. Returns a number of items up to a limit value. Use the limit parameter to make an initial limited request and use the ID of the last-seen item from the response as the marker parameter value in a subsequent limited request. This value cannot be larger than the max_limit option in the [api] section of the configuration. If it is higher than max_limit, only max-limit resources will be returned.

marker (Optional)

query

string

The ID of the last-seen item. Use the limit parameter to make an initial limited request and use the ID of the last-seen item from the response as the marker parameter value in a subsequent limited request.

sort_dir (Optional)

query

string

Sorts the response by the requested sort direction. A valid value is asc (ascending) or desc (descending). Default is asc. You can specify multiple pairs of sort key and sort direction query parameters. If you omit the sort direction in a pair, the API uses the natural sorting direction of the server attribute that is provided as the sort_key.

sort_key (Optional)

query

string

Sorts the response by this attribute value. Default is id. You can specify multiple pairs of sort key and sort direction query parameters. If you omit the sort direction in a pair, the API uses the natural sorting direction of the server attribute that is provided as the sort_key.

Response

Name

In

Type

Description

uuid

body

string

The UUID for the resource.

name (Optional)

body

string

Human-readable identifier for the Node resource. May be undefined. Certain words are reserved.

power_state

body

string

The current power state of this Node. Usually, “power on” or “power off”, but may be “None” if Ironic is unable to determine the power state (eg, due to hardware failure).

target_power_state

body

string

If a power state transition has been requested, this field represents the requested (ie, “target”) state, either “power on” or “power off”.

provision_state

body

string

The current provisioning state of this Node.

target_provision_state

body

string

If a provisioning action has been requested, this field represents the requested (ie, “target”) state. Note that a Node may go through several states during its transition to this target state. For instance, when requesting an instance be deployed to an AVAILABLE Node, the Node may go through the following state change progression: AVAILABLE -> DEPLOYING -> DEPLOYWAIT -> DEPLOYING -> ACTIVE

maintenance

body

boolean

Whether or not this Node is currently in “maintenance mode”. Setting a Node into maintenance mode removes it from the available resource pool and halts some internal automation. This can happen manually (eg, via an API request) or automatically when Ironic detects a hardware fault that prevents communication with the machine.

maintenance_reason (Optional)

body

string

User-settable description of the reason why this Node was placed into maintenance mode

fault (Optional)

body

string

The fault indicates the active fault detected by ironic, typically the Node is in “maintenance mode”. None means no fault has been detected by ironic. “power failure” indicates ironic failed to retrieve power state from this node. There are other possible types, e.g., “clean failure” and “rescue abort failure”.

last_error

body

string

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

reservation

body

string

The name of an Ironic Conductor host which is holding a lock on this node, if a lock is held. Usually “null”, but this field can be useful for debugging.

driver

body

string

The name of the driver.

driver_info

body

JSON

All the metadata required by the driver to manage this Node. List of fields varies between drivers, and can be retrieved from the /v1/drivers/<DRIVER_NAME>/properties resource.

driver_internal_info (Optional)

body

JSON

Internal metadata set and stored by the Node’s driver. This field is read-only.

properties

body

JSON

Physical characteristics of this Node. Populated by ironic-inspector during inspection. May be edited via the REST API at any time.

instance_info

body

JSON

Information used to customize the deployed image. May include root partition size, a base 64 encoded config drive, and other metadata. Note that this field is erased automatically when the instance is deleted (this is done by requesting the Node provision state be changed to DELETED).

instance_uuid

body

string

UUID of the Nova instance associated with this Node.

chassis_uuid

body

string

UUID of the chassis associated with this Node. May be empty or None.

extra

body

object

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

console_enabled

body

boolean

Indicates whether console access is enabled or disabled on this node.

raid_config (Optional)

body

JSON

Represents the current RAID configuration of the node. Introduced with the cleaning feature.

target_raid_config

body

JSON

Represents the requested RAID configuration of the node, which will be applied when the Node next transitions through the CLEANING state. Introduced with the cleaning feature.

clean_step (Optional)

body

string

The current clean step. Introduced with the cleaning feature.

deploy_step (Optional)

body

string

The current deploy step.

links

body

array

A list of relative links. Includes the self and bookmark links.

ports

body

array

Links to the collection of ports on this node

portgroups

body

array

Links to the collection of portgroups on this node.

states

body

array

Links to the collection of states. Note that this resource is also used to request state transitions.

resource_class

body

string

A string which can be used by external schedulers to identify this Node as a unit of a specific type of resource. For more details, see: https://docs.openstack.org/ironic/latest/install/configure-nova-flavors.html

bios_interface

body

string

The bios interface to be used for this node.

boot_interface

body

string

The boot interface for a Node, e.g. “pxe”.

console_interface

body

string

The console interface for a node, e.g. “no-console”.

deploy_interface

body

string

The deploy interface for a node, e.g. “iscsi”.

inspect_interface

body

string

The interface used for node inspection, e.g. “no-inspect”.

management_interface

body

string

Interface for out-of-band node management, e.g. “ipmitool”.

network_interface

body

string

Which Network Interface provider to use when plumbing the network connections for this Node.

power_interface

body

string

Interface used for performing power actions on the node, e.g. “ipmitool”.

raid_interface

body

string

Interface used for configuring RAID on this node, e.g. “no-raid”.

rescue_interface

body

string

The interface used for node rescue, e.g. “no-rescue”.

storage_interface

body

string

Interface used for attaching and detaching volumes on this node, e.g. “cinder”.

traits

body

array

List of traits for this node.

vendor_interface

body

string

Interface for vendor-specific functionality on this node, e.g. “no-vendor”.

volume

body

array

Links to the volume resources.

conductor_group

body

string

The conductor group for a node. Case-insensitive string up to 255 characters, containing a-z, 0-9, _, -, and ..

parent_node (Optional)

body

string

An optional UUID which can be used to denote the “parent” baremetal node.

protected (Optional)

body

boolean

Whether the node is protected from undeploying, rebuilding and deletion.

protected_reason (Optional)

body

string

The reason the node is marked as protected.

owner (Optional)

body

string

A string or UUID of the tenant who owns the object.

lessee (Optional)

body

string

A string or UUID of the tenant who is leasing the object.

shard (Optional)

body

string

A string indicating the shard this node belongs to.

description

body

string

Informational text about this node.

conductor (Optional)

body

string

The conductor currently servicing a node. This field is read-only.

allocation_uuid

body

string

The UUID of the allocation associated with the node. If not null, will be the same as instance_uuid (the opposite is not always true). Unlike instance_uuid, this field is read-only. Please use the Allocation API to remove allocations.

retired (Optional)

body

boolean

Whether the node is retired and can hence no longer be provided, i.e. move from manageable to available, and will end up in manageable after cleaning (rather than available).

retired_reason (Optional)

body

string

The reason the node is marked as retired.

network_data (Optional)

body

JSON

Static network configuration in the OpenStack network data format to use during deployment and cleaning. Requires a specially crafted ramdisk, see DHCP-less documentation.

Example detailed list of Nodes:

{
  "nodes": [
    {
      "allocation_uuid": "5344a3e2-978a-444e-990a-cbf47c62ef88",
      "boot_interface": null,
      "chassis_uuid": null,
      "clean_step": {},
      "conductor": "compute1.localdomain",
      "conductor_group": "group-1",
      "console_enabled": false,
      "console_interface": null,
      "created_at": "2016-08-18T22:28:48.643434+11:11",
      "deploy_interface": null,
      "deploy_step": {},
      "description": null,
      "driver": "fake",
      "driver_info": {
        "ipmi_password": "******",
        "ipmi_username": "ADMIN"
      },
      "driver_internal_info": {
        "clean_steps": null
      },
      "extra": {},
      "inspect_interface": null,
      "inspection_finished_at": null,
      "inspection_started_at": null,
      "instance_info": {},
      "instance_uuid": "5344a3e2-978a-444e-990a-cbf47c62ef88",
      "last_error": null,
      "lessee": null,
      "links": [
        {
          "href": "http://127.0.0.1:6385/v1/nodes/6d85703a-565d-469a-96ce-30b6de53079d",
          "rel": "self"
        },
        {
          "href": "http://127.0.0.1:6385/nodes/6d85703a-565d-469a-96ce-30b6de53079d",
          "rel": "bookmark"
        }
      ],
      "maintenance": false,
      "maintenance_reason": null,
      "management_interface": null,
      "name": "test_node_classic",
      "network_data": {},
      "network_interface": "flat",
      "owner": "john doe",
      "portgroups": [
        {
          "href": "http://127.0.0.1:6385/v1/nodes/6d85703a-565d-469a-96ce-30b6de53079d/portgroups",
          "rel": "self"
        },
        {
          "href": "http://127.0.0.1:6385/nodes/6d85703a-565d-469a-96ce-30b6de53079d/portgroups",
          "rel": "bookmark"
        }
      ],
      "ports": [
        {
          "href": "http://127.0.0.1:6385/v1/nodes/6d85703a-565d-469a-96ce-30b6de53079d/ports",
          "rel": "self"
        },
        {
          "href": "http://127.0.0.1:6385/nodes/6d85703a-565d-469a-96ce-30b6de53079d/ports",
          "rel": "bookmark"
        }
      ],
      "power_interface": null,
      "power_state": "power off",
      "properties": {},
      "protected": false,
      "protected_reason": null,
      "provision_state": "available",
      "provision_updated_at": "2016-08-18T22:28:49.946416+00:00",
      "raid_config": {},
      "raid_interface": null,
      "rescue_interface": null,
      "reservation": null,
      "resource_class": null,
      "retired": false,
      "retired_reason": null,
      "states": [
        {
          "href": "http://127.0.0.1:6385/v1/nodes/6d85703a-565d-469a-96ce-30b6de53079d/states",
          "rel": "self"
        },
        {
          "href": "http://127.0.0.1:6385/nodes/6d85703a-565d-469a-96ce-30b6de53079d/states",
          "rel": "bookmark"
        }
      ],
      "storage_interface": "noop",
      "target_power_state": null,
      "target_provision_state": null,
      "target_raid_config": {},
      "traits": [],
      "updated_at": "2016-08-18T22:28:49.653974+00:00",
      "uuid": "6d85703a-565d-469a-96ce-30b6de53079d",
      "vendor_interface": null,
      "volume": [
        {
          "href": "http://127.0.0.1:6385/v1/nodes/6d85703a-565d-469a-96ce-30b6de53079d/volume",
          "rel": "self"
        },
        {
          "href": "http://127.0.0.1:6385/nodes/6d85703a-565d-469a-96ce-30b6de53079d/volume",
          "rel": "bookmark"
        }
      ]
    },
    {
      "allocation_uuid": null,
      "boot_interface": "pxe",
      "chassis_uuid": null,
      "clean_step": {},
      "conductor": "compute1.localdomain",
      "conductor_group": "",
      "console_enabled": false,
      "console_interface": "no-console",
      "created_at": "2016-08-18T22:28:48.643434+11:11",
      "deploy_interface": "direct",
      "deploy_step": {},
      "driver": "ipmi",
      "driver_info": {
        "ipmi_password": "******",
        "ipmi_username": "ADMIN"
      },
      "driver_internal_info": {},
      "extra": {},
      "inspect_interface": "no-inspect",
      "inspection_finished_at": null,
      "inspection_started_at": null,
      "instance_info": {},
      "instance_uuid": null,
      "last_error": null,
      "lessee": null,
      "links": [
        {
          "href": "http://127.0.0.1:6385/v1/nodes/2b045129-a906-46af-bc1a-092b294b3428",
          "rel": "self"
        },
        {
          "href": "http://127.0.0.1:6385/nodes/2b045129-a906-46af-bc1a-092b294b3428",
          "rel": "bookmark"
        }
      ],
      "maintenance": false,
      "maintenance_reason": null,
      "management_interface": "ipmitool",
      "name": "test_node_dynamic",
      "network_data": {},
      "network_interface": "flat",
      "owner": "43e61ec9-8e42-4dcb-bc45-30d66aa93e5b",
      "portgroups": [
        {
          "href": "http://127.0.0.1:6385/v1/nodes/2b045129-a906-46af-bc1a-092b294b3428/portgroups",
          "rel": "self"
        },
        {
          "href": "http://127.0.0.1:6385/nodes/2b045129-a906-46af-bc1a-092b294b3428/portgroups",
          "rel": "bookmark"
        }
      ],
      "ports": [
        {
          "href": "http://127.0.0.1:6385/v1/nodes/2b045129-a906-46af-bc1a-092b294b3428/ports",
          "rel": "self"
        },
        {
          "href": "http://127.0.0.1:6385/nodes/2b045129-a906-46af-bc1a-092b294b3428/ports",
          "rel": "bookmark"
        }
      ],
      "power_interface": "ipmitool",
      "power_state": null,
      "properties": {},
      "protected": false,
      "protected_reason": null,
      "provision_state": "enroll",
      "provision_updated_at": null,
      "raid_config": {},
      "raid_interface": "no-raid",
      "rescue_interface": "no-rescue",
      "reservation": null,
      "resource_class": null,
      "retired": false,
      "retired_reason": null,
      "states": [
        {
          "href": "http://127.0.0.1:6385/v1/nodes/2b045129-a906-46af-bc1a-092b294b3428/states",
          "rel": "self"
        },
        {
          "href": "http://127.0.0.1:6385/nodes/2b045129-a906-46af-bc1a-092b294b3428/states",
          "rel": "bookmark"
        }
      ],
      "storage_interface": "noop",
      "target_power_state": null,
      "target_provision_state": null,
      "target_raid_config": {},
      "traits": [],
      "updated_at": null,
      "uuid": "2b045129-a906-46af-bc1a-092b294b3428",
      "vendor_interface": "no-vendor",
      "volume": [
        {
          "href": "http://127.0.0.1:6385/v1/nodes/2b045129-a906-46af-bc1a-092b294b3428/volume",
          "rel": "self"
        },
        {
          "href": "http://127.0.0.1:6385/nodes/2b045129-a906-46af-bc1a-092b294b3428/volume",
          "rel": "bookmark"
        }
      ]
    }
  ]
}
GET
/v1/nodes/{node_ident}

Show Node Details

Shows details for a node. By default, this will return the full representation of the resource; an optional fields parameter can be supplied to return only the specified set.

New in version 1.37: Introduced the traits field.

New in version 1.38: Introduced the rescue_interface field.

New in version 1.42: Introduced the fault field.

New in version 1.46: Introduced the conductor_group field.

New in version 1.48: Introduced the protected and protected_reason fields.

New in version 1.49: Introduced the conductor field

New in version 1.50: Introduced the owner field.

New in version 1.51: Introduced the description field.

New in version 1.52: Introduced the allocation_uuid field.

New in version 1.61: Introduced the retired and retired_reason fields.

New in version 1.65: Introduced the lessee field.

New in version 1.66: Introduced the network_data field.

New in version 1.82: Introduced the shard field.

New in version 1.83: Introduced the parent_node field.

Normal response codes: 200

Error codes: 400,403,404,406

Request

Name

In

Type

Description

node_ident

path

string

The UUID or Name of the node.

fields (Optional)

query

array

One or more fields to be returned in the response.

For example, the following request returns only the uuid and name fields for each node:

GET /v1/nodes?fields=uuid,name

Response

Name

In

Type

Description

uuid

body

string

The UUID for the resource.

name (Optional)

body

string

Human-readable identifier for the Node resource. May be undefined. Certain words are reserved.

power_state

body

string

The current power state of this Node. Usually, “power on” or “power off”, but may be “None” if Ironic is unable to determine the power state (eg, due to hardware failure).

target_power_state

body

string

If a power state transition has been requested, this field represents the requested (ie, “target”) state, either “power on” or “power off”.

provision_state

body

string

The current provisioning state of this Node.

target_provision_state

body

string

If a provisioning action has been requested, this field represents the requested (ie, “target”) state. Note that a Node may go through several states during its transition to this target state. For instance, when requesting an instance be deployed to an AVAILABLE Node, the Node may go through the following state change progression: AVAILABLE -> DEPLOYING -> DEPLOYWAIT -> DEPLOYING -> ACTIVE

maintenance

body

boolean

Whether or not this Node is currently in “maintenance mode”. Setting a Node into maintenance mode removes it from the available resource pool and halts some internal automation. This can happen manually (eg, via an API request) or automatically when Ironic detects a hardware fault that prevents communication with the machine.

maintenance_reason (Optional)

body

string

User-settable description of the reason why this Node was placed into maintenance mode

fault (Optional)

body

string

The fault indicates the active fault detected by ironic, typically the Node is in “maintenance mode”. None means no fault has been detected by ironic. “power failure” indicates ironic failed to retrieve power state from this node. There are other possible types, e.g., “clean failure” and “rescue abort failure”.

last_error

body

string

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

reservation

body

string

The name of an Ironic Conductor host which is holding a lock on this node, if a lock is held. Usually “null”, but this field can be useful for debugging.

driver

body

string

The name of the driver.

driver_info

body

JSON

All the metadata required by the driver to manage this Node. List of fields varies between drivers, and can be retrieved from the /v1/drivers/<DRIVER_NAME>/properties resource.

driver_internal_info (Optional)

body

JSON

Internal metadata set and stored by the Node’s driver. This field is read-only.

properties

body

JSON

Physical characteristics of this Node. Populated by ironic-inspector during inspection. May be edited via the REST API at any time.

instance_info

body

JSON

Information used to customize the deployed image. May include root partition size, a base 64 encoded config drive, and other metadata. Note that this field is erased automatically when the instance is deleted (this is done by requesting the Node provision state be changed to DELETED).

instance_uuid

body

string

UUID of the Nova instance associated with this Node.

chassis_uuid

body

string

UUID of the chassis associated with this Node. May be empty or None.

extra

body

object

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

console_enabled

body

boolean

Indicates whether console access is enabled or disabled on this node.

raid_config (Optional)

body

JSON

Represents the current RAID configuration of the node. Introduced with the cleaning feature.

target_raid_config

body

JSON

Represents the requested RAID configuration of the node, which will be applied when the Node next transitions through the CLEANING state. Introduced with the cleaning feature.

clean_step (Optional)

body

string

The current clean step. Introduced with the cleaning feature.

deploy_step (Optional)

body

string

The current deploy step.

links

body

array

A list of relative links. Includes the self and bookmark links.

ports

body

array

Links to the collection of ports on this node

portgroups

body

array

Links to the collection of portgroups on this node.

states

body

array

Links to the collection of states. Note that this resource is also used to request state transitions.

resource_class

body

string

A string which can be used by external schedulers to identify this Node as a unit of a specific type of resource. For more details, see: https://docs.openstack.org/ironic/latest/install/configure-nova-flavors.html

bios_interface

body

string

The bios interface to be used for this node.

boot_interface

body

string

The boot interface for a Node, e.g. “pxe”.

console_interface

body

string

The console interface for a node, e.g. “no-console”.

deploy_interface

body

string

The deploy interface for a node, e.g. “iscsi”.

inspect_interface

body

string

The interface used for node inspection, e.g. “no-inspect”.

management_interface

body

string

Interface for out-of-band node management, e.g. “ipmitool”.

network_interface

body

string

Which Network Interface provider to use when plumbing the network connections for this Node.

power_interface

body

string

Interface used for performing power actions on the node, e.g. “ipmitool”.

raid_interface

body

string

Interface used for configuring RAID on this node, e.g. “no-raid”.

rescue_interface

body

string

The interface used for node rescue, e.g. “no-rescue”.

storage_interface

body

string

Interface used for attaching and detaching volumes on this node, e.g. “cinder”.

traits

body

array

List of traits for this node.

vendor_interface

body

string

Interface for vendor-specific functionality on this node, e.g. “no-vendor”.

volume

body

array

Links to the volume resources.

conductor_group

body

string

The conductor group for a node. Case-insensitive string up to 255 characters, containing a-z, 0-9, _, -, and ..

protected (Optional)

body

boolean

Whether the node is protected from undeploying, rebuilding and deletion.

protected_reason (Optional)

body

string

The reason the node is marked as protected.

owner (Optional)

body

string

A string or UUID of the tenant who owns the object.

lessee (Optional)

body

string

A string or UUID of the tenant who is leasing the object.

shard (Optional)

body

string

A string indicating the shard this node belongs to.

description

body

string

Informational text about this node.

conductor (Optional)

body

string

The conductor currently servicing a node. This field is read-only.

allocation_uuid

body

string

The UUID of the allocation associated with the node. If not null, will be the same as instance_uuid (the opposite is not always true). Unlike instance_uuid, this field is read-only. Please use the Allocation API to remove allocations.

network_data (Optional)

body

JSON

Static network configuration in the OpenStack network data format to use during deployment and cleaning. Requires a specially crafted ramdisk, see DHCP-less documentation.

Example JSON representation of a Node:

{
  "allocation_uuid": null,
  "boot_interface": null,
  "chassis_uuid": null,
  "clean_step": {},
  "conductor": "compute1.localdomain",
  "conductor_group": "group-1",
  "console_enabled": false,
  "console_interface": null,
  "created_at": "2016-08-18T22:28:48.643434+11:11",
  "deploy_interface": null,
  "deploy_step": {},
  "description": null,
  "driver": "fake",
  "driver_info": {
    "ipmi_password": "******",
    "ipmi_username": "ADMIN"
  },
  "driver_internal_info": {
    "clean_steps": null
  },
  "extra": {},
  "inspect_interface": null,
  "inspection_finished_at": null,
  "inspection_started_at": null,
  "instance_info": {},
  "instance_uuid": null,
  "last_error": null,
  "lessee": null,
  "links": [
    {
      "href": "http://127.0.0.1:6385/v1/nodes/6d85703a-565d-469a-96ce-30b6de53079d",
      "rel": "self"
    },
    {
      "href": "http://127.0.0.1:6385/nodes/6d85703a-565d-469a-96ce-30b6de53079d",
      "rel": "bookmark"
    }
  ],
  "maintenance": false,
  "maintenance_reason": null,
  "management_interface": null,
  "name": "test_node_classic",
  "network_data": {},
  "network_interface": "flat",
  "owner": null,
  "portgroups": [
    {
      "href": "http://127.0.0.1:6385/v1/nodes/6d85703a-565d-469a-96ce-30b6de53079d/portgroups",
      "rel": "self"
    },
    {
      "href": "http://127.0.0.1:6385/nodes/6d85703a-565d-469a-96ce-30b6de53079d/portgroups",
      "rel": "bookmark"
    }
  ],
  "ports": [
    {
      "href": "http://127.0.0.1:6385/v1/nodes/6d85703a-565d-469a-96ce-30b6de53079d/ports",
      "rel": "self"
    },
    {
      "href": "http://127.0.0.1:6385/nodes/6d85703a-565d-469a-96ce-30b6de53079d/ports",
      "rel": "bookmark"
    }
  ],
  "power_interface": null,
  "power_state": "power off",
  "properties": {},
  "protected": false,
  "protected_reason": null,
  "provision_state": "available",
  "provision_updated_at": "2016-08-18T22:28:49.946416+00:00",
  "raid_config": {},
  "raid_interface": null,
  "rescue_interface": null,
  "reservation": null,
  "resource_class": "bm-large",
  "retired": false,
  "retired_reason": null,
  "states": [
    {
      "href": "http://127.0.0.1:6385/v1/nodes/6d85703a-565d-469a-96ce-30b6de53079d/states",
      "rel": "self"
    },
    {
      "href": "http://127.0.0.1:6385/nodes/6d85703a-565d-469a-96ce-30b6de53079d/states",
      "rel": "bookmark"
    }
  ],
  "storage_interface": "noop",
  "target_power_state": null,
  "target_provision_state": null,
  "target_raid_config": {},
  "traits": [],
  "updated_at": "2016-08-18T22:28:49.653974+00:00",
  "uuid": "6d85703a-565d-469a-96ce-30b6de53079d",
  "vendor_interface": null,
  "volume": [
    {
      "href": "http://127.0.0.1:6385/v1/nodes/6d85703a-565d-469a-96ce-30b6de53079d/volume",
      "rel": "self"
    },
    {
      "href": "http://127.0.0.1:6385/nodes/6d85703a-565d-469a-96ce-30b6de53079d/volume",
      "rel": "bookmark"
    }
  ]
}
PATCH
/v1/nodes/{node_ident}

Update Node

Updates the information stored about a Node.

Note that this endpoint can not be used to request state changes, which are managed through sub-resources.

New in version 1.25: Introduced the ability to unset a node’s chassis UUID.

New in version 1.51: Introduced the ability to set/unset a node’s description.

New in version 1.82: Introduced the ability to set/unset a node’s shard.

Normal response codes: 200

Error codes: 400,403,404,406,409

Request

The BODY of the PATCH request must be a JSON PATCH document, adhering to RFC 6902.

Name

In

Type

Description

node_ident

path

string

The UUID or Name of the node.

Example PATCH document updating Node driver_info:

[
   {
      "op": "replace",
      "path": "/driver_info/ipmi_username",
      "value": "OPERATOR"
   },
   {
      "op": "add",
      "path": "/driver_info/deploy_kernel",
      "value": "http://127.0.0.1/images/kernel"
   },
   {
       "op": "add",
       "path": "/driver_info/deploy_ramdisk",
       "value": "http://127.0.0.1/images/ramdisk"
   }
]

Response

Name

In

Type

Description

uuid

body

string

The UUID for the resource.

name (Optional)

body

string

Human-readable identifier for the Node resource. May be undefined. Certain words are reserved.

power_state

body

string

The current power state of this Node. Usually, “power on” or “power off”, but may be “None” if Ironic is unable to determine the power state (eg, due to hardware failure).

target_power_state

body

string

If a power state transition has been requested, this field represents the requested (ie, “target”) state, either “power on” or “power off”.

provision_state

body

string

The current provisioning state of this Node.

target_provision_state

body

string

If a provisioning action has been requested, this field represents the requested (ie, “target”) state. Note that a Node may go through several states during its transition to this target state. For instance, when requesting an instance be deployed to an AVAILABLE Node, the Node may go through the following state change progression: AVAILABLE -> DEPLOYING -> DEPLOYWAIT -> DEPLOYING -> ACTIVE

maintenance

body

boolean

Whether or not this Node is currently in “maintenance mode”. Setting a Node into maintenance mode removes it from the available resource pool and halts some internal automation. This can happen manually (eg, via an API request) or automatically when Ironic detects a hardware fault that prevents communication with the machine.

maintenance_reason (Optional)

body

string

User-settable description of the reason why this Node was placed into maintenance mode

fault (Optional)

body

string

The fault indicates the active fault detected by ironic, typically the Node is in “maintenance mode”. None means no fault has been detected by ironic. “power failure” indicates ironic failed to retrieve power state from this node. There are other possible types, e.g., “clean failure” and “rescue abort failure”.

last_error

body

string

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

reservation

body

string

The name of an Ironic Conductor host which is holding a lock on this node, if a lock is held. Usually “null”, but this field can be useful for debugging.

driver

body

string

The name of the driver.

driver_info

body

JSON

All the metadata required by the driver to manage this Node. List of fields varies between drivers, and can be retrieved from the /v1/drivers/<DRIVER_NAME>/properties resource.

driver_internal_info (Optional)

body

JSON

Internal metadata set and stored by the Node’s driver. This field is read-only.

properties

body

JSON

Physical characteristics of this Node. Populated by ironic-inspector during inspection. May be edited via the REST API at any time.

instance_info

body

JSON

Information used to customize the deployed image. May include root partition size, a base 64 encoded config drive, and other metadata. Note that this field is erased automatically when the instance is deleted (this is done by requesting the Node provision state be changed to DELETED).

instance_uuid

body

string

UUID of the Nova instance associated with this Node.

chassis_uuid

body

string

UUID of the chassis associated with this Node. May be empty or None.

extra

body

object

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

console_enabled

body

boolean

Indicates whether console access is enabled or disabled on this node.

raid_config (Optional)

body

JSON

Represents the current RAID configuration of the node. Introduced with the cleaning feature.

target_raid_config

body

JSON

Represents the requested RAID configuration of the node, which will be applied when the Node next transitions through the CLEANING state. Introduced with the cleaning feature.

clean_step (Optional)

body

string

The current clean step. Introduced with the cleaning feature.

deploy_step (Optional)

body

string

The current deploy step.

links

body

array

A list of relative links. Includes the self and bookmark links.

ports

body

array

Links to the collection of ports on this node

portgroups

body

array

Links to the collection of portgroups on this node.

states

body

array

Links to the collection of states. Note that this resource is also used to request state transitions.

resource_class

body

string

A string which can be used by external schedulers to identify this Node as a unit of a specific type of resource. For more details, see: https://docs.openstack.org/ironic/latest/install/configure-nova-flavors.html

boot_interface

body

string

The boot interface for a Node, e.g. “pxe”.

console_interface

body

string

The console interface for a node, e.g. “no-console”.

deploy_interface

body

string

The deploy interface for a node, e.g. “iscsi”.

inspect_interface

body

string

The interface used for node inspection, e.g. “no-inspect”.

management_interface

body

string

Interface for out-of-band node management, e.g. “ipmitool”.

network_interface

body

string

Which Network Interface provider to use when plumbing the network connections for this Node.

power_interface

body

string

Interface used for performing power actions on the node, e.g. “ipmitool”.

raid_interface

body

string

Interface used for configuring RAID on this node, e.g. “no-raid”.

rescue_interface

body

string

The interface used for node rescue, e.g. “no-rescue”.

storage_interface

body

string

Interface used for attaching and detaching volumes on this node, e.g. “cinder”.

traits

body

array

List of traits for this node.

vendor_interface

body

string

Interface for vendor-specific functionality on this node, e.g. “no-vendor”.

volume

body

array

Links to the volume resources.

conductor_group

body

string

The conductor group for a node. Case-insensitive string up to 255 characters, containing a-z, 0-9, _, -, and ..

protected (Optional)

body

boolean

Whether the node is protected from undeploying, rebuilding and deletion.

protected_reason (Optional)

body

string

The reason the node is marked as protected.

owner (Optional)

body

string

A string or UUID of the tenant who owns the object.

lessee (Optional)

body

string

A string or UUID of the tenant who is leasing the object.

shard (Optional)

body

string

A string indicating the shard this node belongs to.

description

body

string

Informational text about this node.

conductor (Optional)

body

string

The conductor currently servicing a node. This field is read-only.

allocation_uuid

body

string

The UUID of the allocation associated with the node. If not null, will be the same as instance_uuid (the opposite is not always true). Unlike instance_uuid, this field is read-only. Please use the Allocation API to remove allocations.

network_data (Optional)

body

JSON

Static network configuration in the OpenStack network data format to use during deployment and cleaning. Requires a specially crafted ramdisk, see DHCP-less documentation.

Example JSON representation of a Node:

{
  "allocation_uuid": null,
  "boot_interface": null,
  "chassis_uuid": null,
  "clean_step": {},
  "conductor": "compute1.localdomain",
  "conductor_group": "group-1",
  "console_enabled": false,
  "console_interface": null,
  "created_at": "2016-08-18T22:28:48.643434+11:11",
  "deploy_interface": null,
  "deploy_step": {},
  "driver": "fake",
  "driver_info": {
    "deploy_kernel": "http://127.0.0.1/images/kernel",
    "deploy_ramdisk": "http://127.0.0.1/images/ramdisk",
    "ipmi_password": "******",
    "ipmi_username": "OPERATOR"
  },
  "driver_internal_info": {
    "clean_steps": null
  },
  "extra": {},
  "inspect_interface": null,
  "inspection_finished_at": null,
  "inspection_started_at": null,
  "instance_info": {},
  "instance_uuid": null,
  "last_error": null,
  "lessee": null,
  "links": [
    {
      "href": "http://127.0.0.1:6385/v1/nodes/6d85703a-565d-469a-96ce-30b6de53079d",
      "rel": "self"
    },
    {
      "href": "http://127.0.0.1:6385/nodes/6d85703a-565d-469a-96ce-30b6de53079d",
      "rel": "bookmark"
    }
  ],
  "maintenance": true,
  "maintenance_reason": "Replacing the hard drive",
  "management_interface": null,
  "name": "test_node_classic",
  "network_data": {},
  "network_interface": "flat",
  "owner": null,
  "portgroups": [
    {
      "href": "http://127.0.0.1:6385/v1/nodes/6d85703a-565d-469a-96ce-30b6de53079d/portgroups",
      "rel": "self"
    },
    {
      "href": "http://127.0.0.1:6385/nodes/6d85703a-565d-469a-96ce-30b6de53079d/portgroups",
      "rel": "bookmark"
    }
  ],
  "ports": [
    {
      "href": "http://127.0.0.1:6385/v1/nodes/6d85703a-565d-469a-96ce-30b6de53079d/ports",
      "rel": "self"
    },
    {
      "href": "http://127.0.0.1:6385/nodes/6d85703a-565d-469a-96ce-30b6de53079d/ports",
      "rel": "bookmark"
    }
  ],
  "power_interface": null,
  "power_state": "power off",
  "properties": {},
  "protected": false,
  "protected_reason": null,
  "provision_state": "available",
  "provision_updated_at": "2016-08-18T22:28:49.946416+00:00",
  "raid_config": {},
  "raid_interface": null,
  "rescue_interface": null,
  "reservation": null,
  "resource_class": null,
  "retired": false,
  "retired_reason": null,
  "states": [
    {
      "href": "http://127.0.0.1:6385/v1/nodes/6d85703a-565d-469a-96ce-30b6de53079d/states",
      "rel": "self"
    },
    {
      "href": "http://127.0.0.1:6385/nodes/6d85703a-565d-469a-96ce-30b6de53079d/states",
      "rel": "bookmark"
    }
  ],
  "storage_interface": "noop",
  "target_power_state": null,
  "target_provision_state": null,
  "target_raid_config": {},
  "traits": [
    "CUSTOM_TRAIT1",
    "HW_CPU_X86_VMX"
  ],
  "updated_at": "2016-08-18T22:28:49.653974+00:00",
  "uuid": "6d85703a-565d-469a-96ce-30b6de53079d",
  "vendor_interface": null,
  "volume": [
    {
      "href": "http://127.0.0.1:6385/v1/nodes/6d85703a-565d-469a-96ce-30b6de53079d/volume",
      "rel": "self"
    },
    {
      "href": "http://127.0.0.1:6385/nodes/6d85703a-565d-469a-96ce-30b6de53079d/volume",
      "rel": "bookmark"
    }
  ]
}
DELETE
/v1/nodes/{node_ident}

Delete Node

Deletes a node.

Normal response codes: 204

Error codes: 400,403,404,409

Request

Name

In

Type

Description

node_ident

path

string

The UUID or Name of the node.

Node Management (nodes)

Nodes can be managed through several sub-resources.

Maintenance mode can be set by the operator, with an optional “reason” stored by Ironic.

The supplied driver_info can be validated to ensure that the selected driver has all the information it requires to manage the Node.

A Node can be rebooted, turned on, or turned off by requesting a change to its power state. This is handled asynchronously and tracked in the target_power_state field after the request is received.

A Node’s boot device can be changed, and the set of supported boot devices can be queried.

A request to change a Node’s provision state is also tracked asynchronously; the target_provision_state represents the requested state. A Node may transition through several discrete provision_state steps before arriving at the requested state. This can vary between drivers and based on configuration.

For example, a Node in the available state can have an instance deployed to it by requesting the provision state of active. During this transition, the Node’s provision_state will temporarily be set to deploying, and depending on the driver, it may also be wait call-back. When the transitions are complete, target_provision_state will be set to None and provision_state will be set to active. To destroy the instance, request the provision state of delete. During this transition, the Node may or may not go through a cleaning state, depending on the service configuration.

GET
/v1/nodes/{node_ident}/validate

Validate Node

Request that Ironic validate whether the Node’s driver has enough information to manage the Node. This polls each interface on the driver, and returns the status of that interface as an element in the response. Note that each driver may require different information to be supplied, and not all drivers support all interfaces.

Normal response codes: 200

Request

Name

In

Type

Description

node_ident

path

string

The UUID or Name of the node.

Response

Each element in the response will contain a “result” variable, which will have a value of “true” or “false”, indicating that the interface either has or does not have sufficient information to function. A value of null indicates that the Node’s driver does not support that interface.

Name

In

Type

Description

bios

body

object

Status of the “bios” interface

boot

body

object

Status of the “boot” interface

console

body

object

Status of the “console” interface

deploy

body

object

Status of the “deploy” interface

inspect

body

object

Status of the “inspect” interface

management

body

object

Status of the “management” interface

network

body

object

Status of the “network” interface

power

body

object

Status of the “power” interface

raid

body

object

Status of the “raid” interface

rescue

body

object

Status of the “rescue” interface

storage

body

object

Status of the “storage” interface

Example node validation response:

{
  "boot": {
    "result": true
  },
  "console": {
    "result": true
  },
  "deploy": {
    "result": true
  },
  "inspect": {
    "result": true
  },
  "management": {
    "result": true
  },
  "network": {
    "result": true
  },
  "power": {
    "result": true
  },
  "raid": {
    "result": true
  },
  "rescue": {
    "reason": "not supported",
    "result": null
  },
  "storage": {
    "result": true
  }
}
PUT
/v1/nodes/{node_ident}/maintenance

Set Maintenance Flag

Request that Ironic set the maintenance flag on the Node. This will disable certain automatic actions that the Node’s driver may take, and remove the Node from Nova’s available resource pool.

Normal response code: 202

Request

Name

In

Type

Description

node_ident

path

string

The UUID or Name of the node.

reason (Optional)

body

string

Specify the reason for setting the Node into maintenance mode.

Example request: mark a node for maintenance:

{
    "reason": "Replacing the hard drive"
}
DELETE
/v1/nodes/{node_ident}/maintenance

Clear Maintenance Flag

The maintenance flag is unset by sending a DELETE request to this endpoint. If the request is accepted, Ironic will also clear the maintenance_reason field.

Normal response code: 202

Request

Name

In

Type

Description

node_ident

path

string

The UUID or Name of the node.

PUT
/v1/nodes/{node_ident}/management/boot_device

Set Boot Device

Set the boot device for the given Node, and set it persistently or for one-time boot. The exact behaviour of this depends on the hardware driver.

Note

In some drivers, eg. the *_ipmitool family, this method initiates a synchronous call to the hardware management device (BMC). It should be used with caution! This is a known bug.

Note

Some drivers do not support one-time boot, and always set the boot device persistently.

Normal response code: 204

Request

Name

In

Type

Description

node_ident

path

string

The UUID or Name of the node.

boot_device

body

string

The boot device for a Node, eg. “pxe” or “disk”.

persistent (Optional)

body

boolean

Whether the boot device should be set only for the next reboot, or persistently.

Example JSON request body to set boot device:

{
    "boot_device": "pxe",
    "persistent": false
}
GET
/v1/nodes/{node_ident}/management/boot_device

Get Boot Device

Get the current boot device for the given Node.

Note

In some drivers, eg. the *_ipmitool family, this method initiates a synchronous call to the hardware management device (BMC). It should be used with caution! This is a known bug.

Normal response code: 200

Request

Name

In

Type

Description

node_ident

path

string

The UUID or Name of the node.

Response

Name

In

Type

Description

boot_device

body

string

The boot device for a Node, eg. “pxe” or “disk”.

persistent

body

boolean

Whether the boot device should be set only for the next reboot, or persistently.

Example JSON response to get boot device:

{
  "boot_device": "pxe",
  "persistent": false
}
GET
/v1/nodes/{node_ident}/management/boot_device/supported

Get Supported Boot Devices

Retrieve the acceptable set of supported boot devices for a specific Node.

Normal response code: 200

Request

Name

In

Type

Description

node_ident

path

string

The UUID or Name of the node.

Response

Name

In

Type

Description

supported_boot_devices

body

array

List of boot devices which this Node’s driver supports.

Example response listing supported boot devices:

{
  "supported_boot_devices": [
    "pxe"
  ]
}
PUT
/v1/nodes/{node_ident}/management/inject_nmi

Inject NMI (Non-Masking Interrupts)

New in version 1.29.

Inject NMI (Non-Masking Interrupts) for the given Node. This feature can be used for hardware diagnostics, and actual support depends on a driver.

Normal response code: 204 (No content)

Error codes:
  • 400 (Invalid)

  • 403 (Forbidden)

  • 404 (NotFound)

  • 406 (NotAcceptable)

  • 409 (NodeLocked, ClientError)

Request

Name

In

Type

Description

node_ident

path

string

The UUID or Name of the node.

Request to inject NMI to a node has to be empty dictionary:

{}
GET
/v1/nodes/{node_ident}/states

Node State Summary

Get a summary of the Node’s current power, provision, boot mode, raid, and console status.

New in version 1.75: Introduced boot_mode and secure_boot fields.

Normal response code: 200

Request

Name

In

Type

Description

node_ident

path

string

The UUID or Name of the node.

Response

Name

In

Type

Description

power_state

body

string

The current power state of this Node. Usually, “power on” or “power off”, but may be “None” if Ironic is unable to determine the power state (eg, due to hardware failure).

target_power_state

body

string

If a power state transition has been requested, this field represents the requested (ie, “target”) state, either “power on” or “power off”.

provision_state

body

string

The current provisioning state of this Node.

target_provision_state

body

string

If a provisioning action has been requested, this field represents the requested (ie, “target”) state. Note that a Node may go through several states during its transition to this target state. For instance, when requesting an instance be deployed to an AVAILABLE Node, the Node may go through the following state change progression: AVAILABLE -> DEPLOYING -> DEPLOYWAIT -> DEPLOYING -> ACTIVE

provision_updated_at

body

string

The UTC date and time when the resource was created, ISO 8601 format. null if the node is not being provisioned.

last_error

body

string

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

console_enabled

body

boolean

Indicates whether console access is enabled or disabled on this node.

raid_config (Optional)

body

JSON

Represents the current RAID configuration of the node. Introduced with the cleaning feature.

target_raid_config

body

JSON

Represents the requested RAID configuration of the node, which will be applied when the Node next transitions through the CLEANING state. Introduced with the cleaning feature.

boot_mode (Optional)

body

string

The current boot mode state (uefi/bios)

secure_boot (Optional)

body

boolean

Indicates whether node is currently booted with secure_boot turned on.

Example node state:

{
  "boot_mode": "uefi",
  "console_enabled": false,
  "last_error": null,
  "power_state": "power off",
  "provision_state": "available",
  "provision_updated_at": "2016-08-18T22:28:49.946416+00:00",
  "raid_config": {},
  "secure_boot": true,
  "target_power_state": null,
  "target_provision_state": null,
  "target_raid_config": {}
}
PUT
/v1/nodes/{node_ident}/states/boot_mode

Change Node Boot Mode

Request a change to the Node’s boot mode.

Note

Depending on the driver and the underlying hardware, changing boot mode may result in an automatic reboot.

New in version 1.76: A change in node’s boot mode can be requested.

Normal response code: 202 (Accepted)

Error codes:
  • 400 (Invalid, InvalidStateRequested, InvalidParameterValue)

  • 404 (NotFound)

  • 409 (Conflict, NodeLocked, ClientError)

  • 503 (NoFreeConductorWorkers)

Request

Name

In

Type

Description

node_ident

path

string

The UUID or Name of the node.

target

body

string

If a boot mode change has been requested, this field represents the requested (ie, “target”) state, either “uefi” or “bios”.

Example request for UEFI boot:

{
    "target": "uefi"
}

Example request for Legacy BIOS boot:

{
    "target": "bios"
}
PUT
/v1/nodes/{node_ident}/states/secure_boot

Change Node Secure Boot

Request a change to the Node’s secure boot state.

Note

Depending on the driver and the underlying hardware, changing the secure boot state may result in an automatic reboot.

New in version 1.76: A change in node’s secure boot state can be requested.

Normal response code: 202 (Accepted)

Error codes:
  • 400 (Invalid, InvalidStateRequested, InvalidParameterValue)

  • 404 (NotFound)

  • 409 (Conflict, NodeLocked, ClientError)

  • 503 (NoFreeConductorWorkers)

Request

Name

In

Type

Description

node_ident

path

string

The UUID or Name of the node.

target

body

boolean

If a secure boot change has been requested, this field represents the requested (ie, “target”) state, either true or false.

Example request to turn off secure boot:

{
    "target": false
}

Example request to turn on secure boot:

{
    "target": true
}
PUT
/v1/nodes/{node_ident}/states/power

Change Node Power State

Request a change to the Node’s power state.

Normal response code: 202 (Accepted)

New in version 1.27: In the request, the target value can also be one of soft power off or soft rebooting.

New in version 1.27: In the request, a timeout can be specified.

Error codes:
  • 409 (NodeLocked, ClientError)

  • 400 (Invalid, InvalidStateRequested, InvalidParameterValue)

  • 406 (NotAcceptable)

  • 503 (NoFreeConductorWorkers)

Request

Name

In

Type

Description

node_ident

path

string

The UUID or Name of the node.

target

body

string

If a power state transition has been requested, this field represents the requested (ie, “target”) state either “power on”, “power off”, “rebooting”, “soft power off” or “soft rebooting”.

timeout (Optional)

body

integer

Timeout (in seconds) for a power state transition.

Example request to power off a Node:

{
    "target": "power off"
}

Example request to soft power off a Node with timeout:

{
    "target": "soft power off",
    "timeout": 300
}
PUT
/v1/nodes/{node_ident}/states/provision

Change Node Provision State

Request a change to the Node’s provision state.

Acceptable target states depend on the Node’s current provision state. More detailed documentation of the Ironic State Machine is available in the developer docs.

New in version 1.35: A configdrive can be provided when setting the node’s provision target state to rebuild.

New in version 1.38: A node can be rescued or unrescued by setting the node’s provision target state to rescue or unrescue respectively.

New in version 1.56: A configdrive can be a JSON object with meta_data, network_data and user_data.

New in version 1.59: A configdrive now accepts vendor_data.

New in version 1.69: deploy_steps can be provided when settings the node’s provision target state to active or rebuild.

New in version 1.70: disable_ramdisk can be provided to avoid booting the ramdisk during manual cleaning.

Normal response code: 202

Error codes:
  • 409 (NodeLocked, ClientError)

  • 400 (InvalidState, NodeInMaintenance)

  • 406 (NotAcceptable)

  • 503 (NoFreeConductorWorkers)

Request

Name

In

Type

Description

node_ident

path

string

The UUID or Name of the node.

target

body

string

The requested provisioning state of this Node.

configdrive (Optional)

body

string or object

A config drive to be written to a partition on the Node’s boot disk. Can be a full gzip’ed and base-64 encoded image or a JSON object with the keys:

  • meta_data (optional) - JSON object with the standard meta data. Ironic will provide the defaults for the uuid and name fields.

  • network_data (optional) - JSON object with networking configuration.

  • user_data (optional) - user data. May be a string (which will be UTF-8 encoded); a JSON object, or a JSON array.

  • vendor_data (optional) - JSON object with extra vendor data.

This parameter is only accepted when setting the state to “active” or “rebuild”.

clean_steps (Optional)

body

array

An ordered list of cleaning steps that will be performed on the node. A cleaning step is a dictionary with required keys ‘interface’ and ‘step’, and optional key ‘args’. If specified, the value for ‘args’ is a keyword variable argument dictionary that is passed to the cleaning step method.

deploy_steps (Optional)

body

array

A list of deploy steps that will be performed on the node. A deploy step is a dictionary with required keys ‘interface’, ‘step’, ‘priority’ and optional key ‘args’. If specified, the value for ‘args’ is a keyword variable argument dictionary that is passed to the deploy step method.

rescue_password (Optional)

body

string

Non-empty password used to configure rescue ramdisk during node rescue operation.

disable_ramdisk (Optional)

body

boolean

If set to true, the ironic-python-agent ramdisk will not be booted for cleaning. Only clean steps explicitly marked as not requiring ramdisk can be executed in this mode. Only allowed for manual cleaning.

Example request to deploy a Node, using a configdrive served via local webserver:

{
    "target": "active",
    "configdrive": "http://127.0.0.1/images/test-node-config-drive.iso.gz"
}

Example request to deploy a Node with custom deploy step:

{
    "target": "active",
    "deploy_steps": [
        {
            "interface": "deploy",
            "step": "upgrade_firmware",
            "args": {
                "force": "True"
            },
            "priority": 95
        }
    ]
}

Example request to clean a Node, with custom clean step:

{
    "target": "clean",
    "clean_steps": [
        {
            "interface": "deploy",
            "step": "upgrade_firmware",
            "args": {
                "force": "True"
            }
        }
    ]
}
PUT
/v1/nodes/{node_ident}/states/raid

Set RAID Config

New in version 1.12.

Store the supplied configuration on the Node’s target_raid_config property. This property must be structured JSON, and will be validated by the driver upon receipt. The request schema is defined in the documentation for the RAID feature

Note

Calling this API only stores the requested configuration; it will be applied the next time that the Node transitions through the cleaning phase.

Normal response code: 204

Request

Name

In

Type

Description

node_ident

path

string

The UUID or Name of the node.

target_raid_config

body

JSON

Represents the requested RAID configuration of the node, which will be applied when the Node next transitions through the CLEANING state. Introduced with the cleaning feature.

Example requested RAID config:

{
   "logical_disks" : [
      {
         "size_gb" : 100,
         "is_root_volume" : true,
         "raid_level" : "1"
      }
   ]
}
GET
/v1/nodes/{node_ident}/states/console

Get Console

Get connection information about the console.

Request

Name

In

Type

Description

node_ident

path

string

The UUID or Name of the node.

PUT
/v1/nodes/{node_ident}/states/console

Start/Stop Console

Start or stop the serial console.

Request

Name

In

Type

Description

node_ident

path

string

The UUID or Name of the node.

enabled

body

boolean

Indicates whether console access is enabled or disabled on this node.

Attach / Detach Virtual Media (nodes)

New in version 1.89.

Attach a generic image as virtual media device to a node or remove it from a node using the v1/nodes/{node_ident}/vmedia endpoint.

POST
/v1/nodes/{node_ident}/vmedia

Attach a virtual media to a node

Attach virtual media device to a node.

Normal response code: 204

Error codes: 400,401,403,404,409

Request

Name

In

Type

Description

node_ident

path

string

The UUID or Name of the node.

device_type

body

string

The type of the virtual media device used, e.g. CDROM

image_url

body

string

The url of the image to attach to a virtual media device.

image_download_source (Optional)

body

string

How the image is served to the BMC, “http” for a remote location or “local” to use the local web server.

Example request to attach virtual media to a Node:

{
    "device_type": "CDROM",
    "image_url": "http://image"
}
DELETE
/v1/nodes/{node_ident}/vmedia

Detach virtual media from a node

Detach virtual media device from a Node.

Normal response code: 204

Error codes: 400,401,403,404

Request

Name

In

Type

Description

node_ident

path

string

The UUID or Name of the node.

Node Vendor Passthru (nodes)

Each driver MAY support vendor-specific extensions, called “passthru” methods.

Internally, Ironic’s driver API supports flexibly exposing functions via the common HTTP methods GET, PUT, POST, and DELETE. To call a passthru method, the query string must contain the name of the method, eg. /vendor_passthru?method=reset_bmc. The contents of the HTTP request are forwarded to the Node’s driver and validated there.

Ironic’s REST API provides a means to discover these methods, but does not provide support, testing, or documentation for these endpoints. The Ironic development team does not guarantee any compatibility within these methods between releases, though we encourage driver authors to provide documentation and support for them.

Besides the endpoints documented here, all other resources and endpoints under the heading vendor_passthru should be considered unsupported APIs, and could be changed without warning by the driver authors.

GET
/v1/nodes/{node_ident}/vendor_passthru/methods

List Methods

Retrieve a list of the available vendor passthru methods for the given Node. The response will indicate which HTTP method(s) each vendor passthru method allows, whether the method call will be synchronous or asynchronous, and whether the response will include any attachment.

Normal response code: 200

Request

Name

In

Type

Description

node_ident

path

string

The UUID or Name of the node.

Response

Example passthru methods listing:

{
  "bmc_reset": {
    "async": true,
    "attach": false,
    "description": "",
    "http_methods": [
      "POST"
    ],
    "require_exclusive_lock": true
  },
  "send_raw": {
    "async": true,
    "attach": false,
    "description": "",
    "http_methods": [
      "POST"
    ],
    "require_exclusive_lock": true
  }
}
METHOD
/v1/nodes/{node_ident}/vendor_passthru?method={method_name}

Call a Method

The HTTP METHOD may be one of GET, POST, PUT, DELETE, depending on the driver and method.

This endpoint passes the request directly to the Node’s hardware driver. The HTTP BODY must be parseable JSON, which will be converted to parameters passed to that function. Unparsable JSON, missing parameters, or excess parameters will cause the request to be rejected with an HTTP 400 error.

Normal response code: 200 202

Request

Name

In

Type

Description

node_ident

path

string

The UUID or Name of the node.

method_name

query

string

Driver specific method name.

All other parameters should be passed in the BODY. Parameter list varies by method_name.

Response

Varies.

Node Traits (nodes)

New in version 1.37.

Node traits are used for scheduling in the Compute service, using qualitative attributes to influence the placement of instances to bare metal compute nodes. Traits specified for a node in the Bare Metal service will be registered on the corresponding resource provider in the Compute service’s placement API.

Traits can be either standard or custom. Standard traits are listed in the os_traits library. Custom traits must meet the following requirements:

  • prefixed with CUSTOM_

  • contain only upper case characters A to Z, digits 0 to 9, or underscores

  • no longer than 255 characters in length

A bare metal node can have a maximum of 50 traits.

GET
/v1/nodes/{node_ident}/traits

List Traits of a Node

Return a list of traits for the node.

Normal response code: 200

Error codes: 400,401,403,404

Request

Name

In

Type

Description

node_ident

path

string

The UUID or Name of the node.

Response

Name

In

Type

Description

traits

body

array

List of traits for this node.

Example list of traits for the node:

{
  "traits": [
    "CUSTOM_TRAIT1",
    "HW_CPU_X86_VMX"
  ]
}
PUT
/v1/nodes/{node_ident}/traits

Set all traits of a node

Set all traits of a node, replacing any existing traits.

Normal response code: 204

Error codes: 400,401,403,404,409

Request

Name

In

Type

Description

node_ident

path

string

The UUID or Name of the node.

traits

body

array

List of traits for this node.

Example request to set all traits of a Node:

{
  "traits": [
    "CUSTOM_TRAIT1",
    "HW_CPU_X86_VMX"
  ]
}
PUT
/v1/nodes/{node_ident}/traits/{trait}

Add a trait to a node

Add a single trait to a node.

Normal response code: 204

Error codes: 400,401,403,404,409

Request

Name

In

Type

Description

node_ident

path

string

The UUID or Name of the node.

trait

path

string

A single trait for this node.

DELETE
/v1/nodes/{node_ident}/traits

Remove all traits from a node

Normal response code: 204

Error codes: 400,401,403,404,409

Request

Name

In

Type

Description

node_ident

path

string

The UUID or Name of the node.

DELETE
/v1/nodes/{node_ident}/traits/{trait}

Remove a trait from a node

Remove a single trait from a node.

Normal response code: 204

Error codes: 400,401,403,404,409

Request

Name

In

Type

Description

node_ident

path

string

The UUID or Name of the node.

trait

path

string

A single trait for this node.

VIFs (Virtual Interfaces) of nodes

New in version 1.28.

Attaching and detaching VIFs (Virtual Interfaces) to or from a node are done via the v1/nodes/{node_ident}/vifs endpoint. Attaching a VIF to a node means that a VIF will be mapped to a free port or port group of the specified node.

GET
/v1/nodes/{node_ident}/vifs

List attached VIFs of a Node

Return a list of VIFs that are attached to the node.

Normal response code: 200

Error codes: 400,401,403,404

Request

Name

In

Type

Description

node_ident

path

string

The UUID or Name of the node.

Response

Name

In

Type

Description

vifs

body

array

VIFs attached to this node.

id

body

string

The UUID or name of the VIF.

Example list of VIFs that are attached to the node:

{
  "vifs": [
    {
      "id": "1974dcfa-836f-41b2-b541-686c100900e5"
    }
  ]
}
POST
/v1/nodes/{node_ident}/vifs

Attach a VIF to a node

Attach a VIF to a node.

Normal response code: 204

Error codes: 400,401,403,404,409

Request

Name

In

Type

Description

id

body

string

The UUID or name of the VIF.

port_uuid (Optional)

body

string

The UUID of a port to attach the VIF to. Cannot be specified with portgroup_uuid.

portgroup_uuid (Optional)

body

string

The UUID of a portgroup to attach the VIF to. Cannot be specified with port_uuid.

node_ident

path

string

The UUID or Name of the node.

Example request to attach a VIF to a Node:

{
    "id": "1974dcfa-836f-41b2-b541-686c100900e5"
}
DELETE
/v1/nodes/{node_ident}/vifs/{node_vif_ident}

Detach VIF from a node

Detach VIF from a Node.

Normal response code: 204

Error codes: 400,401,403,404

Request

Name

In

Type

Description

node_ident

path

string

The UUID or Name of the node.

node_vif_ident

body

string

The UUID or name of the VIF.

Indicators Management

The Indicators management is an extension of the node ReST API endpoint that allows reading and toggling the indicators (e.g. LEDs) on the hardware units.

GET
/v1/nodes/{node_ident}/management/indicators

List Indicators

New in version 1.63.

List all available indicator names for each of the hardware components. The components that the redfish driver may have are: system, chassis and drive. The actual list depends on the support by the underlying hardware.

Normal response code: 200

Error response codes: 404 (if node not found)

Request

Name

In

Type

Description

node_ident

path

string

The UUID or Name of the node.

Response Parameters

Name

In

Type

Description

components

body

array

List all available indicators names for each of the hardware components for this node.

name

body

string

The name of the component available for the node.

links

body

array

A list of relative links. Includes the self and bookmark links.

Example list of indicators for the node:

{
    "components": [
        {
            "name": "system",
            "links": [
                {
                    "href": "http://127.0.0.1:6385/v1/nodes/Compute0/
                    management/indicators/system",
                    "rel": "self"
                },
                {
                    "href": "http://127.0.0.1:6385/nodes/Compute0/
                    management/indicators/system",
                    "rel": "bookmark"
                }
            ]
        },
        {
            "name": "chassis",
            "links": [
                {
                    "href": "http://127.0.0.1:6385/v1/nodes/Compute0/
                    management/indicators/chassis",
                    "rel": "self"
                },
                {
                    "href": "http://127.0.0.1:6385/nodes/Compute0/
                    management/indicators/chassis",
                    "rel": "bookmark"
                }
            ]
        }
    ]
}
GET
/v1/nodes/{node_ident}/management/indicators/{ind_ident}@{component}

Get Indicator State

New in version 1.63.

Retrieves the state of a chosen indicator for a given component of the node. The value of the field in the response object represents its state. The values can be one of OFF, ON, BLINKING or UNKNOWN.

Normal response code: 200

Error response codes: 404 (if node, component or indicator is not found)

Request

Name

In

Type

Description

node_ident

path

string

The UUID or Name of the node.

component

path

string

The Bare Metal node component.

ind_ident

path

string

The indicator of a Bare Metal component.

Response Parameters

Name

In

Type

Description

state

body

string

The state of an indicator of the component of the node. Possible values are: OFF, ON, BLINKING or UNKNOWN.

Example list of indicators for a given component of the node:

{
  "state": "ON"
}
PUT
/v1/nodes/{node_ident}/management/indicators/{ind_ident}@{component}

Set Indicator State

New in version 1.63.

Set the state of the desired indicators of the component.

Normal response code: 204 (No content)

Error codes:
  • 400 (if state is not an accepted value)

  • 404 (if node, component or indicator is not found)

Request

Name

In

Type

Description

node_ident

path

string

The UUID or Name of the node.

component

path

string

The Bare Metal node component.

ind_ident

path

string

The indicator of a Bare Metal component.

state

body

string

The state of an indicator of the component of the node. Possible values are: OFF, ON, BLINKING or UNKNOWN.

Set the State of an Indicator

{
  "state": "BLINKING"
}

Portgroups (portgroups)

New in version 1.23.

Ports can be combined into portgroups to support static link aggregation group (LAG) or multi-chassis link aggregation group (MLAG) configurations. Listing, Searching, Creating, Updating, and Deleting of bare metal Portgroup resources are done through the v1/portgroups resource.

All Portgroups must be associated with a Node when created. This association can be changed, though the request may be rejected if either the current or destination Node are in a transitive state (for example, in the process of deploying) or are in a state that would be non-deterministically affected by such a change (for example, there is an active user instance on the Node).

GET
/v1/portgroups

List Portgroups

Return a list of bare metal Portgroups. Some filtering is possible by passing in some parameters with the request.

By default, this query will return the UUID, name and address for each Portgroup.

New in version 1.43: Added the detail boolean request parameter. When specified True this causes the response to include complete details about each portgroup.

Normal response code: 200

Error codes: 400,401,403,404

Request

Name

In

Type

Description

node (Optional)

query

string

Filter the list of returned Portgroups, and only return the ones associated with this specific node (name or UUID), or an empty set if not found.

address (Optional)

query

string

Filter the list of returned Portgroups, and only return the ones with the specified physical hardware address, typically MAC, or an empty set if not found.

fields (Optional)

query

array

One or more fields to be returned in the response.

For example, the following request returns only the uuid and name fields for each node:

GET /v1/nodes?fields=uuid,name

limit (Optional)

query

integer

Requests a page size of items. Returns a number of items up to a limit value. Use the limit parameter to make an initial limited request and use the ID of the last-seen item from the response as the marker parameter value in a subsequent limited request. This value cannot be larger than the max_limit option in the [api] section of the configuration. If it is higher than max_limit, only max-limit resources will be returned.

marker (Optional)

query

string

The ID of the last-seen item. Use the limit parameter to make an initial limited request and use the ID of the last-seen item from the response as the marker parameter value in a subsequent limited request.

sort_dir (Optional)

query

string

Sorts the response by the requested sort direction. A valid value is asc (ascending) or desc (descending). Default is asc. You can specify multiple pairs of sort key and sort direction query parameters. If you omit the sort direction in a pair, the API uses the natural sorting direction of the server attribute that is provided as the sort_key.

sort_key (Optional)

query

string

Sorts the response by this attribute value. Default is id. You can specify multiple pairs of sort key and sort direction query parameters. If you omit the sort direction in a pair, the API uses the natural sorting direction of the server attribute that is provided as the sort_key.

detail (Optional)

query

boolean

Whether to show detailed information about the resource. This cannot be set to True if fields parameter is specified.

Response

Name

In

Type

Description

portgroups

body

array

A collection of Portgroup resources.

uuid

body

string

The UUID for the resource.

address (Optional)

body

string

Physical hardware address of this Portgroup, typically the hardware MAC address.

name

body

string

Human-readable identifier for the Portgroup resource. May be undefined.

links

body

array

A list of relative links. Includes the self and bookmark links.

Example Portgroup list response:

{
  "portgroups": [
    {
      "address": "11:11:11:11:11:11",
      "links": [
        {
          "href": "http://127.0.0.1:6385/v1/portgroups/e43c722c-248e-4c6e-8ce8-0d8ff129387a",
          "rel": "self"
        },
        {
          "href": "http://127.0.0.1:6385/portgroups/e43c722c-248e-4c6e-8ce8-0d8ff129387a",
          "rel": "bookmark"
        }
      ],
      "name": "test_portgroup",
      "uuid": "e43c722c-248e-4c6e-8ce8-0d8ff129387a"
    }
  ]
}
POST
/v1/portgroups

Create Portgroup

Creates a new Portgroup resource.

This method requires a Node UUID and the physical hardware address for the Portgroup (MAC address in most cases).

Normal response code: 201

Error codes: 400,401,403,404

Request

Name

In

Type

Description

node_uuid

body

string

UUID of the Node this resource belongs to.

address (Optional)

body

string

Physical hardware address of this Portgroup, typically the hardware MAC address.

name (Optional)

body

string

Human-readable identifier for the Portgroup resource. May be undefined.

mode (Optional)

body

string

Mode of the port group. For possible values, refer to https://www.kernel.org/doc/Documentation/networking/bonding.txt. If not specified in a request to create a port group, it will be set to the value of the [DEFAULT]default_portgroup_mode configuration option. When set, can not be removed from the port group.

standalone_ports_supported (Optional)

body

boolean

Indicates whether ports that are members of this portgroup can be used as stand-alone ports.

properties (Optional)

body

JSON

Key/value properties related to the port group’s configuration.

extra (Optional)

body

object

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

uuid (Optional)

body

string

The UUID for the resource.

Example Portgroup creation request:

{
    "node_uuid": "6d85703a-565d-469a-96ce-30b6de53079d",
    "address": "11:11:11:11:11:11",
    "name": "test_portgroup"
}

Response

Name

In

Type

Description

uuid

body

string

The UUID for the resource.

name

body

string

Human-readable identifier for the Portgroup resource. May be undefined.

address (Optional)

body

string

Physical hardware address of this Portgroup, typically the hardware MAC address.

node_uuid

body

string

UUID of the Node this resource belongs to.

standalone_ports_supported

body

boolean

Indicates whether ports that are members of this portgroup can be used as stand-alone ports.

internal_info

body

JSON

Internal metadata set and stored by the Portgroup. This field is read-only.

extra

body

object

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

mode

body

string

Mode of the port group. For possible values, refer to https://www.kernel.org/doc/Documentation/networking/bonding.txt. If not specified in a request to create a port group, it will be set to the value of the [DEFAULT]default_portgroup_mode configuration option. When set, can not be removed from the port group.

properties

body

JSON

Key/value properties related to the port group’s configuration.

created_at

body

string

The UTC date and time when the resource was created, ISO 8601 format.

updated_at

body

string

The UTC date and time when the resource was updated, ISO 8601 format. May be “null”.

links

body

array

A list of relative links. Includes the self and bookmark links.

ports

body

array

Links to the collection of ports belonging to this portgroup.

Example Portgroup creation response:

{
  "address": "11:11:11:11:11:11",
  "created_at": "2016-08-18T22:28:48.643434+11:11",
  "extra": {},
  "internal_info": {},
  "links": [
    {
      "href": "http://127.0.0.1:6385/v1/portgroups/e43c722c-248e-4c6e-8ce8-0d8ff129387a",
      "rel": "self"
    },
    {
      "href": "http://127.0.0.1:6385/portgroups/e43c722c-248e-4c6e-8ce8-0d8ff129387a",
      "rel": "bookmark"
    }
  ],
  "mode": "active-backup",
  "name": "test_portgroup",
  "node_uuid": "6d85703a-565d-469a-96ce-30b6de53079d",
  "ports": [
    {
      "href": "http://127.0.0.1:6385/v1/portgroups/e43c722c-248e-4c6e-8ce8-0d8ff129387a/ports",
      "rel": "self"
    },
    {
      "href": "http://127.0.0.1:6385/portgroups/e43c722c-248e-4c6e-8ce8-0d8ff129387a/ports",
      "rel": "bookmark"
    }
  ],
  "properties": {},
  "standalone_ports_supported": true,
  "updated_at": null,
  "uuid": "e43c722c-248e-4c6e-8ce8-0d8ff129387a"
}
GET
/v1/portgroups/detail

List Detailed Portgroups

Return a list of bare metal Portgroups, with detailed information.

Normal response code: 200

Error codes: 400,401,403,404

Request

Name

In

Type

Description

node (Optional)

query

string

Filter the list of returned Portgroups, and only return the ones associated with this specific node (name or UUID), or an empty set if not found.

address (Optional)

query

string

Filter the list of returned Portgroups, and only return the ones with the specified physical hardware address, typically MAC, or an empty set if not found.

limit (Optional)

query

integer

Requests a page size of items. Returns a number of items up to a limit value. Use the limit parameter to make an initial limited request and use the ID of the last-seen item from the response as the marker parameter value in a subsequent limited request. This value cannot be larger than the max_limit option in the [api] section of the configuration. If it is higher than max_limit, only max-limit resources will be returned.

marker (Optional)

query

string

The ID of the last-seen item. Use the limit parameter to make an initial limited request and use the ID of the last-seen item from the response as the marker parameter value in a subsequent limited request.

sort_dir (Optional)

query

string

Sorts the response by the requested sort direction. A valid value is asc (ascending) or desc (descending). Default is asc. You can specify multiple pairs of sort key and sort direction query parameters. If you omit the sort direction in a pair, the API uses the natural sorting direction of the server attribute that is provided as the sort_key.

sort_key (Optional)

query

string

Sorts the response by this attribute value. Default is id. You can specify multiple pairs of sort key and sort direction query parameters. If you omit the sort direction in a pair, the API uses the natural sorting direction of the server attribute that is provided as the sort_key.

Response

Name

In

Type

Description

portgroups

body

array

A collection of Portgroup resources.

name

body

string

Human-readable identifier for the Portgroup resource. May be undefined.

uuid

body

string

The UUID for the resource.

address (Optional)

body

string

Physical hardware address of this Portgroup, typically the hardware MAC address.

node_uuid

body

string

UUID of the Node this resource belongs to.

standalone_ports_supported

body

boolean

Indicates whether ports that are members of this portgroup can be used as stand-alone ports.

internal_info

body

JSON

Internal metadata set and stored by the Portgroup. This field is read-only.

extra

body

object

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

mode

body

string

Mode of the port group. For possible values, refer to https://www.kernel.org/doc/Documentation/networking/bonding.txt. If not specified in a request to create a port group, it will be set to the value of the [DEFAULT]default_portgroup_mode configuration option. When set, can not be removed from the port group.

properties

body

JSON

Key/value properties related to the port group’s configuration.

created_at

body

string

The UTC date and time when the resource was created, ISO 8601 format.

updated_at

body

string

The UTC date and time when the resource was updated, ISO 8601 format. May be “null”.

links

body

array

A list of relative links. Includes the self and bookmark links.

ports

body

array

Links to the collection of ports belonging to this portgroup.

Example detailed Portgroup list response:

{
  "portgroups": [
    {
      "address": "11:11:11:11:11:11",
      "created_at": "2016-08-18T22:28:48.643434+11:11",
      "extra": {},
      "internal_info": {},
      "links": [
        {
          "href": "http://127.0.0.1:6385/v1/portgroups/e43c722c-248e-4c6e-8ce8-0d8ff129387a",
          "rel": "self"
        },
        {
          "href": "http://127.0.0.1:6385/portgroups/e43c722c-248e-4c6e-8ce8-0d8ff129387a",
          "rel": "bookmark"
        }
      ],
      "mode": "active-backup",
      "name": "test_portgroup",
      "node_uuid": "6d85703a-565d-469a-96ce-30b6de53079d",
      "ports": [
        {
          "href": "http://127.0.0.1:6385/v1/portgroups/e43c722c-248e-4c6e-8ce8-0d8ff129387a/ports",
          "rel": "self"
        },
        {
          "href": "http://127.0.0.1:6385/portgroups/e43c722c-248e-4c6e-8ce8-0d8ff129387a/ports",
          "rel": "bookmark"
        }
      ],
      "properties": {},
      "standalone_ports_supported": true,
      "updated_at": null,
      "uuid": "e43c722c-248e-4c6e-8ce8-0d8ff129387a"
    }
  ]
}
GET
/v1/portgroups/{portgroup_ident}

Show Portgroup Details

Show details for the given Portgroup.

Normal response code: 200

Error codes: 400,401,403,404

Request

Name

In

Type

Description

portgroup_ident

path

string

The UUID or Name of the portgroup.

fields (Optional)

query

array

One or more fields to be returned in the response.

For example, the following request returns only the uuid and name fields for each node:

GET /v1/nodes?fields=uuid,name

Response

Name

In

Type

Description

uuid

body

string

The UUID for the resource.

name

body

string

Human-readable identifier for the Portgroup resource. May be undefined.

address (Optional)

body

string

Physical hardware address of this Portgroup, typically the hardware MAC address.

node_uuid

body

string

UUID of the Node this resource belongs to.

standalone_ports_supported

body

boolean

Indicates whether ports that are members of this portgroup can be used as stand-alone ports.

internal_info

body

JSON

Internal metadata set and stored by the Portgroup. This field is read-only.

extra

body

object

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

mode

body

string

Mode of the port group. For possible values, refer to https://www.kernel.org/doc/Documentation/networking/bonding.txt. If not specified in a request to create a port group, it will be set to the value of the [DEFAULT]default_portgroup_mode configuration option. When set, can not be removed from the port group.

properties

body

JSON

Key/value properties related to the port group’s configuration.

created_at

body

string

The UTC date and time when the resource was created, ISO 8601 format.

updated_at

body

string

The UTC date and time when the resource was updated, ISO 8601 format. May be “null”.

links

body

array

A list of relative links. Includes the self and bookmark links.

ports

body

array

Links to the collection of ports belonging to this portgroup.

Example Portgroup details:

{
  "address": "11:11:11:11:11:11",
  "created_at": "2016-08-18T22:28:48.643434+11:11",
  "extra": {},
  "internal_info": {},
  "links": [
    {
      "href": "http://127.0.0.1:6385/v1/portgroups/e43c722c-248e-4c6e-8ce8-0d8ff129387a",
      "rel": "self"
    },
    {
      "href": "http://127.0.0.1:6385/portgroups/e43c722c-248e-4c6e-8ce8-0d8ff129387a",
      "rel": "bookmark"
    }
  ],
  "mode": "active-backup",
  "name": "test_portgroup",
  "node_uuid": "6d85703a-565d-469a-96ce-30b6de53079d",
  "ports": [
    {
      "href": "http://127.0.0.1:6385/v1/portgroups/e43c722c-248e-4c6e-8ce8-0d8ff129387a/ports",
      "rel": "self"
    },
    {
      "href": "http://127.0.0.1:6385/portgroups/e43c722c-248e-4c6e-8ce8-0d8ff129387a/ports",
      "rel": "bookmark"
    }
  ],
  "properties": {},
  "standalone_ports_supported": true,
  "updated_at": null,
  "uuid": "e43c722c-248e-4c6e-8ce8-0d8ff129387a"
}
PATCH
/v1/portgroups/{portgroup_ident}

Update a Portgroup

Update a Portgroup.

Normal response code: 200

Error codes: 400,401,403,404

Request

The BODY of the PATCH request must be a JSON PATCH document, adhering to RFC 6902.

Name

In

Type

Description

portgroup_ident

path

string

The UUID or Name of the portgroup.

Example Portgroup update request:

[
   {
      "path" : "/address",
      "value" : "22:22:22:22:22:22",
      "op" : "replace"
   }
]

Response

Name

In

Type

Description

uuid

body

string

The UUID for the resource.

name

body

string

Human-readable identifier for the Portgroup resource. May be undefined.

address (Optional)

body

string

Physical hardware address of this Portgroup, typically the hardware MAC address.

node_uuid

body

string

UUID of the Node this resource belongs to.

standalone_ports_supported

body

boolean

Indicates whether ports that are members of this portgroup can be used as stand-alone ports.

internal_info

body

JSON

Internal metadata set and stored by the Portgroup. This field is read-only.

extra

body

object

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

mode

body

string

Mode of the port group. For possible values, refer to https://www.kernel.org/doc/Documentation/networking/bonding.txt. If not specified in a request to create a port group, it will be set to the value of the [DEFAULT]default_portgroup_mode configuration option. When set, can not be removed from the port group.

properties

body

JSON

Key/value properties related to the port group’s configuration.

created_at

body

string

The UTC date and time when the resource was created, ISO 8601 format.

updated_at

body

string

The UTC date and time when the resource was updated, ISO 8601 format. May be “null”.

links

body

array

A list of relative links. Includes the self and bookmark links.

ports

body

array

Links to the collection of ports belonging to this portgroup.

Example Portgroup update response:

{
  "address": "22:22:22:22:22:22",
  "created_at": "2016-08-18T22:28:48.643434+11:11",
  "extra": {},
  "internal_info": {},
  "links": [
    {
      "href": "http://127.0.0.1:6385/v1/portgroups/e43c722c-248e-4c6e-8ce8-0d8ff129387a",
      "rel": "self"
    },
    {
      "href": "http://127.0.0.1:6385/portgroups/e43c722c-248e-4c6e-8ce8-0d8ff129387a",
      "rel": "bookmark"
    }
  ],
  "mode": "active-backup",
  "name": "test_portgroup",
  "node_uuid": "6d85703a-565d-469a-96ce-30b6de53079d",
  "ports": [
    {
      "href": "http://127.0.0.1:6385/v1/portgroups/e43c722c-248e-4c6e-8ce8-0d8ff129387a/ports",
      "rel": "self"
    },
    {
      "href": "http://127.0.0.1:6385/portgroups/e43c722c-248e-4c6e-8ce8-0d8ff129387a/ports",
      "rel": "bookmark"
    }
  ],
  "properties": {},
  "standalone_ports_supported": true,
  "updated_at": "2016-08-18T22:28:49.653974+00:00",
  "uuid": "e43c722c-248e-4c6e-8ce8-0d8ff129387a"
}
DELETE
/v1/portgroups/{portgroup_ident}

Delete Portgroup

Delete a Portgroup.

Normal response code: 204

Error codes: 400,401,403,404

Request

Name

In

Type

Description

portgroup_ident

path

string

The UUID or Name of the portgroup.

Listing Portgroups by Node (nodes, portgroups)

New in version 1.24.

Given a Node identifier (uuid or name), the API exposes the list of, and details of, all Portgroups associated with that Node.

These endpoints do not allow modification of the Portgroups; that should be done by accessing the Portgroup resources under the /v1/portgroups endpoint.

GET
/v1/nodes/{node_ident}/portgroups

List Portgroups by Node

Return a list of bare metal Portgroups associated with node_ident.

Normal response code: 200

Error codes: 400,401,403,404

Request

Name

In

Type

Description

node_ident

path

string

The UUID or Name of the node.

fields (Optional)

query

array

One or more fields to be returned in the response.

For example, the following request returns only the uuid and name fields for each node:

GET /v1/nodes?fields=uuid,name

limit (Optional)

query

integer

Requests a page size of items. Returns a number of items up to a limit value. Use the limit parameter to make an initial limited request and use the ID of the last-seen item from the response as the marker parameter value in a subsequent limited request. This value cannot be larger than the max_limit option in the [api] section of the configuration. If it is higher than max_limit, only max-limit resources will be returned.

marker (Optional)

query

string

The ID of the last-seen item. Use the limit parameter to make an initial limited request and use the ID of the last-seen item from the response as the marker parameter value in a subsequent limited request.

sort_dir (Optional)

query

string

Sorts the response by the requested sort direction. A valid value is asc (ascending) or desc (descending). Default is asc. You can specify multiple pairs of sort key and sort direction query parameters. If you omit the sort direction in a pair, the API uses the natural sorting direction of the server attribute that is provided as the sort_key.

sort_key (Optional)

query

string

Sorts the response by this attribute value. Default is id. You can specify multiple pairs of sort key and sort direction query parameters. If you omit the sort direction in a pair, the API uses the natural sorting direction of the server attribute that is provided as the sort_key.

Response

Name

In

Type

Description

portgroups

body

array

A collection of Portgroup resources.

uuid

body

string

The UUID for the resource.

address (Optional)

body

string

Physical hardware address of this Portgroup, typically the hardware MAC address.

name

body

string

Human-readable identifier for the Portgroup resource. May be undefined.

links

body

array

A list of relative links. Includes the self and bookmark links.

Example list of a Node’s Portgroups:

{
  "portgroups": [
    {
      "address": "22:22:22:22:22:22",
      "links": [
        {
          "href": "http://127.0.0.1:6385/v1/portgroups/e43c722c-248e-4c6e-8ce8-0d8ff129387a",
          "rel": "self"
        },
        {
          "href": "http://127.0.0.1:6385/portgroups/e43c722c-248e-4c6e-8ce8-0d8ff129387a",
          "rel": "bookmark"
        }
      ],
      "name": "test_portgroup",
      "uuid": "e43c722c-248e-4c6e-8ce8-0d8ff129387a"
    }
  ]
}
GET
/v1/nodes/{node_ident}/portgroups/detail

List detailed Portgroups by Node

Return a detailed list of bare metal Portgroups associated with node_ident.

Normal response code: 200

Error codes: 400,401,403,404

Request

Name

In

Type

Description

node_ident

path

string

The UUID or Name of the node.

limit (Optional)

query

integer

Requests a page size of items. Returns a number of items up to a limit value. Use the limit parameter to make an initial limited request and use the ID of the last-seen item from the response as the marker parameter value in a subsequent limited request. This value cannot be larger than the max_limit option in the [api] section of the configuration. If it is higher than max_limit, only max-limit resources will be returned.

marker (Optional)

query

string

The ID of the last-seen item. Use the limit parameter to make an initial limited request and use the ID of the last-seen item from the response as the marker parameter value in a subsequent limited request.

sort_dir (Optional)

query

string

Sorts the response by the requested sort direction. A valid value is asc (ascending) or desc (descending). Default is asc. You can specify multiple pairs of sort key and sort direction query parameters. If you omit the sort direction in a pair, the API uses the natural sorting direction of the server attribute that is provided as the sort_key.

sort_key (Optional)

query

string

Sorts the response by this attribute value. Default is id. You can specify multiple pairs of sort key and sort direction query parameters. If you omit the sort direction in a pair, the API uses the natural sorting direction of the server attribute that is provided as the sort_key.

Response

Name

In

Type

Description

portgroups

body

array

A collection of Portgroup resources.

uuid

body

string

The UUID for the resource.

address (Optional)

body

string

Physical hardware address of this Portgroup, typically the hardware MAC address.

name

body

string

Human-readable identifier for the Portgroup resource. May be undefined.

node_uuid

body

string

UUID of the Node this resource belongs to.

standalone_ports_supported

body

boolean

Indicates whether ports that are members of this portgroup can be used as stand-alone ports.

internal_info

body

JSON

Internal metadata set and stored by the Portgroup. This field is read-only.

extra

body

object

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

mode

body

string

Mode of the port group. For possible values, refer to https://www.kernel.org/doc/Documentation/networking/bonding.txt. If not specified in a request to create a port group, it will be set to the value of the [DEFAULT]default_portgroup_mode configuration option. When set, can not be removed from the port group.

properties

body

JSON

Key/value properties related to the port group’s configuration.

ports

body

array

Links to the collection of ports belonging to this portgroup.

created_at

body

string

The UTC date and time when the resource was created, ISO 8601 format.

updated_at

body

string

The UTC date and time when the resource was updated, ISO 8601 format. May be “null”.

links

body

array

A list of relative links. Includes the self and bookmark links.

Example details of a Node’s Portgroups:

{
  "portgroups": [
    {
      "address": "22:22:22:22:22:22",
      "created_at": "2016-08-18T22:28:48.643434+11:11",
      "extra": {},
      "internal_info": {},
      "links": [
        {
          "href": "http://127.0.0.1:6385/v1/portgroups/e43c722c-248e-4c6e-8ce8-0d8ff129387a",
          "rel": "self"
        },
        {
          "href": "http://127.0.0.1:6385/portgroups/e43c722c-248e-4c6e-8ce8-0d8ff129387a",
          "rel": "bookmark"
        }
      ],
      "mode": "active-backup",
      "name": "test_portgroup",
      "node_uuid": "6d85703a-565d-469a-96ce-30b6de53079d",
      "ports": [
        {
          "href": "http://127.0.0.1:6385/v1/portgroups/e43c722c-248e-4c6e-8ce8-0d8ff129387a/ports",
          "rel": "self"
        },
        {
          "href": "http://127.0.0.1:6385/portgroups/e43c722c-248e-4c6e-8ce8-0d8ff129387a/ports",
          "rel": "bookmark"
        }
      ],
      "properties": {},
      "standalone_ports_supported": true,
      "updated_at": "2016-08-18T22:28:49.653974+00:00",
      "uuid": "e43c722c-248e-4c6e-8ce8-0d8ff129387a"
    }
  ]
}

Ports (ports)

Listing, Searching, Creating, Updating, and Deleting of bare metal Port resources are done through the ports resource.

All Ports must be associated to a Node when created. This association can be changed, though the request may be rejected if either the current or destination Node are in a transitive state (e.g., in the process of deploying) or are in a state that would be non-deterministically affected by such a change (e.g., there is an active user instance on the Node).

GET
/v1/ports

List Ports

Return a list of bare metal Ports. Some filtering is possible by passing in some parameters with the request.

By default, this query will return the uuid and address for each Port.

New in version 1.6: Added the node query parameter. If both node_uuid and node are specified in the request, node_uuid will be used to filter results.

New in version 1.8: Added the fields request parameter. When specified, this causes the content of the response to include only the specified fields, rather than the default set.

New in version 1.19: Added the pxe_enabled and local_link_connection fields.

New in version 1.24: Added the portgroup_uuid field.

New in version 1.34: Added the physical_network field.

New in version 1.43: Added the detail boolean request parameter. When specified True this causes the response to include complete details about each port.

New in version 1.53: Added the is_smartnic field.

New in version 1.82: Added the ability to filter ports based on the shard of the node they are associated with.

Normal response code: 200

Request

Name

In

Type

Description

node (Optional)

query

string

Filter the list of returned Ports, and only return the ones associated with this specific node (name or UUID), or an empty set if not found. This filter takes precedence over all other filters, and cannot be set at the same time as node_uuid or portgroup.

node_uuid (Optional)

query

string

Filter the list of returned Ports, and only return the ones associated with this specific node UUID, or an empty set if not found. This filter takes precedence over all other filters, and cannot be set at the same time as node or portgroup.

portgroup (Optional)

query

string

Filter the list of returned Ports, and only return the ones associated with this specific Portgroup (name or UUID), or an empty set if not found. This filter takes precedence over all other filters, and cannot be set at the same time as node_uuid or node.

address (Optional)

query

string

Filter the list of returned Ports, and only return the ones with the specified physical hardware address, typically MAC, or an empty set if not found.

shard (Optional)

query

array

Filter the list of returned Ports, and only return the ones associated with nodes in this specific shard(s), or an empty set if not found.

fields (Optional)

query

array

One or more fields to be returned in the response.

For example, the following request returns only the uuid and name fields for each node:

GET /v1/nodes?fields=uuid,name

limit (Optional)

query

integer

Requests a page size of items. Returns a number of items up to a limit value. Use the limit parameter to make an initial limited request and use the ID of the last-seen item from the response as the marker parameter value in a subsequent limited request. This value cannot be larger than the max_limit option in the [api] section of the configuration. If it is higher than max_limit, only max-limit resources will be returned.

marker (Optional)

query

string

The ID of the last-seen item. Use the limit parameter to make an initial limited request and use the ID of the last-seen item from the response as the marker parameter value in a subsequent limited request.

sort_dir (Optional)

query

string

Sorts the response by the requested sort direction. A valid value is asc (ascending) or desc (descending). Default is asc. You can specify multiple pairs of sort key and sort direction query parameters. If you omit the sort direction in a pair, the API uses the natural sorting direction of the server attribute that is provided as the sort_key.

sort_key (Optional)

query

string

Sorts the response by this attribute value. Default is id. You can specify multiple pairs of sort key and sort direction query parameters. If you omit the sort direction in a pair, the API uses the natural sorting direction of the server attribute that is provided as the sort_key.

detail (Optional)

query

boolean

Whether to show detailed information about the resource. This cannot be set to True if fields parameter is specified.

Response

Name

In

Type

Description

ports

body

array

A collection of Port resources.

uuid

body

string

The UUID for the resource.

address

body

string

Physical hardware address of this network Port, typically the hardware MAC address.

links

body

array

A list of relative links. Includes the self and bookmark links.

Example Port list response:

{
  "ports": [
    {
      "address": "11:11:11:11:11:11",
      "links": [
        {
          "href": "http://127.0.0.1:6385/v1/ports/d2b30520-907d-46c8-bfee-c5586e6fb3a1",
          "rel": "self"
        },
        {
          "href": "http://127.0.0.1:6385/ports/d2b30520-907d-46c8-bfee-c5586e6fb3a1",
          "rel": "bookmark"
        }
      ],
      "uuid": "d2b30520-907d-46c8-bfee-c5586e6fb3a1"
    }
  ]
}
POST
/v1/ports

Create Port

Creates a new Port resource.

This method requires a Node UUID and the physical hardware address for the Port (MAC address in most cases).

New in version 1.19: Added the pxe_enabled and local_link_connection request and response fields.

New in version 1.24: Added the portgroup_uuid request and response fields.

New in version 1.34: Added the physical_network request and response fields.

New in version 1.53: Added the is_smartnic request and response fields.

New in version 1.88: Added the name field.

New in version 1.90: local_link_connection fields now accepts a dictionary of vtep-logical-switch, vtep-physical-switch and port_id to identify ovn vtep switches.

Normal response code: 201

Request

Name

In

Type

Description

node_uuid

body

string

UUID of the Node this resource belongs to.

address

body

string

Physical hardware address of this network Port, typically the hardware MAC address.

portgroup_uuid (Optional)

body

string

UUID of the Portgroup this resource belongs to.

name (Optional)

body

string

The name assigned to the network Port.

local_link_connection (Optional)

body

JSON

The Port binding profile. If specified, must contain switch_id (only a MAC address or an OpenFlow based datapath_id of the switch are accepted in this field) and port_id (identifier of the physical port on the switch to which node’s port is connected to) fields. switch_info is an optional string field to be used to store any vendor-specific information.

pxe_enabled (Optional)

body

boolean

Indicates whether PXE is enabled or disabled on the Port.

physical_network (Optional)

body

string

The name of the physical network to which a port is connected. May be empty.

extra (Optional)

body

object

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

is_smartnic (Optional)

body

boolean

Indicates whether the Port is a Smart NIC port.

uuid (Optional)

body

string

The UUID for the resource.

Example Port creation request:

{
    "node_uuid": "6d85703a-565d-469a-96ce-30b6de53079d",
    "portgroup_uuid": "e43c722c-248e-4c6e-8ce8-0d8ff129387a",
    "name": "port1",
    "address": "11:11:11:11:11:11",
    "is_smartnic": true,
    "local_link_connection": {
        "switch_id": "0a:1b:2c:3d:4e:5f",
        "port_id": "Ethernet3/1",
        "switch_info": "switch1"
    },
    "physical_network": "physnet1"
}

Response

Name

In

Type

Description

uuid

body

string

The UUID for the resource.

address

body

string

Physical hardware address of this network Port, typically the hardware MAC address.

node_uuid

body

string

UUID of the Node this resource belongs to.

portgroup_uuid

body

string

UUID of the Portgroup this resource belongs to.

name (Optional)

body

string

The name assigned to the network Port.

local_link_connection

body

JSON

The Port binding profile. If specified, must contain switch_id (only a MAC address or an OpenFlow based datapath_id of the switch are accepted in this field) and port_id (identifier of the physical port on the switch to which node’s port is connected to) fields. switch_info is an optional string field to be used to store any vendor-specific information.

pxe_enabled

body

boolean

Indicates whether PXE is enabled or disabled on the Port.

physical_network

body

string

The name of the physical network to which a port is connected. May be empty.

internal_info

body

JSON

Internal metadata set and stored by the Port. This field is read-only.

extra

body

object

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

created_at

body

string

The UTC date and time when the resource was created, ISO 8601 format.

updated_at

body

string

The UTC date and time when the resource was updated, ISO 8601 format. May be “null”.

links

body

array

A list of relative links. Includes the self and bookmark links.

is_smartnic (Optional)

body

boolean

Indicates whether the Port is a Smart NIC port.

Example Port creation response:

{
  "address": "11:11:11:11:11:11",
  "created_at": "2016-08-18T22:28:48.643434+11:11",
  "extra": {},
  "internal_info": {},
  "is_smartnic": true,
  "links": [
    {
      "href": "http://127.0.0.1:6385/v1/ports/d2b30520-907d-46c8-bfee-c5586e6fb3a1",
      "rel": "self"
    },
    {
      "href": "http://127.0.0.1:6385/ports/d2b30520-907d-46c8-bfee-c5586e6fb3a1",
      "rel": "bookmark"
    }
  ],
  "local_link_connection": {
    "port_id": "Ethernet3/1",
    "switch_id": "0a:1b:2c:3d:4e:5f",
    "switch_info": "switch1"
  },
  "name": "port1",
  "node_uuid": "6d85703a-565d-469a-96ce-30b6de53079d",
  "physical_network": "physnet1",
  "portgroup_uuid": "e43c722c-248e-4c6e-8ce8-0d8ff129387a",
  "pxe_enabled": true,
  "updated_at": null,
  "uuid": "d2b30520-907d-46c8-bfee-c5586e6fb3a1"
}
GET
/v1/ports/detail

List Detailed Ports

Return a list of bare metal Ports, with detailed information.

New in version 1.6: Added the node query parameter. If both node_uuid and node are specified in the request, node_uuid will be used to filter results.

New in version 1.19: Added the pxe_enabled and local_link_connection response fields.

New in version 1.24: Added the portgroup query parameter and portgroup_uuid response field.

New in version 1.34: Added the physical_network response field.

New in version 1.53: Added the is_smartnic response fields.

New in version 1.82: Added the ability to filter ports based on the shard of the node they are associated with.

New in version 1.88: Added the name field.

Normal response code: 200

Request

Name

In

Type

Description

node (Optional)

query

string

Filter the list of returned Ports, and only return the ones associated with this specific node (name or UUID), or an empty set if not found. This filter takes precedence over all other filters, and cannot be set at the same time as node_uuid or portgroup.

node_uuid (Optional)

query

string

Filter the list of returned Ports, and only return the ones associated with this specific node UUID, or an empty set if not found. This filter takes precedence over all other filters, and cannot be set at the same time as node or portgroup.

portgroup (Optional)

query

string

Filter the list of returned Ports, and only return the ones associated with this specific Portgroup (name or UUID), or an empty set if not found. This filter takes precedence over all other filters, and cannot be set at the same time as node_uuid or node.

address (Optional)

query

string

Filter the list of returned Ports, and only return the ones with the specified physical hardware address, typically MAC, or an empty set if not found.

shard (Optional)

query

array

Filter the list of returned Ports, and only return the ones associated with nodes in this specific shard(s), or an empty set if not found.

limit (Optional)

query

integer

Requests a page size of items. Returns a number of items up to a limit value. Use the limit parameter to make an initial limited request and use the ID of the last-seen item from the response as the marker parameter value in a subsequent limited request. This value cannot be larger than the max_limit option in the [api] section of the configuration. If it is higher than max_limit, only max-limit resources will be returned.

marker (Optional)

query

string

The ID of the last-seen item. Use the limit parameter to make an initial limited request and use the ID of the last-seen item from the response as the marker parameter value in a subsequent limited request.

sort_dir (Optional)

query

string

Sorts the response by the requested sort direction. A valid value is asc (ascending) or desc (descending). Default is asc. You can specify multiple pairs of sort key and sort direction query parameters. If you omit the sort direction in a pair, the API uses the natural sorting direction of the server attribute that is provided as the sort_key.

sort_key (Optional)

query

string

Sorts the response by this attribute value. Default is id. You can specify multiple pairs of sort key and sort direction query parameters. If you omit the sort direction in a pair, the API uses the natural sorting direction of the server attribute that is provided as the sort_key.

Response

Name

In

Type

Description

ports

body

array

A collection of Port resources.

uuid

body

string

The UUID for the resource.

address

body

string

Physical hardware address of this network Port, typically the hardware MAC address.

node_uuid

body

string

UUID of the Node this resource belongs to.

portgroup_uuid

body

string

UUID of the Portgroup this resource belongs to.

name (Optional)

body

string

The name assigned to the network Port.

local_link_connection

body

JSON

The Port binding profile. If specified, must contain switch_id (only a MAC address or an OpenFlow based datapath_id of the switch are accepted in this field) and port_id (identifier of the physical port on the switch to which node’s port is connected to) fields. switch_info is an optional string field to be used to store any vendor-specific information.

pxe_enabled

body

boolean

Indicates whether PXE is enabled or disabled on the Port.

physical_network

body

string

The name of the physical network to which a port is connected. May be empty.

internal_info

body

JSON

Internal metadata set and stored by the Port. This field is read-only.

extra

body

object

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

created_at

body

string

The UTC date and time when the resource was created, ISO 8601 format.

updated_at

body

string

The UTC date and time when the resource was updated, ISO 8601 format. May be “null”.

links

body

array

A list of relative links. Includes the self and bookmark links.

is_smartnic (Optional)

body

boolean

Indicates whether the Port is a Smart NIC port.

Example detailed Port list response:

{
  "ports": [
    {
      "address": "11:11:11:11:11:11",
      "created_at": "2016-08-18T22:28:48.643434+11:11",
      "extra": {},
      "internal_info": {},
      "is_smartnic": true,
      "links": [
        {
          "href": "http://127.0.0.1:6385/v1/ports/d2b30520-907d-46c8-bfee-c5586e6fb3a1",
          "rel": "self"
        },
        {
          "href": "http://127.0.0.1:6385/ports/d2b30520-907d-46c8-bfee-c5586e6fb3a1",
          "rel": "bookmark"
        }
      ],
      "local_link_connection": {
        "port_id": "Ethernet3/1",
        "switch_id": "0a:1b:2c:3d:4e:5f",
        "switch_info": "switch1"
      },
      "name": "port1",
      "node_uuid": "6d85703a-565d-469a-96ce-30b6de53079d",
      "physical_network": "physnet1",
      "portgroup_uuid": "e43c722c-248e-4c6e-8ce8-0d8ff129387a",
      "pxe_enabled": true,
      "updated_at": null,
      "uuid": "d2b30520-907d-46c8-bfee-c5586e6fb3a1"
    }
  ]
}
GET
/v1/ports/{port_id}

Show Port Details

Show details for the given Port.

New in version 1.8: Added the fields request parameter. When specified, this causes the content of the response to include only the specified fields, rather than the default set.

New in version 1.19: Added the pxe_enabled and local_link_connection response fields.

New in version 1.24: Added the portgroup_uuid response field.

New in version 1.34: Added the physical_network response field.

New in version 1.53: Added the is_smartnic response fields.

New in version 1.88: Added the name

Normal response code: 200

Request

Name

In

Type

Description

port_id

path

string

The UUID or Name of the port.

fields (Optional)

query

array

One or more fields to be returned in the response.

For example, the following request returns only the uuid and name fields for each node:

GET /v1/nodes?fields=uuid,name

Response

Name

In

Type

Description

uuid

body

string

The UUID for the resource.

address

body

string

Physical hardware address of this network Port, typically the hardware MAC address.

node_uuid

body

string

UUID of the Node this resource belongs to.

portgroup_uuid

body

string

UUID of the Portgroup this resource belongs to.

name (Optional)

body

string

The name assigned to the network Port.

local_link_connection

body

JSON

The Port binding profile. If specified, must contain switch_id (only a MAC address or an OpenFlow based datapath_id of the switch are accepted in this field) and port_id (identifier of the physical port on the switch to which node’s port is connected to) fields. switch_info is an optional string field to be used to store any vendor-specific information.

pxe_enabled

body

boolean

Indicates whether PXE is enabled or disabled on the Port.

physical_network

body

string

The name of the physical network to which a port is connected. May be empty.

internal_info

body

JSON

Internal metadata set and stored by the Port. This field is read-only.

extra

body

object

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

created_at

body

string

The UTC date and time when the resource was created, ISO 8601 format.

updated_at

body

string

The UTC date and time when the resource was updated, ISO 8601 format. May be “null”.

links

body

array

A list of relative links. Includes the self and bookmark links.

is_smartnic (Optional)

body

boolean

Indicates whether the Port is a Smart NIC port.

Example Port details:

{
  "address": "11:11:11:11:11:11",
  "created_at": "2016-08-18T22:28:48.643434+11:11",
  "extra": {},
  "internal_info": {},
  "is_smartnic": true,
  "links": [
    {
      "href": "http://127.0.0.1:6385/v1/ports/d2b30520-907d-46c8-bfee-c5586e6fb3a1",
      "rel": "self"
    },
    {
      "href": "http://127.0.0.1:6385/ports/d2b30520-907d-46c8-bfee-c5586e6fb3a1",
      "rel": "bookmark"
    }
  ],
  "local_link_connection": {
    "port_id": "Ethernet3/1",
    "switch_id": "0a:1b:2c:3d:4e:5f",
    "switch_info": "switch1"
  },
  "name": "port1",
  "node_uuid": "6d85703a-565d-469a-96ce-30b6de53079d",
  "physical_network": "physnet1",
  "portgroup_uuid": "e43c722c-248e-4c6e-8ce8-0d8ff129387a",
  "pxe_enabled": true,
  "updated_at": null,
  "uuid": "d2b30520-907d-46c8-bfee-c5586e6fb3a1"
}
PATCH
/v1/ports/{port_id}

Update a Port

Update a Port.

New in version 1.19: Added the pxe_enabled and local_link_connection fields.

New in version 1.24: Added the portgroup_uuid field.

New in version 1.34: Added the physical_network field.

New in version 1.53: Added the is_smartnic fields.

New in version 1.88: Added the name

New in version 1.90: local_link_connection fields now accepts a dictionary of vtep-logical-switch, vtep-physical-switch and port_id to identify ovn vtep switches.

Normal response code: 200

Request

The BODY of the PATCH request must be a JSON PATCH document, adhering to RFC 6902.

Name

In

Type

Description

port_id

path

string

The UUID or Name of the port.

Example Port update request:

[
   {
      "path" : "/address",
      "value" : "22:22:22:22:22:22",
      "op" : "replace"
   }
]

Response

Name

In

Type

Description

uuid

body

string

The UUID for the resource.

address

body

string

Physical hardware address of this network Port, typically the hardware MAC address.

node_uuid

body

string

UUID of the Node this resource belongs to.

portgroup_uuid

body

string

UUID of the Portgroup this resource belongs to.

name (Optional)

body

string

The name assigned to the network Port.

local_link_connection

body

JSON

The Port binding profile. If specified, must contain switch_id (only a MAC address or an OpenFlow based datapath_id of the switch are accepted in this field) and port_id (identifier of the physical port on the switch to which node’s port is connected to) fields. switch_info is an optional string field to be used to store any vendor-specific information.

pxe_enabled

body

boolean

Indicates whether PXE is enabled or disabled on the Port.

physical_network

body

string

The name of the physical network to which a port is connected. May be empty.

internal_info

body

JSON

Internal metadata set and stored by the Port. This field is read-only.

extra

body

object

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

created_at

body

string

The UTC date and time when the resource was created, ISO 8601 format.

updated_at

body

string

The UTC date and time when the resource was updated, ISO 8601 format. May be “null”.

links

body

array

A list of relative links. Includes the self and bookmark links.

is_smartnic (Optional)

body

boolean

Indicates whether the Port is a Smart NIC port.

Example Port update response:

{
  "address": "22:22:22:22:22:22",
  "created_at": "2016-08-18T22:28:48.643434+11:11",
  "extra": {},
  "internal_info": {},
  "is_smartnic": true,
  "links": [
    {
      "href": "http://127.0.0.1:6385/v1/ports/d2b30520-907d-46c8-bfee-c5586e6fb3a1",
      "rel": "self"
    },
    {
      "href": "http://127.0.0.1:6385/ports/d2b30520-907d-46c8-bfee-c5586e6fb3a1",
      "rel": "bookmark"
    }
  ],
  "local_link_connection": {
    "port_id": "Ethernet3/1",
    "switch_id": "0a:1b:2c:3d:4e:5f",
    "switch_info": "switch1"
  },
  "name": "port1",
  "node_uuid": "6d85703a-565d-469a-96ce-30b6de53079d",
  "physical_network": "physnet1",
  "portgroup_uuid": "e43c722c-248e-4c6e-8ce8-0d8ff129387a",
  "pxe_enabled": true,
  "updated_at": "2016-08-18T22:28:49.653974+00:00",
  "uuid": "d2b30520-907d-46c8-bfee-c5586e6fb3a1"
}
DELETE
/v1/ports/{port_id}

Delete Port

Delete a Port.

Normal response code: 204

Request

Name

In

Type

Description

port_id

path

string

The UUID or Name of the port.

Listing Ports by Node (nodes, ports)

Given a Node identifier (uuid or name), the API exposes the list of, and details of, all Ports associated with that Node.

These endpoints do not allow modification of the Ports; that should be done by accessing the Port resources under the /v1/ports endpoint.

GET
/v1/nodes/{node_ident}/ports

List Ports by Node

Return a list of bare metal Ports associated with node_ident.

New in version 1.8: Added the fields request parameter. When specified, this causes the content of the response to include only the specified fields, rather than the default set.

New in version 1.19: Added the pxe_enabled and local_link_connection fields.

New in version 1.24: Added the portgroup_uuid field.

New in version 1.34: Added the physical_network field.

New in version 1.53: Added the is_smartnic response fields.

Normal response code: 200

Error codes: TBD

Request

Name

In

Type

Description

node_ident

path

string

The UUID or Name of the node.

fields (Optional)

query

array

One or more fields to be returned in the response.

For example, the following request returns only the uuid and name fields for each node:

GET /v1/nodes?fields=uuid,name

limit (Optional)

query

integer

Requests a page size of items. Returns a number of items up to a limit value. Use the limit parameter to make an initial limited request and use the ID of the last-seen item from the response as the marker parameter value in a subsequent limited request. This value cannot be larger than the max_limit option in the [api] section of the configuration. If it is higher than max_limit, only max-limit resources will be returned.

marker (Optional)

query

string

The ID of the last-seen item. Use the limit parameter to make an initial limited request and use the ID of the last-seen item from the response as the marker parameter value in a subsequent limited request.

sort_dir (Optional)

query

string

Sorts the response by the requested sort direction. A valid value is asc (ascending) or desc (descending). Default is asc. You can specify multiple pairs of sort key and sort direction query parameters. If you omit the sort direction in a pair, the API uses the natural sorting direction of the server attribute that is provided as the sort_key.

sort_key (Optional)

query

string

Sorts the response by this attribute value. Default is id. You can specify multiple pairs of sort key and sort direction query parameters. If you omit the sort direction in a pair, the API uses the natural sorting direction of the server attribute that is provided as the sort_key.

Response

Name

In

Type

Description

ports

body

array

A collection of Port resources.

uuid

body

string

The UUID for the resource.

address

body

string

Physical hardware address of this network Port, typically the hardware MAC address.

links

body

array

A list of relative links. Includes the self and bookmark links.

Example list of a Node’s Ports:

{
  "ports": [
    {
      "address": "22:22:22:22:22:22",
      "links": [
        {
          "href": "http://127.0.0.1:6385/v1/ports/d2b30520-907d-46c8-bfee-c5586e6fb3a1",
          "rel": "self"
        },
        {
          "href": "http://127.0.0.1:6385/ports/d2b30520-907d-46c8-bfee-c5586e6fb3a1",
          "rel": "bookmark"
        }
      ],
      "uuid": "d2b30520-907d-46c8-bfee-c5586e6fb3a1"
    }
  ]
}
GET
/v1/nodes/{node_ident}/ports/detail

List detailed Ports by Node

Return a detailed list of bare metal Ports associated with node_ident.

New in version 1.19: Added the pxe_enabled and local_link_connection fields.

New in version 1.24: Added the portgroup_uuid field.

New in version 1.34: Added the physical_network field.

New in version 1.53: Added the is_smartnic response fields.

Normal response code: 200

Error codes: TBD

Request

Name

In

Type

Description

node_ident

path

string

The UUID or Name of the node.

fields (Optional)

query

array

One or more fields to be returned in the response.

For example, the following request returns only the uuid and name fields for each node:

GET /v1/nodes?fields=uuid,name

limit (Optional)

query

integer

Requests a page size of items. Returns a number of items up to a limit value. Use the limit parameter to make an initial limited request and use the ID of the last-seen item from the response as the marker parameter value in a subsequent limited request. This value cannot be larger than the max_limit option in the [api] section of the configuration. If it is higher than max_limit, only max-limit resources will be returned.

marker (Optional)

query

string

The ID of the last-seen item. Use the limit parameter to make an initial limited request and use the ID of the last-seen item from the response as the marker parameter value in a subsequent limited request.

sort_dir (Optional)

query

string

Sorts the response by the requested sort direction. A valid value is asc (ascending) or desc (descending). Default is asc. You can specify multiple pairs of sort key and sort direction query parameters. If you omit the sort direction in a pair, the API uses the natural sorting direction of the server attribute that is provided as the sort_key.

sort_key (Optional)

query

string

Sorts the response by this attribute value. Default is id. You can specify multiple pairs of sort key and sort direction query parameters. If you omit the sort direction in a pair, the API uses the natural sorting direction of the server attribute that is provided as the sort_key.

Response

Name

In

Type

Description

ports

body

array

A collection of Port resources.

uuid

body

string

The UUID for the resource.

address

body

string

Physical hardware address of this network Port, typically the hardware MAC address.

node_uuid

body

string

UUID of the Node this resource belongs to.

local_link_connection

body

JSON

The Port binding profile. If specified, must contain switch_id (only a MAC address or an OpenFlow based datapath_id of the switch are accepted in this field) and port_id (identifier of the physical port on the switch to which node’s port is connected to) fields. switch_info is an optional string field to be used to store any vendor-specific information.

pxe_enabled

body

boolean

Indicates whether PXE is enabled or disabled on the Port.

physical_network

body

string

The name of the physical network to which a port is connected. May be empty.

internal_info

body

JSON

Internal metadata set and stored by the Port. This field is read-only.

extra

body

object

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

created_at

body

string

The UTC date and time when the resource was created, ISO 8601 format.

updated_at

body

string

The UTC date and time when the resource was updated, ISO 8601 format. May be “null”.

links

body

array

A list of relative links. Includes the self and bookmark links.

is_smartnic (Optional)

body

boolean

Indicates whether the Port is a Smart NIC port.

Example details of a Node’s Ports:

{
  "ports": [
    {
      "address": "22:22:22:22:22:22",
      "created_at": "2016-08-18T22:28:48.643434+11:11",
      "extra": {},
      "internal_info": {},
      "is_smartnic": true,
      "links": [
        {
          "href": "http://127.0.0.1:6385/v1/ports/d2b30520-907d-46c8-bfee-c5586e6fb3a1",
          "rel": "self"
        },
        {
          "href": "http://127.0.0.1:6385/ports/d2b30520-907d-46c8-bfee-c5586e6fb3a1",
          "rel": "bookmark"
        }
      ],
      "local_link_connection": {
        "port_id": "Ethernet3/1",
        "switch_id": "0a:1b:2c:3d:4e:5f",
        "switch_info": "switch1"
      },
      "node_uuid": "6d85703a-565d-469a-96ce-30b6de53079d",
      "physical_network": "physnet1",
      "portgroup_uuid": "e43c722c-248e-4c6e-8ce8-0d8ff129387a",
      "pxe_enabled": true,
      "updated_at": "2016-08-18T22:28:49.653974+00:00",
      "uuid": "d2b30520-907d-46c8-bfee-c5586e6fb3a1"
    }
  ]
}

Listing Ports by Portgroup (portgroup, ports)

New in version 1.24.

Given a Portgroup identifier (uuid or name), the API exposes the list of, and details of, all Ports associated with that Portgroup.

These endpoints do not allow modification of the Ports; that should be done by accessing the Port resources under the /v1/ports endpoint.

GET
/v1/portgroups/{portgroup_ident}/ports

List Ports by Portgroup

Return a list of bare metal Ports associated with portgroup_ident.

When specified, the fields request parameter causes the content of the Response to include only the specified fields, rather than the default set.

New in version 1.34: Added the physical_network field.

New in version 1.53: Added the is_smartnic response fields.

Normal response code: 200

Error codes: 400,401,403,404

Request

Name

In

Type

Description

portgroup_ident

path

string

The UUID or Name of the portgroup.

fields (Optional)

query

array

One or more fields to be returned in the response.

For example, the following request returns only the uuid and name fields for each node:

GET /v1/nodes?fields=uuid,name

limit (Optional)

query

integer

Requests a page size of items. Returns a number of items up to a limit value. Use the limit parameter to make an initial limited request and use the ID of the last-seen item from the response as the marker parameter value in a subsequent limited request. This value cannot be larger than the max_limit option in the [api] section of the configuration. If it is higher than max_limit, only max-limit resources will be returned.

marker (Optional)

query

string

The ID of the last-seen item. Use the limit parameter to make an initial limited request and use the ID of the last-seen item from the response as the marker parameter value in a subsequent limited request.

sort_dir (Optional)

query

string

Sorts the response by the requested sort direction. A valid value is asc (ascending) or desc (descending). Default is asc. You can specify multiple pairs of sort key and sort direction query parameters. If you omit the sort direction in a pair, the API uses the natural sorting direction of the server attribute that is provided as the sort_key.

sort_key (Optional)

query

string

Sorts the response by this attribute value. Default is id. You can specify multiple pairs of sort key and sort direction query parameters. If you omit the sort direction in a pair, the API uses the natural sorting direction of the server attribute that is provided as the sort_key.

Response

Name

In

Type

Description

ports

body

array

A collection of Port resources.

uuid

body

string

The UUID for the resource.

address

body

string

Physical hardware address of this network Port, typically the hardware MAC address.

links

body

array

A list of relative links. Includes the self and bookmark links.

Example list of a Portgroup’s Ports:

{
  "ports": [
    {
      "address": "22:22:22:22:22:22",
      "links": [
        {
          "href": "http://127.0.0.1:6385/v1/ports/d2b30520-907d-46c8-bfee-c5586e6fb3a1",
          "rel": "self"
        },
        {
          "href": "http://127.0.0.1:6385/ports/d2b30520-907d-46c8-bfee-c5586e6fb3a1",
          "rel": "bookmark"
        }
      ],
      "uuid": "d2b30520-907d-46c8-bfee-c5586e6fb3a1"
    }
  ]
}
GET
/v1/portgroups/{portgroup_ident}/ports/detail

List detailed Ports by Portgroup

Return a detailed list of bare metal Ports associated with portgroup_ident.

New in version 1.34: Added the physical_network field.

New in version 1.53: Added the is_smartnic response fields.

Normal response code: 200

Error codes: 400,401,403,404

Request

Name

In

Type

Description

portgroup_ident

path

string

The UUID or Name of the portgroup.

limit (Optional)

query

integer

Requests a page size of items. Returns a number of items up to a limit value. Use the limit parameter to make an initial limited request and use the ID of the last-seen item from the response as the marker parameter value in a subsequent limited request. This value cannot be larger than the max_limit option in the [api] section of the configuration. If it is higher than max_limit, only max-limit resources will be returned.

marker (Optional)

query

string

The ID of the last-seen item. Use the limit parameter to make an initial limited request and use the ID of the last-seen item from the response as the marker parameter value in a subsequent limited request.

sort_dir (Optional)

query

string

Sorts the response by the requested sort direction. A valid value is asc (ascending) or desc (descending). Default is asc. You can specify multiple pairs of sort key and sort direction query parameters. If you omit the sort direction in a pair, the API uses the natural sorting direction of the server attribute that is provided as the sort_key.

sort_key (Optional)

query

string

Sorts the response by this attribute value. Default is id. You can specify multiple pairs of sort key and sort direction query parameters. If you omit the sort direction in a pair, the API uses the natural sorting direction of the server attribute that is provided as the sort_key.

Response

Name

In

Type

Description

ports

body

array

A collection of Port resources.

uuid

body

string

The UUID for the resource.

address

body

string

Physical hardware address of this network Port, typically the hardware MAC address.

node_uuid

body

string

UUID of the Node this resource belongs to.

local_link_connection

body

JSON

The Port binding profile. If specified, must contain switch_id (only a MAC address or an OpenFlow based datapath_id of the switch are accepted in this field) and port_id (identifier of the physical port on the switch to which node’s port is connected to) fields. switch_info is an optional string field to be used to store any vendor-specific information.

pxe_enabled

body

boolean

Indicates whether PXE is enabled or disabled on the Port.

physical_network

body

string

The name of the physical network to which a port is connected. May be empty.

internal_info

body

JSON

Internal metadata set and stored by the Port. This field is read-only.

extra

body

object

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

portgroup_uuid

body

string

UUID of the Portgroup this resource belongs to.

created_at

body

string

The UTC date and time when the resource was created, ISO 8601 format.

updated_at

body

string

The UTC date and time when the resource was updated, ISO 8601 format. May be “null”.

links

body

array

A list of relative links. Includes the self and bookmark links.

is_smartnic (Optional)

body

boolean

Indicates whether the Port is a Smart NIC port.

Example details of a Portgroup’s Ports:

{
  "ports": [
    {
      "address": "22:22:22:22:22:22",
      "created_at": "2016-08-18T22:28:48.643434+11:11",
      "extra": {},
      "internal_info": {},
      "is_smartnic": true,
      "links": [
        {
          "href": "http://127.0.0.1:6385/v1/ports/d2b30520-907d-46c8-bfee-c5586e6fb3a1",
          "rel": "self"
        },
        {
          "href": "http://127.0.0.1:6385/ports/d2b30520-907d-46c8-bfee-c5586e6fb3a1",
          "rel": "bookmark"
        }
      ],
      "local_link_connection": {
        "port_id": "Ethernet3/1",
        "switch_id": "0a:1b:2c:3d:4e:5f",
        "switch_info": "switch1"
      },
      "node_uuid": "6d85703a-565d-469a-96ce-30b6de53079d",
      "physical_network": "physnet1",
      "portgroup_uuid": "e43c722c-248e-4c6e-8ce8-0d8ff129387a",
      "pxe_enabled": true,
      "updated_at": "2016-08-18T22:28:49.653974+00:00",
      "uuid": "d2b30520-907d-46c8-bfee-c5586e6fb3a1"
    }
  ]
}

Volume (volume)

New in version 1.32.

Information for connecting remote volumes to a node can be associated with a Node. There are two types of resources, Volume connectors and Volume targets. Volume connectors contain initiator information of Nodes. Volume targets contain target information of remote volumes.

Listing, Searching, Creating, Updating, and Deleting of Volume connector resources are done through the v1/volume/connectors resource. The same operations for Volume targets are done through the v1/volume/targets resources.

GET
/v1/volume/connectors

List Volume Connectors

Return a list of Volume connectors for all nodes.

By default, this query will return the UUID, node UUID, type, and connector ID for each Volume connector.

Normal response code: 200

Error codes: 400,401,403,404

Request

Name

In

Type

Description

node (Optional)

query

string

Filter the list of returned Volume connectors, and only return the ones associated with this specific node (name or UUID), or an empty set if not found.

fields (Optional)

query

array

One or more fields to be returned in the response.

For example, the following request returns only the uuid and name fields for each node:

GET /v1/nodes?fields=uuid,name

detail (Optional)

query

boolean

Whether to show detailed information about the resource. This cannot be set to True if fields parameter is specified.

limit (Optional)

query

integer

Requests a page size of items. Returns a number of items up to a limit value. Use the limit parameter to make an initial limited request and use the ID of the last-seen item from the response as the marker parameter value in a subsequent limited request. This value cannot be larger than the max_limit option in the [api] section of the configuration. If it is higher than max_limit, only max-limit resources will be returned.

marker (Optional)

query

string

The ID of the last-seen item. Use the limit parameter to make an initial limited request and use the ID of the last-seen item from the response as the marker parameter value in a subsequent limited request.

sort_dir (Optional)

query

string

Sorts the response by the requested sort direction. A valid value is asc (ascending) or desc (descending). Default is asc. You can specify multiple pairs of sort key and sort direction query parameters. If you omit the sort direction in a pair, the API uses the natural sorting direction of the server attribute that is provided as the sort_key.

sort_key (Optional)

query

string

Sorts the response by this attribute value. Default is id. You can specify multiple pairs of sort key and sort direction query parameters. If you omit the sort direction in a pair, the API uses the natural sorting direction of the server attribute that is provided as the sort_key.

Response

Name

In

Type

Description

connectors

body

array

A collection of Volume connector resources.

uuid

body

string

The UUID for the resource.

type

body

string

The type of Volume connector such as “iqn”, “ip”, “wwnn” and “wwpn”.

connector_id

body

string

The identifier of Volume connector. The identifier format depends on the type of the Volume connector, eg “iqn.2017-05.org.openstack:01:d9a51732c3f” if the type is “iqn”, “192.168.1.2” if the type is “ip”.

node_uuid

body

string

UUID of the Node this resource belongs to.

extra

body

object

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

links

body

array

A list of relative links. Includes the self and bookmark links.

next (Optional)

body

string

A URL to request a next collection of the resource. This parameter is returned when limit is specified in a request and there remain items.

Example Volume connector list response:

{
  "connectors": [
    {
      "connector_id": "iqn.2017-07.org.openstack:01:d9a51732c3f",
      "links": [
        {
          "href": "http://127.0.0.1:6385/v1/volume/connectors/9bf93e01-d728-47a3-ad4b-5e66a835037c",
          "rel": "self"
        },
        {
          "href": "http://127.0.0.1:6385/volume/connectors/9bf93e01-d728-47a3-ad4b-5e66a835037c",
          "rel": "bookmark"
        }
      ],
      "node_uuid": "6d85703a-565d-469a-96ce-30b6de53079d",
      "type": "iqn",
      "uuid": "9bf93e01-d728-47a3-ad4b-5e66a835037c"
    }
  ]
}

Example detailed Volume connector list response:

{
  "connectors": [
    {
      "connector_id": "iqn.2017-07.org.openstack:01:d9a51732c3f",
      "created_at": "2016-08-18T22:28:48.643434+11:11",
      "extra": {},
      "links": [
        {
          "href": "http://127.0.0.1:6385/v1/volume/connectors/9bf93e01-d728-47a3-ad4b-5e66a835037c",
          "rel": "self"
        },
        {
          "href": "http://127.0.0.1:6385/volume/connectors/9bf93e01-d728-47a3-ad4b-5e66a835037c",
          "rel": "bookmark"
        }
      ],
      "node_uuid": "6d85703a-565d-469a-96ce-30b6de53079d",
      "type": "iqn",
      "updated_at": null,
      "uuid": "9bf93e01-d728-47a3-ad4b-5e66a835037c"
    }
  ]
}
POST
/v1/volume/connectors

Create Volume Connector

Creates a new Volume connector resource.

This method requires a Node UUID, a connector type and a connector ID.

Normal response code: 201

Error codes: 400,401,403,404,409

Request

Name

In

Type

Description

node_uuid

body

string

UUID of the Node this resource belongs to.

type

body

string

The type of Volume connector such as “iqn”, “ip”, “wwnn” and “wwpn”.

connector_id

body

string

The identifier of Volume connector. The identifier format depends on the type of the Volume connector, eg “iqn.2017-05.org.openstack:01:d9a51732c3f” if the type is “iqn”, “192.168.1.2” if the type is “ip”.

extra (Optional)

body

object

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

uuid (Optional)

body

string

The UUID for the resource.

Example Volume connector creation request:

{
    "node_uuid": "6d85703a-565d-469a-96ce-30b6de53079d",
    "type": "iqn",
    "connector_id": "iqn.2017-07.org.openstack:01:d9a51732c3f"
}

Response

Name

In

Type

Description

uuid

body

string

The UUID for the resource.

type

body

string

The type of Volume connector such as “iqn”, “ip”, “wwnn” and “wwpn”.

connector_id

body

string

The identifier of Volume connector. The identifier format depends on the type of the Volume connector, eg “iqn.2017-05.org.openstack:01:d9a51732c3f” if the type is “iqn”, “192.168.1.2” if the type is “ip”.

node_uuid

body

string

UUID of the Node this resource belongs to.

extra

body

object

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

links

body

array

A list of relative links. Includes the self and bookmark links.

Example Volume connector creation response:

{
  "connector_id": "iqn.2017-07.org.openstack:01:d9a51732c3f",
  "created_at": "2016-08-18T22:28:48.643434+11:11",
  "extra": {},
  "links": [
    {
      "href": "http://127.0.0.1:6385/v1/volume/connectors/9bf93e01-d728-47a3-ad4b-5e66a835037c",
      "rel": "self"
    },
    {
      "href": "http://127.0.0.1:6385/volume/connectors/9bf93e01-d728-47a3-ad4b-5e66a835037c",
      "rel": "bookmark"
    }
  ],
  "node_uuid": "6d85703a-565d-469a-96ce-30b6de53079d",
  "type": "iqn",
  "updated_at": null,
  "uuid": "9bf93e01-d728-47a3-ad4b-5e66a835037c"
}
GET
/v1/volume/connectors/{volume_connector_id}

Show Volume Connector Details

Show details for the given Volume connector.

Normal response code: 200

Error codes: 400,401,403,404

Request

Name

In

Type

Description

volume_connector_id

path

string

The UUID of the Volume connector.

fields (Optional)

query

array

One or more fields to be returned in the response.

For example, the following request returns only the uuid and name fields for each node:

GET /v1/nodes?fields=uuid,name

Response

Name

In

Type

Description

uuid

body

string

The UUID for the resource.

type

body

string

The type of Volume connector such as “iqn”, “ip”, “wwnn” and “wwpn”.

connector_id

body

string

The identifier of Volume connector. The identifier format depends on the type of the Volume connector, eg “iqn.2017-05.org.openstack:01:d9a51732c3f” if the type is “iqn”, “192.168.1.2” if the type is “ip”.

node_uuid

body

string

UUID of the Node this resource belongs to.

extra

body

object

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

links

body

array

A list of relative links. Includes the self and bookmark links.

Example Volume connector details:

{
  "connector_id": "iqn.2017-07.org.openstack:01:d9a51732c3f",
  "created_at": "2016-08-18T22:28:48.643434+11:11",
  "extra": {},
  "links": [
    {
      "href": "http://127.0.0.1:6385/v1/volume/connectors/9bf93e01-d728-47a3-ad4b-5e66a835037c",
      "rel": "self"
    },
    {
      "href": "http://127.0.0.1:6385/volume/connectors/9bf93e01-d728-47a3-ad4b-5e66a835037c",
      "rel": "bookmark"
    }
  ],
  "node_uuid": "6d85703a-565d-469a-96ce-30b6de53079d",
  "type": "iqn",
  "updated_at": null,
  "uuid": "9bf93e01-d728-47a3-ad4b-5e66a835037c"
}
PATCH
/v1/volume/connectors/{volume_connector_id}

Update a Volume Connector

Update a Volume connector.

A Volume connector can be updated only while a node associated with the Volume connector is powered off.

Normal response code: 200

Error codes: 400,401,403,404,409

Request

The BODY of the PATCH request must be a JSON PATCH document, adhering to RFC 6902.

Name

In

Type

Description

volume_connector_id

path

string

The UUID of the Volume connector.

Example Volume connector update request:

[
   {
      "path" : "/connector_id",
      "value" : "iqn.2017-07.org.openstack:02:10190a4153e",
      "op" : "replace"
   }
]

Response

Name

In

Type

Description

uuid

body

string

The UUID for the resource.

type

body

string

The type of Volume connector such as “iqn”, “ip”, “wwnn” and “wwpn”.

connector_id

body

string

The identifier of Volume connector. The identifier format depends on the type of the Volume connector, eg “iqn.2017-05.org.openstack:01:d9a51732c3f” if the type is “iqn”, “192.168.1.2” if the type is “ip”.

node_uuid

body

string

UUID of the Node this resource belongs to.

extra

body

object

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

links

body

array

A list of relative links. Includes the self and bookmark links.

Example Volume connector update response:

{
  "connector_id": "iqn.2017-07.org.openstack:02:10190a4153e",
  "created_at": "2016-08-18T22:28:48.643434+11:11",
  "extra": {},
  "links": [
    {
      "href": "http://127.0.0.1:6385/v1/volume/connectors/9bf93e01-d728-47a3-ad4b-5e66a835037c",
      "rel": "self"
    },
    {
      "href": "http://127.0.0.1:6385/volume/connectors/9bf93e01-d728-47a3-ad4b-5e66a835037c",
      "rel": "bookmark"
    }
  ],
  "node_uuid": "6d85703a-565d-469a-96ce-30b6de53079d",
  "type": "iqn",
  "updated_at": "2016-08-18T22:28:49.653974+00:00",
  "uuid": "9bf93e01-d728-47a3-ad4b-5e66a835037c"
}
DELETE
/v1/volume/connector/{volume_connector_id}

Delete Volume Connector

Delete a Volume connector.

A Volume connector can be deleted only while a node associated with the Volume connector is powered off.

Normal response code: 204

Error codes: 400,401,403,404,409

Request

Name

In

Type

Description

volume_connector_id

path

string

The UUID of the Volume connector.

GET
/v1/volume/targets

List Volume Targets

Return a list of Volume targets for all nodes.

By default, this query will return the UUID, node UUID, volume type, boot index, and volume ID for each Volume target.

Normal response code: 200

Error codes: 400,401,403,404

Request

Name

In

Type

Description

node (Optional)

query

string

Filter the list of returned Volume targets, and only return the ones associated with this specific node (name or UUID), or an empty set if not found.

fields (Optional)

query

array

One or more fields to be returned in the response.

For example, the following request returns only the uuid and name fields for each node:

GET /v1/nodes?fields=uuid,name

detail (Optional)

query

boolean

Whether to show detailed information about the resource. This cannot be set to True if fields parameter is specified.

limit (Optional)

query

integer

Requests a page size of items. Returns a number of items up to a limit value. Use the limit parameter to make an initial limited request and use the ID of the last-seen item from the response as the marker parameter value in a subsequent limited request. This value cannot be larger than the max_limit option in the [api] section of the configuration. If it is higher than max_limit, only max-limit resources will be returned.

marker (Optional)

query

string

The ID of the last-seen item. Use the limit parameter to make an initial limited request and use the ID of the last-seen item from the response as the marker parameter value in a subsequent limited request.

sort_dir (Optional)

query

string

Sorts the response by the requested sort direction. A valid value is asc (ascending) or desc (descending). Default is asc. You can specify multiple pairs of sort key and sort direction query parameters. If you omit the sort direction in a pair, the API uses the natural sorting direction of the server attribute that is provided as the sort_key.

sort_key (Optional)

query

string

Sorts the response by this attribute value. Default is id. You can specify multiple pairs of sort key and sort direction query parameters. If you omit the sort direction in a pair, the API uses the natural sorting direction of the server attribute that is provided as the sort_key.

Response

Name

In

Type

Description

targets

body

array

A collection of Volume target resources.

uuid

body

string

The UUID for the resource.

volume_type

body

string

The type of Volume target such as ‘iscsi’ and ‘fibre_channel’.

properties

body

object

A set of physical information of the volume such as the identifier (eg. IQN) and LUN number of the volume. This information is used to connect the node to the volume by the storage interface. The contents depend on the volume type.

boot_index

body

string

The boot index of the Volume target. “0” indicates that this volume is used as a boot volume.

volume_id

body

string

The identifier of the volume. This ID is used by storage interface to distinguish volumes.

extra

body

object

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

node_uuid

body

string

UUID of the Node this resource belongs to.

links

body

array

A list of relative links. Includes the self and bookmark links.

next (Optional)

body

string

A URL to request a next collection of the resource. This parameter is returned when limit is specified in a request and there remain items.

Example Volume target list response:

{
  "targets": [
    {
      "boot_index": 0,
      "links": [
        {
          "href": "http://127.0.0.1:6385/v1/volume/targets/bd4d008c-7d31-463d-abf9-6c23d9d55f7f",
          "rel": "self"
        },
        {
          "href": "http://127.0.0.1:6385/volume/targets/bd4d008c-7d31-463d-abf9-6c23d9d55f7f",
          "rel": "bookmark"
        }
      ],
      "node_uuid": "6d85703a-565d-469a-96ce-30b6de53079d",
      "uuid": "bd4d008c-7d31-463d-abf9-6c23d9d55f7f",
      "volume_id": "04452bed-5367-4202-8bf5-de4335ac56d2",
      "volume_type": "iscsi"
    }
  ]
}

Example detailed Volume target list response:

{
  "targets": [
    {
      "boot_index": 0,
      "created_at": "2016-08-18T22:28:48.643434+11:11",
      "extra": {},
      "links": [
        {
          "href": "http://127.0.0.1:6385/v1/volume/targets/bd4d008c-7d31-463d-abf9-6c23d9d55f7f",
          "rel": "self"
        },
        {
          "href": "http://127.0.0.1:6385/volume/targets/bd4d008c-7d31-463d-abf9-6c23d9d55f7f",
          "rel": "bookmark"
        }
      ],
      "node_uuid": "6d85703a-565d-469a-96ce-30b6de53079d",
      "properties": {},
      "updated_at": null,
      "uuid": "bd4d008c-7d31-463d-abf9-6c23d9d55f7f",
      "volume_id": "04452bed-5367-4202-8bf5-de4335ac56d2",
      "volume_type": "iscsi"
    }
  ]
}
POST
/v1/volume/targets

Create Volume Target

Creates a new Volume target resource.

This method requires a Node UUID, volume type, volume ID, and boot index..

Normal response code: 201

Error codes: 400,401,403,404,409

Request

Name

In

Type

Description

node_uuid

body

string

UUID of the Node this resource belongs to.

volume_type

body

string

The type of Volume target such as ‘iscsi’ and ‘fibre_channel’.

properties (Optional)

body

object

A set of physical information of the volume such as the identifier (eg. IQN) and LUN number of the volume. This information is used to connect the node to the volume by the storage interface. The contents depend on the volume type.

boot_index

body

string

The boot index of the Volume target. “0” indicates that this volume is used as a boot volume.

volume_id

body

string

The identifier of the volume. This ID is used by storage interface to distinguish volumes.

extra (Optional)

body

object

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

uuid (Optional)

body

string

The UUID for the resource.

Example Volume target creation request:

{
    "node_uuid": "6d85703a-565d-469a-96ce-30b6de53079d",
    "volume_type": "iscsi",
    "boot_index": 0,
    "volume_id": "04452bed-5367-4202-8bf5-de4335ac56d2"
}

Response

Name

In

Type

Description

uuid

body

string

The UUID for the resource.

volume_type

body

string

The type of Volume target such as ‘iscsi’ and ‘fibre_channel’.

properties

body

object

A set of physical information of the volume such as the identifier (eg. IQN) and LUN number of the volume. This information is used to connect the node to the volume by the storage interface. The contents depend on the volume type.

boot_index

body

string

The boot index of the Volume target. “0” indicates that this volume is used as a boot volume.

volume_id

body

string

The identifier of the volume. This ID is used by storage interface to distinguish volumes.

extra

body

object

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

node_uuid

body

string

UUID of the Node this resource belongs to.

links

body

array

A list of relative links. Includes the self and bookmark links.

Example Volume target creation response:

{
  "boot_index": 0,
  "created_at": "2016-08-18T22:28:48.643434+11:11",
  "extra": {},
  "links": [
    {
      "href": "http://127.0.0.1:6385/v1/volume/targets/bd4d008c-7d31-463d-abf9-6c23d9d55f7f",
      "rel": "self"
    },
    {
      "href": "http://127.0.0.1:6385/volume/targets/bd4d008c-7d31-463d-abf9-6c23d9d55f7f",
      "rel": "bookmark"
    }
  ],
  "node_uuid": "6d85703a-565d-469a-96ce-30b6de53079d",
  "properties": {},
  "updated_at": null,
  "uuid": "bd4d008c-7d31-463d-abf9-6c23d9d55f7f",
  "volume_id": "04452bed-5367-4202-8bf5-de4335ac56d2",
  "volume_type": "iscsi"
}
GET
/v1/volume/targets/{volume_target_id}

Show Volume Target Details

Show details for the given Volume target.

Normal response code: 200

Error codes: 400,401,403,404

Request

Name

In

Type

Description

volume_target_id

path

string

The UUID of the Volume target.

fields (Optional)

query

array

One or more fields to be returned in the response.

For example, the following request returns only the uuid and name fields for each node:

GET /v1/nodes?fields=uuid,name

Response

Name

In

Type

Description

uuid

body

string

The UUID for the resource.

volume_type

body

string

The type of Volume target such as ‘iscsi’ and ‘fibre_channel’.

properties

body

object

A set of physical information of the volume such as the identifier (eg. IQN) and LUN number of the volume. This information is used to connect the node to the volume by the storage interface. The contents depend on the volume type.

boot_index

body

string

The boot index of the Volume target. “0” indicates that this volume is used as a boot volume.

volume_id

body

string

The identifier of the volume. This ID is used by storage interface to distinguish volumes.

extra

body

object

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

node_uuid

body

string

UUID of the Node this resource belongs to.

links

body

array

A list of relative links. Includes the self and bookmark links.

Example Volume target details:

{
  "boot_index": 0,
  "created_at": "2016-08-18T22:28:48.643434+11:11",
  "extra": {},
  "links": [
    {
      "href": "http://127.0.0.1:6385/v1/volume/targets/bd4d008c-7d31-463d-abf9-6c23d9d55f7f",
      "rel": "self"
    },
    {
      "href": "http://127.0.0.1:6385/volume/targets/bd4d008c-7d31-463d-abf9-6c23d9d55f7f",
      "rel": "bookmark"
    }
  ],
  "node_uuid": "6d85703a-565d-469a-96ce-30b6de53079d",
  "properties": {},
  "updated_at": null,
  "uuid": "bd4d008c-7d31-463d-abf9-6c23d9d55f7f",
  "volume_id": "04452bed-5367-4202-8bf5-de4335ac56d2",
  "volume_type": "iscsi"
}
PATCH
/v1/volume/targets/{volume_target_id}

Update a Volume Target

Update a Volume target.

A Volume target can be updated only while a node associated with the Volume target is powered off.

Normal response code: 200

Error codes: 400,401,403,404,409

Request

The BODY of the PATCH request must be a JSON PATCH document, adhering to RFC 6902.

Name

In

Type

Description

volume_target_id

path

string

The UUID of the Volume target.

Example Volume target update request:

[
   {
      "path" : "/volume_id",
      "value" : "7211f7d3-3f32-4efc-b64e-9b8e92e64a8e",
      "op" : "replace"
   }
]

Response

Name

In

Type

Description

uuid

body

string

The UUID for the resource.

volume_type

body

string

The type of Volume target such as ‘iscsi’ and ‘fibre_channel’.

properties

body

object

A set of physical information of the volume such as the identifier (eg. IQN) and LUN number of the volume. This information is used to connect the node to the volume by the storage interface. The contents depend on the volume type.

boot_index

body

string

The boot index of the Volume target. “0” indicates that this volume is used as a boot volume.

volume_id

body

string

The identifier of the volume. This ID is used by storage interface to distinguish volumes.

extra

body

object

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

node_uuid

body

string

UUID of the Node this resource belongs to.

links

body

array

A list of relative links. Includes the self and bookmark links.

Example Volume target update response:

{
  "boot_index": 0,
  "created_at": "2016-08-18T22:28:48.643434+11:11",
  "extra": {},
  "links": [
    {
      "href": "http://127.0.0.1:6385/v1/volume/targets/bd4d008c-7d31-463d-abf9-6c23d9d55f7f",
      "rel": "self"
    },
    {
      "href": "http://127.0.0.1:6385/volume/targets/bd4d008c-7d31-463d-abf9-6c23d9d55f7f",
      "rel": "bookmark"
    }
  ],
  "node_uuid": "6d85703a-565d-469a-96ce-30b6de53079d",
  "properties": {},
  "updated_at": "2016-08-18T22:28:49.653974+00:00",
  "uuid": "bd4d008c-7d31-463d-abf9-6c23d9d55f7f",
  "volume_id": "7211f7d3-3f32-4efc-b64e-9b8e92e64a8e",
  "volume_type": "iscsi"
}
DELETE
/v1/volume/target/{volume_target_id}

Delete Volume Target

Delete a Volume target.

A Volume target can be deleted only while a node associated with the Volume target is powered off.

Normal response code: 204

Error codes: 400,401,403,404,409

Request

Name

In

Type

Description

volume_target_id

path

string

The UUID of the Volume target.

Listing Volume resources by Node (nodes, volume)

New in version 1.32.

Given a Node identifier (uuid or name), the API exposes the list of, and details of, all Volume resources associated with that Node.

These endpoints do not allow modification of the Volume connectors and Volume targets; that should be done by accessing the Volume resources under the /v1/volume/connectors and /v1/volume/targets endpoint.

GET
/v1/nodes/{node_ident}/volume/connectors

List Volume connectors by Node

Return a list of bare metal Volume connectors associated with node_ident.

Normal response code: 200

Error codes: 400,401,403,404

Request

Name

In

Type

Description

node_ident

path

string

The UUID or Name of the node.

fields (Optional)

query

array

One or more fields to be returned in the response.

For example, the following request returns only the uuid and name fields for each node:

GET /v1/nodes?fields=uuid,name

limit (Optional)

query

integer

Requests a page size of items. Returns a number of items up to a limit value. Use the limit parameter to make an initial limited request and use the ID of the last-seen item from the response as the marker parameter value in a subsequent limited request. This value cannot be larger than the max_limit option in the [api] section of the configuration. If it is higher than max_limit, only max-limit resources will be returned.

marker (Optional)

query

string

The ID of the last-seen item. Use the limit parameter to make an initial limited request and use the ID of the last-seen item from the response as the marker parameter value in a subsequent limited request.

sort_dir (Optional)

query

string

Sorts the response by the requested sort direction. A valid value is asc (ascending) or desc (descending). Default is asc. You can specify multiple pairs of sort key and sort direction query parameters. If you omit the sort direction in a pair, the API uses the natural sorting direction of the server attribute that is provided as the sort_key.

sort_key (Optional)

query

string

Sorts the response by this attribute value. Default is id. You can specify multiple pairs of sort key and sort direction query parameters. If you omit the sort direction in a pair, the API uses the natural sorting direction of the server attribute that is provided as the sort_key.

Response

Name

In

Type

Description

connectors

body

array

A collection of Volume connector resources.

uuid

body

string

The UUID for the resource.

type

body

string

The type of Volume connector such as “iqn”, “ip”, “wwnn” and “wwpn”.

connector_id

body

string

The identifier of Volume connector. The identifier format depends on the type of the Volume connector, eg “iqn.2017-05.org.openstack:01:d9a51732c3f” if the type is “iqn”, “192.168.1.2” if the type is “ip”.

node_uuid

body

string

UUID of the Node this resource belongs to.

extra

body

object

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

links

body

array

A list of relative links. Includes the self and bookmark links.

next (Optional)

body

string

A URL to request a next collection of the resource. This parameter is returned when limit is specified in a request and there remain items.

Example list of Node’s Volume connectors:

{
  "connectors": [
    {
      "connector_id": "iqn.2017-07.org.openstack:02:10190a4153e",
      "links": [
        {
          "href": "http://127.0.0.1:6385/v1/volume/connectors/9bf93e01-d728-47a3-ad4b-5e66a835037c",
          "rel": "self"
        },
        {
          "href": "http://127.0.0.1:6385/volume/connectors/9bf93e01-d728-47a3-ad4b-5e66a835037c",
          "rel": "bookmark"
        }
      ],
      "node_uuid": "6d85703a-565d-469a-96ce-30b6de53079d",
      "type": "iqn",
      "uuid": "9bf93e01-d728-47a3-ad4b-5e66a835037c"
    }
  ]
}

Example detailed list of Node’s Volume connectors:

{
  "connectors": [
    {
      "connector_id": "iqn.2017-07.org.openstack:02:10190a4153e",
      "created_at": "2016-08-18T22:28:48.643434+11:11",
      "extra": {},
      "links": [
        {
          "href": "http://127.0.0.1:6385/v1/volume/connectors/9bf93e01-d728-47a3-ad4b-5e66a835037c",
          "rel": "self"
        },
        {
          "href": "http://127.0.0.1:6385/volume/connectors/9bf93e01-d728-47a3-ad4b-5e66a835037c",
          "rel": "bookmark"
        }
      ],
      "node_uuid": "6d85703a-565d-469a-96ce-30b6de53079d",
      "type": "iqn",
      "updated_at": "2016-08-18T22:28:49.653974+00:00",
      "uuid": "9bf93e01-d728-47a3-ad4b-5e66a835037c"
    }
  ]
}
GET
/v1/nodes/{node_ident}/volume/targets

List Volume targets by Node

Return a list of bare metal Volume targets associated with node_ident.

Normal response code: 200

Error codes: 400,401,403,404

Request

Name

In

Type

Description

node_ident

path

string

The UUID or Name of the node.

fields (Optional)

query

array

One or more fields to be returned in the response.

For example, the following request returns only the uuid and name fields for each node:

GET /v1/nodes?fields=uuid,name

limit (Optional)

query

integer

Requests a page size of items. Returns a number of items up to a limit value. Use the limit parameter to make an initial limited request and use the ID of the last-seen item from the response as the marker parameter value in a subsequent limited request. This value cannot be larger than the max_limit option in the [api] section of the configuration. If it is higher than max_limit, only max-limit resources will be returned.

marker (Optional)

query

string

The ID of the last-seen item. Use the limit parameter to make an initial limited request and use the ID of the last-seen item from the response as the marker parameter value in a subsequent limited request.

sort_dir (Optional)

query

string

Sorts the response by the requested sort direction. A valid value is asc (ascending) or desc (descending). Default is asc. You can specify multiple pairs of sort key and sort direction query parameters. If you omit the sort direction in a pair, the API uses the natural sorting direction of the server attribute that is provided as the sort_key.

sort_key (Optional)

query

string

Sorts the response by this attribute value. Default is id. You can specify multiple pairs of sort key and sort direction query parameters. If you omit the sort direction in a pair, the API uses the natural sorting direction of the server attribute that is provided as the sort_key.

Response

Name

In

Type

Description

targets

body

array

A collection of Volume target resources.

uuid

body

string

The UUID for the resource.

volume_type

body

string

The type of Volume target such as ‘iscsi’ and ‘fibre_channel’.

properties

body

object

A set of physical information of the volume such as the identifier (eg. IQN) and LUN number of the volume. This information is used to connect the node to the volume by the storage interface. The contents depend on the volume type.

boot_index

body

string

The boot index of the Volume target. “0” indicates that this volume is used as a boot volume.

volume_id

body

string

The identifier of the volume. This ID is used by storage interface to distinguish volumes.

extra

body

object

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

node_uuid

body

string

UUID of the Node this resource belongs to.

links

body

array

A list of relative links. Includes the self and bookmark links.

next (Optional)

body

string

A URL to request a next collection of the resource. This parameter is returned when limit is specified in a request and there remain items.

Example list of Node’s Volume targets:

{
  "targets": [
    {
      "boot_index": 0,
      "links": [
        {
          "href": "http://127.0.0.1:6385/v1/volume/targets/bd4d008c-7d31-463d-abf9-6c23d9d55f7f",
          "rel": "self"
        },
        {
          "href": "http://127.0.0.1:6385/volume/targets/bd4d008c-7d31-463d-abf9-6c23d9d55f7f",
          "rel": "bookmark"
        }
      ],
      "node_uuid": "6d85703a-565d-469a-96ce-30b6de53079d",
      "uuid": "bd4d008c-7d31-463d-abf9-6c23d9d55f7f",
      "volume_id": "7211f7d3-3f32-4efc-b64e-9b8e92e64a8e",
      "volume_type": "iscsi"
    }
  ]
}

Example detailed list of Node’s Volume targets:

{
  "targets": [
    {
      "boot_index": 0,
      "created_at": "2016-08-18T22:28:48.643434+11:11",
      "extra": {},
      "links": [
        {
          "href": "http://127.0.0.1:6385/v1/volume/targets/bd4d008c-7d31-463d-abf9-6c23d9d55f7f",
          "rel": "self"
        },
        {
          "href": "http://127.0.0.1:6385/volume/targets/bd4d008c-7d31-463d-abf9-6c23d9d55f7f",
          "rel": "bookmark"
        }
      ],
      "node_uuid": "6d85703a-565d-469a-96ce-30b6de53079d",
      "properties": {},
      "updated_at": "2016-08-18T22:28:49.653974+00:00",
      "uuid": "bd4d008c-7d31-463d-abf9-6c23d9d55f7f",
      "volume_id": "7211f7d3-3f32-4efc-b64e-9b8e92e64a8e",
      "volume_type": "iscsi"
    }
  ]
}

Drivers (drivers)

Changed in version 1.30: The REST API now also exposes information about dynamic drivers.

Ironic has two types of drivers: classic drivers and dynamic drivers.

A classic driver is a Python object containing all the logic to manage the bare metal nodes enrolled within Ironic. A driver may be loaded within one or more ironic-conductor services. Each driver contains a pre-determined set of instantiated interfaces. Each type of interface (eg, power or boot) performs a specific hardware function.

Dynamic drivers are supported via hardware types, which are Python classes enabled via entry points. Unlike classic drivers, which have pre-determined interfaces, a hardware type may support multiple types of interfaces. For example, the ipmi hardware type may support multiple methods for enabling node console. Which interface a node of a particular hardware type uses is determined at runtime. This collection of interfaces is called a dynamic driver. For more information about this, see the node API documentation.

The REST API exposes the list of drivers and which ironic-conductor processes have loaded that driver via the Driver resource (/v1/drivers endpoint). This can be useful for operators to validate their configuration in a heterogeneous hardware environment. Each ironic-conductor process may load one or more drivers, and does not necessarily need to load the same classic drivers as another ironic-conductor. Each ironic-conductor with the same hardware types must have the same hardware interfaces enabled.

The REST API also exposes details about each driver, such as what properties must be supplied to a node’s driver_info for that driver to manage hardware.

Lastly, some drivers may expose methods through a driver_vendor_passthru endpoint, allowing one to interact with the driver directly (i.e., without knowing a specific node identifier). For example, this is used by the ironic python agent ramdisk to get the UUID of the node being deployed/cleaned by using MAC addresses of the node’s network interfaces the agent has discovered.

GET
/v1/drivers

List drivers

Lists all drivers.

New in version 1.77: Added fields selector to query for particular fields.

Normal response codes: 200

Request

Name

In

Type

Description

type (Optional)

query

string

Only list drivers of this type. Options are “classic” or “dynamic”.

detail (Optional)

query

boolean

Whether to show detailed information about the drivers (e.g. the “boot_interface” field).

fields (Optional)

query

array

One or more fields to be returned in the response.

For example, the following request returns only the uuid and name fields for each node:

GET /v1/nodes?fields=uuid,name

Response Parameters

The response BODY contains a single key, “drivers”, whose value is a list of drivers supported by this Ironic service.

Name

In

Type

Description

drivers

body

array

A list of driver objects.

name

body

string

The name of the driver.

hosts

body

array

A list of active hosts that support this driver.

type

body

string

Type of this driver (“classic” or “dynamic”).

links

body

array

A list of relative links. Includes the self and bookmark links.

properties

body

array

A list of links to driver properties.

Changed in version 1.30: If the request has the “detail” URL parameter set to true, each driver will also include the following fields.

New in version 1.86: Introduced the default_firmware_interface and enabled_firmware_interfaces fields.

Name

In

Type

Description

default_bios_interface

body

string

The default bios interface used for a node with a dynamic driver, if no bios interface is specified for the node.

default_boot_interface

body

string

The default boot interface used for a node with a dynamic driver, if no boot interface is specified for the node.

default_console_interface

body

string

The default console interface used for a node with a dynamic driver, if no console interface is specified for the node.

default_deploy_interface

body

string

The default deploy interface used for a node with a dynamic driver, if no deploy interface is specified for the node.

default_firmware_interface

body

string

The default firmware interface used for a node with a dynamic driver, if no firmware interface is specified for the node.

default_inspect_interface

body

string

The default inspection interface used for a node with a dynamic driver, if no inspection interface is specified for the node.

default_management_interface

body

string

The default management interface used for a node with a dynamic driver, if no management interface is specified for the node.

default_network_interface

body

string

The default network interface used for a node with a dynamic driver, if no network interface is specified for the node.

default_power_interface

body

string

The default power interface used for a node with a dynamic driver, if no power interface is specified for the node.

default_raid_interface

body

string

The default RAID interface used for a node with a dynamic driver, if no RAID interface is specified for the node.

default_rescue_interface

body

string

The default rescue interface used for a node with a dynamic driver, if no rescue interface is specified for the node.

default_storage_interface

body

string

The default storage interface used for a node with a dynamic driver, if no storage interface is specified for the node.

default_vendor_interface

body

string

The default vendor interface used for a node with a dynamic driver, if no vendor interface is specified for the node.

enabled_bios_interfaces

body

list

The enabled bios interfaces for this driver.

enabled_boot_interfaces

body

list

The enabled boot interfaces for this driver.

enabled_console_interfaces

body

list

The enabled console interfaces for this driver.

enabled_deploy_interfaces

body

list

The enabled deploy interfaces for this driver.

enabled_firmware_interfaces

body

list

The enabled firmware interfaces for this driver.

enabled_inspect_interfaces

body

list

The enabled inspection interfaces for this driver.

enabled_management_interfaces

body

list

The enabled management interfaces for this driver.

enabled_network_interfaces

body

list

The enabled network interfaces for this driver.

enabled_power_interfaces

body

list

The enabled power interfaces for this driver.

enabled_rescue_interfaces

body

list

The enabled rescue interfaces for this driver.

enabled_raid_interfaces

body

list

The enabled RAID interfaces for this driver.

enabled_storage_interfaces

body

list

The enabled storage interfaces for this driver.

enabled_vendor_interfaces

body

list

The enabled vendor interfaces for this driver.

Response Example

Example for a request with detail=false (the default):

{
  "drivers": [
    {
      "hosts": [
        "897ab1dad809"
      ],
      "links": [
        {
          "href": "http://127.0.0.1:6385/v1/drivers/agent_ipmitool",
          "rel": "self"
        },
        {
          "href": "http://127.0.0.1:6385/drivers/agent_ipmitool",
          "rel": "bookmark"
        }
      ],
      "name": "agent_ipmitool",
      "properties": [
        {
          "href": "http://127.0.0.1:6385/v1/drivers/agent_ipmitool/properties",
          "rel": "self"
        },
        {
          "href": "http://127.0.0.1:6385/drivers/agent_ipmitool/properties",
          "rel": "bookmark"
        }
      ],
      "type": "classic"
    },
    {
      "hosts": [
        "897ab1dad809"
      ],
      "links": [
        {
          "href": "http://127.0.0.1:6385/v1/drivers/fake",
          "rel": "self"
        },
        {
          "href": "http://127.0.0.1:6385/drivers/fake",
          "rel": "bookmark"
        }
      ],
      "name": "fake",
      "properties": [
        {
          "href": "http://127.0.0.1:6385/v1/drivers/fake/properties",
          "rel": "self"
        },
        {
          "href": "http://127.0.0.1:6385/drivers/fake/properties",
          "rel": "bookmark"
        }
      ],
      "type": "classic"
    },
    {
      "hosts": [
        "897ab1dad809"
      ],
      "links": [
        {
          "href": "http://127.0.0.1:6385/v1/drivers/ipmi",
          "rel": "self"
        },
        {
          "href": "http://127.0.0.1:6385/drivers/ipmi",
          "rel": "bookmark"
        }
      ],
      "name": "ipmi",
      "properties": [
        {
          "href": "http://127.0.0.1:6385/v1/drivers/ipmi/properties",
          "rel": "self"
        },
        {
          "href": "http://127.0.0.1:6385/drivers/ipmi/properties",
          "rel": "bookmark"
        }
      ],
      "type": "dynamic"
    }
  ]
}

Example for a request with detail=true:

{
  "drivers": [
    {
      "default_bios_interface": null,
      "default_boot_interface": null,
      "default_console_interface": null,
      "default_deploy_interface": null,
      "default_firmware_interface": null,
      "default_inspect_interface": null,
      "default_management_interface": null,
      "default_network_interface": null,
      "default_power_interface": null,
      "default_raid_interface": null,
      "default_rescue_interface": null,
      "default_storage_interface": null,
      "default_vendor_interface": null,
      "enabled_bios_interfaces": null,
      "enabled_boot_interfaces": null,
      "enabled_console_interfaces": null,
      "enabled_deploy_interfaces": null,
      "enabled_firmware_interfaces": null,
      "enabled_inspect_interfaces": null,
      "enabled_management_interfaces": null,
      "enabled_network_interfaces": null,
      "enabled_power_interfaces": null,
      "enabled_raid_interfaces": null,
      "enabled_rescue_interfaces": null,
      "enabled_storage_interfaces": null,
      "enabled_vendor_interfaces": null,
      "hosts": [
        "897ab1dad809"
      ],
      "links": [
        {
          "href": "http://127.0.0.1:6385/v1/drivers/agent_ipmitool",
          "rel": "self"
        },
        {
          "href": "http://127.0.0.1:6385/drivers/agent_ipmitool",
          "rel": "bookmark"
        }
      ],
      "name": "agent_ipmitool",
      "properties": [
        {
          "href": "http://127.0.0.1:6385/v1/drivers/agent_ipmitool/properties",
          "rel": "self"
        },
        {
          "href": "http://127.0.0.1:6385/drivers/agent_ipmitool/properties",
          "rel": "bookmark"
        }
      ],
      "type": "classic"
    },
    {
      "default_bios_interface": null,
      "default_boot_interface": null,
      "default_console_interface": null,
      "default_deploy_interface": null,
      "default_firmware_interface": null,
      "default_inspect_interface": null,
      "default_management_interface": null,
      "default_network_interface": null,
      "default_power_interface": null,
      "default_raid_interface": null,
      "default_rescue_interface": null,
      "default_storage_interface": null,
      "default_vendor_interface": null,
      "enabled_bios_interfaces": null,
      "enabled_boot_interfaces": null,
      "enabled_console_interfaces": null,
      "enabled_deploy_interfaces": null,
      "enabled_firmware_interfaces": null,
      "enabled_inspect_interfaces": null,
      "enabled_management_interfaces": null,
      "enabled_network_interfaces": null,
      "enabled_power_interfaces": null,
      "enabled_raid_interfaces": null,
      "enabled_rescue_interfaces": null,
      "enabled_storage_interfaces": null,
      "enabled_vendor_interfaces": null,
      "hosts": [
        "897ab1dad809"
      ],
      "links": [
        {
          "href": "http://127.0.0.1:6385/v1/drivers/fake",
          "rel": "self"
        },
        {
          "href": "http://127.0.0.1:6385/drivers/fake",
          "rel": "bookmark"
        }
      ],
      "name": "fake",
      "properties": [
        {
          "href": "http://127.0.0.1:6385/v1/drivers/fake/properties",
          "rel": "self"
        },
        {
          "href": "http://127.0.0.1:6385/drivers/fake/properties",
          "rel": "bookmark"
        }
      ],
      "type": "classic"
    },
    {
      "default_bios_interface": "no-bios",
      "default_boot_interface": "pxe",
      "default_console_interface": "no-console",
      "default_deploy_interface": "direct",
      "default_firmware_interface": "no-firmware",
      "default_inspect_interface": "no-inspect",
      "default_management_interface": "ipmitool",
      "default_network_interface": "flat",
      "default_power_interface": "ipmitool",
      "default_raid_interface": "no-raid",
      "default_rescue_interface": "no-rescue",
      "default_storage_interface": "noop",
      "default_vendor_interface": "no-vendor",
      "enabled_bios_interfaces": [
        "no-bios"
      ],
      "enabled_boot_interfaces": [
        "pxe"
      ],
      "enabled_console_interfaces": [
        "no-console"
      ],
      "enabled_deploy_interfaces": [
        "ansible",
        "direct"
      ],
      "enabled_firmware_interface": [
        "no-firmware"
      ],
      "enabled_inspect_interfaces": [
        "no-inspect"
      ],
      "enabled_management_interfaces": [
        "ipmitool"
      ],
      "enabled_network_interfaces": [
        "flat",
        "noop"
      ],
      "enabled_power_interfaces": [
        "ipmitool"
      ],
      "enabled_raid_interfaces": [
        "no-raid",
        "agent"
      ],
      "enabled_rescue_interfaces": [
        "no-rescue"
      ],
      "enabled_storage_interfaces": [
        "noop"
      ],
      "enabled_vendor_interfaces": [
        "no-vendor"
      ],
      "hosts": [
        "897ab1dad809"
      ],
      "links": [
        {
          "href": "http://127.0.0.1:6385/v1/drivers/ipmi",
          "rel": "self"
        },
        {
          "href": "http://127.0.0.1:6385/drivers/ipmi",
          "rel": "bookmark"
        }
      ],
      "name": "ipmi",
      "properties": [
        {
          "href": "http://127.0.0.1:6385/v1/drivers/ipmi/properties",
          "rel": "self"
        },
        {
          "href": "http://127.0.0.1:6385/drivers/ipmi/properties",
          "rel": "bookmark"
        }
      ],
      "type": "dynamic"
    }
  ]
}
GET
/v1/drivers/{driver_name}

Show driver details

Shows details for a driver.

New in version 1.77: Added fields selector to query for particular fields.

New in version 1.86: Introduced the default_firmware_interface and enabled_firmware_interfaces fields.

Normal response codes: 200

Request

Name

In

Type

Description

driver_name

path

string

The name of the driver.

fields (Optional)

query

array

One or more fields to be returned in the response.

For example, the following request returns only the uuid and name fields for each node:

GET /v1/nodes?fields=uuid,name

Response Parameters

Name

In

Type

Description

name

body

string

The name of the driver.

hosts

body

array

A list of active hosts that support this driver.

type

body

string

Type of this driver (“classic” or “dynamic”).

default_bios_interface

body

string

The default bios interface used for a node with a dynamic driver, if no bios interface is specified for the node.

default_boot_interface

body

string

The default boot interface used for a node with a dynamic driver, if no boot interface is specified for the node.

default_console_interface

body

string

The default console interface used for a node with a dynamic driver, if no console interface is specified for the node.

default_deploy_interface

body

string

The default deploy interface used for a node with a dynamic driver, if no deploy interface is specified for the node.

default_firmware_interface

body

string

The default firmware interface used for a node with a dynamic driver, if no firmware interface is specified for the node.

default_inspect_interface

body

string

The default inspection interface used for a node with a dynamic driver, if no inspection interface is specified for the node.

default_management_interface

body

string

The default management interface used for a node with a dynamic driver, if no management interface is specified for the node.

default_network_interface

body

string

The default network interface used for a node with a dynamic driver, if no network interface is specified for the node.

default_power_interface

body

string

The default power interface used for a node with a dynamic driver, if no power interface is specified for the node.

default_raid_interface

body

string

The default RAID interface used for a node with a dynamic driver, if no RAID interface is specified for the node.

default_rescue_interface

body

string

The default rescue interface used for a node with a dynamic driver, if no rescue interface is specified for the node.

default_storage_interface

body

string

The default storage interface used for a node with a dynamic driver, if no storage interface is specified for the node.

default_vendor_interface

body

string

The default vendor interface used for a node with a dynamic driver, if no vendor interface is specified for the node.

enabled_bios_interfaces

body

list

The enabled bios interfaces for this driver.

enabled_boot_interfaces

body

list

The enabled boot interfaces for this driver.

enabled_console_interfaces

body

list

The enabled console interfaces for this driver.

enabled_deploy_interfaces

body

list

The enabled deploy interfaces for this driver.

enabled_firmware_interfaces

body

list

The enabled firmware interfaces for this driver.

enabled_inspect_interfaces

body

list

The enabled inspection interfaces for this driver.

enabled_management_interfaces

body

list

The enabled management interfaces for this driver.

enabled_network_interfaces

body

list

The enabled network interfaces for this driver.

enabled_power_interfaces

body

list

The enabled power interfaces for this driver.

enabled_raid_interfaces

body

list

The enabled RAID interfaces for this driver.

enabled_rescue_interfaces

body

list

The enabled rescue interfaces for this driver.

enabled_storage_interfaces

body

list

The enabled storage interfaces for this driver.

enabled_vendor_interfaces

body

list

The enabled vendor interfaces for this driver.

links

body

array

A list of relative links. Includes the self and bookmark links.

properties

body

array

A list of links to driver properties.

Response Example

{
  "default_bios_interface": "no-bios",
  "default_boot_interface": "pxe",
  "default_console_interface": "no-console",
  "default_deploy_interface": "direct",
  "default_firmware_interface": "no-firmware",
  "default_inspect_interface": "no-inspect",
  "default_management_interface": "ipmitool",
  "default_network_interface": "flat",
  "default_power_interface": "ipmitool",
  "default_raid_interface": "no-raid",
  "default_rescue_interface": "no-rescue",
  "default_storage_interface": "noop",
  "default_vendor_interface": "no-vendor",
  "enabled_bios_interfaces": [
    "no-bios"
  ],
  "enabled_boot_interfaces": [
    "pxe"
  ],
  "enabled_console_interfaces": [
    "no-console"
  ],
  "enabled_deploy_interfaces": [
    "ansible",
    "direct"
  ],
  "enabled_firmware_interface": [
    "no-firmware"
  ],
  "enabled_inspect_interfaces": [
    "no-inspect"
  ],
  "enabled_management_interfaces": [
    "ipmitool"
  ],
  "enabled_network_interfaces": [
    "flat",
    "noop"
  ],
  "enabled_power_interfaces": [
    "ipmitool"
  ],
  "enabled_raid_interfaces": [
    "no-raid",
    "agent"
  ],
  "enabled_rescue_interfaces": [
    "no-rescue"
  ],
  "enabled_storage_interfaces": [
    "noop"
  ],
  "enabled_vendor_interfaces": [
    "no-vendor"
  ],
  "hosts": [
    "897ab1dad809"
  ],
  "links": [
    {
      "href": "http://127.0.0.1:6385/v1/drivers/ipmi",
      "rel": "self"
    },
    {
      "href": "http://127.0.0.1:6385/drivers/ipmi",
      "rel": "bookmark"
    }
  ],
  "name": "ipmi",
  "properties": [
    {
      "href": "http://127.0.0.1:6385/v1/drivers/ipmi/properties",
      "rel": "self"
    },
    {
      "href": "http://127.0.0.1:6385/drivers/ipmi/properties",
      "rel": "bookmark"
    }
  ],
  "type": "dynamic"
}
GET
/v1/drivers/{driver_name}/properties

Show driver properties

Shows the required and optional parameters that driver_name expects to be supplied in the driver_info field for every Node it manages.

To check if all required parameters have been supplied to a Node, you should query the /v1/nodes/{node_ident}/validate endpoint.

Normal response codes: 200

Request

Name

In

Type

Description

driver_name

path

string

The name of the driver.

Response Example

The response BODY is a dictionary, but the keys are unique to each driver. The structure of the response is property : description.

The following example is returned from the agent_ipmitool driver.

{
  "deploy_forces_oob_reboot": "Whether Ironic should force a reboot of the Node via the out-of-band channel after deployment is complete. Provides compatibility with older deploy ramdisks. Defaults to False. Optional.",
  "deploy_kernel": "UUID (from Glance) of the deployment kernel. Required.",
  "deploy_ramdisk": "UUID (from Glance) of the ramdisk that is mounted at boot time. Required.",
  "image_http_proxy": "URL of a proxy server for HTTP connections. Optional.",
  "image_https_proxy": "URL of a proxy server for HTTPS connections. Optional.",
  "image_no_proxy": "A comma-separated list of host names, IP addresses and domain names (with optional :port) that will be excluded from proxying. To denote a domain name, use a dot to prefix the domain name. This value will be ignored if ``image_http_proxy`` and ``image_https_proxy`` are not specified. Optional.",
  "ipmi_address": "IP address or hostname of the node. Required.",
  "ipmi_bridging": "bridging_type; default is \"no\". One of \"single\", \"dual\", \"no\". Optional.",
  "ipmi_disable_boot_timeout": "By default ironic will send a raw IPMI command to disable the 60 second timeout for booting.  Setting this option to False will NOT send that command; default value is True. Optional.",
  "ipmi_force_boot_device": "Whether Ironic should specify the boot device to the BMC each time the server is turned on, eg. because the BMC is not capable of remembering the selected boot device across power cycles; default value is False. Optional.",
  "ipmi_local_address": "local IPMB address for bridged requests. Used only if ipmi_bridging is set to \"single\" or \"dual\". Optional.",
  "ipmi_password": "password. Optional.",
  "ipmi_port": "remote IPMI RMCP port. Optional.",
  "ipmi_priv_level": "privilege level; default is ADMINISTRATOR. One of ADMINISTRATOR, CALLBACK, OPERATOR, USER. Optional.",
  "ipmi_protocol_version": "the version of the IPMI protocol; default is \"2.0\". One of \"1.5\", \"2.0\". Optional.",
  "ipmi_target_address": "destination address for bridged request. Required only if ipmi_bridging is set to \"single\" or \"dual\".",
  "ipmi_target_channel": "destination channel for bridged request. Required only if ipmi_bridging is set to \"single\" or \"dual\".",
  "ipmi_terminal_port": "node's UDP port to connect to. Only required for console access.",
  "ipmi_transit_address": "transit address for bridged request. Required only if ipmi_bridging is set to \"dual\".",
  "ipmi_transit_channel": "transit channel for bridged request. Required only if ipmi_bridging is set to \"dual\".",
  "ipmi_username": "username; default is NULL user. Optional."
}
GET
/v1/drivers/{driver_name}/raid/logical_disk_properties

Show driver logical disk properties

New in version 1.12.

Show the required and optional parameters that driver_name expects to be supplied in the node’s raid_config field, if a RAID configuration change is requested.

Normal response codes: 200

Request

Name

In

Type

Description

driver_name

path

string

The name of the driver.

Response Example

The response BODY is a dictionary, but the keys are unique to each driver. The structure of the response is property : description.

The following example is returned from the agent_ipmitool driver.

{
  "controller": "Controller to use for this logical disk. If not specified, the driver will choose a suitable RAID controller on the bare metal node. Optional.",
  "disk_type": "The type of disk preferred. Valid values are 'hdd' and 'ssd'. If this is not specified, disk type will not be a selection criterion for choosing backing physical disks. Optional.",
  "interface_type": "The interface type of disk. Valid values are 'sata', 'scsi' and 'sas'. If this is not specified, interface type will not be a selection criterion for choosing backing physical disks. Optional.",
  "is_root_volume": "Specifies whether this disk is a root volume. By default, this is False. Optional.",
  "number_of_physical_disks": "Number of physical disks to use for this logical disk. By default, the driver uses the minimum number of disks required for that RAID level. Optional.",
  "physical_disks": "The physical disks to use for this logical disk. If not specified, the driver will choose suitable physical disks to use. Optional.",
  "raid_level": "RAID level for the logical disk. Valid values are 'JBOD', '0', '1', '2', '5', '6', '1+0', '5+0' and '6+0'. Required.",
  "share_physical_disks": "Specifies whether other logical disks can share physical disks with this logical disk. By default, this is False. Optional.",
  "size_gb": "Size in GiB (Integer) for the logical disk. Use 'MAX' as size_gb if this logical disk is supposed to use the rest of the space available. Required.",
  "volume_name": "Name of the volume to be created. If this is not specified, it will be auto-generated. Optional."
}

Driver Vendor Passthru (drivers)

Each driver MAY support vendor-specific extensions, called “passthru” methods.

Internally, Ironic’s driver API supports flexibly exposing functions via the common HTTP methods GET, PUT, POST, and DELETE. To call a passthru method, the query string must contain the name of the method. For example, if the method name was my_passthru_method, the request would look like /vendor_passthru?method=my_passthru_method. The contents of the HTTP request are forwarded to the driver and validated there.

Ironic’s REST API provides a means to discover these methods, but does not provide support, testing, or documentation for these endpoints. The Ironic development team does not guarantee any compatibility within these methods between releases, though we encourage driver authors to provide documentation and support for them.

Besides the endpoints documented here, all other resources and endpoints under the heading vendor_passthru should be considered unsupported APIs, and could be changed without warning by the driver authors.

GET
/v1/drivers/{driver_name}/vendor_passthru/methods

List Methods

Retrieve a list of the available vendor passthru methods for the given Driver. The response will indicate which HTTP method(s) each vendor passthru method allows, whether the method call will be synchronous or asynchronous, and whether the response will include any attachment.

Normal response code: 200

Request

Name

In

Type

Description

driver_name

path

string

The name of the driver.

Response

The response BODY is a dictionary whose keys are the method names. The value of each item is itself a dictionary describing how to interact with that method.

Name

In

Type

Description

async

body

boolean

If True the passthru function is invoked asynchronously; if False, synchronously.

attach

body

boolean

True if the return value will be attached to the response object, and False if the return value will be returned in the response body.

description

body

string

A description of what the method does, including any method parameters.

http_methods

body

array

A list of HTTP methods supported by the vendor function.

METHOD
/v1/drivers/{driver_name}/vendor_passthru?method={method_name}

Call a Method

The HTTP METHOD may be one of GET, POST, PUT, DELETE, depending on the driver and method.

This endpoint passes the request directly to the hardware driver. The HTTP BODY must be parseable JSON, which will be converted to parameters passed to that function. Unparsable JSON, missing parameters, or excess parameters will cause the request to be rejected with an HTTP 400 error.

Normal response code: 200 202

Error codes: 400

Request

Name

In

Type

Description

driver_name

path

string

The name of the driver.

method_name

query

string

Driver specific method name.

All other parameters should be passed in the BODY. Parameter list varies by method_name.

Response

Varies.

Node Bios (nodes)

New in version 1.40.

Given a Node identifier (uuid or name), the API exposes the list of all Bios settings associated with that Node.

These endpoints do not allow modification of the Bios settings; that should be done by using clean steps.

GET
/v1/nodes/{node_ident}/bios

List all Bios settings by Node

Return a list of Bios settings associated with node_ident.

New in version 1.74: Added additional fields from bios registry which can be retrieved using ?detail=True (see detailed response below). Added fields selector to query for particular fields.

Normal response code: 200

Error codes: 404

Request

Name

In

Type

Description

node_ident

path

string

The UUID or Name of the node.

fields (Optional)

query

array

One or more fields to be returned in the response.

For example, the following request returns only the uuid and name fields for each node:

GET /v1/nodes?fields=uuid,name

detail (Optional)

query

boolean

Whether to show detailed information about the resource. This cannot be set to True if fields parameter is specified.

Response

Name

In

Type

Description

bios

body

array

Optional list of one or more Bios settings. It includes following fields “created_at”, “updated_at”, “links”, “name”, “value”, “attribute_type”, “allowable_values”, “lower_bound”, “max_length”, “min_length”, “read_only”, “reset_required”, “unique”, “upper_bound”

created_at

body

string

The UTC date and time when the resource was created, ISO 8601 format.

updated_at

body

string

The UTC date and time when the resource was updated, ISO 8601 format. May be “null”.

links

body

array

A list of relative links. Includes the self and bookmark links.

name

body

string

The name of a Bios setting for a Node, eg. “virtualization”.

value

body

string

The value of a Bios setting for a Node, eg. “on”.

Example list of a Node’s Bios settings:

{
  "bios": [
    {
      "created_at": "2016-08-18T22:28:49.653974+00:00",
      "updated_at": "2016-08-18T22:28:49.653974+00:00",
      "links": [
        {
          "href": "http://127.0.0.1:6385/v1/nodes/6d85703a-565d-469a-96ce-30b6de53079d/bios/virtualization",
          "rel": "self"
        },
        {
          "href": "http://127.0.0.1:6385/v1/nodes/6d85703a-565d-469a-96ce-30b6de53079d/bios/virtualization",
          "rel": "bookmark"
        }
      ],
      "name": "Virtualization",
      "value": "Enabled"
    }
  ]
}
GET
/v1/nodes/{node_ident}/bios/?detail=True

List detailed Bios settings by Node

Return a list of detailed Bios settings associated with node_ident. The detailed list includes the BIOS Attribute Registry information retrieved via Redfish.

New in version 1.74: Introduced

Normal response code: 200

Error codes: 404

Request

Name

In

Type

Description

node_ident

path

string

The UUID or Name of the node.

Response

Name

In

Type

Description

bios

body

array

Optional list of one or more Bios settings. It includes following fields “created_at”, “updated_at”, “links”, “name”, “value”, “attribute_type”, “allowable_values”, “lower_bound”, “max_length”, “min_length”, “read_only”, “reset_required”, “unique”, “upper_bound”

created_at

body

string

The UTC date and time when the resource was created, ISO 8601 format.

updated_at

body

string

The UTC date and time when the resource was updated, ISO 8601 format. May be “null”.

links

body

array

A list of relative links. Includes the self and bookmark links.

name

body

string

The name of a Bios setting for a Node, eg. “virtualization”.

value

body

string

The value of a Bios setting for a Node, eg. “on”.

attribute_type

body

string

A string describing the type of the Bios setting. May be null.

allowable_values

body

array

A list of allowable values, otherwise null.

lower_bound

body

integer

The lowest allowed integer value. May be null.

max_length

body

integer

The maximum string length of the value. May be null.

min_length

body

integer

The minimum string length of the value. May be null.

read_only

body

boolean

This Bios setting is read only and can’t be changed. May be None.

reset_required

body

boolean

After setting this Bios setting a node reboot is required. May be None.

unique

body

boolean

This Bios setting is unique to this node. May be null.

upper_bound

body

integer

The highest allowed integer value. May be null.

Example list of a Node’s Bios settings:

{
  "bios": [
    {
      "created_at": "2016-08-18T22:28:49.653974+00:00",
      "updated_at": "2016-08-18T22:28:49.653974+00:00",
      "links": [
        {
          "href": "http://127.0.0.1:6385/v1/nodes/6d85703a-565d-469a-96ce-30b6de53079d/bios/virtualization",
          "rel": "self"
        },
        {
          "href": "http://127.0.0.1:6385/v1/nodes/6d85703a-565d-469a-96ce-30b6de53079d/bios/virtualization",
          "rel": "bookmark"
        }
      ],
      "name": "Virtualization",
      "value": "Enabled",
      "attribute_type": "Enumeration",
      "allowable_values": ["Enabled", "Disabled"],
      "lower_bound": None,
      "max_length": None,
      "min_length": None,
      "read_only": false,
      "reset_required": None,
      "unique": None,
      "upper_bound": None
    }
  ]
}

GET
/v1/nodes/{node_ident}/bios/{bios_setting}

Show single Bios setting of a Node

Return the content of the specific bios bios_setting associated with node_ident.

New in version 1.74: Introduced fields from the BIOS registry.

Normal response code: 200

Error codes: 404

Request

Name

In

Type

Description

node_ident

path

string

The UUID or Name of the node.

bios_setting

path

string

The name of the Bios setting.

Response

Name

In

Type

Description

<key>

body

dictionary

Dictionary containing the definition of a Bios setting. It includes the following fields “created_at”, “updated_at”, “links”, “name”, “value”.

created_at

body

string

The UTC date and time when the resource was created, ISO 8601 format.

updated_at

body

string

The UTC date and time when the resource was updated, ISO 8601 format. May be “null”.

links

body

array

A list of relative links. Includes the self and bookmark links.

name

body

string

The name of a Bios setting for a Node, eg. “virtualization”.

value

body

string

The value of a Bios setting for a Node, eg. “on”.

attribute_type

body

string

A string describing the type of the Bios setting. May be null.

allowable_values

body

array

A list of allowable values, otherwise null.

lower_bound

body

integer

The lowest allowed integer value. May be null.

max_length

body

integer

The maximum string length of the value. May be null.

min_length

body

integer

The minimum string length of the value. May be null.

read_only

body

boolean

This Bios setting is read only and can’t be changed. May be None.

reset_required

body

boolean

After setting this Bios setting a node reboot is required. May be None.

unique

body

boolean

This Bios setting is unique to this node. May be null.

upper_bound

body

integer

The highest allowed integer value. May be null.

Example details of a Node’s Bios setting details:

{
  "virtualization": {
    "created_at": "2016-08-18T22:28:49.653974+00:00",
    "updated_at": "2016-08-18T22:28:49.653974+00:00",
    "links": [
      {
        "href": "http://127.0.0.1:6385/v1/nodes/6d85703a-565d-469a-96ce-30b6de53079d/bios/virtualization",
        "rel": "self"
      },
      {
        "href": "http://127.0.0.1:6385/v1/nodes/6d85703a-565d-469a-96ce-30b6de53079d/bios/virtualization",
        "rel": "bookmark"
      }
    ],
    "name": "Virtualization",
    "value": "Enabled",
    "attribute_type": "Enumeration",
    "allowable_values": ["Enabled", "Disabled"],
    "lower_bound": None,
    "max_length": None,
    "min_length": None,
    "read_only": false,
    "reset_required": None,
    "unique": None,
    "upper_bound": None
  }
}

Node Firmware (nodes)

New in version 1.86.

Given a Node identifier (uuid or name), the API exposes the list of all Firmware Components associated with that Node.

These endpoints do not allow modification of the Firmware Components; that should be done by using clean steps.

GET
/v1/nodes/{node_ident}/firmware

List all Firmware Components by Node

Return a list of Firmware Components associated with node_ident.

Normal response code: 200

Error codes: 404

Request

Name

In

Type

Description

node_ident

path

string

The UUID or Name of the node.

Response

Name

In

Type

Description

firmware

body

array

List of Firmware Components of the node. It includes following fields “created_at”, “updated_at”, “component”, “initial_version”, “current_version”, “last_version_flashed”

created_at

body

string

The UTC date and time when the resource was created, ISO 8601 format.

updated_at

body

string

The UTC date and time when the resource was updated, ISO 8601 format. May be “null”.

component

body

string

The Firmware Component of a Node, eg. “bios”.

initial_version

body

string

The initial version of a Firmware Component.

current_version

body

string

The current version of a Firmware Component.

last_version_flashed

body

string

The last version flashed of a Firmware Component.

Example list of a Node’s Firmware Components:

{
  "firmware": [
    {
      "created_at": "2016-08-18T22:28:49.653974+00:00",
      "updated_at": "2016-08-18T22:28:49.653974+00:00",
      "component": "BMC",
      "initial_version": "v1.0.0",
      "current_version": "v1.2.0",
      "last_version_flashed": "v1.2.0"
    },
    {
      "created_at": "2016-08-18T22:28:49.653974+00:00",
      "updated_at": "2016-08-18T22:28:49.653974+00:00",
      "component": "BIOS",
      "initial_version": "v1.0.0",
      "current_version": "v1.1.5",
      "last_version_flashed": "v1.1.5"
    }
  ]
}

Conductors (conductors)

New in version 1.49.

Listing Conductor resources is done through the conductors resource.

Conductor resources are read-only, they can not be created, updated, or removed.

GET
/v1/conductors

List Conductors

Return a list of conductors known by the Bare Metal service.

By default, this query will return the hostname, conductor group, and alive status for each Conductor. When detail is set to True in the query string, will return the full representation of the resource.

Normal response code: 200

Request

Name

In

Type

Description

fields (Optional)

query

array

One or more fields to be returned in the response.

For example, the following request returns only the hostname and alive fields for each conductor:

GET /v1/conductors?fields=hostname,alive

limit (Optional)

query

integer

Requests a page size of items. Returns a number of items up to a limit value. Use the limit parameter to make an initial limited request and use the ID of the last-seen item from the response as the marker parameter value in a subsequent limited request. This value cannot be larger than the max_limit option in the [api] section of the configuration. If it is higher than max_limit, only max-limit resources will be returned.

marker (Optional)

query

string

The ID of the last-seen item. Use the limit parameter to make an initial limited request and use the ID of the last-seen item from the response as the marker parameter value in a subsequent limited request.

sort_dir (Optional)

query

string

Sorts the response by the requested sort direction. A valid value is asc (ascending) or desc (descending). Default is asc. You can specify multiple pairs of sort key and sort direction query parameters. If you omit the sort direction in a pair, the API uses the natural sorting direction of the server attribute that is provided as the sort_key.

sort_key (Optional)

query

string

Sorts the response by this attribute value. Default is id. You can specify multiple pairs of sort key and sort direction query parameters. If you omit the sort direction in a pair, the API uses the natural sorting direction of the server attribute that is provided as the sort_key.

detail (Optional)

query

boolean

Whether to show detailed information about the resource. This cannot be set to True if fields parameter is specified.

Response

Name

In

Type

Description

hostname

body

array

The hostname of this conductor.

conductor_group

body

string

The conductor group for a node. Case-insensitive string up to 255 characters, containing a-z, 0-9, _, -, and ..

alive

body

boolean

The conductor status indicates whether a conductor is considered alive or not.

drivers

body

array

A list of driver objects.

links

body

array

A list of relative links. Includes the self and bookmark links.

Example Conductor list response:

{
  "conductors": [
    {
      "hostname": "compute1.localdomain",
      "conductor_group": "",
      "links": [
        {
          "href": "http://127.0.0.1:6385/v1/conductors/compute1.localdomain",
          "rel": "self"
        },
        {
          "href": "http://127.0.0.1:6385/conductors/compute1.localdomain",
          "rel": "bookmark"
        }
      ],
      "alive": false
    },
    {
      "hostname": "compute2.localdomain",
      "conductor_group": "",
      "links": [
        {
          "href": "http://127.0.0.1:6385/v1/conductors/compute2.localdomain",
          "rel": "self"
        },
        {
          "href": "http://127.0.0.1:6385/conductors/compute2.localdomain",
          "rel": "bookmark"
        }
      ],
      "alive": true
    }
  ]
}

Example detailed Conductor list response:

{
  "conductors": [
    {
      "links": [
        {
          "href": "http://127.0.0.1:6385/v1/conductors/compute1.localdomain",
          "rel": "self"
        },
        {
          "href": "http://127.0.0.1:6385/conductors/compute1.localdomain",
          "rel": "bookmark"
        }
      ],
      "created_at": "2018-08-07T08:39:21+00:00",
      "hostname": "compute1.localdomain",
      "conductor_group": "",
      "updated_at": "2018-11-30T07:07:23+00:00",
      "alive": false,
      "drivers": [
        "ipmi"
      ]
    },
    {
      "links": [
        {
          "href": "http://127.0.0.1:6385/v1/conductors/compute2.localdomain",
          "rel": "self"
        },
        {
          "href": "http://127.0.0.1:6385/conductors/compute2.localdomain",
          "rel": "bookmark"
        }
      ],
      "created_at": "2018-12-05T07:03:19+00:00",
      "hostname": "compute2.localdomain",
      "conductor_group": "",
      "updated_at": "2018-12-05T07:03:21+00:00",
      "alive": true,
      "drivers": [
        "ipmi"
      ]
    }
  ]
}
GET
/v1/conductors/{hostname}

Show Conductor Details

Shows details for a conductor. By default, this will return the full representation of the resource; an optional fields parameter can be supplied to return only the specified set.

Normal response codes: 200

Error codes: 400,403,404,406

Request

Name

In

Type

Description

hostname

path

string

The hostname of the conductor.

fields (Optional)

query

array

One or more fields to be returned in the response.

For example, the following request returns only the hostname and alive fields for each conductor:

GET /v1/conductors?fields=hostname,alive

Response

Name

In

Type

Description

hostname

body

array

The hostname of this conductor.

conductor_group

body

string

The conductor group for a node. Case-insensitive string up to 255 characters, containing a-z, 0-9, _, -, and ..

alive

body

boolean

The conductor status indicates whether a conductor is considered alive or not.

drivers

body

array

A list of driver objects.

links

body

array

A list of relative links. Includes the self and bookmark links.

Example JSON representation of a Conductor:

{
  "links": [
    {
      "href": "http://127.0.0.1:6385/v1/conductors/compute2.localdomain",
      "rel": "self"
    },
    {
      "href": "http://127.0.0.1:6385/conductors/compute2.localdomain",
      "rel": "bookmark"
    }
  ],
  "created_at": "2018-12-05T07:03:19+00:00",
  "hostname": "compute2.localdomain",
  "conductor_group": "",
  "updated_at": "2018-12-05T07:03:21+00:00",
  "alive": true,
  "drivers": [
    "ipmi"
  ]
}

Allocations (allocations)

The Allocation resource represents a request to find and allocate a Node for deployment.

New in version 1.52: Allocation API was introduced.

POST
/v1/allocations

Create Allocation

Creates an allocation.

A Node can be requested by its resource class and traits. Additionally, Nodes can be pre-filtered on the client side, and the resulting list of UUIDs and/or names can be submitted as candidate_nodes. Otherwise all nodes are considered.

A Node is suitable for an Allocation if all of the following holds:

  • provision_state is available

  • power_state is not null

  • maintenance is false

  • instance_uuid is null

  • resource_class matches requested one

  • traits list contains all of the requested ones

The allocation process is asynchronous. The new Allocation is returned in the allocating state, and the process continues in the background. If it succeeds, the node_uuid field is populated with the Node’s UUID, and the Node’s instance_uuid field is set to the Allocation’s UUID.

If you want to backfill an allocation for an already deployed node, you can pass the UUID or name of this node to node. In this case the allocation is created immediately, bypassing the normal allocation process. Other parameters must be missing or match the provided node.

New in version 1.52: Allocation API was introduced.

New in version 1.58: Added support for backfilling allocations.

New in version 1.60: Introduced the owner field.

New in version 1.79: A node with the same name as the allocation name is moved to the start of the derived candidate list.

Normal response codes: 201

Error response codes: 400, 401, 403, 409, 503

Request

Name

In

Type

Description

resource_class

body

string

The requested resource class for the allocation. Can only be missing when backfilling an allocation (will be set to the node’s resource_class in such case).

candidate_nodes (Optional)

body

array

The list of nodes (names or UUIDs) that should be considered for this allocation. If not provided, all available nodes will be considered.

name (Optional)

body

string

The unique name of the Allocation.

traits (Optional)

body

array

The list of requested traits for the allocation.

uuid (Optional)

body

string

The UUID for the resource.

extra (Optional)

body

object

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

node (Optional)

body

string

The node UUID or name to create the allocation against, bypassing the normal allocation process.

Warning

This field must not be used to request a normal allocation with one candidate node, use candidate_nodes instead.

owner (Optional)

body

string

A string or UUID of the tenant who owns the object.

Request Example

{
    "name": "allocation-1",
    "resource_class": "bm-large"
}

Response Parameters

Name

In

Type

Description

uuid

body

string

The UUID for the resource.

candidate_nodes

body

array

A list of UUIDs of the nodes that are candidates for this allocation.

last_error

body

string

The error message for the allocation if it is in the error state, null otherwise.

name

body

string

The unique name of the allocation.

node_uuid

body

string

The UUID of the node assigned to the allocation. Will be null if a node is not yet assigned.

resource_class

body

string

The resource class requested for the allocation. Can be null if the allocation was created via backfilling and the target node did not have the resource class set.

state

body

string

The current state of the allocation. One of:

  • allocating - allocation is in progress.

  • active - allocation is finished and node_uuid is assigned.

  • error - allocation has failed, see last_error for details.

traits

body

array

The list of the traits requested for the allocation.

owner (Optional)

body

string

A string or UUID of the tenant who owns the object.

extra

body

object

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

created_at

body

string

The UTC date and time when the resource was created, ISO 8601 format.

updated_at

body

string

The UTC date and time when the resource was updated, ISO 8601 format. May be “null”.

links

body

array

A list of relative links. Includes the self and bookmark links.

Response Example

{
  "candidate_nodes": [],
  "created_at": "2019-02-20T09:43:58+00:00",
  "extra": {},
  "last_error": null,
  "links": [
    {
      "href": "http://127.0.0.1:6385/v1/allocations/5344a3e2-978a-444e-990a-cbf47c62ef88",
      "rel": "self"
    },
    {
      "href": "http://127.0.0.1:6385/allocations/5344a3e2-978a-444e-990a-cbf47c62ef88",
      "rel": "bookmark"
    }
  ],
  "name": "allocation-1",
  "node_uuid": null,
  "owner": null,
  "resource_class": "bm-large",
  "state": "allocating",
  "traits": [],
  "updated_at": null,
  "uuid": "5344a3e2-978a-444e-990a-cbf47c62ef88"
}
GET
/v1/allocations

List Allocations

Lists all Allocations.

New in version 1.52: Allocation API was introduced.

New in version 1.60: Introduced the owner field.

Normal response codes: 200

Error response codes: 400, 401, 403, 404

Request

Name

In

Type

Description

node (Optional)

query

string

Filter the list of allocations by the node UUID or name.

resource_class (Optional)

query

string

Filter the list of returned nodes, and only return the ones with the specified resource class.

state (Optional)

query

string

Filter the list of allocations by the allocation state, one of active, allocating or error.

owner (Optional)

body

string

A string or UUID of the tenant who owns the object.

fields (Optional)

query

array

One or more fields to be returned in the response.

For example, the following request returns only the uuid and name fields for each node:

GET /v1/nodes?fields=uuid,name

limit (Optional)

query

integer

Requests a page size of items. Returns a number of items up to a limit value. Use the limit parameter to make an initial limited request and use the ID of the last-seen item from the response as the marker parameter value in a subsequent limited request. This value cannot be larger than the max_limit option in the [api] section of the configuration. If it is higher than max_limit, only max-limit resources will be returned.

marker (Optional)

query

string

The ID of the last-seen item. Use the limit parameter to make an initial limited request and use the ID of the last-seen item from the response as the marker parameter value in a subsequent limited request.

sort_dir (Optional)

query

string

Sorts the response by the requested sort direction. A valid value is asc (ascending) or desc (descending). Default is asc. You can specify multiple pairs of sort key and sort direction query parameters. If you omit the sort direction in a pair, the API uses the natural sorting direction of the server attribute that is provided as the sort_key.

sort_key (Optional)

query

string

Sorts the response by this attribute value. Default is id. You can specify multiple pairs of sort key and sort direction query parameters. If you omit the sort direction in a pair, the API uses the natural sorting direction of the server attribute that is provided as the sort_key.

Response Parameters

Name

In

Type

Description

uuid

body

string

The UUID for the resource.

candidate_nodes

body

array

A list of UUIDs of the nodes that are candidates for this allocation.

last_error

body

string

The error message for the allocation if it is in the error state, null otherwise.

name

body

string

The unique name of the allocation.

node_uuid

body

string

The UUID of the node assigned to the allocation. Will be null if a node is not yet assigned.

resource_class

body

string

The resource class requested for the allocation. Can be null if the allocation was created via backfilling and the target node did not have the resource class set.

state

body

string

The current state of the allocation. One of:

  • allocating - allocation is in progress.

  • active - allocation is finished and node_uuid is assigned.

  • error - allocation has failed, see last_error for details.

traits

body

array

The list of the traits requested for the allocation.

owner (Optional)

body

string

A string or UUID of the tenant who owns the object.

extra

body

object

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

created_at

body

string

The UTC date and time when the resource was created, ISO 8601 format.

updated_at

body

string

The UTC date and time when the resource was updated, ISO 8601 format. May be “null”.

links

body

array

A list of relative links. Includes the self and bookmark links.

Response Example

{
  "allocations": [
    {
      "candidate_nodes": [],
      "created_at": "2019-02-20T09:43:58+00:00",
      "extra": {},
      "last_error": null,
      "links": [
        {
          "href": "http://127.0.0.1:6385/v1/allocations/5344a3e2-978a-444e-990a-cbf47c62ef88",
          "rel": "self"
        },
        {
          "href": "http://127.0.0.1:6385/allocations/5344a3e2-978a-444e-990a-cbf47c62ef88",
          "rel": "bookmark"
        }
      ],
      "name": "allocation-1",
      "node_uuid": "6d85703a-565d-469a-96ce-30b6de53079d",
      "owner": null,
      "resource_class": "bm-large",
      "state": "active",
      "traits": [],
      "updated_at": "2019-02-20T09:43:58+00:00",
      "uuid": "5344a3e2-978a-444e-990a-cbf47c62ef88"
    },
    {
      "candidate_nodes": [],
      "created_at": "2019-02-20T09:43:58+00:00",
      "extra": {},
      "last_error": "Failed to process allocation eff80f47-75f0-4d41-b1aa-cf07c201adac: no available nodes match the resource class bm-large.",
      "links": [
        {
          "href": "http://127.0.0.1:6385/v1/allocations/eff80f47-75f0-4d41-b1aa-cf07c201adac",
          "rel": "self"
        },
        {
          "href": "http://127.0.0.1:6385/allocations/eff80f47-75f0-4d41-b1aa-cf07c201adac",
          "rel": "bookmark"
        }
      ],
      "name": "allocation-2",
      "node_uuid": null,
      "owner": null,
      "resource_class": "bm-large",
      "state": "error",
      "traits": [
        "CUSTOM_GOLD"
      ],
      "updated_at": "2019-02-20T09:43:58+00:00",
      "uuid": "eff80f47-75f0-4d41-b1aa-cf07c201adac"
    }
  ]
}
GET
/v1/allocations/{allocation_id}

Show Allocation Details

Shows details for an Allocation.

New in version 1.52: Allocation API was introduced.

New in version 1.60: Introduced the owner field.

Normal response codes: 200

Error response codes: 400, 401, 403, 404

Request

Name

In

Type

Description

fields (Optional)

query

array

One or more fields to be returned in the response.

For example, the following request returns only the uuid and name fields for each node:

GET /v1/nodes?fields=uuid,name

allocation_id

path

string

The UUID or name of the allocation.

Response Parameters

Name

In

Type

Description

uuid

body

string

The UUID for the resource.

candidate_nodes

body

array

A list of UUIDs of the nodes that are candidates for this allocation.

last_error

body

string

The error message for the allocation if it is in the error state, null otherwise.

name

body

string

The unique name of the allocation.

node_uuid

body

string

The UUID of the node assigned to the allocation. Will be null if a node is not yet assigned.

resource_class

body

string

The resource class requested for the allocation. Can be null if the allocation was created via backfilling and the target node did not have the resource class set.

state

body

string

The current state of the allocation. One of:

  • allocating - allocation is in progress.

  • active - allocation is finished and node_uuid is assigned.

  • error - allocation has failed, see last_error for details.

traits

body

array

The list of the traits requested for the allocation.

owner (Optional)

body

string

A string or UUID of the tenant who owns the object.

extra

body

object

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

created_at

body

string

The UTC date and time when the resource was created, ISO 8601 format.

updated_at

body

string

The UTC date and time when the resource was updated, ISO 8601 format. May be “null”.

links

body

array

A list of relative links. Includes the self and bookmark links.

Response Example

{
  "candidate_nodes": [],
  "created_at": "2019-02-20T09:43:58+00:00",
  "extra": {},
  "last_error": null,
  "links": [
    {
      "href": "http://127.0.0.1:6385/v1/allocations/5344a3e2-978a-444e-990a-cbf47c62ef88",
      "rel": "self"
    },
    {
      "href": "http://127.0.0.1:6385/allocations/5344a3e2-978a-444e-990a-cbf47c62ef88",
      "rel": "bookmark"
    }
  ],
  "name": "allocation-1",
  "node_uuid": "6d85703a-565d-469a-96ce-30b6de53079d",
  "owner": null,
  "resource_class": "bm-large",
  "state": "active",
  "traits": [],
  "updated_at": "2019-02-20T09:43:58+00:00",
  "uuid": "5344a3e2-978a-444e-990a-cbf47c62ef88"
}
PATCH
/v1/allocations/{allocation_id}

Update Allocation

Updates an allocation. Allows updating only name and extra fields.

New in version 1.57: Allocation update API was introduced.

Normal response codes: 200

Error response codes: 400, 401, 403, 404, 409, 503

Request

The BODY of the PATCH request must be a JSON PATCH document, adhering to RFC 6902.

Name

In

Type

Description

allocation_id

path

string

The UUID or name of the allocation.

name (Optional)

body

string

The unique name of the Allocation.

extra (Optional)

body

object

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

Request Example

[
    {
        "op": "add",
        "path": "/extra/foo",
        "value": "bar"
    }
]

Response Parameters

Name

In

Type

Description

uuid

body

string

The UUID for the resource.

candidate_nodes

body

array

A list of UUIDs of the nodes that are candidates for this allocation.

last_error

body

string

The error message for the allocation if it is in the error state, null otherwise.

name

body

string

The unique name of the allocation.

node_uuid

body

string

The UUID of the node assigned to the allocation. Will be null if a node is not yet assigned.

resource_class

body

string

The resource class requested for the allocation. Can be null if the allocation was created via backfilling and the target node did not have the resource class set.

state

body

string

The current state of the allocation. One of:

  • allocating - allocation is in progress.

  • active - allocation is finished and node_uuid is assigned.

  • error - allocation has failed, see last_error for details.

traits

body

array

The list of the traits requested for the allocation.

owner (Optional)

body

string

A string or UUID of the tenant who owns the object.

extra

body

object

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

created_at

body

string

The UTC date and time when the resource was created, ISO 8601 format.

updated_at

body

string

The UTC date and time when the resource was updated, ISO 8601 format. May be “null”.

links

body

array

A list of relative links. Includes the self and bookmark links.

Response Example

{
  "node_uuid": null,
  "uuid": "241db410-7b04-4b1c-87ae-4e336435db08",
  "links": [
    {
      "href": "http://10.66.169.122/v1/allocations/241db410-7b04-4b1c-87ae-4e336435db08",
      "rel": "self"
    },
    {
      "href": "http://10.66.169.122/allocations/241db410-7b04-4b1c-87ae-4e336435db08",
      "rel": "bookmark"
    }
  ],
  "extra":
    {
      "foo": "bar"
    },
  "last_error": null,
  "created_at": "2019-06-04T07:46:25+00:00",
  "owner": null,
  "resource_class": "CUSTOM_GOLD",
  "updated_at": "2019-06-06T03:28:19.496960+00:00",
  "traits": [],
  "state": "error",
  "candidate_nodes": [],
  "name": "test_allocation"
}
DELETE
/v1/allocations/{allocation_id}

Delete Allocation

Deletes an Allocation.

If the Allocation has a Node associated, the Node’s instance_uuid is reset.

The deletion will fail if the Allocation has a Node assigned and the Node is active and not in the maintenance mode.

New in version 1.52: Allocation API was introduced.

Normal response codes: 204

Error response codes: 400, 401, 403, 404, 409, 503

Request

Name

In

Type

Description

allocation_id

path

string

The UUID or name of the allocation.

Node Allocation (allocations, nodes)

Given a Node identifier (uuid or name), the API allows to get and delete the associated allocation.

New in version 1.52: Allocation API was introduced.

GET
/v1/nodes/{node_ident}/allocation

Show Allocation by Node

Shows details for an allocation.

New in version 1.52: Allocation API was introduced.

Normal response codes: 200

Error response codes: 400, 401, 403, 404

Request

Name

In

Type

Description

node_ident

path

string

The UUID or Name of the node.

fields (Optional)

query

array

One or more fields to be returned in the response.

For example, the following request returns only the uuid and name fields for each node:

GET /v1/nodes?fields=uuid,name

Response Parameters

Name

In

Type

Description

uuid

body

string

The UUID for the resource.

candidate_nodes

body

array

A list of UUIDs of the nodes that are candidates for this allocation.

last_error

body

string

The error message for the allocation if it is in the error state, null otherwise.

name

body

string

The unique name of the allocation.

node_uuid

body

string

The UUID of the node assigned to the allocation. Will be null if a node is not yet assigned.

resource_class

body

string

The resource class requested for the allocation. Can be null if the allocation was created via backfilling and the target node did not have the resource class set.

state

body

string

The current state of the allocation. One of:

  • allocating - allocation is in progress.

  • active - allocation is finished and node_uuid is assigned.

  • error - allocation has failed, see last_error for details.

traits

body

array

The list of the traits requested for the allocation.

extra

body

object

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

created_at

body

string

The UTC date and time when the resource was created, ISO 8601 format.

updated_at

body

string

The UTC date and time when the resource was updated, ISO 8601 format. May be “null”.

links

body

array

A list of relative links. Includes the self and bookmark links.

Response Example

{
  "candidate_nodes": [],
  "created_at": "2019-02-20T09:43:58+00:00",
  "extra": {},
  "last_error": null,
  "links": [
    {
      "href": "http://127.0.0.1:6385/v1/allocations/5344a3e2-978a-444e-990a-cbf47c62ef88",
      "rel": "self"
    },
    {
      "href": "http://127.0.0.1:6385/allocations/5344a3e2-978a-444e-990a-cbf47c62ef88",
      "rel": "bookmark"
    }
  ],
  "name": "allocation-1",
  "node_uuid": "6d85703a-565d-469a-96ce-30b6de53079d",
  "owner": null,
  "resource_class": "bm-large",
  "state": "active",
  "traits": [],
  "updated_at": "2019-02-20T09:43:58+00:00",
  "uuid": "5344a3e2-978a-444e-990a-cbf47c62ef88"
}
DELETE
/v1/nodes/{node_ident}/allocation

Delete Allocation by Node

Deletes the allocation of this node and resets its instance_uuid.

The deletion will fail if the allocation the node is active and not in the maintenance mode.

New in version 1.52: Allocation API was introduced.

Normal response codes: 204

Error response codes: 400, 401, 403, 404, 409, 503

Request

Name

In

Type

Description

node_ident

path

string

The UUID or Name of the node.

Deploy Templates (deploy_templates)

The Deploy Template resource represents a collection of Deploy Steps that may be executed during deployment of a node. A deploy template is matched for a node if at the time of deployment, the template’s name matches a trait in the node’s instance_info.traits.

New in version 1.55: Deploy Template API was introduced.

POST
/v1/deploy_templates

Create Deploy Template

Creates a deploy template.

New in version 1.55: Deploy Template API was introduced.

Normal response codes: 201

Error response codes: 400, 401, 403, 409

Request

Name

In

Type

Description

name

body

string

The unique name of the deploy template.

steps

body

array

The deploy steps of the deploy template. Must be a list of dictionaries containing at least one deploy step. See Request Step for step parameters.

uuid (Optional)

body

string

The UUID for the resource.

extra (Optional)

body

object

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

Request Step

Name

In

Type

Description

interface

body

string

The name of the driver interface.

step

body

string

The name of the deploy step method on the driver interface.

args

body

object

A dictionary of arguments that are passed to the deploy step method.

priority

body

integer

A non-negative integer priority for the step. A value of 0 will disable that step.

Request Example

{
    "extra": {},
    "name": "CUSTOM_HYPERTHREADING_ON",
    "steps": [
        {
            "interface": "bios",
            "step": "apply_configuration",
            "args": {
                "settings": [
                    {
                        "name": "LogicalProc",
                        "value": "Enabled"
                    }
                ]
            },
            "priority": 150
        }
    ]
}

Response Parameters

Name

In

Type

Description

uuid

body

string

The UUID for the resource.

name

body

string

The unique name of the deploy template.

steps

body

array

The deploy steps of the deploy template. Must be a list of dictionaries containing at least one deploy step. See Request Step for step parameters.

extra

body

object

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

created_at

body

string

The UTC date and time when the resource was created, ISO 8601 format.

updated_at

body

string

The UTC date and time when the resource was updated, ISO 8601 format. May be “null”.

links

body

array

A list of relative links. Includes the self and bookmark links.

Response Example

{
  "created_at": "2016-08-18T22:28:48.643434+11:11",
  "extra": {},
  "links": [
    {
      "href": "http://10.60.253.180:6385/v1/deploy_templates/bbb45f41-d4bc-4307-8d1d-32f95ce1e920",
      "rel": "self"
    },
    {
      "href": "http://10.60.253.180:6385/deploy_templates/bbb45f41-d4bc-4307-8d1d-32f95ce1e920",
      "rel": "bookmark"
    }
  ],
  "name": "CUSTOM_HYPERTHREADING_ON",
  "steps": [
    {
      "args": {
        "settings": [
          {
            "name": "LogicalProc",
            "value": "Enabled"
          }
        ]
      },
      "interface": "bios",
      "priority": 150,
      "step": "apply_configuration"
    }
  ],
  "updated_at": null,
  "uuid": "bbb45f41-d4bc-4307-8d1d-32f95ce1e920"
}
GET
/v1/deploy_templates

List Deploy Templates

Lists all deploy templates.

New in version 1.55: Deploy Template API was introduced.

Normal response codes: 200

Error response codes: 400, 401, 403, 404

Request

Name

In

Type

Description

fields (Optional)

query

array

One or more fields to be returned in the response.

For example, the following request returns only the uuid and name fields for each node:

GET /v1/nodes?fields=uuid,name

limit (Optional)

query

integer

Requests a page size of items. Returns a number of items up to a limit value. Use the limit parameter to make an initial limited request and use the ID of the last-seen item from the response as the marker parameter value in a subsequent limited request. This value cannot be larger than the max_limit option in the [api] section of the configuration. If it is higher than max_limit, only max-limit resources will be returned.

marker (Optional)

query

string

The ID of the last-seen item. Use the limit parameter to make an initial limited request and use the ID of the last-seen item from the response as the marker parameter value in a subsequent limited request.

sort_dir (Optional)

query

string

Sorts the response by the requested sort direction. A valid value is asc (ascending) or desc (descending). Default is asc. You can specify multiple pairs of sort key and sort direction query parameters. If you omit the sort direction in a pair, the API uses the natural sorting direction of the server attribute that is provided as the sort_key.

sort_key (Optional)

query

string

Sorts the response by this attribute value. Default is id. You can specify multiple pairs of sort key and sort direction query parameters. If you omit the sort direction in a pair, the API uses the natural sorting direction of the server attribute that is provided as the sort_key.

detail (Optional)

query

boolean

Whether to show detailed information about the resource. This cannot be set to True if fields parameter is specified.

Response Parameters

Name

In

Type

Description

uuid

body

string

The UUID for the resource.

name

body

string

The unique name of the deploy template.

steps

body

array

The deploy steps of the deploy template. Must be a list of dictionaries containing at least one deploy step. See Request Step for step parameters.

extra

body

object

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

created_at

body

string

The UTC date and time when the resource was created, ISO 8601 format.

updated_at

body

string

The UTC date and time when the resource was updated, ISO 8601 format. May be “null”.

links

body

array

A list of relative links. Includes the self and bookmark links.

Response Example

Example deploy template list response:

{
  "deploy_templates": [
    {
      "links": [
        {
          "href": "http://10.60.253.180:6385/v1/deploy_templates/bbb45f41-d4bc-4307-8d1d-32f95ce1e920",
          "rel": "self"
        },
        {
          "href": "http://10.60.253.180:6385/deploy_templates/bbb45f41-d4bc-4307-8d1d-32f95ce1e920",
          "rel": "bookmark"
        }
      ],
      "name": "CUSTOM_HYPERTHREADING_ON",
      "uuid": "bbb45f41-d4bc-4307-8d1d-32f95ce1e920"
    }
  ]
}

Example detailed deploy template list response:

{
  "deploy_templates": [
    {
      "created_at": "2016-08-18T22:28:48.643434+11:11",
      "extra": {},
      "links": [
        {
          "href": "http://10.60.253.180:6385/v1/deploy_templates/bbb45f41-d4bc-4307-8d1d-32f95ce1e920",
          "rel": "self"
        },
        {
          "href": "http://10.60.253.180:6385/deploy_templates/bbb45f41-d4bc-4307-8d1d-32f95ce1e920",
          "rel": "bookmark"
        }
      ],
      "name": "CUSTOM_HYPERTHREADING_ON",
      "steps": [
        {
          "args": {
            "settings": [
              {
                "name": "LogicalProc",
                "value": "Enabled"
              }
            ]
          },
          "interface": "bios",
          "priority": 150,
          "step": "apply_configuration"
        }
      ],
      "updated_at": null,
      "uuid": "bbb45f41-d4bc-4307-8d1d-32f95ce1e920"
    }
  ]
}
GET
/v1/deploy_templates/{deploy_template_id}

Show Deploy Template Details

Shows details for a deploy template.

New in version 1.55: Deploy Template API was introduced.

Normal response codes: 200

Error response codes: 400, 401, 403, 404

Request

Name

In

Type

Description

fields (Optional)

query

array

One or more fields to be returned in the response.

For example, the following request returns only the uuid and name fields for each node:

GET /v1/nodes?fields=uuid,name

deploy_template_id

path

string

The UUID or name of the deploy template.

Response Parameters

Name

In

Type

Description

uuid

body

string

The UUID for the resource.

name

body

string

The unique name of the deploy template.

steps

body

array

The deploy steps of the deploy template. Must be a list of dictionaries containing at least one deploy step. See Request Step for step parameters.

extra

body

object

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

created_at

body

string

The UTC date and time when the resource was created, ISO 8601 format.

updated_at

body

string

The UTC date and time when the resource was updated, ISO 8601 format. May be “null”.

links

body

array

A list of relative links. Includes the self and bookmark links.

Response Example

{
  "created_at": "2016-08-18T22:28:48.643434+11:11",
  "extra": {},
  "links": [
    {
      "href": "http://10.60.253.180:6385/v1/deploy_templates/bbb45f41-d4bc-4307-8d1d-32f95ce1e920",
      "rel": "self"
    },
    {
      "href": "http://10.60.253.180:6385/deploy_templates/bbb45f41-d4bc-4307-8d1d-32f95ce1e920",
      "rel": "bookmark"
    }
  ],
  "name": "CUSTOM_HYPERTHREADING_ON",
  "steps": [
    {
      "args": {
        "settings": [
          {
            "name": "LogicalProc",
            "value": "Enabled"
          }
        ]
      },
      "interface": "bios",
      "priority": 150,
      "step": "apply_configuration"
    }
  ],
  "updated_at": null,
  "uuid": "bbb45f41-d4bc-4307-8d1d-32f95ce1e920"
}
PATCH
/v1/deploy_templates/{deploy_template_id}

Update a Deploy Template

Update a deploy template.

New in version 1.55: Deploy Template API was introduced.

Normal response code: 200

Error response codes: 400, 401, 403, 404, 409

Request

The BODY of the PATCH request must be a JSON PATCH document, adhering to RFC 6902.

Request

Name

In

Type

Description

deploy_template_id

path

string

The UUID or name of the deploy template.

[
   {
      "path" : "/name",
      "value" : "CUSTOM_HT_ON",
      "op" : "replace"
   }
]

Response

Name

In

Type

Description

uuid

body

string

The UUID for the resource.

name

body

string

The unique name of the deploy template.

steps

body

array

The deploy steps of the deploy template. Must be a list of dictionaries containing at least one deploy step. See Request Step for step parameters.

extra

body

object

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

created_at

body

string

The UTC date and time when the resource was created, ISO 8601 format.

updated_at

body

string

The UTC date and time when the resource was updated, ISO 8601 format. May be “null”.

links

body

array

A list of relative links. Includes the self and bookmark links.

{
  "created_at": "2016-08-18T22:28:48.643434+11:11",
  "extra": {},
  "links": [
    {
      "href": "http://10.60.253.180:6385/v1/deploy_templates/bbb45f41-d4bc-4307-8d1d-32f95ce1e920",
      "rel": "self"
    },
    {
      "href": "http://10.60.253.180:6385/deploy_templates/bbb45f41-d4bc-4307-8d1d-32f95ce1e920",
      "rel": "bookmark"
    }
  ],
  "name": "CUSTOM_HT_ON",
  "steps": [
    {
      "args": {
        "settings": [
          {
            "name": "LogicalProc",
            "value": "Enabled"
          }
        ]
      },
      "interface": "bios",
      "priority": 150,
      "step": "apply_configuration"
    }
  ],
  "updated_at": "2016-08-18T22:28:49.653974+00:00",
  "uuid": "bbb45f41-d4bc-4307-8d1d-32f95ce1e920"
}
DELETE
/v1/deploy_templates/{deploy_template_id}

Delete Deploy Template

Deletes a deploy template.

New in version 1.55: Deploy Template API was introduced.

Normal response codes: 204

Error response codes: 400, 401, 403, 404

Request

Name

In

Type

Description

deploy_template_id

path

string

The UUID or name of the deploy template.

History of nodes

New in version 1.78.

Identifying history of events from nodes is available via API version 1.78 via the v1/nodes/{node_ident}/history endpoint. In default policy configuration, only “System” scoped users as well as owners who are listed owners of associated nodes can list and retrieve nodes.

GET
/v1/nodes/{node_ident}/history

List history entries for a node

Normal response code: 200

Error codes: 400,401,403,404

Request

Name

In

Type

Description

node_ident

path

string

The UUID or Name of the node.

detail (Optional)

query

boolean

Whether to show detailed information about the resource. This cannot be set to True if fields parameter is specified.

marker (Optional)

query

string

The ID of the last-seen item. Use the limit parameter to make an initial limited request and use the ID of the last-seen item from the response as the marker parameter value in a subsequent limited request.

limit (Optional)

query

integer

Requests a page size of items. Returns a number of items up to a limit value. Use the limit parameter to make an initial limited request and use the ID of the last-seen item from the response as the marker parameter value in a subsequent limited request. This value cannot be larger than the max_limit option in the [api] section of the configuration. If it is higher than max_limit, only max-limit resources will be returned.

Response

Name

In

Type

Description

history

body

array

History events attached to this node.

Example list of history events from a node:

{
  "history": [
    {
      "uuid": "e5840e39-b4ba-4a93-8071-cff9aa2c9633",
      "created_at": "2021-09-15T17:45:04.686541+00:00",
      "severity": "ERROR",
      "event": "Something is wrong",
      "links": [
        {
          "href": "http://localhost/v1/nodes/1be26c0b-03f2-4d2e-ae87-c02d7f33c123/history/e5840e39-b4ba-4a93-8071-cff9aa2c9633",
          "rel": "self"
        }
      ]
    }
  ]
}
GET
/v1/nodes/{node_ident}/history/{history_event_uuid}

Retrieve a specific history entry

Request

Name

In

Type

Description

node_ident

path

string

The UUID or Name of the node.

history_event_uuid

path

string

The UUID of a history event.

Response

Name

In

Type

Description

uuid

body

string

The UUID for the resource.

created_at

body

string

The UTC date and time when the resource was created, ISO 8601 format.

user

body

string

The UUID value representing the user whom appears to have caused the recorded event.

severity

body

string

Severity indicator for the event being returned. Typically this will indicate if this was an Error or Informational entry.

event

body

string

The event message body which has been logged related to the node for this error.

event_type

body

string

Short descriptive string to indicate where the error occurred at to enable API users/System Operators to be able to identify repeated issues in a particular area of operation, such as ‘deployment’, ‘console’, ‘cleaning’, ‘monitoring’.

conductor

body

array

The hostname of this conductor.

Deleting history entries for a node

Due to the nature of an immutable history record, records cannot be deleted via the REST API. Records and ultimately expired history records are managed by the conductor.

Node inventory

New in version 1.81.

Given a Node identifier, the API provides access to the introspection data associated to the Node via v1/nodes/{node_ident}/inventory endpoint.

The format inventory comes from ironic-python-agent and is currently documented in the agent inventory documentation.

GET
/v1/nodes/{node_ident}/inventory

Show Node Inventory

Normal response code: 200

Error codes:
  • 404 (NodeNotFound, InventoryNotRecorded)

Request

Name

In

Type

Description

node_ident

path

string

The UUID or Name of the node.

Response

Name

In

Type

Description

inventory (Optional)

body

JSON

Inventory of this node.

plugin_data (Optional)

body

JSON

Plugin data of this node.

Example of inventory from a node:

{
  "inventory": {
    "interfaces":[
      {
        "name":"eth0",
        "mac_address":"52:54:00:90:35:d6",
        "ipv4_address":"192.168.122.128",
        "ipv6_address":"fe80::5054:ff:fe90:35d6%eth0",
        "has_carrier":true,
        "lldp":null,
        "vendor":"0x1af4",
        "product":"0x0001"
      }
    ],
    "cpu":{
      "model_name":"QEMU Virtual CPU version 2.5+",
      "frequency":null,
      "count":1,
      "architecture":"x86_64"
    }
  },
  "plugin_data":{
    "macs":[
      "52:54:00:90:35:d6"
    ],
    "local_gb":10,
    "cpu_arch":"x86_64",
    "memory_mb":2048
  }
}

Shards

This section describes an API endpoint returning the population of shards among nodes in the Bare Metal Service. Shards are a way to group nodes in the Bare Metal service. They are used by API clients to separate nodes into groups, allowing horizontal scaling.

Shards are not directly added and removed from the Bare Metal service. Instead, operators can configure a node into a given shard by setting the shard key to any unique string value representing the shard.

Note

The Bare Metal Service does not use shards directly. It instead relies on API clients and external services to use shards to group nodes into smaller areas of responsibility.

GET
/v1/shards

Shards

New in version 1.82.

The /v1/shards endpoint exists to allow querying the distribution of nodes between all defined shards.

Normal response codes: 200

Error response codes: 400 403 404

Request

No request parameters are accepted by this endpoint.

Response

Returns a list of shards and the count of nodes assigned to each. The list is sorted by descending count.

Name

In

Type

Description

name (Optional)

body

string

The name of the shard. A value of “None” indicates the count of nodes with an empty shard value.

count (Optional)

body

integer

The number of nodes with this current string as their assigned shard value.

Response Example

{
  "shards": [
    {
      "count": 47,
      "name": "example_shard1",
    },
    {
      "count": 46,
      "name": "example_shard2"
    }
  ]
}

Chassis (chassis)

The Chassis resource type was originally conceived as a means to group Node resources. Support for this continues to exist in the REST API, however, it is very minimal. The Chassis object does not provide any functionality today aside from a means to list a group of Nodes.

Use of this resource is discouraged, and may be deprecated and removed in a future release.

GET
/v1/chassis/detail

List chassis with details

Lists all chassis with details.

Normal response codes: 200

Request

Name

In

Type

Description

limit (Optional)

query

integer

Requests a page size of items. Returns a number of items up to a limit value. Use the limit parameter to make an initial limited request and use the ID of the last-seen item from the response as the marker parameter value in a subsequent limited request. This value cannot be larger than the max_limit option in the [api] section of the configuration. If it is higher than max_limit, only max-limit resources will be returned.

marker (Optional)

query

string

The ID of the last-seen item. Use the limit parameter to make an initial limited request and use the ID of the last-seen item from the response as the marker parameter value in a subsequent limited request.

sort_dir (Optional)

query

string

Sorts the response by the requested sort direction. A valid value is asc (ascending) or desc (descending). Default is asc. You can specify multiple pairs of sort key and sort direction query parameters. If you omit the sort direction in a pair, the API uses the natural sorting direction of the server attribute that is provided as the sort_key.

sort_key (Optional)

query

string

Sorts the response by this attribute value. Default is id. You can specify multiple pairs of sort key and sort direction query parameters. If you omit the sort direction in a pair, the API uses the natural sorting direction of the server attribute that is provided as the sort_key.

Response Parameters

Name

In

Type

Description

uuid

body

string

The UUID for the resource.

chassis

body

array

A chassis object.

description

body

string

Descriptive text about the Ironic service.

extra

body

object

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

Response Example

{
  "chassis": [
    {
      "created_at": "2016-08-18T22:28:48.643434+11:11",
      "description": "Sample chassis",
      "extra": {},
      "links": [
        {
          "href": "http://127.0.0.1:6385/v1/chassis/dff29d23-1ded-43b4-8ae1-5eebb3e30de1",
          "rel": "self"
        },
        {
          "href": "http://127.0.0.1:6385/chassis/dff29d23-1ded-43b4-8ae1-5eebb3e30de1",
          "rel": "bookmark"
        }
      ],
      "nodes": [
        {
          "href": "http://127.0.0.1:6385/v1/chassis/dff29d23-1ded-43b4-8ae1-5eebb3e30de1/nodes",
          "rel": "self"
        },
        {
          "href": "http://127.0.0.1:6385/chassis/dff29d23-1ded-43b4-8ae1-5eebb3e30de1/nodes",
          "rel": "bookmark"
        }
      ],
      "updated_at": null,
      "uuid": "dff29d23-1ded-43b4-8ae1-5eebb3e30de1"
    }
  ]
}
GET
/v1/chassis/{chassis_id}

Show chassis details

Shows details for a chassis.

Normal response codes: 200

Request

Name

In

Type

Description

fields (Optional)

query

array

One or more fields to be returned in the response.

For example, the following request returns only the uuid and name fields for each node:

GET /v1/nodes?fields=uuid,name

chassis_id

path

string

The UUID of the chassis.

Response Parameters

Name

In

Type

Description

uuid

body

string

The UUID for the resource.

chassis

body

array

A chassis object.

description

body

string

Descriptive text about the Ironic service.

extra

body

object

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

Response Example

{
  "created_at": "2016-08-18T22:28:48.643434+11:11",
  "description": "Sample chassis",
  "extra": {},
  "links": [
    {
      "href": "http://127.0.0.1:6385/v1/chassis/dff29d23-1ded-43b4-8ae1-5eebb3e30de1",
      "rel": "self"
    },
    {
      "href": "http://127.0.0.1:6385/chassis/dff29d23-1ded-43b4-8ae1-5eebb3e30de1",
      "rel": "bookmark"
    }
  ],
  "nodes": [
    {
      "href": "http://127.0.0.1:6385/v1/chassis/dff29d23-1ded-43b4-8ae1-5eebb3e30de1/nodes",
      "rel": "self"
    },
    {
      "href": "http://127.0.0.1:6385/chassis/dff29d23-1ded-43b4-8ae1-5eebb3e30de1/nodes",
      "rel": "bookmark"
    }
  ],
  "updated_at": null,
  "uuid": "dff29d23-1ded-43b4-8ae1-5eebb3e30de1"
}
PATCH
/v1/chassis/{chassis_id}

Update chassis

Updates a chassis.

Normal response codes: 200

Request

The BODY of the PATCH request must be a JSON PATCH document, adhering to RFC 6902.

Name

In

Type

Description

chassis_id

path

string

The UUID of the chassis.

description (Optional)

body

string

Descriptive text about the Ironic service.

extra (Optional)

body

object

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

Request Example

[
    {
        "op": "replace",
        "path": "/description",
        "value": "Updated Chassis"
    }
]

Response Parameters

Name

In

Type

Description

description

body

string

Descriptive text about the Ironic service.

links

body

array

A list of relative links. Includes the self and bookmark links.

extra

body

object

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

created_at

body

string

The UTC date and time when the resource was created, ISO 8601 format.

updated_at

body

string

The UTC date and time when the resource was updated, ISO 8601 format. May be “null”.

chassis

body

array

A chassis object.

nodes

body

array

Links to the collection of nodes contained in this chassis.

uuid

body

string

The UUID for the resource.

Response Example

{
  "created_at": "2016-08-18T22:28:48.643434+11:11",
  "description": "Updated Chassis",
  "extra": {},
  "links": [
    {
      "href": "http://127.0.0.1:6385/v1/chassis/dff29d23-1ded-43b4-8ae1-5eebb3e30de1",
      "rel": "self"
    },
    {
      "href": "http://127.0.0.1:6385/chassis/dff29d23-1ded-43b4-8ae1-5eebb3e30de1",
      "rel": "bookmark"
    }
  ],
  "nodes": [
    {
      "href": "http://127.0.0.1:6385/v1/chassis/dff29d23-1ded-43b4-8ae1-5eebb3e30de1/nodes",
      "rel": "self"
    },
    {
      "href": "http://127.0.0.1:6385/chassis/dff29d23-1ded-43b4-8ae1-5eebb3e30de1/nodes",
      "rel": "bookmark"
    }
  ],
  "updated_at": "2016-08-18T22:28:49.653974+00:00",
  "uuid": "dff29d23-1ded-43b4-8ae1-5eebb3e30de1"
}
DELETE
/v1/chassis/{chassis_id}

Delete chassis

Deletes a chassis.

Request

Name

In

Type

Description

chassis_id

path

string

The UUID of the chassis.

POST
/v1/chassis

Create chassis

Creates a chassis.

Error response codes:201,413,415,405,404,403,401,400,503,409,

Request

Name

In

Type

Description

uuid (Optional)

body

string

The UUID for the resource.

description (Optional)

body

string

Descriptive text about the Ironic service.

extra (Optional)

body

object

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

Request Example

{
    "description": "Sample chassis"
}

Response Parameters

Name

In

Type

Description

description

body

string

Descriptive text about the Ironic service.

links

body

array

A list of relative links. Includes the self and bookmark links.

extra

body

object

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

created_at

body

string

The UTC date and time when the resource was created, ISO 8601 format.

updated_at

body

string

The UTC date and time when the resource was updated, ISO 8601 format. May be “null”.

nodes

body

array

Links to the collection of nodes contained in this chassis.

uuid

body

string

The UUID for the resource.

Response Example

{
  "created_at": "2016-08-18T22:28:48.643434+11:11",
  "description": "Sample chassis",
  "extra": {},
  "links": [
    {
      "href": "http://127.0.0.1:6385/v1/chassis/dff29d23-1ded-43b4-8ae1-5eebb3e30de1",
      "rel": "self"
    },
    {
      "href": "http://127.0.0.1:6385/chassis/dff29d23-1ded-43b4-8ae1-5eebb3e30de1",
      "rel": "bookmark"
    }
  ],
  "nodes": [
    {
      "href": "http://127.0.0.1:6385/v1/chassis/dff29d23-1ded-43b4-8ae1-5eebb3e30de1/nodes",
      "rel": "self"
    },
    {
      "href": "http://127.0.0.1:6385/chassis/dff29d23-1ded-43b4-8ae1-5eebb3e30de1/nodes",
      "rel": "bookmark"
    }
  ],
  "updated_at": null,
  "uuid": "dff29d23-1ded-43b4-8ae1-5eebb3e30de1"
}
GET
/v1/chassis

List chassis

Lists all chassis.

New in version 1.43: Added the detail boolean request parameter. When specified True this causes the response to include complete details about each chassis.

Normal response codes: 200

Request

Name

In

Type

Description

limit (Optional)

query

integer

Requests a page size of items. Returns a number of items up to a limit value. Use the limit parameter to make an initial limited request and use the ID of the last-seen item from the response as the marker parameter value in a subsequent limited request. This value cannot be larger than the max_limit option in the [api] section of the configuration. If it is higher than max_limit, only max-limit resources will be returned.

marker (Optional)

query

string

The ID of the last-seen item. Use the limit parameter to make an initial limited request and use the ID of the last-seen item from the response as the marker parameter value in a subsequent limited request.

sort_dir (Optional)

query

string

Sorts the response by the requested sort direction. A valid value is asc (ascending) or desc (descending). Default is asc. You can specify multiple pairs of sort key and sort direction query parameters. If you omit the sort direction in a pair, the API uses the natural sorting direction of the server attribute that is provided as the sort_key.

sort_key (Optional)

query

string

Sorts the response by this attribute value. Default is id. You can specify multiple pairs of sort key and sort direction query parameters. If you omit the sort direction in a pair, the API uses the natural sorting direction of the server attribute that is provided as the sort_key.

fields (Optional)

query

array

One or more fields to be returned in the response.

For example, the following request returns only the uuid and name fields for each node:

GET /v1/nodes?fields=uuid,name

detail (Optional)

query

boolean

Whether to show detailed information about the resource. This cannot be set to True if fields parameter is specified.

Response Parameters

Name

In

Type

Description

description

body

string

Descriptive text about the Ironic service.

links

body

array

A list of relative links. Includes the self and bookmark links.

extra

body

object

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

created_at

body

string

The UTC date and time when the resource was created, ISO 8601 format.

updated_at

body

string

The UTC date and time when the resource was updated, ISO 8601 format. May be “null”.

nodes

body

array

Links to the collection of nodes contained in this chassis.

uuid

body

string

The UUID for the resource.

Response Example

{
  "chassis": [
    {
      "description": "Sample chassis",
      "links": [
        {
          "href": "http://127.0.0.1:6385/v1/chassis/dff29d23-1ded-43b4-8ae1-5eebb3e30de1",
          "rel": "self"
        },
        {
          "href": "http://127.0.0.1:6385/chassis/dff29d23-1ded-43b4-8ae1-5eebb3e30de1",
          "rel": "bookmark"
        }
      ],
      "uuid": "dff29d23-1ded-43b4-8ae1-5eebb3e30de1"
    }
  ]
}

Utility

This section describes two API endpoints used by the ironic-python-agent ramdisk as it communicates with the Bare Metal service. These were previously exposed as vendor passthrough methods, however, as ironic-python-agent has become the standard ramdisk agent, these methods have been made a part of the official REST API.

Note

Operators are reminded not to expose the Bare Metal Service’s API to unsecured networks. Both API endpoints listed below are available to unauthenticated clients because the default method for booting the ironic-python-agent ramdisk does not provide the agent with keystone credentials.

Note

It is possible to include keys in your ramdisk, or pass keys in via the boot method, if your driver supports it; if that is done, you may configure these endpoints to require authentication by changing the policy rules baremetal:driver:ipa_lookup and baremetal:node:ipa_heartbeat. In light of that, operators are recommended to ensure that this endpoint is only available on the provisioning and cleaning networks.

GET
/v1/lookup

Agent Lookup

New in version 1.22.

A /lookup method is exposed at the root of the REST API. This should only be used by the ironic-python-agent ramdisk to retrieve required configuration data from the Bare Metal service.

By default, /v1/lookup will only match Nodes that are expected to be running the ironic-python-agent ramdisk (for instance, because the Bare Metal service has just initiated a deployment). It can not be used as a generic search mechanism, though this behaviour may be changed by setting the [api] restrict_lookup = false configuration option for the ironic-api service.

The query string should include either or both a node_uuid or an addresses query parameter. If a matching Node is found, information about that Node shall be returned.

Normal response codes: 200

Error response codes: 400 404

Request

Name

In

Type

Description

node_uuid (Optional)

query

string

Optional Node UUID.

addresses (Optional)

query

array

Optional list of one or more Port addresses.

Response

Returns only the information about the corresponding Node that the ironic-python-agent process requires.

Name

In

Type

Description

node

body

JSON

JSON document containing the Node fields “uuid”, “properties”, “instance_info”, and “driver_internal_info”; used by the ironic-python-agent process as it operates on the Node.

config

body

JSON

JSON document of configuration data for the ironic-python-agent process.

Response Example

{
  "config": {
    "heartbeat_timeout": 300,
    "metrics": {
      "backend": "noop",
      "global_prefix": null,
      "prepend_host": false,
      "prepend_host_reverse": true,
      "prepend_uuid": false
    },
    "metrics_statsd": {
      "statsd_host": "localhost",
      "statsd_port": 8125
    }
  },
  "node": {
    "driver_internal_info": {
      "clean_steps": null
    },
    "instance_info": {},
    "links": [
      {
        "href": "http://127.0.0.1:6385/v1/nodes/6d85703a-565d-469a-96ce-30b6de53079d",
        "rel": "self"
      },
      {
        "href": "http://127.0.0.1:6385/nodes/6d85703a-565d-469a-96ce-30b6de53079d",
        "rel": "bookmark"
      }
    ],
    "properties": {},
    "uuid": "6d85703a-565d-469a-96ce-30b6de53079d"
  }
}
POST
/v1/heartbeat/{node_ident}

Agent Heartbeat

New in version 1.22.

A /heartbeat method is exposed at the root of the REST API. This is used as a callback from within the ironic-python-agent ramdisk, so that an active ramdisk may periodically contact the Bare Metal service and provide the current URL at which to contact the agent.

Normal response codes: 202

Error response codes: 400 404

New in version 1.36: agent_version parameter for passing the version of the Ironic Python Agent to Ironic during heartbeat

New in version 1.62: agent_token parameter for passing the token of the Ironic Python Agent to Ironic during heartbeat

Request

Name

In

Type

Description

node_ident

path

string

The UUID or Name of the node.

callback_url

query

string

The URL of an active ironic-python-agent ramdisk, sent back to the Bare Metal service and stored temporarily during a provisioning action.

agent_version

query

string

The version of the ironic-python-agent ramdisk, sent back to the Bare Metal service and stored during provisioning.

agent_token

query

string

The token of the ironic-python-agent ramdisk, sent to the Bare Metal service for authentication purposes.