Bare Metal API

updated: Fri Jun 16 12:12:10 2017, commit 6fcf371

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.

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.31"
  },
  "description": "Ironic is an OpenStack project which aims to provision 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.31"
    }
  ]
}

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/developer/ironic/dev/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"
    }
  ]
}

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.

Beginning with API microversion 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.

If the specified driver is a dynamic driver (available from API microversion 1.31), 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.

API microversion 1.2 introduced the new 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.

API microversion 1.11 changed 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.

Normal response codes: 201

Request¶

Name	In	Type	Description
driver	body	string	The name of the driver used to manage this Node.

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"
}

Example Node creation request with a classic driver:

{
    "name": "test_node_classic",
    "driver": "agent_ipmitool",
    "driver_info": {
        "ipmi_username": "ADMIN",
        "ipmi_password": "password"
    }
}

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 “”.

API microversion 1.5 introduced the name field.

API microversion 1.7 introduced the clean_step field`

API microversion 1.12 introduced support for the raid_config and target_raid_config fields.

API microversion 1.20 introduced the network_interface field. If this field is not supplied when creating the Node, the default value will be used.

API microversion 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.

API microversion 1.24 introduced the /nodes/{node_ident}/portgroups endpoint.

API microversion 1.31 introduced all of the *_interface fields (boot_interface, deploy_interface, etc.), with the exception of the network_interface field, which was introduced in API microversion 1.20. If this field is not supplied when creating the Node, the default value will be used.

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

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. Added in API microversion 1.5
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”, “power off”, or “rebooting”. Added new target power states “soft power off” and “soft rebooting” in API microversion 1.27.
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
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.
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. Added in API microversion 1.24.
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. This will be used by the openstack Placement Engine in a future release. Added in API microversion 1.21.
boot_interface	body	string	The boot interface for a Node, e.g. “pxe”. Added in API microversion 1.31.
console_interface	body	string	The console interface for a node, e.g. “no-console”. Added in API microversion 1.31.
deploy_interface	body	string	The deploy interface for a node, e.g. “iscsi”. Added in API microversion 1.31.
inspect_interface	body	string	The interface used for node inspection, e.g. “no-inspect”. Added in API microversion 1.31.
management_interface	body	string	Interface for out-of-band node management, e.g. “ipmitool”. Added in API microversion 1.31.
network_interface	body	string	Which Network Interface provider to use when plumbing the network connections for this Node. Added in API microversion v1.20
power_interface	body	string	Interface used for performing power actions on the node, e.g. “ipmitool”. Added in API microversion 1.31.
raid_interface	body	string	Interface used for configuring RAID on this node, e.g. “no-raid”. Added in API microversion 1.31.
vendor_interface	body	string	Interface for vendor-specific functionality on this node, e.g. “no-vendor”. Added in API microversion 1.31.

Example JSON representation of a Node:

{
  "boot_interface": null,
  "chassis_uuid": null,
  "clean_step": {},
  "console_enabled": false,
  "console_interface": null,
  "created_at": "2016-08-18T22:28:48.643434+11:11",
  "deploy_interface": 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,
  "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_interface": "flat",
  "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": {},
  "provision_state": "enroll",
  "provision_updated_at": null,
  "raid_config": {},
  "raid_interface": null,
  "reservation": null,
  "resource_class": 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"
    }
  ],
  "target_power_state": null,
  "target_provision_state": null,
  "target_raid_config": {},
  "updated_at": null,
  "uuid": "6d85703a-565d-469a-96ce-30b6de53079d",
  "vendor_interface": null
}

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.

API microversion 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.

API microversion 1.9 added the provision_state Request parameter, allowing the list of returned Nodes to be filtered by their current state.

API microversion 1.16 added the driver Request parameter, allowing the list of returned Nodes to be filtered by their driver name.

API microversion 1.21 added the resource_class Request parameter, allowing the list of returned Nodes to be filtered by this field.

Normal response codes: 200

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. Introduced in API version 1.21.
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 the 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. Added in API microversion 1.5
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

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}

Normal response codes: 200

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. Introduced in API version 1.21.
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 the 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. Added in API microversion 1.5
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”, “power off”, or “rebooting”. Added new target power states “soft power off” and “soft rebooting” in API microversion 1.27.
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
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.
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. Added in API microversion 1.24.
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. This will be used by the openstack Placement Engine in a future release. Added in API microversion 1.21.
boot_interface	body	string	The boot interface for a Node, e.g. “pxe”. Added in API microversion 1.31.
console_interface	body	string	The console interface for a node, e.g. “no-console”. Added in API microversion 1.31.
deploy_interface	body	string	The deploy interface for a node, e.g. “iscsi”. Added in API microversion 1.31.
inspect_interface	body	string	The interface used for node inspection, e.g. “no-inspect”. Added in API microversion 1.31.
management_interface	body	string	Interface for out-of-band node management, e.g. “ipmitool”. Added in API microversion 1.31.
network_interface	body	string	Which Network Interface provider to use when plumbing the network connections for this Node. Added in API microversion v1.20
power_interface	body	string	Interface used for performing power actions on the node, e.g. “ipmitool”. Added in API microversion 1.31.
raid_interface	body	string	Interface used for configuring RAID on this node, e.g. “no-raid”. Added in API microversion 1.31.
vendor_interface	body	string	Interface for vendor-specific functionality on this node, e.g. “no-vendor”. Added in API microversion 1.31.

Example detailed list of Nodes:

{
  "nodes": [
    {
      "boot_interface": null,
      "chassis_uuid": null,
      "clean_step": {},
      "console_enabled": false,
      "console_interface": null,
      "created_at": "2016-08-18T22:28:48.643434+11:11",
      "deploy_interface": 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,
      "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_interface": "flat",
      "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": {},
      "provision_state": "available",
      "provision_updated_at": "2016-08-18T22:28:49.946416+00:00",
      "raid_config": {},
      "raid_interface": null,
      "reservation": null,
      "resource_class": 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"
        }
      ],
      "target_power_state": null,
      "target_provision_state": null,
      "target_raid_config": {},
      "updated_at": "2016-08-18T22:28:49.653974+00:00",
      "uuid": "6d85703a-565d-469a-96ce-30b6de53079d",
      "vendor_interface": null
    },
    {
      "boot_interface": "pxe",
      "chassis_uuid": null,
      "clean_step": {},
      "console_enabled": false,
      "console_interface": "no-console",
      "created_at": "2016-08-18T22:28:48.643434+11:11",
      "deploy_interface": "iscsi",
      "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,
      "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_interface": "flat",
      "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": {},
      "provision_state": "enroll",
      "provision_updated_at": null,
      "raid_config": {},
      "raid_interface": "no-raid",
      "reservation": null,
      "resource_class": 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"
        }
      ],
      "target_power_state": null,
      "target_provision_state": null,
      "target_raid_config": {},
      "updated_at": null,
      "uuid": "2b045129-a906-46af-bc1a-092b294b3428",
      "vendor_interface": "no-vendor"
    }
  ]
}

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.

Normal response codes: 200

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. Added in API microversion 1.5
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”, “power off”, or “rebooting”. Added new target power states “soft power off” and “soft rebooting” in API microversion 1.27.
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
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.
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. Added in API microversion 1.24.
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. This will be used by the openstack Placement Engine in a future release. Added in API microversion 1.21.
boot_interface	body	string	The boot interface for a Node, e.g. “pxe”. Added in API microversion 1.31.
console_interface	body	string	The console interface for a node, e.g. “no-console”. Added in API microversion 1.31.
deploy_interface	body	string	The deploy interface for a node, e.g. “iscsi”. Added in API microversion 1.31.
inspect_interface	body	string	The interface used for node inspection, e.g. “no-inspect”. Added in API microversion 1.31.
management_interface	body	string	Interface for out-of-band node management, e.g. “ipmitool”. Added in API microversion 1.31.
network_interface	body	string	Which Network Interface provider to use when plumbing the network connections for this Node. Added in API microversion v1.20
power_interface	body	string	Interface used for performing power actions on the node, e.g. “ipmitool”. Added in API microversion 1.31.
raid_interface	body	string	Interface used for configuring RAID on this node, e.g. “no-raid”. Added in API microversion 1.31.
vendor_interface	body	string	Interface for vendor-specific functionality on this node, e.g. “no-vendor”. Added in API microversion 1.31.

Example JSON representation of a Node:

{
  "boot_interface": null,
  "chassis_uuid": null,
  "clean_step": {},
  "console_enabled": false,
  "console_interface": null,
  "created_at": "2016-08-18T22:28:48.643434+11:11",
  "deploy_interface": 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,
  "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_interface": "flat",
  "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": {},
  "provision_state": "available",
  "provision_updated_at": "2016-08-18T22:28:49.946416+00:00",
  "raid_config": {},
  "raid_interface": null,
  "reservation": null,
  "resource_class": 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"
    }
  ],
  "target_power_state": null,
  "target_provision_state": null,
  "target_raid_config": {},
  "updated_at": "2016-08-18T22:28:49.653974+00:00",
  "uuid": "6d85703a-565d-469a-96ce-30b6de53079d",
  "vendor_interface": null
}

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.

API microversion 1.25 introduced the ability to unset a node’s chassis UUID.

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
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. Added in API microversion 1.5
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”, “power off”, or “rebooting”. Added new target power states “soft power off” and “soft rebooting” in API microversion 1.27.
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
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.
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. Added in API microversion 1.24.
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. This will be used by the openstack Placement Engine in a future release. Added in API microversion 1.21.
boot_interface	body	string	The boot interface for a Node, e.g. “pxe”. Added in API microversion 1.31.
console_interface	body	string	The console interface for a node, e.g. “no-console”. Added in API microversion 1.31.
deploy_interface	body	string	The deploy interface for a node, e.g. “iscsi”. Added in API microversion 1.31.
inspect_interface	body	string	The interface used for node inspection, e.g. “no-inspect”. Added in API microversion 1.31.
management_interface	body	string	Interface for out-of-band node management, e.g. “ipmitool”. Added in API microversion 1.31.
network_interface	body	string	Which Network Interface provider to use when plumbing the network connections for this Node. Added in API microversion v1.20
power_interface	body	string	Interface used for performing power actions on the node, e.g. “ipmitool”. Added in API microversion 1.31.
raid_interface	body	string	Interface used for configuring RAID on this node, e.g. “no-raid”. Added in API microversion 1.31.
vendor_interface	body	string	Interface for vendor-specific functionality on this node, e.g. “no-vendor”. Added in API microversion 1.31.

Example JSON representation of a Node:

{
  "boot_interface": null,
  "chassis_uuid": null,
  "clean_step": {},
  "console_enabled": false,
  "console_interface": null,
  "created_at": "2016-08-18T22:28:48.643434+11:11",
  "deploy_interface": null,
  "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,
  "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_interface": "flat",
  "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": {},
  "provision_state": "available",
  "provision_updated_at": "2016-08-18T22:28:49.946416+00:00",
  "raid_config": {},
  "raid_interface": null,
  "reservation": null,
  "resource_class": 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"
    }
  ],
  "target_power_state": null,
  "target_provision_state": null,
  "target_raid_config": {},
  "updated_at": "2016-08-18T22:28:49.653974+00:00",
  "uuid": "6d85703a-565d-469a-96ce-30b6de53079d",
  "vendor_interface": null
}

DELETE

/v1/nodes/{node_ident}

Delete Node

Deletes a node.

Normal response codes: 204

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
power	body	object	Status of the “power” interface
boot	body	object	Status of the “boot” interface
deploy	body	object	Status of the “deploy” interface
console	body	object	Status of the “console” interface
management	body	object	Status of the “management” interface
inspect	body	object	Status of the “inspect” interface
raid	body	object	Status of the “raid” 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
  }
}

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	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)

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, raid, and console status.

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”, “power off”, or “rebooting”. Added new target power states “soft power off” and “soft rebooting” in API microversion 1.27.
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.

Example node state:

{
  "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": {},
  "target_power_state": null,
  "target_provision_state": null,
  "target_raid_config": {}
}

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)

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”, or “rebooting”. Added new target power states “soft power off” and “soft rebooting” in API microversion 1.27.
timeout (Optional)	body	integer	Timeout for a power state transition. Added in API microversion 1.27.

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.

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	One of the provisioning verbs: manage, provide, inspect, clean, active, rebuild, delete (deleted), abort.
configdrive (Optional)	body	string or gzip+b64 blob	A gzip’ed and base-64 encoded config drive, to be written to a partition on the Node’s boot disk. This parameter is only accepted when setting the state to “active”.
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.

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 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

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.

Added in API microversion: 1.12

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.

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. Unparseable 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.

VIFs (Virtual Interfaces) of nodes¶

Starting with API 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

Response¶

Name	In	Type	Description
id	body	string	The UUID or name of the VIF. Added in API microversion 1.28.
vifs	body	array	VIFs attached to this node. Added in API microversion 1.28.
node_ident	path	string	The UUID or Name of the node.

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. Added in API microversion 1.28.
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

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. Added in API microversion 1.28.

Detach VIF from a Node.

Normal response code: 204

Error codes: 400,401,403,404

Portgroups (portgroups)¶

Starting with API 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.

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. Added in API microversion 1.23.
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. Added in API microversion 1.23.
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 the 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. Added in API microversion 1.23.
uuid	body	string	The UUID for the resource.
address	body	string	Physical hardware address of this Portgroup, typically the hardware MAC address. Added in API microversion 1.23.
name (Optional)	body	string	Human-readable identifier for the Portgroup resource. May be undefined. Added in API microversion 1.23.
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	body	string	Physical hardware address of this Portgroup, typically the hardware MAC address. Added in API microversion 1.23.

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 (Optional)	body	string	Human-readable identifier for the Portgroup resource. May be undefined. Added in API microversion 1.23.
address	body	string	Physical hardware address of this Portgroup, typically the hardware MAC address. Added in API microversion 1.23.
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. Added in API microversion 1.23.
internal_info	body	JSON	Internal metadata set and stored by the Portgroup. This field is read-only. Added in API microversion 1.23.
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. Added in API microversion 1.26.
properties	body	JSON	Key/value properties related to the port group’s configuration. Added in API microversion 1.26.
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. Added in API microversion 1.24.

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. Added in API microversion 1.23.
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. Added in API microversion 1.23.
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 the 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. Added in API microversion 1.23.
name (Optional)	body	string	Human-readable identifier for the Portgroup resource. May be undefined. Added in API microversion 1.23.
uuid	body	string	The UUID for the resource.
address	body	string	Physical hardware address of this Portgroup, typically the hardware MAC address. Added in API microversion 1.23.
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. Added in API microversion 1.23.
internal_info	body	JSON	Internal metadata set and stored by the Portgroup. This field is read-only. Added in API microversion 1.23.
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. Added in API microversion 1.26.
properties	body	JSON	Key/value properties related to the port group’s configuration. Added in API microversion 1.26.
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. Added in API microversion 1.24.

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_id}

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_id path string The UUID or Name of the portgroup. Added in API microversion 1.23.

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 Portgroup resource. May be undefined. Added in API microversion 1.23.
address	body	string	Physical hardware address of this Portgroup, typically the hardware MAC address. Added in API microversion 1.23.
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. Added in API microversion 1.23.
internal_info	body	JSON	Internal metadata set and stored by the Portgroup. This field is read-only. Added in API microversion 1.23.
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. Added in API microversion 1.26.
properties	body	JSON	Key/value properties related to the port group’s configuration. Added in API microversion 1.26.
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. Added in API microversion 1.24.

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_id}

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_id	path	string	The UUID or Name of the portgroup. Added in API microversion 1.23.

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 (Optional)	body	string	Human-readable identifier for the Portgroup resource. May be undefined. Added in API microversion 1.23.
address	body	string	Physical hardware address of this Portgroup, typically the hardware MAC address. Added in API microversion 1.23.
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. Added in API microversion 1.23.
internal_info	body	JSON	Internal metadata set and stored by the Portgroup. This field is read-only. Added in API microversion 1.23.
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. Added in API microversion 1.26.
properties	body	JSON	Key/value properties related to the port group’s configuration. Added in API microversion 1.26.
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. Added in API microversion 1.24.

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_id}

Delete Portgroup

Delete a Portgroup.

Normal response code: 204

Error codes: 400,401,403,404

Request¶

Name	In	Type	Description
portgroup_id	path	string	The UUID or Name of the portgroup. Added in API microversion 1.23.

Listing Portgroups by Node (nodes, portgroups)¶

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.

Portgroup resource was added in API microversion 1.24, if using older version, all the requests return Not Found (404) error code.

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 the 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. Added in API microversion 1.23.
uuid	body	string	The UUID for the resource.
address	body	string	Physical hardware address of this Portgroup, typically the hardware MAC address. Added in API microversion 1.23.
name (Optional)	body	string	Human-readable identifier for the Portgroup resource. May be undefined. Added in API microversion 1.23.
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 the 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. Added in API microversion 1.23.
uuid	body	string	The UUID for the resource.
address	body	string	Physical hardware address of this Portgroup, typically the hardware MAC address. Added in API microversion 1.23.
name (Optional)	body	string	Human-readable identifier for the Portgroup resource. May be undefined. Added in API microversion 1.23.
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. Added in API microversion 1.23.
internal_info	body	JSON	Internal metadata set and stored by the Portgroup. This field is read-only. Added in API microversion 1.23.
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. Added in API microversion 1.26.
properties	body	JSON	Key/value properties related to the port group’s configuration. Added in API microversion 1.26.
ports	body	array	Links to the collection of ports belonging to this portgroup. Added in API microversion 1.24.
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 (eg, 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.

node query parameter was added in API microversion 1.6. If both node_uuid and node are specified in the request, node_uuid will be used to filter results.

API microversion 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.

API microversion 1.19 added the pxe_enabled and local_link_connection fields.

API microversion 1.24 added the portgroup_uuid 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.
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.
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. Added in API microversion 1.24.
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.
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 the 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 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).

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.

Example Port creation request:

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

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. Added in API microversion 1.23.
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. Added in API microversion 1.19.
pxe_enabled	body	boolean	Indicates whether PXE is enabled or disabled on the Port. Added in API microversion 1.19.
internal_info	body	JSON	Internal metadata set and stored by the Port. This field is read-only. Added in API microversion 1.18.
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.

Example Port 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/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",
  "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.

node query parameter was added in API microversion 1.6. If both node_uuid and node are specified in the request, node_uuid will be used to filter results.

portgroup query parameter and portgroup_uuid response field were added in API microversion 1.24.

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.
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.
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. Added in API microversion 1.24.
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.
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 the 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. Added in API microversion 1.23.
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. Added in API microversion 1.19.
pxe_enabled	body	boolean	Indicates whether PXE is enabled or disabled on the Port. Added in API microversion 1.19.
internal_info	body	JSON	Internal metadata set and stored by the Port. This field is read-only. Added in API microversion 1.18.
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.

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": {},
      "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",
      "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.

API microversion 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.

portgroup query parameter and portgroup_uuid response field were added in API microversion 1.24.

Normal response code: 200

Request¶

Name In Type Description

port_id path string The UUID 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. Added in API microversion 1.23.
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. Added in API microversion 1.19.
pxe_enabled	body	boolean	Indicates whether PXE is enabled or disabled on the Port. Added in API microversion 1.19.
internal_info	body	JSON	Internal metadata set and stored by the Port. This field is read-only. Added in API microversion 1.18.
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.

Example Port 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/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",
  "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.

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 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. Added in API microversion 1.23.
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. Added in API microversion 1.19.
pxe_enabled	body	boolean	Indicates whether PXE is enabled or disabled on the Port. Added in API microversion 1.19.
internal_info	body	JSON	Internal metadata set and stored by the Port. This field is read-only. Added in API microversion 1.18.
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.

Example Port 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/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",
  "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 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.

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 the 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.

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 the 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. Added in API microversion 1.19.
pxe_enabled	body	boolean	Indicates whether PXE is enabled or disabled on the Port. Added in API microversion 1.19.
internal_info	body	JSON	Internal metadata set and stored by the Port. This field is read-only. Added in API microversion 1.18.
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.

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": {},
      "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",
      "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)¶

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.

/v1/portgroups/{portgroup_ident}/ports endpoint was added in API microversion 1.24, if using older version, all the requests return Not Found (404) error code.

GET

/v1/portgroups/{portgroup_ident}/ports

List Ports by Portgroup

Return a list of bare metal Ports associated with portgroup_ident.

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. Added in API microversion 1.23.
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 the 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.

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. Added in API microversion 1.23.
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 the 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. Added in API microversion 1.19.
pxe_enabled	body	boolean	Indicates whether PXE is enabled or disabled on the Port. Added in API microversion 1.19.
internal_info	body	JSON	Internal metadata set and stored by the Port. This field is read-only. Added in API microversion 1.18.
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. Added in API microversion 1.23.
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 Portgroup’s Ports:

{
  "ports": [
    {
      "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/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",
      "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"
    }
  ]
}

Drivers (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.

As of API version 1.30, the REST API also exposes information about dynamic drivers. 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.

Normal response codes: 200

Request¶

Name	In	Type	Description
type (Optional)	query	string	Only list drivers of this type. Options are “classic” or “dynamic”. Added in API microversion 1.30.
detail (Optional)	query	boolean	Whether to show detailed information about the drivers (e.g. the “boot_interface” field). Added in API microversion 1.30.

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. Added in API microversion 1.14.

Additionally, if the request has the “detail” URL parameter set to true, each driver will also include the following fields.

Name	In	Type	Description
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. Added in API microversion 1.30.
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. Added in API microversion 1.30.
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. Added in API microversion 1.30.
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. Added in API microversion 1.30.
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. Added in API microversion 1.30.
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. Added in API microversion 1.30.
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. Added in API microversion 1.30.
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. Added in API microversion 1.30.
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. Added in API microversion 1.30.
enabled_boot_interfaces	body	list	The enabled boot interfaces for this driver. Added in API microversion 1.30.
enabled_console_interfaces	body	list	The enabled console interfaces for this driver. Added in API microversion 1.30.
enabled_deploy_interfaces	body	list	The enabled deploy interfaces for this driver. Added in API microversion 1.30.
enabled_inspect_interfaces	body	list	The enabled inspection interfaces for this driver. Added in API microversion 1.30.
enabled_management_interfaces	body	list	The enabled management interfaces for this driver. Added in API microversion 1.30.
enabled_network_interfaces	body	list	The enabled network interfaces for this driver. Added in API microversion 1.30.
enabled_power_interfaces	body	list	The enabled power interfaces for this driver. Added in API microversion 1.30.
enabled_raid_interfaces	body	list	The enabled RAID interfaces for this driver. Added in API microversion 1.30.
enabled_vendor_interfaces	body	list	The enabled vendor interfaces for this driver. Added in API microversion 1.30.

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_boot_interface": null,
      "default_console_interface": null,
      "default_deploy_interface": null,
      "default_inspect_interface": null,
      "default_management_interface": null,
      "default_network_interface": null,
      "default_power_interface": null,
      "default_raid_interface": null,
      "default_vendor_interface": null,
      "enabled_boot_interfaces": null,
      "enabled_console_interfaces": null,
      "enabled_deploy_interfaces": null,
      "enabled_inspect_interfaces": null,
      "enabled_management_interfaces": null,
      "enabled_network_interfaces": null,
      "enabled_power_interfaces": null,
      "enabled_raid_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_boot_interface": null,
      "default_console_interface": null,
      "default_deploy_interface": null,
      "default_inspect_interface": null,
      "default_management_interface": null,
      "default_network_interface": null,
      "default_power_interface": null,
      "default_raid_interface": null,
      "default_vendor_interface": null,
      "enabled_boot_interfaces": null,
      "enabled_console_interfaces": null,
      "enabled_deploy_interfaces": null,
      "enabled_inspect_interfaces": null,
      "enabled_management_interfaces": null,
      "enabled_network_interfaces": null,
      "enabled_power_interfaces": null,
      "enabled_raid_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_boot_interface": "pxe",
      "default_console_interface": "no-console",
      "default_deploy_interface": "iscsi",
      "default_inspect_interface": "no-inspect",
      "default_management_interface": "ipmitool",
      "default_network_interface": "flat",
      "default_power_interface": "ipmitool",
      "default_raid_interface": "no-raid",
      "default_vendor_interface": "no-vendor",
      "enabled_boot_interfaces": [
        "pxe"
      ],
      "enabled_console_interfaces": [
        "no-console"
      ],
      "enabled_deploy_interfaces": [
        "iscsi",
        "direct"
      ],
      "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_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.

Normal response codes: 200

Request¶

Name	In	Type	Description
driver_name	path	string	The name of the driver.

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_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. Added in API microversion 1.30.
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. Added in API microversion 1.30.
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. Added in API microversion 1.30.
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. Added in API microversion 1.30.
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. Added in API microversion 1.30.
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. Added in API microversion 1.30.
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. Added in API microversion 1.30.
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. Added in API microversion 1.30.
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. Added in API microversion 1.30.
enabled_boot_interfaces	body	list	The enabled boot interfaces for this driver. Added in API microversion 1.30.
enabled_console_interfaces	body	list	The enabled console interfaces for this driver. Added in API microversion 1.30.
enabled_deploy_interfaces	body	list	The enabled deploy interfaces for this driver. Added in API microversion 1.30.
enabled_inspect_interfaces	body	list	The enabled inspection interfaces for this driver. Added in API microversion 1.30.
enabled_management_interfaces	body	list	The enabled management interfaces for this driver. Added in API microversion 1.30.
enabled_network_interfaces	body	list	The enabled network interfaces for this driver. Added in API microversion 1.30.
enabled_power_interfaces	body	list	The enabled power interfaces for this driver. Added in API microversion 1.30.
enabled_raid_interfaces	body	list	The enabled RAID interfaces for this driver. Added in API microversion 1.30.
enabled_vendor_interfaces	body	list	The enabled vendor interfaces for this driver. Added in API microversion 1.30.
links	body	array	A list of relative links. Includes the self and bookmark links.
properties	body	array	A list of links to driver properties. Added in API microversion 1.14.

Response Example¶

{
  "default_boot_interface": "pxe",
  "default_console_interface": "no-console",
  "default_deploy_interface": "iscsi",
  "default_inspect_interface": "no-inspect",
  "default_management_interface": "ipmitool",
  "default_network_interface": "flat",
  "default_power_interface": "ipmitool",
  "default_raid_interface": "no-raid",
  "default_vendor_interface": "no-vendor",
  "enabled_boot_interfaces": [
    "pxe"
  ],
  "enabled_console_interfaces": [
    "no-console"
  ],
  "enabled_deploy_interfaces": [
    "iscsi",
    "direct"
  ],
  "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_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 doman 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_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

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.

This resource was added in API microversion 1.12.

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.

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. Unparseable 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.

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 the 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	body	string	Descriptive text about the Ironic service.
extra	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
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.

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.

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 the 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

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": [
    {
      "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

Beginning with the v1.22 API, 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, including instance-specific information such as the configdrive.

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 a subset of Node fields, 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

Beginning with the v1.22 API, 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

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.

updated: Fri Jun 16 12:12:10 2017, commit 6fcf371

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