Bare Metal API

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
  },
  "heartbeat": {
    "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, eg. /vendor_passthru?method=lookup. The contents of the HTTP request are forwarded to the driver and validated there.

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

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

GET
/v1/drivers/{driver_name}/vendor_passthru/methods

List Methods

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

Normal response code: 200

Request

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

Response Parameters

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.

Response Example

The response BODY is a dictionary whose keys are a method_name. The value of each item is itself a dictionary describing how to interact with that method.

{
  "lookup": {
    "async": false,
    "attach": false,
    "description": "",
    "http_methods": [
      "POST"
    ]
  }
}
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 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

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.

This deprecates the agent-driver specific vendor_passthru method of the same name, previously accessible at /v1/drivers/agent_*/vendor_passthru?method=lookup.

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.

This deprecates the agent-driver specific vendor_passthru method of the same name, previously accessible at /v1/nodes/{node_ident}/vendor_passthru?method=heartbeat.

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.
Creative Commons Attribution 3.0 License

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