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-Versionheader or the new standard singular headerOpenStack-API-Version: baremetal <version>.
The Version APIs work differently from other APIs as they do not require authentication.
Upon the Dalmatian release, all API requests support the
new standard singular header OpenStack-API-Version: baremetal <version>.
If that’s not present, we fall back to the legacy headers.
Beginning with the Kilo release, all API requests support the
X-OpenStack-Ironic-API-Version header. This header SHOULD be supplied
with every request; in the absence of this header, each request is treated
as though coming from an older pre-Kilo client. This was done to preserve
backwards compatibility as we introduced new features in the server.
If you try to use a feature with an API version older than when that feature
was introduced the ironic service will respond as would before that feature
existed. For example if a new API URL was added, and you try to make a request
with an older API version, then you will get a Not Found (404) error, or if
a new field was added to an existing API and you request an older API version
then you will get an Invalid Parameter response.
This fetches all the information about all known major API versions in the deployment. Links to more specific information will be provided for each major API version, as well as information about supported min and max microversions.
Normal response codes: 200
Request¶
Response Example¶
Name |
In |
Type |
Description |
|---|---|---|---|
description |
body |
string |
Descriptive text about the Ironic service. |
versions |
body |
array |
Array of information about currently supported versions. |
version |
body |
string |
Versioning of this API response, eg. “1.22”. |
id |
body |
string |
Major API version, eg, “v1” |
links |
body |
array |
A list of relative links. Includes the self and bookmark links. |
min_version |
header |
string |
Minimum API microversion supported by this endpoint, eg. “1.1” |
{
"default_version": {
"id": "v1",
"links": [
{
"href": "http://127.0.0.1:6385/v1/",
"rel": "self"
}
],
"min_version": "1.1",
"status": "CURRENT",
"version": "1.37"
},
"description": "Ironic is an OpenStack project which enables the provision and management of baremetal machines.",
"name": "OpenStack Ironic API",
"versions": [
{
"id": "v1",
"links": [
{
"href": "http://127.0.0.1:6385/v1/",
"rel": "self"
}
],
"min_version": "1.1",
"status": "CURRENT",
"version": "1.37"
}
]
}
Show all the resources within the Ironic v1 API.
Normal response codes: 200
Request¶
Response Example¶
Name |
In |
Type |
Description |
|---|---|---|---|
id |
body |
string |
Major API version, eg, “v1” |
links |
body |
array |
A list of relative links. Includes the self and bookmark links. |
openstack-request-id (Optional) |
header |
string |
A unique ID for tracking the request. The request ID associated with the request appears in the log lines for that request. By default, the middleware configuration ensures that the request ID appears in the log files. |
x-openstack-ironic-api-version |
header |
string |
Specific API microversion used to generate this response. |
x-openstack-ironic-api-min-version |
header |
string |
Minimum API microversion supported by this endpoint, eg. “1.1” |
x-openstack-ironic-api-max-version |
header |
string |
Maximum API microversion supported by this endpoint, eg. “1.22” |
{
"chassis": [
{
"href": "http://127.0.0.1:6385/v1/chassis/",
"rel": "self"
},
{
"href": "http://127.0.0.1:6385/chassis/",
"rel": "bookmark"
}
],
"drivers": [
{
"href": "http://127.0.0.1:6385/v1/drivers/",
"rel": "self"
},
{
"href": "http://127.0.0.1:6385/drivers/",
"rel": "bookmark"
}
],
"heartbeat": [
{
"href": "http://127.0.0.1:6385/v1/heartbeat/",
"rel": "self"
},
{
"href": "http://127.0.0.1:6385/heartbeat/",
"rel": "bookmark"
}
],
"id": "v1",
"links": [
{
"href": "http://127.0.0.1:6385/v1/",
"rel": "self"
},
{
"href": "https://docs.openstack.org/ironic/latest/contributor/webapi.html",
"rel": "describedby",
"type": "text/html"
}
],
"lookup": [
{
"href": "http://127.0.0.1:6385/v1/lookup/",
"rel": "self"
},
{
"href": "http://127.0.0.1:6385/lookup/",
"rel": "bookmark"
}
],
"media_types": [
{
"base": "application/json",
"type": "application/vnd.openstack.ironic.v1+json"
}
],
"nodes": [
{
"href": "http://127.0.0.1:6385/v1/nodes/",
"rel": "self"
},
{
"href": "http://127.0.0.1:6385/nodes/",
"rel": "bookmark"
}
],
"portgroups": [
{
"href": "http://127.0.0.1:6385/v1/portgroups/",
"rel": "self"
},
{
"href": "http://127.0.0.1:6385/portgroups/",
"rel": "bookmark"
}
],
"ports": [
{
"href": "http://127.0.0.1:6385/v1/ports/",
"rel": "self"
},
{
"href": "http://127.0.0.1:6385/ports/",
"rel": "bookmark"
}
],
"volume": [
{
"href": "http://127.0.0.1:6385/v1/volume/",
"rel": "self"
},
{
"href": "http://127.0.0.1:6385/volume/",
"rel": "bookmark"
}
]
}
Nodes (nodes)¶
List, Searching, Creating, Updating, and Deleting of bare metal Node resources
are done through the /v1/nodes resource. There are also several sub-resources,
which allow further actions to be performed on a bare metal Node.
A Node is the canonical representation of a discretely allocatable server,
capable of running an Operating System. Each Node must be associated with a
driver; this informs Ironic what protocol to use when managing the Node.
Changed in version 1.6: A Node may be referenced both by its UUID and by a unique human-readable
“name” in any request. Throughout this documentation, this is referred to as
the node_ident. Responses clearly indicate whether a given field is a
uuid or a name.
Changed in version 1.91: In older API versions, we have a pecan feature enabled that strips .json
extensions from the end of a resource reference query and treat it as if it
was referenced by just its UUID or node_ident. E.g.
0178-0c2c-9c26-ca69-3011-a9dd.json, is treated as
0178-0c2c-9c26-ca69-3011-a9dd. This feature is now disabled in newer API
versions.
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
“******”.
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.
Added in version 1.2: Added available state name, which replaced None as the status of an
unprovisioned Node. All clients should be updated to use the new
available state name. Nodes in the available state may have
workloads provisioned on them; they are “available” for use.
Added in version 1.5: Introduced the name field.
Added in version 1.7: Introduced the clean_step field.
Changed in version 1.11: The default initial state of newly-created Nodes from available to
enroll. This provides users a workflow to verify the manageability of a
Node and perform necessary operational functions (eg, building a RAID array)
before making the Node available for provisioning.
Added in version 1.12: Introduced support for the raid_config and target_raid_config fields.
Added in version 1.20: Introduced the network_interface field. If this field is not supplied
when creating the Node, the default value will be used.
Added in version 1.21: Introduced the resource_class field, which may be used to store a
resource designation for the proposed OpenStack Placement Engine. This field
has no effect within Ironic.
Added in version 1.31: Introduced the boot_interface, deploy_interface,
management_interface, power_interface, inspect_interface,
console_interface, vendor_interface and raid_interface fields. If
any of these fields are not supplied when creating the Node, their default
value will be used.
Changed in version 1.31: If the specified driver is a dynamic driver, then all the interfaces (boot_interface, deploy_interface, etc.) will be set to the default interface for that driver unless another enabled interface is specified in the creation request.
Added in version 1.33: Introduced the storage_interface field. If this field is not supplied
when creating the Node, the default value will be used.
Added in version 1.38: Introduced the rescue_interface field. If this field is not supplied
when creating the Node, the default value will be used.
Added in version 1.44: Introduced the deploy_step field.
Added in version 1.46: Introduced the conductor_group field.
Added in version 1.50: Introduced the owner field.
Added in version 1.51: Introduced the description field.
Added in version 1.52: Introduced the allocation_uuid field.
Added in version 1.65: Introduced the lessee field.
Added in version 1.82: Introduced the shard field.
Normal response codes: 201
Error codes: 400,403,406
Request¶
Name |
In |
Type |
Description |
|---|---|---|---|
boot_interface (Optional) |
body |
string |
The boot interface for a Node, e.g. “pxe”. |
conductor_group (Optional) |
body |
string |
The conductor group for a node. Case-insensitive string up to 255
characters, containing |
console_interface (Optional) |
body |
string |
The console interface for a node, e.g. “no-console”. |
deploy_interface (Optional) |
body |
string |
The deploy interface for a node, e.g. “iscsi”. |
disable_power_off (Optional) |
body |
boolean |
If set to |
driver_info (Optional) |
body |
JSON |
All the metadata required by the driver to manage this Node. List of fields
varies between drivers, and can be retrieved from the
|
driver |
body |
string |
The name of the driver used to manage this Node. |
extra (Optional) |
body |
object |
A set of one or more arbitrary metadata key and value pairs. |
inspect_interface (Optional) |
body |
string |
The interface used for node inspection, e.g. “no-inspect”. |
management_interface (Optional) |
body |
string |
Interface for out-of-band node management, e.g. “ipmitool”. |
name (Optional) |
body |
string |
Human-readable identifier for the Node resource. May be undefined. Certain words are reserved. |
network_interface (Optional) |
body |
string |
Which Network Interface provider to use when plumbing the network connections for this Node. |
power_interface (Optional) |
body |
string |
Interface used for performing power actions on the node, e.g. “ipmitool”. |
properties (Optional) |
body |
JSON |
Physical characteristics of this Node. Populated during inspection, if performed. Can be edited via the REST API at any time. |
raid_interface (Optional) |
body |
string |
Interface used for configuring RAID on this node, e.g. “no-raid”. |
rescue_interface (Optional) |
body |
string |
The interface used for node rescue, e.g. “no-rescue”. |
resource_class (Optional) |
body |
string |
A string which can be used by external schedulers to identify this Node as a unit of a specific type of resource. |
storage_interface (Optional) |
body |
string |
Interface used for attaching and detaching volumes on this node, e.g. “cinder”. |
uuid (Optional) |
body |
string |
The UUID for the resource. |
vendor_interface (Optional) |
body |
string |
Interface for vendor-specific functionality on this node, e.g. “no-vendor”. |
owner (Optional) |
body |
string |
A string or UUID of the tenant who owns the object. |
description (Optional) |
body |
string |
Informational text about this node. |
lessee (Optional) |
body |
string |
A string or UUID of the tenant who is leasing the object. |
shard (Optional) |
body |
string |
A string indicating the shard this node belongs to. |
automated_clean (Optional) |
body |
boolean |
Indicates whether the node will perform automated clean or not. |
bios_interface (Optional) |
body |
string |
The bios interface to be used for this node. |
chassis_uuid (Optional) |
body |
string |
UUID of the chassis associated with this Node. May be empty or None. |
instance_info (Optional) |
body |
JSON |
Information used to customize the deployed image. May include root partition size, a base 64 encoded config drive, and other metadata. Note that this field is erased automatically when the instance is deleted (this is done by requesting the Node provision state be changed to DELETED). |
instance_uuid (Optional) |
body |
string |
UUID of the Nova instance associated with this Node. |
maintenance (Optional) |
body |
boolean |
Whether or not this Node is currently in “maintenance mode”. Setting a Node into maintenance mode removes it from the available resource pool and halts some internal automation. This can happen manually (eg, via an API request) or automatically when Ironic detects a hardware fault that prevents communication with the machine. |
maintenance_reason (Optional) |
body |
string |
User-settable description of the reason why this Node was placed into maintenance mode |
network_data (Optional) |
body |
JSON |
Static network configuration in the OpenStack network data format to use during deployment and cleaning. Requires a specially crafted ramdisk, see DHCP-less documentation. |
parent_node (Optional) |
body |
string |
An optional UUID which can be used to denote the “parent” baremetal node. |
protected (Optional) |
body |
boolean |
Whether the node is protected from undeploying, rebuilding and deletion. |
protected_reason (Optional) |
body |
string |
The reason the node is marked as protected. |
retired (Optional) |
body |
boolean |
Whether the node is retired and can hence no longer be provided, i.e. move
from |
retired_reason (Optional) |
body |
string |
The reason the node is marked as retired. |
Example Node creation request with a dynamic driver:
{
"name": "test_node_dynamic",
"driver": "ipmi",
"driver_info": {
"ipmi_username": "ADMIN",
"ipmi_password": "password"
},
"power_interface": "ipmitool",
"resource_class": "bm-large"
}
Response¶
The response will contain the complete Node record, with the supplied data, and any defaults added for non-specified fields. Most fields default to “null” or “”.
The list and example below are representative of the response as of API microversion 1.95.
Name |
In |
Type |
Description |
|---|---|---|---|
uuid |
body |
string |
The UUID for the resource. |
name (Optional) |
body |
string |
Human-readable identifier for the Node resource. May be undefined. Certain words are reserved. |
power_state |
body |
string |
The current power state of this Node. Usually, “power on” or “power off”, but may be “None” if Ironic is unable to determine the power state (eg, due to hardware failure). |
target_power_state |
body |
string |
If a power state transition has been requested, this field represents the requested (ie, “target”) state, either “power on” or “power off”. |
provision_state |
body |
string |
The current provisioning state of this Node. |
target_provision_state |
body |
string |
If a provisioning action has been requested, this field represents the requested (ie, “target”) state. Note that a Node may go through several states during its transition to this target state. For instance, when requesting an instance be deployed to an AVAILABLE Node, the Node may go through the following state change progression: AVAILABLE -> DEPLOYING -> DEPLOYWAIT -> DEPLOYING -> ACTIVE |
maintenance |
body |
boolean |
Whether or not this Node is currently in “maintenance mode”. Setting a Node into maintenance mode removes it from the available resource pool and halts some internal automation. This can happen manually (eg, via an API request) or automatically when Ironic detects a hardware fault that prevents communication with the machine. |
maintenance_reason (Optional) |
body |
string |
User-settable description of the reason why this Node was placed into maintenance mode |
fault (Optional) |
body |
string |
The fault indicates the active fault detected by ironic, typically the Node is in “maintenance mode”. None means no fault has been detected by ironic. “power failure” indicates ironic failed to retrieve power state from this node. There are other possible types, e.g., “clean failure” and “rescue abort failure”. |
last_error |
body |
string |
Any error from the most recent (last) transaction that started but failed to finish. |
reservation |
body |
string |
The |
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 |
driver_internal_info (Optional) |
body |
JSON |
Internal metadata set and stored by the Node’s driver. This field is read-only. |
properties |
body |
JSON |
Physical characteristics of this Node. Populated by ironic-inspector during inspection. May be edited via the REST API at any time. |
instance_info |
body |
JSON |
Information used to customize the deployed image. May include root partition size, a base 64 encoded config drive, and other metadata. Note that this field is erased automatically when the instance is deleted (this is done by requesting the Node provision state be changed to DELETED). |
instance_uuid |
body |
string |
UUID of the Nova instance associated with this Node. |
chassis_uuid |
body |
string |
UUID of the chassis associated with this Node. May be empty or None. |
extra |
body |
object |
A set of one or more arbitrary metadata key and value pairs. |
console_enabled |
body |
boolean |
Indicates whether console access is enabled or disabled on this node. |
raid_config (Optional) |
body |
JSON |
Represents the current RAID configuration of the node. Introduced with the cleaning feature. |
target_raid_config |
body |
JSON |
Represents the requested RAID configuration of the node, which will be applied when the Node next transitions through the CLEANING state. Introduced with the cleaning feature. |
clean_step (Optional) |
body |
string |
The current clean step. Introduced with the cleaning feature. |
deploy_step (Optional) |
body |
string |
The current deploy step. |
links |
body |
array |
A list of relative links. Includes the self and bookmark links. |
ports |
body |
array |
Links to the collection of ports on this node |
portgroups |
body |
array |
Links to the collection of portgroups on this node. |
states |
body |
array |
Links to the collection of states. Note that this resource is also used to request state transitions. |
resource_class |
body |
string |
A string which can be used by external schedulers to identify this Node as a unit of a specific type of resource. For more details, see: https://docs.openstack.org/ironic/latest/install/configure-nova-flavors.html |
boot_interface |
body |
string |
The boot interface for a Node, e.g. “pxe”. |
console_interface |
body |
string |
The console interface for a node, e.g. “no-console”. |
deploy_interface |
body |
string |
The deploy interface for a node, e.g. “iscsi”. |
inspect_interface |
body |
string |
The interface used for node inspection, e.g. “no-inspect”. |
management_interface |
body |
string |
Interface for out-of-band node management, e.g. “ipmitool”. |
network_interface |
body |
string |
Which Network Interface provider to use when plumbing the network connections for this Node. |
power_interface |
body |
string |
Interface used for performing power actions on the node, e.g. “ipmitool”. |
raid_interface |
body |
string |
Interface used for configuring RAID on this node, e.g. “no-raid”. |
rescue_interface |
body |
string |
The interface used for node rescue, e.g. “no-rescue”. |
storage_interface |
body |
string |
Interface used for attaching and detaching volumes on this node, e.g. “cinder”. |
traits |
body |
array |
List of traits for this node. |
vendor_interface |
body |
string |
Interface for vendor-specific functionality on this node, e.g. “no-vendor”. |
volume |
body |
array |
Links to the volume resources. |
conductor_group |
body |
string |
The conductor group for a node. Case-insensitive string up to 255
characters, containing |
parent_node (Optional) |
body |
string |
An optional UUID which can be used to denote the “parent” baremetal node. |
protected (Optional) |
body |
boolean |
Whether the node is protected from undeploying, rebuilding and deletion. |
protected_reason (Optional) |
body |
string |
The reason the node is marked as protected. |
conductor (Optional) |
body |
string |
The conductor currently servicing a node. This field is read-only. |
owner (Optional) |
body |
string |
A string or UUID of the tenant who owns the object. |
lessee (Optional) |
body |
string |
A string or UUID of the tenant who is leasing the object. |
shard (Optional) |
body |
string |
A string indicating the shard this node belongs to. |
description |
body |
string |
Informational text about this node. |
allocation_uuid |
body |
string |
The UUID of the allocation associated with the node. If not |
automated_clean |
body |
boolean |
Indicates whether the node will perform automated clean or not. |
bios_interface |
body |
string |
The bios interface to be used for this node. |
network_data (Optional) |
body |
JSON |
Static network configuration in the OpenStack network data format to use during deployment and cleaning. Requires a specially crafted ramdisk, see DHCP-less documentation. |
retired (Optional) |
body |
boolean |
Whether the node is retired and can hence no longer be provided, i.e. move
from |
retired_reason (Optional) |
body |
string |
The reason the node is marked as retired. |
disable_power_off (Optional) |
body |
boolean |
If set to true, power off for the node is explicitly disabled, instead, a reboot will be used in place of power on/off. Additionally, when possible, the node will be disabled (i.e., its API agent will be rendered unusable and network configuration will be removed) instead of being powered off. |
Example JSON representation of a Node:
{
"allocation_uuid": null,
"boot_interface": null,
"chassis_uuid": null,
"clean_step": {},
"conductor_group": "group-1",
"console_enabled": false,
"console_interface": null,
"created_at": "2016-08-18T22:28:48.643434+11:11",
"deploy_interface": null,
"deploy_step": {},
"description": null,
"driver": "agent_ipmitool",
"driver_info": {
"ipmi_password": "******",
"ipmi_username": "ADMIN"
},
"driver_internal_info": {},
"extra": {},
"inspect_interface": null,
"inspection_finished_at": null,
"inspection_started_at": null,
"instance_info": {},
"instance_uuid": null,
"last_error": null,
"lessee": null,
"links": [
{
"href": "http://127.0.0.1:6385/v1/nodes/6d85703a-565d-469a-96ce-30b6de53079d",
"rel": "self"
},
{
"href": "http://127.0.0.1:6385/nodes/6d85703a-565d-469a-96ce-30b6de53079d",
"rel": "bookmark"
}
],
"maintenance": false,
"maintenance_reason": null,
"management_interface": null,
"name": "test_node_classic",
"network_data": {},
"network_interface": "flat",
"owner": null,
"portgroups": [
{
"href": "http://127.0.0.1:6385/v1/nodes/6d85703a-565d-469a-96ce-30b6de53079d/portgroups",
"rel": "self"
},
{
"href": "http://127.0.0.1:6385/nodes/6d85703a-565d-469a-96ce-30b6de53079d/portgroups",
"rel": "bookmark"
}
],
"ports": [
{
"href": "http://127.0.0.1:6385/v1/nodes/6d85703a-565d-469a-96ce-30b6de53079d/ports",
"rel": "self"
},
{
"href": "http://127.0.0.1:6385/nodes/6d85703a-565d-469a-96ce-30b6de53079d/ports",
"rel": "bookmark"
}
],
"power_interface": null,
"power_state": null,
"properties": {},
"protected": false,
"protected_reason": null,
"provision_state": "enroll",
"provision_updated_at": null,
"raid_config": {},
"raid_interface": null,
"rescue_interface": null,
"reservation": null,
"resource_class": "bm-large",
"retired": false,
"retired_reason": null,
"states": [
{
"href": "http://127.0.0.1:6385/v1/nodes/6d85703a-565d-469a-96ce-30b6de53079d/states",
"rel": "self"
},
{
"href": "http://127.0.0.1:6385/nodes/6d85703a-565d-469a-96ce-30b6de53079d/states",
"rel": "bookmark"
}
],
"storage_interface": "noop",
"target_power_state": null,
"target_provision_state": null,
"target_raid_config": {},
"traits": [],
"updated_at": null,
"uuid": "6d85703a-565d-469a-96ce-30b6de53079d",
"vendor_interface": null,
"volume": [
{
"href": "http://127.0.0.1:6385/v1/nodes/6d85703a-565d-469a-96ce-30b6de53079d/volume",
"rel": "self"
},
{
"href": "http://127.0.0.1:6385/nodes/6d85703a-565d-469a-96ce-30b6de53079d/volume",
"rel": "bookmark"
}
]
}
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.
Added in version 1.8: Added the fields Request parameter. When specified,
this causes the content of the Response to include only the specified fields,
rather than the default set.
Added in version 1.9: Added the provision_state Request parameter, allowing the list of
returned Nodes to be filtered by their current state.
Added in version 1.16: Added the driver Request parameter, allowing the list of returned Nodes
to be filtered by their driver name.
Added in version 1.21: Added the resource_class Request parameter, allowing the list of returned
Nodes to be filtered by this field.
Added in version 1.42: Introduced the fault field.
Added in version 1.43: Added the detail boolean request parameter. When specified True this
causes the response to include complete details about each node, as shown
in the “List Nodes Detailed” section below.
Added in version 1.46: Introduced the conductor_group request parameter, to allow filtering the
list of returned nodes by conductor group.
Added in version 1.49: Introduced the conductor request parameter, to allow filtering the
list of returned nodes by conductor.
Added in version 1.50: Introduced the owner field.
Added in version 1.51: Introduced the description field.
Added in version 1.65: Introduced the lessee field.
Added in version 1.82: Introduced the shard field. Introduced the sharded request parameter.
Added in version 1.83: Introduced the parent_node field and query parameter to identify
matching nodes.
Introduced the include_children parameter which allows for all child
nodes to be enumerated, which are normally hidden as child nodes are not
normally intended for direct consumption by end users.
Normal response codes: 200
Error codes: 400,403,406
Request¶
Name |
In |
Type |
Description |
|---|---|---|---|
instance_uuid (Optional) |
query |
string |
Filter the list of returned nodes, and only return the node with this specific instance UUID, or an empty set if not found. |
maintenance (Optional) |
query |
boolean |
Filter the list of returned nodes and only return those with
|
associated (Optional) |
query |
boolean |
Filter the list of returned nodes and only return those which are, or are
not, associated with an |
provision_state (Optional) |
query |
string |
Filter the list of returned nodes, and only return those with the specified
|
driver (Optional) |
query |
string |
Filter the list of returned nodes, and only return those with the specified
|
resource_class (Optional) |
query |
string |
Filter the list of returned nodes, and only return the ones with the specified resource class. |
conductor_group (Optional) |
query |
string |
Filter the list of returned nodes, and only return those with the
specified |
conductor (Optional) |
query |
string |
Filter the list of returned nodes, and only return those with the
specified |
fault (Optional) |
query |
string |
Filter the list of returned nodes, and only return those with the specified
|
owner (Optional) |
body |
string |
A string or UUID of the tenant who owns the object. |
lessee (Optional) |
body |
string |
A string or UUID of the tenant who is leasing the object. |
shard (Optional) |
body |
array |
Filter the list of returned Nodes, and only return the ones associated with nodes in this specific shard(s), or an empty set if not found. |
sharded (Optional) |
body |
boolean |
When true, filter the list of returned Nodes, and only return the ones with
a non-null |
description_contains (Optional) |
query |
string |
Filter the list of returned nodes, and only return those containing
substring specified by |
fields (Optional) |
query |
array |
One or more fields to be returned in the response. For example, the following request returns only the 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 |
marker (Optional) |
query |
string |
The ID of the last-seen item. Use the |
sort_dir (Optional) |
query |
string |
Sorts the response by the requested sort
direction. A valid value is |
sort_key (Optional) |
query |
string |
Sorts the response by this attribute value.
Default is |
detail (Optional) |
query |
boolean |
Whether to show detailed information about the resource. This cannot be
set to True if |
parent_node (Optional) |
body |
string |
An optional UUID which can be used to denote the “parent” baremetal node. |
include_children (Optional) |
query |
boolean |
Whether to show child nodes in the node list, which are normally hidden. |
Response¶
Name |
In |
Type |
Description |
|---|---|---|---|
uuid |
body |
string |
The UUID for the resource. |
name (Optional) |
body |
string |
Human-readable identifier for the Node resource. May be undefined. Certain words are reserved. |
instance_uuid |
body |
string |
UUID of the Nova instance associated with this Node. |
power_state |
body |
string |
The current power state of this Node. Usually, “power on” or “power off”, but may be “None” if Ironic is unable to determine the power state (eg, due to hardware failure). |
provision_state |
body |
string |
The current provisioning state of this Node. |
maintenance |
body |
boolean |
Whether or not this Node is currently in “maintenance mode”. Setting a Node into maintenance mode removes it from the available resource pool and halts some internal automation. This can happen manually (eg, via an API request) or automatically when Ironic detects a hardware fault that prevents communication with the machine. |
links |
body |
array |
A list of relative links. Includes the self and bookmark links. |
Example list of Nodes:
{
"nodes": [
{
"instance_uuid": null,
"links": [
{
"href": "http://127.0.0.1:6385/v1/nodes/6d85703a-565d-469a-96ce-30b6de53079d",
"rel": "self"
},
{
"href": "http://127.0.0.1:6385/nodes/6d85703a-565d-469a-96ce-30b6de53079d",
"rel": "bookmark"
}
],
"maintenance": false,
"name": "test_node_classic",
"power_state": "power off",
"provision_state": "available",
"uuid": "6d85703a-565d-469a-96ce-30b6de53079d"
},
{
"instance_uuid": null,
"links": [
{
"href": "http://127.0.0.1:6385/v1/nodes/2b045129-a906-46af-bc1a-092b294b3428",
"rel": "self"
},
{
"href": "http://127.0.0.1:6385/nodes/2b045129-a906-46af-bc1a-092b294b3428",
"rel": "bookmark"
}
],
"maintenance": false,
"name": "test_node_dynamic",
"power_state": null,
"provision_state": "enroll",
"uuid": "2b045129-a906-46af-bc1a-092b294b3428"
}
]
}
Deprecated since version Use: ?detail=True query string instead.
Return a list of bare metal Nodes with complete details. Some filtering is possible by passing in flags with the request.
This method is particularly useful to locate the Node associated to a given
Nova instance, eg. with a request to v1/nodes/detail?instance_uuid={NOVA INSTANCE UUID}
Added in version 1.37: Introduced the traits field.
Added in version 1.38: Introduced the rescue_interface field.
Added in version 1.42: Introduced the fault field.
Added in version 1.46: Introduced the conductor_group field.
Added in version 1.48: Introduced the protected and protected_reason fields.
Added in version 1.49: Introduced the conductor request parameter and conductor field.
Added in version 1.50: Introduced the owner field.
Added in version 1.51: Introduced the description field.
Added in version 1.52: Introduced the allocation_uuid field.
Added in version 1.65: Introduced the lessee field.
Added in version 1.82: Introduced the shard field. Introduced the sharded request parameter.
Normal response codes: 200
Error codes: 400,403,406
Request¶
Name |
In |
Type |
Description |
|---|---|---|---|
instance_uuid (Optional) |
query |
string |
Filter the list of returned nodes, and only return the node with this specific instance UUID, or an empty set if not found. |
maintenance (Optional) |
query |
boolean |
Filter the list of returned nodes and only return those with
|
fault (Optional) |
query |
string |
Filter the list of returned nodes, and only return those with the specified
|
associated (Optional) |
query |
boolean |
Filter the list of returned nodes and only return those which are, or are
not, associated with an |
provision_state (Optional) |
query |
string |
Filter the list of returned nodes, and only return those with the specified
|
driver (Optional) |
query |
string |
Filter the list of returned nodes, and only return those with the specified
|
resource_class (Optional) |
query |
string |
Filter the list of returned nodes, and only return the ones with the specified resource class. |
conductor_group (Optional) |
query |
string |
Filter the list of returned nodes, and only return those with the
specified |
conductor (Optional) |
query |
string |
Filter the list of returned nodes, and only return those with the
specified |
owner (Optional) |
body |
string |
A string or UUID of the tenant who owns the object. |
lessee (Optional) |
body |
string |
A string or UUID of the tenant who is leasing the object. |
shard (Optional) |
body |
array |
Filter the list of returned Nodes, and only return the ones associated with nodes in this specific shard(s), or an empty set if not found. |
sharded (Optional) |
body |
boolean |
When true, filter the list of returned Nodes, and only return the ones with
a non-null |
description_contains (Optional) |
query |
string |
Filter the list of returned nodes, and only return those containing
substring specified by |
limit (Optional) |
query |
integer |
Requests a page size of items. Returns a number of items up to a limit
value. Use the |
marker (Optional) |
query |
string |
The ID of the last-seen item. Use the |
sort_dir (Optional) |
query |
string |
Sorts the response by the requested sort
direction. A valid value is |
sort_key (Optional) |
query |
string |
Sorts the response by this attribute value.
Default is |
Response¶
Name |
In |
Type |
Description |
|---|---|---|---|
uuid |
body |
string |
The UUID for the resource. |
name (Optional) |
body |
string |
Human-readable identifier for the Node resource. May be undefined. Certain words are reserved. |
power_state |
body |
string |
The current power state of this Node. Usually, “power on” or “power off”, but may be “None” if Ironic is unable to determine the power state (eg, due to hardware failure). |
target_power_state |
body |
string |
If a power state transition has been requested, this field represents the requested (ie, “target”) state, either “power on” or “power off”. |
provision_state |
body |
string |
The current provisioning state of this Node. |
target_provision_state |
body |
string |
If a provisioning action has been requested, this field represents the requested (ie, “target”) state. Note that a Node may go through several states during its transition to this target state. For instance, when requesting an instance be deployed to an AVAILABLE Node, the Node may go through the following state change progression: AVAILABLE -> DEPLOYING -> DEPLOYWAIT -> DEPLOYING -> ACTIVE |
maintenance |
body |
boolean |
Whether or not this Node is currently in “maintenance mode”. Setting a Node into maintenance mode removes it from the available resource pool and halts some internal automation. This can happen manually (eg, via an API request) or automatically when Ironic detects a hardware fault that prevents communication with the machine. |
maintenance_reason (Optional) |
body |
string |
User-settable description of the reason why this Node was placed into maintenance mode |
fault (Optional) |
body |
string |
The fault indicates the active fault detected by ironic, typically the Node is in “maintenance mode”. None means no fault has been detected by ironic. “power failure” indicates ironic failed to retrieve power state from this node. There are other possible types, e.g., “clean failure” and “rescue abort failure”. |
last_error |
body |
string |
Any error from the most recent (last) transaction that started but failed to finish. |
reservation |
body |
string |
The |
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 |
driver_internal_info (Optional) |
body |
JSON |
Internal metadata set and stored by the Node’s driver. This field is read-only. |
properties |
body |
JSON |
Physical characteristics of this Node. Populated by ironic-inspector during inspection. May be edited via the REST API at any time. |
instance_info |
body |
JSON |
Information used to customize the deployed image. May include root partition size, a base 64 encoded config drive, and other metadata. Note that this field is erased automatically when the instance is deleted (this is done by requesting the Node provision state be changed to DELETED). |
instance_uuid |
body |
string |
UUID of the Nova instance associated with this Node. |
chassis_uuid |
body |
string |
UUID of the chassis associated with this Node. May be empty or None. |
extra |
body |
object |
A set of one or more arbitrary metadata key and value pairs. |
console_enabled |
body |
boolean |
Indicates whether console access is enabled or disabled on this node. |
raid_config (Optional) |
body |
JSON |
Represents the current RAID configuration of the node. Introduced with the cleaning feature. |
target_raid_config |
body |
JSON |
Represents the requested RAID configuration of the node, which will be applied when the Node next transitions through the CLEANING state. Introduced with the cleaning feature. |
clean_step (Optional) |
body |
string |
The current clean step. Introduced with the cleaning feature. |
deploy_step (Optional) |
body |
string |
The current deploy step. |
links |
body |
array |
A list of relative links. Includes the self and bookmark links. |
ports |
body |
array |
Links to the collection of ports on this node |
portgroups |
body |
array |
Links to the collection of portgroups on this node. |
states |
body |
array |
Links to the collection of states. Note that this resource is also used to request state transitions. |
resource_class |
body |
string |
A string which can be used by external schedulers to identify this Node as a unit of a specific type of resource. For more details, see: https://docs.openstack.org/ironic/latest/install/configure-nova-flavors.html |
bios_interface |
body |
string |
The bios interface to be used for this node. |
boot_interface |
body |
string |
The boot interface for a Node, e.g. “pxe”. |
console_interface |
body |
string |
The console interface for a node, e.g. “no-console”. |
deploy_interface |
body |
string |
The deploy interface for a node, e.g. “iscsi”. |
inspect_interface |
body |
string |
The interface used for node inspection, e.g. “no-inspect”. |
management_interface |
body |
string |
Interface for out-of-band node management, e.g. “ipmitool”. |
network_interface |
body |
string |
Which Network Interface provider to use when plumbing the network connections for this Node. |
power_interface |
body |
string |
Interface used for performing power actions on the node, e.g. “ipmitool”. |
raid_interface |
body |
string |
Interface used for configuring RAID on this node, e.g. “no-raid”. |
rescue_interface |
body |
string |
The interface used for node rescue, e.g. “no-rescue”. |
storage_interface |
body |
string |
Interface used for attaching and detaching volumes on this node, e.g. “cinder”. |
traits |
body |
array |
List of traits for this node. |
vendor_interface |
body |
string |
Interface for vendor-specific functionality on this node, e.g. “no-vendor”. |
volume |
body |
array |
Links to the volume resources. |
conductor_group |
body |
string |
The conductor group for a node. Case-insensitive string up to 255
characters, containing |
parent_node (Optional) |
body |
string |
An optional UUID which can be used to denote the “parent” baremetal node. |
protected (Optional) |
body |
boolean |
Whether the node is protected from undeploying, rebuilding and deletion. |
protected_reason (Optional) |
body |
string |
The reason the node is marked as protected. |
owner (Optional) |
body |
string |
A string or UUID of the tenant who owns the object. |
lessee (Optional) |
body |
string |
A string or UUID of the tenant who is leasing the object. |
shard (Optional) |
body |
string |
A string indicating the shard this node belongs to. |
description |
body |
string |
Informational text about this node. |
conductor (Optional) |
body |
string |
The conductor currently servicing a node. This field is read-only. |
allocation_uuid |
body |
string |
The UUID of the allocation associated with the node. If not |
retired (Optional) |
body |
boolean |
Whether the node is retired and can hence no longer be provided, i.e. move
from |
retired_reason (Optional) |
body |
string |
The reason the node is marked as retired. |
network_data (Optional) |
body |
JSON |
Static network configuration in the OpenStack network data format to use during deployment and cleaning. Requires a specially crafted ramdisk, see DHCP-less documentation. |
automated_clean |
body |
boolean |
Indicates whether the node will perform automated clean or not. |
service_step |
body |
JSON |
A dictionary containing the interface and step to be executed on the node. The dictionary must contain the keys ‘interface’ and ‘step’. If specified, the value for ‘args’ is a keyword variable argument dictionary that is passed to the cleaning step method. |
firmware_interface |
body |
string |
Firmware interface for a node, e.g. “redfish”. |
provision_updated_at |
body |
string |
The UTC date and time when the resource was created,
ISO 8601 format.
|
inspection_started_at |
body |
string |
The UTC date and time when the hardware inspection was started, ISO 8601 format. May be “null”. |
inspection_finished_at |
body |
string |
The UTC date and time when the last hardware inspection finished successfully, ISO 8601 format. May be “null”. |
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”. |
disable_power_off (Optional) |
body |
boolean |
If set to true, power off for the node is explicitly disabled, instead, a reboot will be used in place of power on/off. Additionally, when possible, the node will be disabled (i.e., its API agent will be rendered unusable and network configuration will be removed) instead of being powered off. |
Example detailed list of Nodes:
{
"nodes": [
{
"allocation_uuid": "5344a3e2-978a-444e-990a-cbf47c62ef88",
"boot_interface": null,
"chassis_uuid": null,
"clean_step": {},
"conductor": "compute1.localdomain",
"conductor_group": "group-1",
"console_enabled": false,
"console_interface": null,
"created_at": "2016-08-18T22:28:48.643434+11:11",
"deploy_interface": null,
"deploy_step": {},
"description": null,
"driver": "fake",
"driver_info": {
"ipmi_password": "******",
"ipmi_username": "ADMIN"
},
"driver_internal_info": {
"clean_steps": null
},
"extra": {},
"inspect_interface": null,
"inspection_finished_at": null,
"inspection_started_at": null,
"instance_info": {},
"instance_uuid": "5344a3e2-978a-444e-990a-cbf47c62ef88",
"last_error": null,
"lessee": null,
"links": [
{
"href": "http://127.0.0.1:6385/v1/nodes/6d85703a-565d-469a-96ce-30b6de53079d",
"rel": "self"
},
{
"href": "http://127.0.0.1:6385/nodes/6d85703a-565d-469a-96ce-30b6de53079d",
"rel": "bookmark"
}
],
"maintenance": false,
"maintenance_reason": null,
"management_interface": null,
"name": "test_node_classic",
"network_data": {},
"network_interface": "flat",
"owner": "john doe",
"portgroups": [
{
"href": "http://127.0.0.1:6385/v1/nodes/6d85703a-565d-469a-96ce-30b6de53079d/portgroups",
"rel": "self"
},
{
"href": "http://127.0.0.1:6385/nodes/6d85703a-565d-469a-96ce-30b6de53079d/portgroups",
"rel": "bookmark"
}
],
"ports": [
{
"href": "http://127.0.0.1:6385/v1/nodes/6d85703a-565d-469a-96ce-30b6de53079d/ports",
"rel": "self"
},
{
"href": "http://127.0.0.1:6385/nodes/6d85703a-565d-469a-96ce-30b6de53079d/ports",
"rel": "bookmark"
}
],
"power_interface": null,
"power_state": "power off",
"properties": {},
"protected": false,
"protected_reason": null,
"provision_state": "available",
"provision_updated_at": "2016-08-18T22:28:49.946416+00:00",
"raid_config": {},
"raid_interface": null,
"rescue_interface": null,
"reservation": null,
"resource_class": null,
"retired": false,
"retired_reason": null,
"states": [
{
"href": "http://127.0.0.1:6385/v1/nodes/6d85703a-565d-469a-96ce-30b6de53079d/states",
"rel": "self"
},
{
"href": "http://127.0.0.1:6385/nodes/6d85703a-565d-469a-96ce-30b6de53079d/states",
"rel": "bookmark"
}
],
"storage_interface": "noop",
"target_power_state": null,
"target_provision_state": null,
"target_raid_config": {},
"traits": [],
"updated_at": "2016-08-18T22:28:49.653974+00:00",
"uuid": "6d85703a-565d-469a-96ce-30b6de53079d",
"vendor_interface": null,
"volume": [
{
"href": "http://127.0.0.1:6385/v1/nodes/6d85703a-565d-469a-96ce-30b6de53079d/volume",
"rel": "self"
},
{
"href": "http://127.0.0.1:6385/nodes/6d85703a-565d-469a-96ce-30b6de53079d/volume",
"rel": "bookmark"
}
]
},
{
"allocation_uuid": null,
"boot_interface": "pxe",
"chassis_uuid": null,
"clean_step": {},
"conductor": "compute1.localdomain",
"conductor_group": "",
"console_enabled": false,
"console_interface": "no-console",
"created_at": "2016-08-18T22:28:48.643434+11:11",
"deploy_interface": "direct",
"deploy_step": {},
"driver": "ipmi",
"driver_info": {
"ipmi_password": "******",
"ipmi_username": "ADMIN"
},
"driver_internal_info": {},
"extra": {},
"inspect_interface": "no-inspect",
"inspection_finished_at": null,
"inspection_started_at": null,
"instance_info": {},
"instance_uuid": null,
"last_error": null,
"lessee": null,
"links": [
{
"href": "http://127.0.0.1:6385/v1/nodes/2b045129-a906-46af-bc1a-092b294b3428",
"rel": "self"
},
{
"href": "http://127.0.0.1:6385/nodes/2b045129-a906-46af-bc1a-092b294b3428",
"rel": "bookmark"
}
],
"maintenance": false,
"maintenance_reason": null,
"management_interface": "ipmitool",
"name": "test_node_dynamic",
"network_data": {},
"network_interface": "flat",
"owner": "43e61ec9-8e42-4dcb-bc45-30d66aa93e5b",
"portgroups": [
{
"href": "http://127.0.0.1:6385/v1/nodes/2b045129-a906-46af-bc1a-092b294b3428/portgroups",
"rel": "self"
},
{
"href": "http://127.0.0.1:6385/nodes/2b045129-a906-46af-bc1a-092b294b3428/portgroups",
"rel": "bookmark"
}
],
"ports": [
{
"href": "http://127.0.0.1:6385/v1/nodes/2b045129-a906-46af-bc1a-092b294b3428/ports",
"rel": "self"
},
{
"href": "http://127.0.0.1:6385/nodes/2b045129-a906-46af-bc1a-092b294b3428/ports",
"rel": "bookmark"
}
],
"power_interface": "ipmitool",
"power_state": null,
"properties": {},
"protected": false,
"protected_reason": null,
"provision_state": "enroll",
"provision_updated_at": null,
"raid_config": {},
"raid_interface": "no-raid",
"rescue_interface": "no-rescue",
"reservation": null,
"resource_class": null,
"retired": false,
"retired_reason": null,
"states": [
{
"href": "http://127.0.0.1:6385/v1/nodes/2b045129-a906-46af-bc1a-092b294b3428/states",
"rel": "self"
},
{
"href": "http://127.0.0.1:6385/nodes/2b045129-a906-46af-bc1a-092b294b3428/states",
"rel": "bookmark"
}
],
"storage_interface": "noop",
"target_power_state": null,
"target_provision_state": null,
"target_raid_config": {},
"traits": [],
"updated_at": null,
"uuid": "2b045129-a906-46af-bc1a-092b294b3428",
"vendor_interface": "no-vendor",
"volume": [
{
"href": "http://127.0.0.1:6385/v1/nodes/2b045129-a906-46af-bc1a-092b294b3428/volume",
"rel": "self"
},
{
"href": "http://127.0.0.1:6385/nodes/2b045129-a906-46af-bc1a-092b294b3428/volume",
"rel": "bookmark"
}
]
}
]
}
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.
Added in version 1.37: Introduced the traits field.
Added in version 1.38: Introduced the rescue_interface field.
Added in version 1.42: Introduced the fault field.
Added in version 1.46: Introduced the conductor_group field.
Added in version 1.48: Introduced the protected and protected_reason fields.
Added in version 1.49: Introduced the conductor field
Added in version 1.50: Introduced the owner field.
Added in version 1.51: Introduced the description field.
Added in version 1.52: Introduced the allocation_uuid field.
Added in version 1.61: Introduced the retired and retired_reason fields.
Added in version 1.65: Introduced the lessee field.
Added in version 1.66: Introduced the network_data field.
Added in version 1.82: Introduced the shard field.
Added in version 1.83: Introduced the parent_node field.
Added in version 1.95: Introduced the disable_power_off field.
Normal response codes: 200
Error codes: 400,403,404,406
Request¶
Name |
In |
Type |
Description |
|---|---|---|---|
node_ident |
path |
string |
The UUID or Name of the node. |
fields (Optional) |
query |
array |
One or more fields to be returned in the response. For example, the following request returns only the GET /v1/nodes?fields=uuid,name
|
Response¶
Name |
In |
Type |
Description |
|---|---|---|---|
uuid |
body |
string |
The UUID for the resource. |
name (Optional) |
body |
string |
Human-readable identifier for the Node resource. May be undefined. Certain words are reserved. |
power_state |
body |
string |
The current power state of this Node. Usually, “power on” or “power off”, but may be “None” if Ironic is unable to determine the power state (eg, due to hardware failure). |
target_power_state |
body |
string |
If a power state transition has been requested, this field represents the requested (ie, “target”) state, either “power on” or “power off”. |
provision_state |
body |
string |
The current provisioning state of this Node. |
target_provision_state |
body |
string |
If a provisioning action has been requested, this field represents the requested (ie, “target”) state. Note that a Node may go through several states during its transition to this target state. For instance, when requesting an instance be deployed to an AVAILABLE Node, the Node may go through the following state change progression: AVAILABLE -> DEPLOYING -> DEPLOYWAIT -> DEPLOYING -> ACTIVE |
maintenance |
body |
boolean |
Whether or not this Node is currently in “maintenance mode”. Setting a Node into maintenance mode removes it from the available resource pool and halts some internal automation. This can happen manually (eg, via an API request) or automatically when Ironic detects a hardware fault that prevents communication with the machine. |
maintenance_reason (Optional) |
body |
string |
User-settable description of the reason why this Node was placed into maintenance mode |
fault (Optional) |
body |
string |
The fault indicates the active fault detected by ironic, typically the Node is in “maintenance mode”. None means no fault has been detected by ironic. “power failure” indicates ironic failed to retrieve power state from this node. There are other possible types, e.g., “clean failure” and “rescue abort failure”. |
last_error |
body |
string |
Any error from the most recent (last) transaction that started but failed to finish. |
reservation |
body |
string |
The |
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 |
driver_internal_info (Optional) |
body |
JSON |
Internal metadata set and stored by the Node’s driver. This field is read-only. |
properties |
body |
JSON |
Physical characteristics of this Node. Populated by ironic-inspector during inspection. May be edited via the REST API at any time. |
instance_info |
body |
JSON |
Information used to customize the deployed image. May include root partition size, a base 64 encoded config drive, and other metadata. Note that this field is erased automatically when the instance is deleted (this is done by requesting the Node provision state be changed to DELETED). |
instance_uuid |
body |
string |
UUID of the Nova instance associated with this Node. |
chassis_uuid |
body |
string |
UUID of the chassis associated with this Node. May be empty or None. |
extra |
body |
object |
A set of one or more arbitrary metadata key and value pairs. |
console_enabled |
body |
boolean |
Indicates whether console access is enabled or disabled on this node. |
raid_config (Optional) |
body |
JSON |
Represents the current RAID configuration of the node. Introduced with the cleaning feature. |
target_raid_config |
body |
JSON |
Represents the requested RAID configuration of the node, which will be applied when the Node next transitions through the CLEANING state. Introduced with the cleaning feature. |
clean_step (Optional) |
body |
string |
The current clean step. Introduced with the cleaning feature. |
deploy_step (Optional) |
body |
string |
The current deploy step. |
links |
body |
array |
A list of relative links. Includes the self and bookmark links. |
ports |
body |
array |
Links to the collection of ports on this node |
portgroups |
body |
array |
Links to the collection of portgroups on this node. |
states |
body |
array |
Links to the collection of states. Note that this resource is also used to request state transitions. |
resource_class |
body |
string |
A string which can be used by external schedulers to identify this Node as a unit of a specific type of resource. For more details, see: https://docs.openstack.org/ironic/latest/install/configure-nova-flavors.html |
bios_interface |
body |
string |
The bios interface to be used for this node. |
boot_interface |
body |
string |
The boot interface for a Node, e.g. “pxe”. |
console_interface |
body |
string |
The console interface for a node, e.g. “no-console”. |
deploy_interface |
body |
string |
The deploy interface for a node, e.g. “iscsi”. |
inspect_interface |
body |
string |
The interface used for node inspection, e.g. “no-inspect”. |
management_interface |
body |
string |
Interface for out-of-band node management, e.g. “ipmitool”. |
network_interface |
body |
string |
Which Network Interface provider to use when plumbing the network connections for this Node. |
power_interface |
body |
string |
Interface used for performing power actions on the node, e.g. “ipmitool”. |
raid_interface |
body |
string |
Interface used for configuring RAID on this node, e.g. “no-raid”. |
rescue_interface |
body |
string |
The interface used for node rescue, e.g. “no-rescue”. |
storage_interface |
body |
string |
Interface used for attaching and detaching volumes on this node, e.g. “cinder”. |
traits |
body |
array |
List of traits for this node. |
vendor_interface |
body |
string |
Interface for vendor-specific functionality on this node, e.g. “no-vendor”. |
volume |
body |
array |
Links to the volume resources. |
conductor_group |
body |
string |
The conductor group for a node. Case-insensitive string up to 255
characters, containing |
protected (Optional) |
body |
boolean |
Whether the node is protected from undeploying, rebuilding and deletion. |
protected_reason (Optional) |
body |
string |
The reason the node is marked as protected. |
owner (Optional) |
body |
string |
A string or UUID of the tenant who owns the object. |
lessee (Optional) |
body |
string |
A string or UUID of the tenant who is leasing the object. |
shard (Optional) |
body |
string |
A string indicating the shard this node belongs to. |
description |
body |
string |
Informational text about this node. |
conductor (Optional) |
body |
string |
The conductor currently servicing a node. This field is read-only. |
allocation_uuid |
body |
string |
The UUID of the allocation associated with the node. If not |
network_data (Optional) |
body |
JSON |
Static network configuration in the OpenStack network data format to use during deployment and cleaning. Requires a specially crafted ramdisk, see DHCP-less documentation. |
disable_power_off (Optional) |
body |
boolean |
If set to true, power off for the node is explicitly disabled, instead, a reboot will be used in place of power on/off. Additionally, when possible, the node will be disabled (i.e., its API agent will be rendered unusable and network configuration will be removed) instead of being powered off. |
Example JSON representation of a Node:
{
"allocation_uuid": null,
"boot_interface": null,
"chassis_uuid": null,
"clean_step": {},
"conductor": "compute1.localdomain",
"conductor_group": "group-1",
"console_enabled": false,
"console_interface": null,
"created_at": "2016-08-18T22:28:48.643434+11:11",
"deploy_interface": null,
"deploy_step": {},
"description": null,
"driver": "fake",
"driver_info": {
"ipmi_password": "******",
"ipmi_username": "ADMIN"
},
"driver_internal_info": {
"clean_steps": null
},
"extra": {},
"inspect_interface": null,
"inspection_finished_at": null,
"inspection_started_at": null,
"instance_info": {},
"instance_uuid": null,
"last_error": null,
"lessee": null,
"links": [
{
"href": "http://127.0.0.1:6385/v1/nodes/6d85703a-565d-469a-96ce-30b6de53079d",
"rel": "self"
},
{
"href": "http://127.0.0.1:6385/nodes/6d85703a-565d-469a-96ce-30b6de53079d",
"rel": "bookmark"
}
],
"maintenance": false,
"maintenance_reason": null,
"management_interface": null,
"name": "test_node_classic",
"network_data": {},
"network_interface": "flat",
"owner": null,
"portgroups": [
{
"href": "http://127.0.0.1:6385/v1/nodes/6d85703a-565d-469a-96ce-30b6de53079d/portgroups",
"rel": "self"
},
{
"href": "http://127.0.0.1:6385/nodes/6d85703a-565d-469a-96ce-30b6de53079d/portgroups",
"rel": "bookmark"
}
],
"ports": [
{
"href": "http://127.0.0.1:6385/v1/nodes/6d85703a-565d-469a-96ce-30b6de53079d/ports",
"rel": "self"
},
{
"href": "http://127.0.0.1:6385/nodes/6d85703a-565d-469a-96ce-30b6de53079d/ports",
"rel": "bookmark"
}
],
"power_interface": null,
"power_state": "power off",
"properties": {},
"protected": false,
"protected_reason": null,
"provision_state": "available",
"provision_updated_at": "2016-08-18T22:28:49.946416+00:00",
"raid_config": {},
"raid_interface": null,
"rescue_interface": null,
"reservation": null,
"resource_class": "bm-large",
"retired": false,
"retired_reason": null,
"states": [
{
"href": "http://127.0.0.1:6385/v1/nodes/6d85703a-565d-469a-96ce-30b6de53079d/states",
"rel": "self"
},
{
"href": "http://127.0.0.1:6385/nodes/6d85703a-565d-469a-96ce-30b6de53079d/states",
"rel": "bookmark"
}
],
"storage_interface": "noop",
"target_power_state": null,
"target_provision_state": null,
"target_raid_config": {},
"traits": [],
"updated_at": "2016-08-18T22:28:49.653974+00:00",
"uuid": "6d85703a-565d-469a-96ce-30b6de53079d",
"vendor_interface": null,
"volume": [
{
"href": "http://127.0.0.1:6385/v1/nodes/6d85703a-565d-469a-96ce-30b6de53079d/volume",
"rel": "self"
},
{
"href": "http://127.0.0.1:6385/nodes/6d85703a-565d-469a-96ce-30b6de53079d/volume",
"rel": "bookmark"
}
]
}
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.
Added in version 1.25: Introduced the ability to unset a node’s chassis UUID.
Added in version 1.51: Introduced the ability to set/unset a node’s description.
Added in version 1.82: Introduced the ability to set/unset a node’s shard.
Normal response codes: 200
Error codes: 400,403,404,406,409
Request¶
The BODY of the PATCH request must be a JSON PATCH document, adhering to RFC 6902.
Name |
In |
Type |
Description |
|---|---|---|---|
node_ident |
path |
string |
The UUID or Name of the node. |
Example PATCH document updating Node driver_info:
[
{
"op": "replace",
"path": "/driver_info/ipmi_username",
"value": "OPERATOR"
},
{
"op": "add",
"path": "/driver_info/deploy_kernel",
"value": "http://127.0.0.1/images/kernel"
},
{
"op": "add",
"path": "/driver_info/deploy_ramdisk",
"value": "http://127.0.0.1/images/ramdisk"
}
]
Response¶
Name |
In |
Type |
Description |
|---|---|---|---|
uuid |
body |
string |
The UUID for the resource. |
name (Optional) |
body |
string |
Human-readable identifier for the Node resource. May be undefined. Certain words are reserved. |
power_state |
body |
string |
The current power state of this Node. Usually, “power on” or “power off”, but may be “None” if Ironic is unable to determine the power state (eg, due to hardware failure). |
target_power_state |
body |
string |
If a power state transition has been requested, this field represents the requested (ie, “target”) state, either “power on” or “power off”. |
provision_state |
body |
string |
The current provisioning state of this Node. |
target_provision_state |
body |
string |
If a provisioning action has been requested, this field represents the requested (ie, “target”) state. Note that a Node may go through several states during its transition to this target state. For instance, when requesting an instance be deployed to an AVAILABLE Node, the Node may go through the following state change progression: AVAILABLE -> DEPLOYING -> DEPLOYWAIT -> DEPLOYING -> ACTIVE |
maintenance |
body |
boolean |
Whether or not this Node is currently in “maintenance mode”. Setting a Node into maintenance mode removes it from the available resource pool and halts some internal automation. This can happen manually (eg, via an API request) or automatically when Ironic detects a hardware fault that prevents communication with the machine. |
maintenance_reason (Optional) |
body |
string |
User-settable description of the reason why this Node was placed into maintenance mode |
fault (Optional) |
body |
string |
The fault indicates the active fault detected by ironic, typically the Node is in “maintenance mode”. None means no fault has been detected by ironic. “power failure” indicates ironic failed to retrieve power state from this node. There are other possible types, e.g., “clean failure” and “rescue abort failure”. |
last_error |
body |
string |
Any error from the most recent (last) transaction that started but failed to finish. |
reservation |
body |
string |
The |
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 |
driver_internal_info (Optional) |
body |
JSON |
Internal metadata set and stored by the Node’s driver. This field is read-only. |
properties |
body |
JSON |
Physical characteristics of this Node. Populated by ironic-inspector during inspection. May be edited via the REST API at any time. |
instance_info |
body |
JSON |
Information used to customize the deployed image. May include root partition size, a base 64 encoded config drive, and other metadata. Note that this field is erased automatically when the instance is deleted (this is done by requesting the Node provision state be changed to DELETED). |
instance_uuid |
body |
string |
UUID of the Nova instance associated with this Node. |
chassis_uuid |
body |
string |
UUID of the chassis associated with this Node. May be empty or None. |
extra |
body |
object |
A set of one or more arbitrary metadata key and value pairs. |
console_enabled |
body |
boolean |
Indicates whether console access is enabled or disabled on this node. |
raid_config (Optional) |
body |
JSON |
Represents the current RAID configuration of the node. Introduced with the cleaning feature. |
target_raid_config |
body |
JSON |
Represents the requested RAID configuration of the node, which will be applied when the Node next transitions through the CLEANING state. Introduced with the cleaning feature. |
clean_step (Optional) |
body |
string |
The current clean step. Introduced with the cleaning feature. |
deploy_step (Optional) |
body |
string |
The current deploy step. |
links |
body |
array |
A list of relative links. Includes the self and bookmark links. |
ports |
body |
array |
Links to the collection of ports on this node |
portgroups |
body |
array |
Links to the collection of portgroups on this node. |
states |
body |
array |
Links to the collection of states. Note that this resource is also used to request state transitions. |
resource_class |
body |
string |
A string which can be used by external schedulers to identify this Node as a unit of a specific type of resource. For more details, see: https://docs.openstack.org/ironic/latest/install/configure-nova-flavors.html |
boot_interface |
body |
string |
The boot interface for a Node, e.g. “pxe”. |
console_interface |
body |
string |
The console interface for a node, e.g. “no-console”. |
deploy_interface |
body |
string |
The deploy interface for a node, e.g. “iscsi”. |
inspect_interface |
body |
string |
The interface used for node inspection, e.g. “no-inspect”. |
management_interface |
body |
string |
Interface for out-of-band node management, e.g. “ipmitool”. |
network_interface |
body |
string |
Which Network Interface provider to use when plumbing the network connections for this Node. |
power_interface |
body |
string |
Interface used for performing power actions on the node, e.g. “ipmitool”. |
raid_interface |
body |
string |
Interface used for configuring RAID on this node, e.g. “no-raid”. |
rescue_interface |
body |
string |
The interface used for node rescue, e.g. “no-rescue”. |
storage_interface |
body |
string |
Interface used for attaching and detaching volumes on this node, e.g. “cinder”. |
traits |
body |
array |
List of traits for this node. |
vendor_interface |
body |
string |
Interface for vendor-specific functionality on this node, e.g. “no-vendor”. |
volume |
body |
array |
Links to the volume resources. |
conductor_group |
body |
string |
The conductor group for a node. Case-insensitive string up to 255
characters, containing |
protected (Optional) |
body |
boolean |
Whether the node is protected from undeploying, rebuilding and deletion. |
protected_reason (Optional) |
body |
string |
The reason the node is marked as protected. |
owner (Optional) |
body |
string |
A string or UUID of the tenant who owns the object. |
lessee (Optional) |
body |
string |
A string or UUID of the tenant who is leasing the object. |
shard (Optional) |
body |
string |
A string indicating the shard this node belongs to. |
description |
body |
string |
Informational text about this node. |
conductor (Optional) |
body |
string |
The conductor currently servicing a node. This field is read-only. |
allocation_uuid |
body |
string |
The UUID of the allocation associated with the node. If not |
network_data (Optional) |
body |
JSON |
Static network configuration in the OpenStack network data format to use during deployment and cleaning. Requires a specially crafted ramdisk, see DHCP-less documentation. |
disable_power_off (Optional) |
body |
boolean |
If set to true, power off for the node is explicitly disabled, instead, a reboot will be used in place of power on/off. Additionally, when possible, the node will be disabled (i.e., its API agent will be rendered unusable and network configuration will be removed) instead of being powered off. |
Example JSON representation of a Node:
{
"allocation_uuid": null,
"boot_interface": null,
"chassis_uuid": null,
"clean_step": {},
"conductor": "compute1.localdomain",
"conductor_group": "group-1",
"console_enabled": false,
"console_interface": null,
"created_at": "2016-08-18T22:28:48.643434+11:11",
"deploy_interface": null,
"deploy_step": {},
"driver": "fake",
"driver_info": {
"deploy_kernel": "http://127.0.0.1/images/kernel",
"deploy_ramdisk": "http://127.0.0.1/images/ramdisk",
"ipmi_password": "******",
"ipmi_username": "OPERATOR"
},
"driver_internal_info": {
"clean_steps": null
},
"extra": {},
"inspect_interface": null,
"inspection_finished_at": null,
"inspection_started_at": null,
"instance_info": {},
"instance_uuid": null,
"last_error": null,
"lessee": null,
"links": [
{
"href": "http://127.0.0.1:6385/v1/nodes/6d85703a-565d-469a-96ce-30b6de53079d",
"rel": "self"
},
{
"href": "http://127.0.0.1:6385/nodes/6d85703a-565d-469a-96ce-30b6de53079d",
"rel": "bookmark"
}
],
"maintenance": true,
"maintenance_reason": "Replacing the hard drive",
"management_interface": null,
"name": "test_node_classic",
"network_data": {},
"network_interface": "flat",
"owner": null,
"portgroups": [
{
"href": "http://127.0.0.1:6385/v1/nodes/6d85703a-565d-469a-96ce-30b6de53079d/portgroups",
"rel": "self"
},
{
"href": "http://127.0.0.1:6385/nodes/6d85703a-565d-469a-96ce-30b6de53079d/portgroups",
"rel": "bookmark"
}
],
"ports": [
{
"href": "http://127.0.0.1:6385/v1/nodes/6d85703a-565d-469a-96ce-30b6de53079d/ports",
"rel": "self"
},
{
"href": "http://127.0.0.1:6385/nodes/6d85703a-565d-469a-96ce-30b6de53079d/ports",
"rel": "bookmark"
}
],
"power_interface": null,
"power_state": "power off",
"properties": {},
"protected": false,
"protected_reason": null,
"provision_state": "available",
"provision_updated_at": "2016-08-18T22:28:49.946416+00:00",
"raid_config": {},
"raid_interface": null,
"rescue_interface": null,
"reservation": null,
"resource_class": null,
"retired": false,
"retired_reason": null,
"states": [
{
"href": "http://127.0.0.1:6385/v1/nodes/6d85703a-565d-469a-96ce-30b6de53079d/states",
"rel": "self"
},
{
"href": "http://127.0.0.1:6385/nodes/6d85703a-565d-469a-96ce-30b6de53079d/states",
"rel": "bookmark"
}
],
"storage_interface": "noop",
"target_power_state": null,
"target_provision_state": null,
"target_raid_config": {},
"traits": [
"CUSTOM_TRAIT1",
"HW_CPU_X86_VMX"
],
"updated_at": "2016-08-18T22:28:49.653974+00:00",
"uuid": "6d85703a-565d-469a-96ce-30b6de53079d",
"vendor_interface": null,
"volume": [
{
"href": "http://127.0.0.1:6385/v1/nodes/6d85703a-565d-469a-96ce-30b6de53079d/volume",
"rel": "self"
},
{
"href": "http://127.0.0.1:6385/nodes/6d85703a-565d-469a-96ce-30b6de53079d/volume",
"rel": "bookmark"
}
]
}
Deletes a node.
Normal response codes: 204
Error codes: 400,403,404,409
Request¶
Name |
In |
Type |
Description |
|---|---|---|---|
node_ident |
path |
string |
The UUID or Name of the node. |
Node Management (nodes)¶
Nodes can be managed through several sub-resources.
Maintenance mode can be set by the operator, with an optional “reason” stored by Ironic.
The supplied driver_info can be validated to ensure that the selected
driver has all the information it requires to manage the Node.
A Node can be rebooted, turned on, or turned off by requesting a change to its
power state. This is handled asynchronously and tracked in the target_power_state
field after the request is received.
A Node’s boot device can be changed, and the set of supported boot devices can be queried.
A request to change a Node’s provision state is also tracked asynchronously;
the target_provision_state represents the requested state. A Node
may transition through several discrete provision_state steps before arriving
at the requested state. This can vary between drivers and based on configuration.
For example, a Node in the available state can have an instance deployed to it
by requesting the provision state of active. During this transition, the Node’s
provision_state will temporarily be set to deploying, and depending on the driver,
it may also be wait call-back. When the transitions are complete, target_provision_state
will be set to None and provision_state will be set to active.
To destroy the instance, request the provision state of delete. During this
transition, the Node may or may not go through a cleaning state,
depending on the service configuration.
Request that Ironic validate whether the Node’s driver has enough information
to manage the Node. This polls each interface on the driver, and returns
the status of that interface as an element in the response. Note that each
driver may require different information to be supplied, and not all drivers
support all interfaces.
Normal response codes: 200
Request¶
Name |
In |
Type |
Description |
|---|---|---|---|
node_ident |
path |
string |
The UUID or Name of the node. |
Response¶
Each element in the response will contain a “result” variable, which will have
a value of “true” or “false”, indicating that the interface either has or does
not have sufficient information to function. A value of null indicates that
the Node’s driver does not support that interface.
Name |
In |
Type |
Description |
|---|---|---|---|
bios |
body |
object |
Status of the “bios” interface |
boot |
body |
object |
Status of the “boot” interface |
console |
body |
object |
Status of the “console” interface |
deploy |
body |
object |
Status of the “deploy” interface |
inspect |
body |
object |
Status of the “inspect” interface |
management |
body |
object |
Status of the “management” interface |
network |
body |
object |
Status of the “network” interface |
power |
body |
object |
Status of the “power” interface |
raid |
body |
object |
Status of the “raid” interface |
rescue |
body |
object |
Status of the “rescue” interface |
storage |
body |
object |
Status of the “storage” interface |
Example node validation response:
{
"boot": {
"result": true
},
"console": {
"result": true
},
"deploy": {
"result": true
},
"inspect": {
"result": true
},
"management": {
"result": true
},
"network": {
"result": true
},
"power": {
"result": true
},
"raid": {
"result": true
},
"rescue": {
"reason": "not supported",
"result": null
},
"storage": {
"result": true
}
}
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"
}
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. |
Set the boot device for the given Node, and set it persistently or for one-time boot. The exact behaviour of this depends on the hardware driver.
Note
In some drivers, eg. the *_ipmitool family, this method initiates a synchronous call
to the hardware management device (BMC). It should be used with caution! This
is a known bug.
Note
Some drivers do not support one-time boot, and always set the boot device persistently.
Normal response code: 204
Request¶
Name |
In |
Type |
Description |
|---|---|---|---|
node_ident |
path |
string |
The UUID or Name of the node. |
boot_device |
body |
string |
The boot device for a Node, eg. “pxe” or “disk”. |
persistent (Optional) |
body |
boolean |
Whether the boot device should be set only for the next reboot, or persistently. |
Example JSON request body to set boot device:
{
"boot_device": "pxe",
"persistent": false
}
Get 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
}
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"
]
}
Added in version 1.29.
Inject NMI (Non-Masking Interrupts) for the given Node. This feature can be used for hardware diagnostics, and actual support depends on a driver.
Normal response code: 204 (No content)
- Error codes:
400 (Invalid)
403 (Forbidden)
404 (NotFound)
406 (NotAcceptable)
409 (NodeLocked, ClientError)
Request¶
Name |
In |
Type |
Description |
|---|---|---|---|
node_ident |
path |
string |
The UUID or Name of the node. |
Request to inject NMI to a node has to be empty dictionary:
{}
Get a summary of the Node’s current power, provision, boot mode, raid, and console status.
Added in version 1.75: Introduced boot_mode and secure_boot fields.
Normal response code: 200
Request¶
Name |
In |
Type |
Description |
|---|---|---|---|
node_ident |
path |
string |
The UUID or Name of the node. |
Response¶
Name |
In |
Type |
Description |
|---|---|---|---|
power_state |
body |
string |
The current power state of this Node. Usually, “power on” or “power off”, but may be “None” if Ironic is unable to determine the power state (eg, due to hardware failure). |
target_power_state |
body |
string |
If a power state transition has been requested, this field represents the requested (ie, “target”) state, either “power on” or “power off”. |
provision_state |
body |
string |
The current provisioning state of this Node. |
target_provision_state |
body |
string |
If a provisioning action has been requested, this field represents the requested (ie, “target”) state. Note that a Node may go through several states during its transition to this target state. For instance, when requesting an instance be deployed to an AVAILABLE Node, the Node may go through the following state change progression: AVAILABLE -> DEPLOYING -> DEPLOYWAIT -> DEPLOYING -> ACTIVE |
provision_updated_at |
body |
string |
The UTC date and time when the resource was created,
ISO 8601 format.
|
last_error |
body |
string |
Any error from the most recent (last) transaction that started but failed to finish. |
console_enabled |
body |
boolean |
Indicates whether console access is enabled or disabled on this node. |
raid_config (Optional) |
body |
JSON |
Represents the current RAID configuration of the node. Introduced with the cleaning feature. |
target_raid_config |
body |
JSON |
Represents the requested RAID configuration of the node, which will be applied when the Node next transitions through the CLEANING state. Introduced with the cleaning feature. |
boot_mode (Optional) |
body |
string |
The current boot mode state (uefi/bios) |
secure_boot (Optional) |
body |
boolean |
Indicates whether node is currently booted with secure_boot turned on. |
Example node state:
{
"boot_mode": "uefi",
"console_enabled": false,
"last_error": null,
"power_state": "power off",
"provision_state": "available",
"provision_updated_at": "2016-08-18T22:28:49.946416+00:00",
"raid_config": {},
"secure_boot": true,
"target_power_state": null,
"target_provision_state": null,
"target_raid_config": {}
}
Request a change to the Node’s boot mode.
Note
Depending on the driver and the underlying hardware, changing boot mode may result in an automatic reboot.
Added in version 1.76: A change in node’s boot mode can be requested.
Normal response code: 202 (Accepted)
- Error codes:
400 (Invalid, InvalidStateRequested, InvalidParameterValue)
404 (NotFound)
409 (Conflict, NodeLocked, ClientError)
503 (NoFreeConductorWorkers)
Request¶
Name |
In |
Type |
Description |
|---|---|---|---|
node_ident |
path |
string |
The UUID or Name of the node. |
target |
body |
string |
If a boot mode change has been requested, this field represents the requested (ie, “target”) state, either “uefi” or “bios”. |
Example request for UEFI boot:
{
"target": "uefi"
}
Example request for Legacy BIOS boot:
{
"target": "bios"
}
Request a change to the Node’s secure boot state.
Note
Depending on the driver and the underlying hardware, changing the secure boot state may result in an automatic reboot.
Added in version 1.76: A change in node’s secure boot state can be requested.
Normal response code: 202 (Accepted)
- Error codes:
400 (Invalid, InvalidStateRequested, InvalidParameterValue)
404 (NotFound)
409 (Conflict, NodeLocked, ClientError)
503 (NoFreeConductorWorkers)
Request¶
Name |
In |
Type |
Description |
|---|---|---|---|
node_ident |
path |
string |
The UUID or Name of the node. |
target |
body |
boolean |
If a secure boot change has been requested, this field represents the
requested (ie, “target”) state, either |
Example request to turn off secure boot:
{
"target": false
}
Example request to turn on secure boot:
{
"target": true
}
Request a change to the Node’s power state.
Normal response code: 202 (Accepted)
Added in version 1.27: In the request, the target value can also be one of soft power off
or soft rebooting.
Added in version 1.27: In the request, a timeout can be specified.
- Error codes:
409 (NodeLocked, ClientError)
400 (Invalid, InvalidStateRequested, InvalidParameterValue)
406 (NotAcceptable)
503 (NoFreeConductorWorkers)
Request¶
Name |
In |
Type |
Description |
|---|---|---|---|
node_ident |
path |
string |
The UUID or Name of the node. |
target |
body |
string |
If a power state transition has been requested, this field represents the requested (ie, “target”) state either “power on”, “power off”, “rebooting”, “soft power off” or “soft rebooting”. |
timeout (Optional) |
body |
integer |
Timeout (in seconds) for a power state transition. |
Example request to power off a Node:
{
"target": "power off"
}
Example request to soft power off a Node with timeout:
{
"target": "soft power off",
"timeout": 300
}
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.
Added in version 1.35: A configdrive can be provided when setting the node’s provision target state to rebuild.
Added in version 1.38: A node can be rescued or unrescued by setting the node’s provision target state to
rescue or unrescue respectively.
Added in version 1.56: A configdrive can be a JSON object with meta_data, network_data
and user_data.
Added in version 1.59: A configdrive now accepts vendor_data.
Added in version 1.69: deploy_steps can be provided when settings the node’s provision target
state to active or rebuild.
Added in version 1.70: disable_ramdisk can be provided to avoid booting the ramdisk during
manual cleaning.
Added in version 1.87: A node can be serviced by setting the provision target state to service
with a list of service_steps.
Added in version 1.92: Added the ability to allow for predefined sets of steps to be executed
during provisioning by passing in a runbook_ident that’s already
approved for the given node, as an alternative to providing clean_steps
or service_steps dictionary.
Added in version 1.95: Added the ability to set/unset disable_power_off on a node.
Normal response code: 202
- Error codes:
409 (NodeLocked, ClientError)
400 (InvalidState, NodeInMaintenance)
406 (NotAcceptable)
503 (NoFreeConductorWorkers)
Request¶
Name |
In |
Type |
Description |
|---|---|---|---|
node_ident |
path |
string |
The UUID or Name of the node. |
target |
body |
string |
The requested provisioning state of this Node. |
configdrive (Optional) |
body |
string or object |
A config drive to be written to a partition on the Node’s boot disk. Can be a full gzip’ed and base-64 encoded image or a JSON object with the keys:
This parameter is only accepted when setting the state to “active” or “rebuild”. |
clean_steps (Optional) |
body |
array |
An ordered list of cleaning steps that will be performed on the node. A cleaning step is a dictionary with required keys ‘interface’ and ‘step’, and optional key ‘args’. If specified, the value for ‘args’ is a keyword variable argument dictionary that is passed to the cleaning step method. |
deploy_steps (Optional) |
body |
array |
A list of deploy steps that will be performed on the node. A deploy step is a dictionary with required keys ‘interface’, ‘step’, ‘priority’ and optional key ‘args’. If specified, the value for ‘args’ is a keyword variable argument dictionary that is passed to the deploy step method. |
service_steps (Optional) |
body |
array |
An ordered list of service 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. |
rescue_password (Optional) |
body |
string |
Non-empty password used to configure rescue ramdisk during node rescue operation. |
disable_ramdisk (Optional) |
body |
boolean |
If set to |
runbook |
path |
string |
The UUID or name of the runbook. |
Example request to deploy a Node, using a configdrive served via local webserver:
{
"target": "active",
"configdrive": "http://127.0.0.1/images/test-node-config-drive.iso.gz"
}
Example request to deploy a Node with custom deploy step:
{
"target": "active",
"deploy_steps": [
{
"interface": "deploy",
"step": "upgrade_firmware",
"args": {
"force": "True"
},
"priority": 95
}
]
}
Example request to clean a Node, with custom clean step:
{
"target": "clean",
"clean_steps": [
{
"interface": "deploy",
"step": "upgrade_firmware",
"args": {
"force": "True"
}
}
]
}
Example request to service a Node, with custom service step:
{
"target":"service",
"sevice_steps": [
{
"interface": "raid",
"step": "apply_configuration",
"args": {
"create_nonroot_volumes": "True"
}
}
]
}
Example request to set provision state for a Node with a runbook:
{
"target": "clean",
"runbook": "runbook_ident"
}
Note
Use runbook as an alternative to clean_steps or
service_steps. If runbook is provided, clean_steps or
service_steps must not be included in the request.
Added in version 1.12.
Store the supplied configuration on the Node’s target_raid_config property.
This property must be structured JSON, and will be validated by the driver upon receipt. The request
schema is defined in the documentation for the RAID feature
Note
Calling this API only stores the requested configuration; it will be applied the next time
that the Node transitions through the cleaning phase.
Normal response code: 204
Request¶
Name |
In |
Type |
Description |
|---|---|---|---|
node_ident |
path |
string |
The UUID or Name of the node. |
target_raid_config |
body |
JSON |
Represents the requested RAID configuration of the node, which will be applied when the Node next transitions through the CLEANING state. Introduced with the cleaning feature. |
Example requested RAID config:
{
"logical_disks" : [
{
"size_gb" : 100,
"is_root_volume" : true,
"raid_level" : "1"
}
]
}
Get connection information about the console.
Request¶
Name |
In |
Type |
Description |
|---|---|---|---|
node_ident |
path |
string |
The UUID or Name of the node. |
Start or stop the serial console.
Request¶
Name |
In |
Type |
Description |
|---|---|---|---|
node_ident |
path |
string |
The UUID or Name of the node. |
enabled |
body |
boolean |
Indicates whether console access is enabled or disabled on this node. |
Attach / Detach Virtual Media (nodes)¶
Added in version 1.89.
Attach a generic image as virtual media device to a node or remove
it from a node using the v1/nodes/{node_ident}/vmedia endpoint.
Attach virtual media device to a node.
Normal response code: 204
Error codes: 400,401,403,404,409
Request¶
Name |
In |
Type |
Description |
|---|---|---|---|
node_ident |
path |
string |
The UUID or Name of the node. |
device_type |
body |
string |
The type of the virtual media device used, e.g. CDROM |
image_url |
body |
string |
The url of the image to attach to a virtual media device. |
image_download_source (Optional) |
body |
string |
How the image is served to the BMC, “http” for a remote location or “local” to use the local web server. |
Example request to attach virtual media to a Node:
{
"device_type": "CDROM",
"image_url": "http://image"
}
Detach virtual media device from a Node.
Normal response code: 204
Error codes: 400,401,403,404
Request¶
Name |
In |
Type |
Description |
|---|---|---|---|
node_ident |
path |
string |
The UUID or Name of the node. |
Node Vendor Passthru (nodes)¶
Each driver MAY support vendor-specific extensions, called “passthru” methods.
Internally, Ironic’s driver API supports flexibly exposing functions via the
common HTTP methods GET, PUT, POST, and DELETE. To call a passthru method,
the query string must contain the name of the method, eg.
/vendor_passthru?method=reset_bmc. The contents of the HTTP request are
forwarded to the Node’s driver and validated there.
Ironic’s REST API provides a means to discover these methods, but does not provide support, testing, or documentation for these endpoints. The Ironic development team does not guarantee any compatibility within these methods between releases, though we encourage driver authors to provide documentation and support for them.
Besides the endpoints documented here, all other resources and endpoints
under the heading vendor_passthru should be considered
unsupported APIs, and could be changed without warning by the driver authors.
Retrieve a list of the available vendor passthru methods for the given Node. The response will indicate which HTTP method(s) each vendor passthru method allows, whether the method call will be synchronous or asynchronous, and whether the response will include any attachment.
Normal response code: 200
Request¶
Name |
In |
Type |
Description |
|---|---|---|---|
node_ident |
path |
string |
The UUID or Name of the node. |
Response¶
Example passthru methods listing:
{
"bmc_reset": {
"async": true,
"attach": false,
"description": "",
"http_methods": [
"POST"
],
"require_exclusive_lock": true
},
"send_raw": {
"async": true,
"attach": false,
"description": "",
"http_methods": [
"POST"
],
"require_exclusive_lock": true
}
}
The HTTP METHOD may be one of GET, POST, PUT, DELETE, depending on the driver and method.
This endpoint passes the request directly to the Node’s hardware driver. The HTTP BODY must be parseable JSON, which will be converted to parameters passed to that function. Unparsable JSON, missing parameters, or excess parameters will cause the request to be rejected with an HTTP 400 error.
Normal response code: 200 202
Request¶
Name |
In |
Type |
Description |
|---|---|---|---|
node_ident |
path |
string |
The UUID or Name of the node. |
method_name |
query |
string |
Driver specific method name. |
All other parameters should be passed in the BODY. Parameter list varies by method_name.
Response¶
Varies.
Node Traits (nodes)¶
Added in version 1.37.
Node traits are used for scheduling in the Compute service, using qualitative attributes to influence the placement of instances to bare metal compute nodes. Traits specified for a node in the Bare Metal service will be registered on the corresponding resource provider in the Compute service’s placement API.
Traits can be either standard or custom. Standard traits are listed in the os_traits library. Custom traits must meet the following requirements:
prefixed with
CUSTOM_contain only upper case characters A to Z, digits 0 to 9, or underscores
no longer than 255 characters in length
A bare metal node can have a maximum of 50 traits.
Return a list of traits for the node.
Normal response code: 200
Error codes: 400,401,403,404
Request¶
Name |
In |
Type |
Description |
|---|---|---|---|
node_ident |
path |
string |
The UUID or Name of the node. |
Response¶
Name |
In |
Type |
Description |
|---|---|---|---|
traits |
body |
array |
List of traits for this node. |
Example list of traits for the node:
{
"traits": [
"CUSTOM_TRAIT1",
"HW_CPU_X86_VMX"
]
}
Set all traits of a node, replacing any existing traits.
Normal response code: 204
Error codes: 400,401,403,404,409
Request¶
Name |
In |
Type |
Description |
|---|---|---|---|
node_ident |
path |
string |
The UUID or Name of the node. |
traits |
body |
array |
List of traits for this node. |
Example request to set all traits of a Node:
{
"traits": [
"CUSTOM_TRAIT1",
"HW_CPU_X86_VMX"
]
}
Add a single trait to a node.
Normal response code: 204
Error codes: 400,401,403,404,409
Request¶
Name |
In |
Type |
Description |
|---|---|---|---|
node_ident |
path |
string |
The UUID or Name of the node. |
trait |
path |
string |
A single trait for this node. |
Normal response code: 204
Error codes: 400,401,403,404,409
Request¶
Name |
In |
Type |
Description |
|---|---|---|---|
node_ident |
path |
string |
The UUID or Name of the node. |
Remove a single trait from a node.
Normal response code: 204
Error codes: 400,401,403,404,409
Request¶
Name |
In |
Type |
Description |
|---|---|---|---|
node_ident |
path |
string |
The UUID or Name of the node. |
trait |
path |
string |
A single trait for this node. |
VIFs (Virtual Interfaces) of nodes¶
Added in version 1.28.
Attaching and detaching VIFs (Virtual Interfaces) to or from a node are done
via the v1/nodes/{node_ident}/vifs endpoint. Attaching a VIF to a node
means that a VIF will be mapped to a free port or port group of the specified
node.
Return a list of VIFs that are attached to the node.
Normal response code: 200
Error codes: 400,401,403,404
Request¶
Name |
In |
Type |
Description |
|---|---|---|---|
node_ident |
path |
string |
The UUID or Name of the node. |
Response¶
Name |
In |
Type |
Description |
|---|---|---|---|
vifs |
body |
array |
VIFs attached to this node. |
id |
body |
string |
The UUID or name of the VIF. |
Example list of VIFs that are attached to the node:
{
"vifs": [
{
"id": "1974dcfa-836f-41b2-b541-686c100900e5"
}
]
}
Attach a VIF to a node.
Normal response code: 204
Error codes: 400,401,403,404,409
Request¶
Name |
In |
Type |
Description |
|---|---|---|---|
id |
body |
string |
The UUID or name of the VIF. |
port_uuid (Optional) |
body |
string |
The UUID of a port to attach the VIF to. Cannot be specified with
|
portgroup_uuid (Optional) |
body |
string |
The UUID of a portgroup to attach the VIF to. Cannot be specified with
|
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"
}
Detach VIF from a Node.
Normal response code: 204
Error codes: 400,401,403,404
Request¶
Name |
In |
Type |
Description |
|---|---|---|---|
node_ident |
path |
string |
The UUID or Name of the node. |
node_vif_ident |
body |
string |
The UUID or name of the VIF. |
Indicators Management¶
The Indicators management is an extension of the node ReST API endpoint that allows reading and toggling the indicators (e.g. LEDs) on the hardware units.
Added in version 1.63.
List all available indicator names for each of the hardware components.
The components that the redfish driver may have are: system,
chassis and drive. The actual list depends on the support by the
underlying hardware.
Normal response code: 200
Error response codes: 404 (if node not found)
Request¶
Name |
In |
Type |
Description |
|---|---|---|---|
node_ident |
path |
string |
The UUID or Name of the node. |
Response Parameters¶
Name |
In |
Type |
Description |
|---|---|---|---|
components |
body |
array |
List all available indicators names for each of the hardware components for this node. |
name |
body |
string |
The name of the component available for the node. |
links |
body |
array |
A list of relative links. Includes the self and bookmark links. |
Example list of indicators for the node:
{
"components": [
{
"name": "system",
"links": [
{
"href": "http://127.0.0.1:6385/v1/nodes/Compute0/management/indicators/system",
"rel": "self"
},
{
"href": "http://127.0.0.1:6385/nodes/Compute0/management/indicators/system",
"rel": "bookmark"
}
]
},
{
"name": "chassis",
"links": [
{
"href": "http://127.0.0.1:6385/v1/nodes/Compute0/management/indicators/chassis",
"rel": "self"
},
{
"href": "http://127.0.0.1:6385/nodes/Compute0/management/indicators/chassis",
"rel": "bookmark"
}
]
}
]
}
Added in version 1.63.
Retrieves the state of a chosen indicator for a given component of the node.
The value of the field in the response object represents its state. The values
can be one of OFF, ON, BLINKING or UNKNOWN.
Normal response code: 200
Error response codes: 404 (if node, component or indicator is not found)
Request¶
Name |
In |
Type |
Description |
|---|---|---|---|
node_ident |
path |
string |
The UUID or Name of the node. |
component |
path |
string |
The Bare Metal node component. |
ind_ident |
path |
string |
The indicator of a Bare Metal component. |
Response Parameters¶
Name |
In |
Type |
Description |
|---|---|---|---|
state |
body |
string |
The state of an indicator of the component of the node. Possible values
are: |
Example list of indicators for a given component of the node:
{
"state": "ON"
}
Added in version 1.63.
Set the state of the desired indicators of the component.
Normal response code: 204 (No content)
- Error codes:
400 (if state is not an accepted value)
404 (if node, component or indicator is not found)
Request¶
Name |
In |
Type |
Description |
|---|---|---|---|
node_ident |
path |
string |
The UUID or Name of the node. |
component |
path |
string |
The Bare Metal node component. |
ind_ident |
path |
string |
The indicator of a Bare Metal component. |
state |
body |
string |
The state of an indicator of the component of the node. Possible values
are: |
Set the State of an Indicator
{
"state": "BLINKING"
}
Portgroups (portgroups)¶
Added in version 1.23.
Ports can be combined into portgroups to support static link aggregation group
(LAG) or multi-chassis link aggregation group (MLAG) configurations. Listing,
Searching, Creating, Updating, and Deleting of bare metal Portgroup resources
are done through the v1/portgroups resource.
All Portgroups must be associated with a Node when created. This association can be changed, though the request may be rejected if either the current or destination Node are in a transitive state (for example, in the process of deploying) or are in a state that would be non-deterministically affected by such a change (for example, there is an active user instance on the Node).
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.
Added in version 1.43: Added the detail boolean request parameter. When specified True this
causes the response to include complete details about each portgroup.
Normal response code: 200
Error codes: 400,401,403,404
Request¶
Name |
In |
Type |
Description |
|---|---|---|---|
node (Optional) |
query |
string |
Filter the list of returned Portgroups, and only return the ones associated with this specific node (name or UUID), or an empty set if not found. |
address (Optional) |
query |
string |
Filter the list of returned Portgroups, and only return the ones with the specified physical hardware address, typically MAC, or an empty set if not found. |
fields (Optional) |
query |
array |
One or more fields to be returned in the response. For example, the following request returns only the 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 |
marker (Optional) |
query |
string |
The ID of the last-seen item. Use the |
sort_dir (Optional) |
query |
string |
Sorts the response by the requested sort
direction. A valid value is |
sort_key (Optional) |
query |
string |
Sorts the response by this attribute value.
Default is |
detail (Optional) |
query |
boolean |
Whether to show detailed information about the resource. This cannot be
set to True if |
Response¶
Name |
In |
Type |
Description |
|---|---|---|---|
portgroups |
body |
array |
A collection of Portgroup resources. |
uuid |
body |
string |
The UUID for the resource. |
address (Optional) |
body |
string |
Physical hardware address of this Portgroup, typically the hardware MAC address. |
name |
body |
string |
Human-readable identifier for the Portgroup resource. May be undefined. |
links |
body |
array |
A list of relative links. Includes the self and bookmark links. |
Example Portgroup list response:
{
"portgroups": [
{
"address": "11:11:11:11:11:11",
"links": [
{
"href": "http://127.0.0.1:6385/v1/portgroups/e43c722c-248e-4c6e-8ce8-0d8ff129387a",
"rel": "self"
},
{
"href": "http://127.0.0.1:6385/portgroups/e43c722c-248e-4c6e-8ce8-0d8ff129387a",
"rel": "bookmark"
}
],
"name": "test_portgroup",
"uuid": "e43c722c-248e-4c6e-8ce8-0d8ff129387a"
}
]
}
Creates a new Portgroup resource.
This method requires a Node UUID and the physical hardware address for the Portgroup (MAC address in most cases).
Normal response code: 201
Error codes: 400,401,403,404
Request¶
Name |
In |
Type |
Description |
|---|---|---|---|
node_uuid |
body |
string |
UUID of the Node this resource belongs to. |
address (Optional) |
body |
string |
Physical hardware address of this Portgroup, typically the hardware MAC address. |
name (Optional) |
body |
string |
Human-readable identifier for the Portgroup resource. May be undefined. |
mode (Optional) |
body |
string |
Mode of the port group. For possible values, refer to
https://www.kernel.org/doc/Documentation/networking/bonding.txt. If not
specified in a request to create a port group, it will be set to the value
of the |
standalone_ports_supported (Optional) |
body |
boolean |
Indicates whether ports that are members of this portgroup can be used as stand-alone ports. |
properties (Optional) |
body |
JSON |
Key/value properties related to the port group’s configuration. |
extra (Optional) |
body |
object |
A set of one or more arbitrary metadata key and value pairs. |
uuid (Optional) |
body |
string |
The UUID for the resource. |
Example Portgroup creation request:
{
"node_uuid": "6d85703a-565d-469a-96ce-30b6de53079d",
"address": "11:11:11:11:11:11",
"name": "test_portgroup"
}
Response¶
Name |
In |
Type |
Description |
|---|---|---|---|
uuid |
body |
string |
The UUID for the resource. |
name |
body |
string |
Human-readable identifier for the Portgroup resource. May be undefined. |
address (Optional) |
body |
string |
Physical hardware address of this Portgroup, typically the hardware MAC address. |
node_uuid |
body |
string |
UUID of the Node this resource belongs to. |
standalone_ports_supported |
body |
boolean |
Indicates whether ports that are members of this portgroup can be used as stand-alone ports. |
internal_info |
body |
JSON |
Internal metadata set and stored by the Portgroup. This field is read-only. |
extra |
body |
object |
A set of one or more arbitrary metadata key and value pairs. |
mode |
body |
string |
Mode of the port group. For possible values, refer to
https://www.kernel.org/doc/Documentation/networking/bonding.txt. If not
specified in a request to create a port group, it will be set to the value
of the |
properties |
body |
JSON |
Key/value properties related to the port group’s configuration. |
created_at |
body |
string |
The UTC date and time when the resource was created, ISO 8601 format. |
updated_at |
body |
string |
The UTC date and time when the resource was updated, ISO 8601 format. May be “null”. |
links |
body |
array |
A list of relative links. Includes the self and bookmark links. |
ports |
body |
array |
Links to the collection of ports belonging to this portgroup. |
Example Portgroup creation response:
{
"address": "11:11:11:11:11:11",
"created_at": "2016-08-18T22:28:48.643434+11:11",
"extra": {},
"internal_info": {},
"links": [
{
"href": "http://127.0.0.1:6385/v1/portgroups/e43c722c-248e-4c6e-8ce8-0d8ff129387a",
"rel": "self"
},
{
"href": "http://127.0.0.1:6385/portgroups/e43c722c-248e-4c6e-8ce8-0d8ff129387a",
"rel": "bookmark"
}
],
"mode": "active-backup",
"name": "test_portgroup",
"node_uuid": "6d85703a-565d-469a-96ce-30b6de53079d",
"ports": [
{
"href": "http://127.0.0.1:6385/v1/portgroups/e43c722c-248e-4c6e-8ce8-0d8ff129387a/ports",
"rel": "self"
},
{
"href": "http://127.0.0.1:6385/portgroups/e43c722c-248e-4c6e-8ce8-0d8ff129387a/ports",
"rel": "bookmark"
}
],
"properties": {},
"standalone_ports_supported": true,
"updated_at": null,
"uuid": "e43c722c-248e-4c6e-8ce8-0d8ff129387a"
}
Return a list of bare metal Portgroups, with detailed information.
Normal response code: 200
Error codes: 400,401,403,404
Request¶
Name |
In |
Type |
Description |
|---|---|---|---|
node (Optional) |
query |
string |
Filter the list of returned Portgroups, and only return the ones associated with this specific node (name or UUID), or an empty set if not found. |
address (Optional) |
query |
string |
Filter the list of returned Portgroups, and only return the ones with the specified physical hardware address, typically MAC, or an empty set if not found. |
limit (Optional) |
query |
integer |
Requests a page size of items. Returns a number of items up to a limit
value. Use the |
marker (Optional) |
query |
string |
The ID of the last-seen item. Use the |
sort_dir (Optional) |
query |
string |
Sorts the response by the requested sort
direction. A valid value is |
sort_key (Optional) |
query |
string |
Sorts the response by this attribute value.
Default is |
Response¶
Name |
In |
Type |
Description |
|---|---|---|---|
portgroups |
body |
array |
A collection of Portgroup resources. |
name |
body |
string |
Human-readable identifier for the Portgroup resource. May be undefined. |
uuid |
body |
string |
The UUID for the resource. |
address (Optional) |
body |
string |
Physical hardware address of this Portgroup, typically the hardware MAC address. |
node_uuid |
body |
string |
UUID of the Node this resource belongs to. |
standalone_ports_supported |
body |
boolean |
Indicates whether ports that are members of this portgroup can be used as stand-alone ports. |
internal_info |
body |
JSON |
Internal metadata set and stored by the Portgroup. This field is read-only. |
extra |
body |
object |
A set of one or more arbitrary metadata key and value pairs. |
mode |
body |
string |
Mode of the port group. For possible values, refer to
https://www.kernel.org/doc/Documentation/networking/bonding.txt. If not
specified in a request to create a port group, it will be set to the value
of the |
properties |
body |
JSON |
Key/value properties related to the port group’s configuration. |
created_at |
body |
string |
The UTC date and time when the resource was created, ISO 8601 format. |
updated_at |
body |
string |
The UTC date and time when the resource was updated, ISO 8601 format. May be “null”. |
links |
body |
array |
A list of relative links. Includes the self and bookmark links. |
ports |
body |
array |
Links to the collection of ports belonging to this portgroup. |
Example detailed Portgroup list response:
{
"portgroups": [
{
"address": "11:11:11:11:11:11",
"created_at": "2016-08-18T22:28:48.643434+11:11",
"extra": {},
"internal_info": {},
"links": [
{
"href": "http://127.0.0.1:6385/v1/portgroups/e43c722c-248e-4c6e-8ce8-0d8ff129387a",
"rel": "self"
},
{
"href": "http://127.0.0.1:6385/portgroups/e43c722c-248e-4c6e-8ce8-0d8ff129387a",
"rel": "bookmark"
}
],
"mode": "active-backup",
"name": "test_portgroup",
"node_uuid": "6d85703a-565d-469a-96ce-30b6de53079d",
"ports": [
{
"href": "http://127.0.0.1:6385/v1/portgroups/e43c722c-248e-4c6e-8ce8-0d8ff129387a/ports",
"rel": "self"
},
{
"href": "http://127.0.0.1:6385/portgroups/e43c722c-248e-4c6e-8ce8-0d8ff129387a/ports",
"rel": "bookmark"
}
],
"properties": {},
"standalone_ports_supported": true,
"updated_at": null,
"uuid": "e43c722c-248e-4c6e-8ce8-0d8ff129387a"
}
]
}
Show details for the given Portgroup.
Normal response code: 200
Error codes: 400,401,403,404
Request¶
Name |
In |
Type |
Description |
|---|---|---|---|
portgroup_ident |
path |
string |
The UUID or Name of the portgroup. |
fields (Optional) |
query |
array |
One or more fields to be returned in the response. For example, the following request returns only the GET /v1/nodes?fields=uuid,name
|
Response¶
Name |
In |
Type |
Description |
|---|---|---|---|
uuid |
body |
string |
The UUID for the resource. |
name |
body |
string |
Human-readable identifier for the Portgroup resource. May be undefined. |
address (Optional) |
body |
string |
Physical hardware address of this Portgroup, typically the hardware MAC address. |
node_uuid |
body |
string |
UUID of the Node this resource belongs to. |
standalone_ports_supported |
body |
boolean |
Indicates whether ports that are members of this portgroup can be used as stand-alone ports. |
internal_info |
body |
JSON |
Internal metadata set and stored by the Portgroup. This field is read-only. |
extra |
body |
object |
A set of one or more arbitrary metadata key and value pairs. |
mode |
body |
string |
Mode of the port group. For possible values, refer to
https://www.kernel.org/doc/Documentation/networking/bonding.txt. If not
specified in a request to create a port group, it will be set to the value
of the |
properties |
body |
JSON |
Key/value properties related to the port group’s configuration. |
created_at |
body |
string |
The UTC date and time when the resource was created, ISO 8601 format. |
updated_at |
body |
string |
The UTC date and time when the resource was updated, ISO 8601 format. May be “null”. |
links |
body |
array |
A list of relative links. Includes the self and bookmark links. |
ports |
body |
array |
Links to the collection of ports belonging to this portgroup. |
Example Portgroup details:
{
"address": "11:11:11:11:11:11",
"created_at": "2016-08-18T22:28:48.643434+11:11",
"extra": {},
"internal_info": {},
"links": [
{
"href": "http://127.0.0.1:6385/v1/portgroups/e43c722c-248e-4c6e-8ce8-0d8ff129387a",
"rel": "self"
},
{
"href": "http://127.0.0.1:6385/portgroups/e43c722c-248e-4c6e-8ce8-0d8ff129387a",
"rel": "bookmark"
}
],
"mode": "active-backup",
"name": "test_portgroup",
"node_uuid": "6d85703a-565d-469a-96ce-30b6de53079d",
"ports": [
{
"href": "http://127.0.0.1:6385/v1/portgroups/e43c722c-248e-4c6e-8ce8-0d8ff129387a/ports",
"rel": "self"
},
{
"href": "http://127.0.0.1:6385/portgroups/e43c722c-248e-4c6e-8ce8-0d8ff129387a/ports",
"rel": "bookmark"
}
],
"properties": {},
"standalone_ports_supported": true,
"updated_at": null,
"uuid": "e43c722c-248e-4c6e-8ce8-0d8ff129387a"
}
Update a Portgroup.
Normal response code: 200
Error codes: 400,401,403,404
Request¶
The BODY of the PATCH request must be a JSON PATCH document, adhering to RFC 6902.
Name |
In |
Type |
Description |
|---|---|---|---|
portgroup_ident |
path |
string |
The UUID or Name of the portgroup. |
Example Portgroup update request:
[
{
"path" : "/address",
"value" : "22:22:22:22:22:22",
"op" : "replace"
}
]
Response¶
Name |
In |
Type |
Description |
|---|---|---|---|
uuid |
body |
string |
The UUID for the resource. |
name |
body |
string |
Human-readable identifier for the Portgroup resource. May be undefined. |
address (Optional) |
body |
string |
Physical hardware address of this Portgroup, typically the hardware MAC address. |
node_uuid |
body |
string |
UUID of the Node this resource belongs to. |
standalone_ports_supported |
body |
boolean |
Indicates whether ports that are members of this portgroup can be used as stand-alone ports. |
internal_info |
body |
JSON |
Internal metadata set and stored by the Portgroup. This field is read-only. |
extra |
body |
object |
A set of one or more arbitrary metadata key and value pairs. |
mode |
body |
string |
Mode of the port group. For possible values, refer to
https://www.kernel.org/doc/Documentation/networking/bonding.txt. If not
specified in a request to create a port group, it will be set to the value
of the |
properties |
body |
JSON |
Key/value properties related to the port group’s configuration. |
created_at |
body |
string |
The UTC date and time when the resource was created, ISO 8601 format. |
updated_at |
body |
string |
The UTC date and time when the resource was updated, ISO 8601 format. May be “null”. |
links |
body |
array |
A list of relative links. Includes the self and bookmark links. |
ports |
body |
array |
Links to the collection of ports belonging to this portgroup. |
Example Portgroup update response:
{
"address": "22:22:22:22:22:22",
"created_at": "2016-08-18T22:28:48.643434+11:11",
"extra": {},
"internal_info": {},
"links": [
{
"href": "http://127.0.0.1:6385/v1/portgroups/e43c722c-248e-4c6e-8ce8-0d8ff129387a",
"rel": "self"
},
{
"href": "http://127.0.0.1:6385/portgroups/e43c722c-248e-4c6e-8ce8-0d8ff129387a",
"rel": "bookmark"
}
],
"mode": "active-backup",
"name": "test_portgroup",
"node_uuid": "6d85703a-565d-469a-96ce-30b6de53079d",
"ports": [
{
"href": "http://127.0.0.1:6385/v1/portgroups/e43c722c-248e-4c6e-8ce8-0d8ff129387a/ports",
"rel": "self"
},
{
"href": "http://127.0.0.1:6385/portgroups/e43c722c-248e-4c6e-8ce8-0d8ff129387a/ports",
"rel": "bookmark"
}
],
"properties": {},
"standalone_ports_supported": true,
"updated_at": "2016-08-18T22:28:49.653974+00:00",
"uuid": "e43c722c-248e-4c6e-8ce8-0d8ff129387a"
}
Delete a Portgroup.
Normal response code: 204
Error codes: 400,401,403,404
Request¶
Name |
In |
Type |
Description |
|---|---|---|---|
portgroup_ident |
path |
string |
The UUID or Name of the portgroup. |
Listing Portgroups by Node (nodes, portgroups)¶
Added in version 1.24.
Given a Node identifier (uuid or name), the API exposes the list of,
and details of, all Portgroups associated with that Node.
These endpoints do not allow modification of the Portgroups; that should be
done by accessing the Portgroup resources under the /v1/portgroups
endpoint.
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 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 |
marker (Optional) |
query |
string |
The ID of the last-seen item. Use the |
sort_dir (Optional) |
query |
string |
Sorts the response by the requested sort
direction. A valid value is |
sort_key (Optional) |
query |
string |
Sorts the response by this attribute value.
Default is |
Response¶
Name |
In |
Type |
Description |
|---|---|---|---|
portgroups |
body |
array |
A collection of Portgroup resources. |
uuid |
body |
string |
The UUID for the resource. |
address (Optional) |
body |
string |
Physical hardware address of this Portgroup, typically the hardware MAC address. |
name |
body |
string |
Human-readable identifier for the Portgroup resource. May be undefined. |
links |
body |
array |
A list of relative links. Includes the self and bookmark links. |
Example list of a Node’s Portgroups:
{
"portgroups": [
{
"address": "22:22:22:22:22:22",
"links": [
{
"href": "http://127.0.0.1:6385/v1/portgroups/e43c722c-248e-4c6e-8ce8-0d8ff129387a",
"rel": "self"
},
{
"href": "http://127.0.0.1:6385/portgroups/e43c722c-248e-4c6e-8ce8-0d8ff129387a",
"rel": "bookmark"
}
],
"name": "test_portgroup",
"uuid": "e43c722c-248e-4c6e-8ce8-0d8ff129387a"
}
]
}
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 |
marker (Optional) |
query |
string |
The ID of the last-seen item. Use the |
sort_dir (Optional) |
query |
string |
Sorts the response by the requested sort
direction. A valid value is |
sort_key (Optional) |
query |
string |
Sorts the response by this attribute value.
Default is |
Response¶
Name |
In |
Type |
Description |
|---|---|---|---|
portgroups |
body |
array |
A collection of Portgroup resources. |
uuid |
body |
string |
The UUID for the resource. |
address (Optional) |
body |
string |
Physical hardware address of this Portgroup, typically the hardware MAC address. |
name |
body |
string |
Human-readable identifier for the Portgroup resource. May be undefined. |
node_uuid |
body |
string |
UUID of the Node this resource belongs to. |
standalone_ports_supported |
body |
boolean |
Indicates whether ports that are members of this portgroup can be used as stand-alone ports. |
internal_info |
body |
JSON |
Internal metadata set and stored by the Portgroup. This field is read-only. |
extra |
body |
object |
A set of one or more arbitrary metadata key and value pairs. |
mode |
body |
string |
Mode of the port group. For possible values, refer to
https://www.kernel.org/doc/Documentation/networking/bonding.txt. If not
specified in a request to create a port group, it will be set to the value
of the |
properties |
body |
JSON |
Key/value properties related to the port group’s configuration. |
ports |
body |
array |
Links to the collection of ports belonging to this portgroup. |
created_at |
body |
string |
The UTC date and time when the resource was created, ISO 8601 format. |
updated_at |
body |
string |
The UTC date and time when the resource was updated, ISO 8601 format. May be “null”. |
links |
body |
array |
A list of relative links. Includes the self and bookmark links. |
Example details of a Node’s Portgroups:
{
"portgroups": [
{
"address": "22:22:22:22:22:22",
"created_at": "2016-08-18T22:28:48.643434+11:11",
"extra": {},
"internal_info": {},
"links": [
{
"href": "http://127.0.0.1:6385/v1/portgroups/e43c722c-248e-4c6e-8ce8-0d8ff129387a",
"rel": "self"
},
{
"href": "http://127.0.0.1:6385/portgroups/e43c722c-248e-4c6e-8ce8-0d8ff129387a",
"rel": "bookmark"
}
],
"mode": "active-backup",
"name": "test_portgroup",
"node_uuid": "6d85703a-565d-469a-96ce-30b6de53079d",
"ports": [
{
"href": "http://127.0.0.1:6385/v1/portgroups/e43c722c-248e-4c6e-8ce8-0d8ff129387a/ports",
"rel": "self"
},
{
"href": "http://127.0.0.1:6385/portgroups/e43c722c-248e-4c6e-8ce8-0d8ff129387a/ports",
"rel": "bookmark"
}
],
"properties": {},
"standalone_ports_supported": true,
"updated_at": "2016-08-18T22:28:49.653974+00:00",
"uuid": "e43c722c-248e-4c6e-8ce8-0d8ff129387a"
}
]
}
Ports (ports)¶
Listing, Searching, Creating, Updating, and Deleting of bare metal Port
resources are done through the ports resource.
All Ports must be associated to a Node when created. This association can be changed, though the request may be rejected if either the current or destination Node are in a transitive state (e.g., in the process of deploying) or are in a state that would be non-deterministically affected by such a change (e.g., there is an active user instance on the Node).
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.
Added in version 1.6: Added the node query parameter. If both node_uuid and node are
specified in the request, node_uuid will be used to filter results.
Added in version 1.8: Added the fields request parameter. When specified, this causes the
content of the response to include only the specified fields, rather than the
default set.
Added in version 1.19: Added the pxe_enabled and local_link_connection fields.
Added in version 1.24: Added the portgroup_uuid field.
Added in version 1.34: Added the physical_network field.
Added in version 1.43: Added the detail boolean request parameter. When specified True this
causes the response to include complete details about each port.
Added in version 1.53: Added the is_smartnic field.
Added in version 1.82: Added the ability to filter ports based on the shard of the node they are associated with.
Normal response code: 200
Request¶
Name |
In |
Type |
Description |
|---|---|---|---|
node (Optional) |
query |
string |
Filter the list of returned Ports, and only return the ones associated with this specific node (name or UUID), or an empty set if not found. This filter takes precedence over all other filters, and cannot be set at the same time as node_uuid or portgroup. |
node_uuid (Optional) |
query |
string |
Filter the list of returned Ports, and only return the ones associated with this specific node UUID, or an empty set if not found. This filter takes precedence over all other filters, and cannot be set at the same time as node or portgroup. |
portgroup (Optional) |
query |
string |
Filter the list of returned Ports, and only return the ones associated with this specific Portgroup (name or UUID), or an empty set if not found. This filter takes precedence over all other filters, and cannot be set at the same time as node_uuid or node. |
address (Optional) |
query |
string |
Filter the list of returned Ports, and only return the ones with the specified physical hardware address, typically MAC, or an empty set if not found. |
shard (Optional) |
query |
array |
Filter the list of returned Ports, and only return the ones associated with nodes in this specific shard(s), or an empty set if not found. |
fields (Optional) |
query |
array |
One or more fields to be returned in the response. For example, the following request returns only the 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 |
marker (Optional) |
query |
string |
The ID of the last-seen item. Use the |
sort_dir (Optional) |
query |
string |
Sorts the response by the requested sort
direction. A valid value is |
sort_key (Optional) |
query |
string |
Sorts the response by this attribute value.
Default is |
detail (Optional) |
query |
boolean |
Whether to show detailed information about the resource. This cannot be
set to True if |
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"
}
]
}
Creates a new Port resource.
This method requires a Node UUID and the physical hardware address for the Port (MAC address in most cases).
Added in version 1.19: Added the pxe_enabled and local_link_connection
request and response fields.
Added in version 1.24: Added the portgroup_uuid request and response fields.
Added in version 1.34: Added the physical_network request and response fields.
Added in version 1.53: Added the is_smartnic request and response fields.
Added in version 1.88: Added the name field.
Added in version 1.90: local_link_connection fields now accepts a dictionary
of vtep-logical-switch, vtep-physical-switch and port_id
to identify ovn vtep switches.
Added in version 1.94: Added support to create ports passing in either the node name or UUID.
Normal response code: 201
Request¶
Name |
In |
Type |
Description |
|---|---|---|---|
node_ident |
path |
string |
The UUID or Name of the node. |
address |
body |
string |
Physical hardware address of this network Port, typically the hardware MAC address. |
portgroup_uuid (Optional) |
body |
string |
UUID of the Portgroup this resource belongs to. |
name (Optional) |
body |
string |
The name assigned to the network Port. |
local_link_connection (Optional) |
body |
JSON |
The Port binding profile. If specified, must contain |
pxe_enabled (Optional) |
body |
boolean |
Indicates whether PXE is enabled or disabled on the Port. |
physical_network (Optional) |
body |
string |
The name of the physical network to which a port is connected. May be empty. |
extra (Optional) |
body |
object |
A set of one or more arbitrary metadata key and value pairs. |
is_smartnic (Optional) |
body |
boolean |
Indicates whether the Port is a Smart NIC port. |
uuid (Optional) |
body |
string |
The UUID for the resource. |
Note
Either node_ident or node_uuid is a valid parameter.
Example Port creation request:
{
"node_ident": "6d85703a-565d-469a-96ce-30b6de53079d",
"portgroup_uuid": "e43c722c-248e-4c6e-8ce8-0d8ff129387a",
"name": "port1",
"address": "11:11:11:11:11:11",
"is_smartnic": true,
"local_link_connection": {
"switch_id": "0a:1b:2c:3d:4e:5f",
"port_id": "Ethernet3/1",
"switch_info": "switch1"
},
"physical_network": "physnet1"
}
Response¶
Name |
In |
Type |
Description |
|---|---|---|---|
uuid |
body |
string |
The UUID for the resource. |
address |
body |
string |
Physical hardware address of this network Port, typically the hardware MAC address. |
node_uuid |
body |
string |
UUID of the Node this resource belongs to. |
portgroup_uuid |
body |
string |
UUID of the Portgroup this resource belongs to. |
name (Optional) |
body |
string |
The name assigned to the network Port. |
local_link_connection |
body |
JSON |
The Port binding profile. If specified, must contain |
pxe_enabled |
body |
boolean |
Indicates whether PXE is enabled or disabled on the Port. |
physical_network |
body |
string |
The name of the physical network to which a port is connected. May be empty. |
internal_info |
body |
JSON |
Internal metadata set and stored by the Port. This field is read-only. |
extra |
body |
object |
A set of one or more arbitrary metadata key and value pairs. |
created_at |
body |
string |
The UTC date and time when the resource was created, ISO 8601 format. |
updated_at |
body |
string |
The UTC date and time when the resource was updated, ISO 8601 format. May be “null”. |
links |
body |
array |
A list of relative links. Includes the self and bookmark links. |
is_smartnic (Optional) |
body |
boolean |
Indicates whether the Port is a Smart NIC port. |
Example Port creation response:
{
"address": "11:11:11:11:11:11",
"created_at": "2016-08-18T22:28:48.643434+11:11",
"extra": {},
"internal_info": {},
"is_smartnic": true,
"links": [
{
"href": "http://127.0.0.1:6385/v1/ports/d2b30520-907d-46c8-bfee-c5586e6fb3a1",
"rel": "self"
},
{
"href": "http://127.0.0.1:6385/ports/d2b30520-907d-46c8-bfee-c5586e6fb3a1",
"rel": "bookmark"
}
],
"local_link_connection": {
"port_id": "Ethernet3/1",
"switch_id": "0a:1b:2c:3d:4e:5f",
"switch_info": "switch1"
},
"name": "port1",
"node_uuid": "6d85703a-565d-469a-96ce-30b6de53079d",
"physical_network": "physnet1",
"portgroup_uuid": "e43c722c-248e-4c6e-8ce8-0d8ff129387a",
"pxe_enabled": true,
"updated_at": null,
"uuid": "d2b30520-907d-46c8-bfee-c5586e6fb3a1"
}
Return a list of bare metal Ports, with detailed information.
Added in version 1.6: Added the node query parameter. If both node_uuid and node are
specified in the request, node_uuid will be used to filter results.
Added in version 1.19: Added the pxe_enabled and local_link_connection response fields.
Added in version 1.24: Added the portgroup query parameter and portgroup_uuid response
field.
Added in version 1.34: Added the physical_network response field.
Added in version 1.53: Added the is_smartnic response fields.
Added in version 1.82: Added the ability to filter ports based on the shard of the node they are associated with.
Added in version 1.88: Added the name field.
Normal response code: 200
Request¶
Name |
In |
Type |
Description |
|---|---|---|---|
node (Optional) |
query |
string |
Filter the list of returned Ports, and only return the ones associated with this specific node (name or UUID), or an empty set if not found. This filter takes precedence over all other filters, and cannot be set at the same time as node_uuid or portgroup. |
node_uuid (Optional) |
query |
string |
Filter the list of returned Ports, and only return the ones associated with this specific node UUID, or an empty set if not found. This filter takes precedence over all other filters, and cannot be set at the same time as node or portgroup. |
portgroup (Optional) |
query |
string |
Filter the list of returned Ports, and only return the ones associated with this specific Portgroup (name or UUID), or an empty set if not found. This filter takes precedence over all other filters, and cannot be set at the same time as node_uuid or node. |
address (Optional) |
query |
string |
Filter the list of returned Ports, and only return the ones with the specified physical hardware address, typically MAC, or an empty set if not found. |
shard (Optional) |
query |
array |
Filter the list of returned Ports, and only return the ones associated with nodes in this specific shard(s), or an empty set if not found. |
limit (Optional) |
query |
integer |
Requests a page size of items. Returns a number of items up to a limit
value. Use the |
marker (Optional) |
query |
string |
The ID of the last-seen item. Use the |
sort_dir (Optional) |
query |
string |
Sorts the response by the requested sort
direction. A valid value is |
sort_key (Optional) |
query |
string |
Sorts the response by this attribute value.
Default is |
Response¶
Name |
In |
Type |
Description |
|---|---|---|---|
ports |
body |
array |
A collection of Port resources. |
uuid |
body |
string |
The UUID for the resource. |
address |
body |
string |
Physical hardware address of this network Port, typically the hardware MAC address. |
node_uuid |
body |
string |
UUID of the Node this resource belongs to. |
portgroup_uuid |
body |
string |
UUID of the Portgroup this resource belongs to. |
name (Optional) |
body |
string |
The name assigned to the network Port. |
local_link_connection |
body |
JSON |
The Port binding profile. If specified, must contain |
pxe_enabled |
body |
boolean |
Indicates whether PXE is enabled or disabled on the Port. |
physical_network |
body |
string |
The name of the physical network to which a port is connected. May be empty. |
internal_info |
body |
JSON |
Internal metadata set and stored by the Port. This field is read-only. |
extra |
body |
object |
A set of one or more arbitrary metadata key and value pairs. |
created_at |
body |
string |
The UTC date and time when the resource was created, ISO 8601 format. |
updated_at |
body |
string |
The UTC date and time when the resource was updated, ISO 8601 format. May be “null”. |
links |
body |
array |
A list of relative links. Includes the self and bookmark links. |
is_smartnic (Optional) |
body |
boolean |
Indicates whether the Port is a Smart NIC port. |
Example detailed Port list response:
{
"ports": [
{
"address": "11:11:11:11:11:11",
"created_at": "2016-08-18T22:28:48.643434+11:11",
"extra": {},
"internal_info": {},
"is_smartnic": true,
"links": [
{
"href": "http://127.0.0.1:6385/v1/ports/d2b30520-907d-46c8-bfee-c5586e6fb3a1",
"rel": "self"
},
{
"href": "http://127.0.0.1:6385/ports/d2b30520-907d-46c8-bfee-c5586e6fb3a1",
"rel": "bookmark"
}
],
"local_link_connection": {
"port_id": "Ethernet3/1",
"switch_id": "0a:1b:2c:3d:4e:5f",
"switch_info": "switch1"
},
"name": "port1",
"node_uuid": "6d85703a-565d-469a-96ce-30b6de53079d",
"physical_network": "physnet1",
"portgroup_uuid": "e43c722c-248e-4c6e-8ce8-0d8ff129387a",
"pxe_enabled": true,
"updated_at": null,
"uuid": "d2b30520-907d-46c8-bfee-c5586e6fb3a1"
}
]
}
Show details for the given Port.
Added in version 1.8: Added the fields request parameter. When specified, this causes the
content of the response to include only the specified fields, rather than the
default set.
Added in version 1.19: Added the pxe_enabled and local_link_connection response fields.
Added in version 1.24: Added the portgroup_uuid response field.
Added in version 1.34: Added the physical_network response field.
Added in version 1.53: Added the is_smartnic response fields.
Added in version 1.88: Added the name
Normal response code: 200
Request¶
Name |
In |
Type |
Description |
|---|---|---|---|
port_id |
path |
string |
The UUID or Name of the port. |
fields (Optional) |
query |
array |
One or more fields to be returned in the response. For example, the following request returns only the GET /v1/nodes?fields=uuid,name
|
Response¶
Name |
In |
Type |
Description |
|---|---|---|---|
uuid |
body |
string |
The UUID for the resource. |
address |
body |
string |
Physical hardware address of this network Port, typically the hardware MAC address. |
node_uuid |
body |
string |
UUID of the Node this resource belongs to. |
portgroup_uuid |
body |
string |
UUID of the Portgroup this resource belongs to. |
name (Optional) |
body |
string |
The name assigned to the network Port. |
local_link_connection |
body |
JSON |
The Port binding profile. If specified, must contain |
pxe_enabled |
body |
boolean |
Indicates whether PXE is enabled or disabled on the Port. |
physical_network |
body |
string |
The name of the physical network to which a port is connected. May be empty. |
internal_info |
body |
JSON |
Internal metadata set and stored by the Port. This field is read-only. |
extra |
body |
object |
A set of one or more arbitrary metadata key and value pairs. |
created_at |
body |
string |
The UTC date and time when the resource was created, ISO 8601 format. |
updated_at |
body |
string |
The UTC date and time when the resource was updated, ISO 8601 format. May be “null”. |
links |
body |
array |
A list of relative links. Includes the self and bookmark links. |
is_smartnic (Optional) |
body |
boolean |
Indicates whether the Port is a Smart NIC port. |
Example Port details:
{
"address": "11:11:11:11:11:11",
"created_at": "2016-08-18T22:28:48.643434+11:11",
"extra": {},
"internal_info": {},
"is_smartnic": true,
"links": [
{
"href": "http://127.0.0.1:6385/v1/ports/d2b30520-907d-46c8-bfee-c5586e6fb3a1",
"rel": "self"
},
{
"href": "http://127.0.0.1:6385/ports/d2b30520-907d-46c8-bfee-c5586e6fb3a1",
"rel": "bookmark"
}
],
"local_link_connection": {
"port_id": "Ethernet3/1",
"switch_id": "0a:1b:2c:3d:4e:5f",
"switch_info": "switch1"
},
"name": "port1",
"node_uuid": "6d85703a-565d-469a-96ce-30b6de53079d",
"physical_network": "physnet1",
"portgroup_uuid": "e43c722c-248e-4c6e-8ce8-0d8ff129387a",
"pxe_enabled": true,
"updated_at": null,
"uuid": "d2b30520-907d-46c8-bfee-c5586e6fb3a1"
}
Update a Port.
Added in version 1.19: Added the pxe_enabled and local_link_connection fields.
Added in version 1.24: Added the portgroup_uuid field.
Added in version 1.34: Added the physical_network field.
Added in version 1.53: Added the is_smartnic fields.
Added in version 1.88: Added the name
Added in version 1.90: local_link_connection fields now accepts a dictionary
of vtep-logical-switch, vtep-physical-switch and port_id
to identify ovn vtep switches.
Normal response code: 200
Request¶
The BODY of the PATCH request must be a JSON PATCH document, adhering to RFC 6902.
Name |
In |
Type |
Description |
|---|---|---|---|
port_id |
path |
string |
The UUID or Name of the port. |
Example Port update request:
[
{
"path" : "/address",
"value" : "22:22:22:22:22:22",
"op" : "replace"
}
]
Response¶
Name |
In |
Type |
Description |
|---|---|---|---|
uuid |
body |
string |
The UUID for the resource. |
address |
body |
string |
Physical hardware address of this network Port, typically the hardware MAC address. |
node_uuid |
body |
string |
UUID of the Node this resource belongs to. |
portgroup_uuid |
body |
string |
UUID of the Portgroup this resource belongs to. |
name (Optional) |
body |
string |
The name assigned to the network Port. |
local_link_connection |
body |
JSON |
The Port binding profile. If specified, must contain |
pxe_enabled |
body |
boolean |
Indicates whether PXE is enabled or disabled on the Port. |
physical_network |
body |
string |
The name of the physical network to which a port is connected. May be empty. |
internal_info |
body |
JSON |
Internal metadata set and stored by the Port. This field is read-only. |
extra |
body |
object |
A set of one or more arbitrary metadata key and value pairs. |
created_at |
body |
string |
The UTC date and time when the resource was created, ISO 8601 format. |
updated_at |
body |
string |
The UTC date and time when the resource was updated, ISO 8601 format. May be “null”. |
links |
body |
array |
A list of relative links. Includes the self and bookmark links. |
is_smartnic (Optional) |
body |
boolean |
Indicates whether the Port is a Smart NIC port. |
Example Port update response:
{
"address": "22:22:22:22:22:22",
"created_at": "2016-08-18T22:28:48.643434+11:11",
"extra": {},
"internal_info": {},
"is_smartnic": true,
"links": [
{
"href": "http://127.0.0.1:6385/v1/ports/d2b30520-907d-46c8-bfee-c5586e6fb3a1",
"rel": "self"
},
{
"href": "http://127.0.0.1:6385/ports/d2b30520-907d-46c8-bfee-c5586e6fb3a1",
"rel": "bookmark"
}
],
"local_link_connection": {
"port_id": "Ethernet3/1",
"switch_id": "0a:1b:2c:3d:4e:5f",
"switch_info": "switch1"
},
"name": "port1",
"node_uuid": "6d85703a-565d-469a-96ce-30b6de53079d",
"physical_network": "physnet1",
"portgroup_uuid": "e43c722c-248e-4c6e-8ce8-0d8ff129387a",
"pxe_enabled": true,
"updated_at": "2016-08-18T22:28:49.653974+00:00",
"uuid": "d2b30520-907d-46c8-bfee-c5586e6fb3a1"
}
Delete a Port.
Normal response code: 204
Request¶
Name |
In |
Type |
Description |
|---|---|---|---|
port_id |
path |
string |
The UUID or Name of the port. |
Listing Ports by Node (nodes, ports)¶
Given a Node identifier (uuid or name), the API exposes the list of,
and details of, all Ports associated with that Node.
These endpoints do not allow modification of the Ports; that should be done
by accessing the Port resources under the /v1/ports endpoint.
Return a list of bare metal Ports associated with node_ident.
Added in version 1.8: Added the fields request parameter. When specified, this causes the
content of the response to include only the specified fields, rather than the
default set.
Added in version 1.19: Added the pxe_enabled and local_link_connection fields.
Added in version 1.24: Added the portgroup_uuid field.
Added in version 1.34: Added the physical_network field.
Added in version 1.53: Added the is_smartnic response fields.
Normal response code: 200
Error codes: TBD
Request¶
Name |
In |
Type |
Description |
|---|---|---|---|
node_ident |
path |
string |
The UUID or Name of the node. |
fields (Optional) |
query |
array |
One or more fields to be returned in the response. For example, the following request returns only the 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 |
marker (Optional) |
query |
string |
The ID of the last-seen item. Use the |
sort_dir (Optional) |
query |
string |
Sorts the response by the requested sort
direction. A valid value is |
sort_key (Optional) |
query |
string |
Sorts the response by this attribute value.
Default is |
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"
}
]
}
Return a detailed list of bare metal Ports associated with node_ident.
Added in version 1.19: Added the pxe_enabled and local_link_connection fields.
Added in version 1.24: Added the portgroup_uuid field.
Added in version 1.34: Added the physical_network field.
Added in version 1.53: Added the is_smartnic response fields.
Normal response code: 200
Error codes: TBD
Request¶
Name |
In |
Type |
Description |
|---|---|---|---|
node_ident |
path |
string |
The UUID or Name of the node. |
fields (Optional) |
query |
array |
One or more fields to be returned in the response. For example, the following request returns only the 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 |
marker (Optional) |
query |
string |
The ID of the last-seen item. Use the |
sort_dir (Optional) |
query |
string |
Sorts the response by the requested sort
direction. A valid value is |
sort_key (Optional) |
query |
string |
Sorts the response by this attribute value.
Default is |
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 |
pxe_enabled |
body |
boolean |
Indicates whether PXE is enabled or disabled on the Port. |
physical_network |
body |
string |
The name of the physical network to which a port is connected. May be empty. |
internal_info |
body |
JSON |
Internal metadata set and stored by the Port. This field is read-only. |
extra |
body |
object |
A set of one or more arbitrary metadata key and value pairs. |
created_at |
body |
string |
The UTC date and time when the resource was created, ISO 8601 format. |
updated_at |
body |
string |
The UTC date and time when the resource was updated, ISO 8601 format. May be “null”. |
links |
body |
array |
A list of relative links. Includes the self and bookmark links. |
is_smartnic (Optional) |
body |
boolean |
Indicates whether the Port is a Smart NIC port. |
Example details of a Node’s Ports:
{
"ports": [
{
"address": "22:22:22:22:22:22",
"created_at": "2016-08-18T22:28:48.643434+11:11",
"extra": {},
"internal_info": {},
"is_smartnic": true,
"links": [
{
"href": "http://127.0.0.1:6385/v1/ports/d2b30520-907d-46c8-bfee-c5586e6fb3a1",
"rel": "self"
},
{
"href": "http://127.0.0.1:6385/ports/d2b30520-907d-46c8-bfee-c5586e6fb3a1",
"rel": "bookmark"
}
],
"local_link_connection": {
"port_id": "Ethernet3/1",
"switch_id": "0a:1b:2c:3d:4e:5f",
"switch_info": "switch1"
},
"node_uuid": "6d85703a-565d-469a-96ce-30b6de53079d",
"physical_network": "physnet1",
"portgroup_uuid": "e43c722c-248e-4c6e-8ce8-0d8ff129387a",
"pxe_enabled": true,
"updated_at": "2016-08-18T22:28:49.653974+00:00",
"uuid": "d2b30520-907d-46c8-bfee-c5586e6fb3a1"
}
]
}
Listing Ports by Portgroup (portgroup, ports)¶
Added in version 1.24.
Given a Portgroup identifier (uuid or name), the API exposes the list
of, and details of, all Ports associated with that Portgroup.
These endpoints do not allow modification of the Ports; that should be done
by accessing the Port resources under the /v1/ports endpoint.
Return a list of bare metal Ports associated with portgroup_ident.
When specified, the fields request parameter causes the content of the
Response to include only the specified fields, rather than the default set.
Added in version 1.34: Added the physical_network field.
Added in version 1.53: Added the is_smartnic response fields.
Normal response code: 200
Error codes: 400,401,403,404
Request¶
Name |
In |
Type |
Description |
|---|---|---|---|
portgroup_ident |
path |
string |
The UUID or Name of the portgroup. |
fields (Optional) |
query |
array |
One or more fields to be returned in the response. For example, the following request returns only the 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 |
marker (Optional) |
query |
string |
The ID of the last-seen item. Use the |
sort_dir (Optional) |
query |
string |
Sorts the response by the requested sort
direction. A valid value is |
sort_key (Optional) |
query |
string |
Sorts the response by this attribute value.
Default is |
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"
}
]
}
Return a detailed list of bare metal Ports associated with portgroup_ident.
Added in version 1.34: Added the physical_network field.
Added in version 1.53: Added the is_smartnic response fields.
Normal response code: 200
Error codes: 400,401,403,404
Request¶
Name |
In |
Type |
Description |
|---|---|---|---|
portgroup_ident |
path |
string |
The UUID or Name of the portgroup. |
limit (Optional) |
query |
integer |
Requests a page size of items. Returns a number of items up to a limit
value. Use the |
marker (Optional) |
query |
string |
The ID of the last-seen item. Use the |
sort_dir (Optional) |
query |
string |
Sorts the response by the requested sort
direction. A valid value is |
sort_key (Optional) |
query |
string |
Sorts the response by this attribute value.
Default is |
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 |
pxe_enabled |
body |
boolean |
Indicates whether PXE is enabled or disabled on the Port. |
physical_network |
body |
string |
The name of the physical network to which a port is connected. May be empty. |
internal_info |
body |
JSON |
Internal metadata set and stored by the Port. This field is read-only. |
extra |
body |
object |
A set of one or more arbitrary metadata key and value pairs. |
portgroup_uuid |
body |
string |
UUID of the Portgroup this resource belongs to. |
created_at |
body |
string |
The UTC date and time when the resource was created, ISO 8601 format. |
updated_at |
body |
string |
The UTC date and time when the resource was updated, ISO 8601 format. May be “null”. |
links |
body |
array |
A list of relative links. Includes the self and bookmark links. |
is_smartnic (Optional) |
body |
boolean |
Indicates whether the Port is a Smart NIC port. |
Example details of a Portgroup’s Ports:
{
"ports": [
{
"address": "22:22:22:22:22:22",
"created_at": "2016-08-18T22:28:48.643434+11:11",
"extra": {},
"internal_info": {},
"is_smartnic": true,
"links": [
{
"href": "http://127.0.0.1:6385/v1/ports/d2b30520-907d-46c8-bfee-c5586e6fb3a1",
"rel": "self"
},
{
"href": "http://127.0.0.1:6385/ports/d2b30520-907d-46c8-bfee-c5586e6fb3a1",
"rel": "bookmark"
}
],
"local_link_connection": {
"port_id": "Ethernet3/1",
"switch_id": "0a:1b:2c:3d:4e:5f",
"switch_info": "switch1"
},
"node_uuid": "6d85703a-565d-469a-96ce-30b6de53079d",
"physical_network": "physnet1",
"portgroup_uuid": "e43c722c-248e-4c6e-8ce8-0d8ff129387a",
"pxe_enabled": true,
"updated_at": "2016-08-18T22:28:49.653974+00:00",
"uuid": "d2b30520-907d-46c8-bfee-c5586e6fb3a1"
}
]
}
Volume (volume)¶
Added in version 1.32.
Information for connecting remote volumes to a node can be associated with a Node. There are two types of resources, Volume connectors and Volume targets. Volume connectors contain initiator information of Nodes. Volume targets contain target information of remote volumes.
Listing, Searching, Creating, Updating, and Deleting of Volume connector
resources are done through the v1/volume/connectors resource. The same
operations for Volume targets are done through the v1/volume/targets
resources.
Return a list of links to all volume resources.
Normal response code: 200
Request¶
Response¶
Name |
In |
Type |
Description |
|---|---|---|---|
connectors |
body |
array |
Links to a collection of Volume connector resources. |
targets |
body |
array |
Links to a collection of Volume target resources. |
links |
body |
array |
A list of relative links. Includes the self and bookmark links. |
Example Volume list response:
{
"connectors": [
{
"href": "http://127.0.0.1:6385/v1/volume/connectors",
"rel": "self"
},
{
"href": "http://127.0.0.1:6385/volume/connectors",
"rel": "bookmark"
}
],
"links": [
{
"href": "http://127.0.0.1:6385/v1/volume/",
"rel": "self"
},
{
"href": "http://127.0.0.1:6385/volume/",
"rel": "bookmark"
}
],
"targets": [
{
"href": "http://127.0.0.1:6385/v1/volume/targets",
"rel": "self"
},
{
"href": "http://127.0.0.1:6385/volume/targets",
"rel": "bookmark"
}
]
}
Return a list of Volume connectors for all nodes.
By default, this query will return the UUID, node UUID, type, and connector ID for each Volume connector.
Normal response code: 200
Error codes: 400,401,403,404
Request¶
Name |
In |
Type |
Description |
|---|---|---|---|
node (Optional) |
query |
string |
Filter the list of returned Volume connectors, and only return the ones associated with this specific node (name or UUID), or an empty set if not found. |
fields (Optional) |
query |
array |
One or more fields to be returned in the response. For example, the following request returns only the GET /v1/nodes?fields=uuid,name
|
detail (Optional) |
query |
boolean |
Whether to show detailed information about the resource. This cannot be
set to True if |
limit (Optional) |
query |
integer |
Requests a page size of items. Returns a number of items up to a limit
value. Use the |
marker (Optional) |
query |
string |
The ID of the last-seen item. Use the |
sort_dir (Optional) |
query |
string |
Sorts the response by the requested sort
direction. A valid value is |
sort_key (Optional) |
query |
string |
Sorts the response by this attribute value.
Default is |
Response¶
Name |
In |
Type |
Description |
|---|---|---|---|
connectors |
body |
array |
A collection of Volume connector resources. |
uuid |
body |
string |
The UUID for the resource. |
type |
body |
string |
The type of Volume connector such as “iqn”, “ip”, “wwnn” and “wwpn”. |
connector_id |
body |
string |
The identifier of Volume connector. The identifier format depends on the
|
node_uuid |
body |
string |
UUID of the Node this resource belongs to. |
extra |
body |
object |
A set of one or more arbitrary metadata key and value pairs. |
links |
body |
array |
A list of relative links. Includes the self and bookmark links. |
next (Optional) |
body |
string |
A URL to request a next collection of the resource. This parameter is
returned when |
Example Volume connector list response:
{
"connectors": [
{
"connector_id": "iqn.2017-07.org.openstack:01:d9a51732c3f",
"links": [
{
"href": "http://127.0.0.1:6385/v1/volume/connectors/9bf93e01-d728-47a3-ad4b-5e66a835037c",
"rel": "self"
},
{
"href": "http://127.0.0.1:6385/volume/connectors/9bf93e01-d728-47a3-ad4b-5e66a835037c",
"rel": "bookmark"
}
],
"node_uuid": "6d85703a-565d-469a-96ce-30b6de53079d",
"type": "iqn",
"uuid": "9bf93e01-d728-47a3-ad4b-5e66a835037c"
}
]
}
Example detailed Volume connector list response:
{
"connectors": [
{
"connector_id": "iqn.2017-07.org.openstack:01:d9a51732c3f",
"created_at": "2016-08-18T22:28:48.643434+11:11",
"extra": {},
"links": [
{
"href": "http://127.0.0.1:6385/v1/volume/connectors/9bf93e01-d728-47a3-ad4b-5e66a835037c",
"rel": "self"
},
{
"href": "http://127.0.0.1:6385/volume/connectors/9bf93e01-d728-47a3-ad4b-5e66a835037c",
"rel": "bookmark"
}
],
"node_uuid": "6d85703a-565d-469a-96ce-30b6de53079d",
"type": "iqn",
"updated_at": null,
"uuid": "9bf93e01-d728-47a3-ad4b-5e66a835037c"
}
]
}
Creates a new Volume connector resource.
This method requires a Node UUID, a connector type and a connector ID.
Normal response code: 201
Error codes: 400,401,403,404,409
Request¶
Name |
In |
Type |
Description |
|---|---|---|---|
node_uuid |
body |
string |
UUID of the Node this resource belongs to. |
type |
body |
string |
The type of Volume connector such as “iqn”, “ip”, “wwnn” and “wwpn”. |
connector_id |
body |
string |
The identifier of Volume connector. The identifier format depends on the
|
extra (Optional) |
body |
object |
A set of one or more arbitrary metadata key and value pairs. |
uuid (Optional) |
body |
string |
The UUID for the resource. |
Example Volume connector creation request:
{
"node_uuid": "6d85703a-565d-469a-96ce-30b6de53079d",
"type": "iqn",
"connector_id": "iqn.2017-07.org.openstack:01:d9a51732c3f"
}
Response¶
Name |
In |
Type |
Description |
|---|---|---|---|
uuid |
body |
string |
The UUID for the resource. |
type |
body |
string |
The type of Volume connector such as “iqn”, “ip”, “wwnn” and “wwpn”. |
connector_id |
body |
string |
The identifier of Volume connector. The identifier format depends on the
|
node_uuid |
body |
string |
UUID of the Node this resource belongs to. |
extra |
body |
object |
A set of one or more arbitrary metadata key and value pairs. |
links |
body |
array |
A list of relative links. Includes the self and bookmark links. |
Example Volume connector creation response:
{
"connector_id": "iqn.2017-07.org.openstack:01:d9a51732c3f",
"created_at": "2016-08-18T22:28:48.643434+11:11",
"extra": {},
"links": [
{
"href": "http://127.0.0.1:6385/v1/volume/connectors/9bf93e01-d728-47a3-ad4b-5e66a835037c",
"rel": "self"
},
{
"href": "http://127.0.0.1:6385/volume/connectors/9bf93e01-d728-47a3-ad4b-5e66a835037c",
"rel": "bookmark"
}
],
"node_uuid": "6d85703a-565d-469a-96ce-30b6de53079d",
"type": "iqn",
"updated_at": null,
"uuid": "9bf93e01-d728-47a3-ad4b-5e66a835037c"
}
Show details for the given Volume connector.
Normal response code: 200
Error codes: 400,401,403,404
Request¶
Name |
In |
Type |
Description |
|---|---|---|---|
volume_connector_id |
path |
string |
The UUID of the Volume connector. |
fields (Optional) |
query |
array |
One or more fields to be returned in the response. For example, the following request returns only the GET /v1/nodes?fields=uuid,name
|
Response¶
Name |
In |
Type |
Description |
|---|---|---|---|
uuid |
body |
string |
The UUID for the resource. |
type |
body |
string |
The type of Volume connector such as “iqn”, “ip”, “wwnn” and “wwpn”. |
connector_id |
body |
string |
The identifier of Volume connector. The identifier format depends on the
|
node_uuid |
body |
string |
UUID of the Node this resource belongs to. |
extra |
body |
object |
A set of one or more arbitrary metadata key and value pairs. |
links |
body |
array |
A list of relative links. Includes the self and bookmark links. |
Example Volume connector details:
{
"connector_id": "iqn.2017-07.org.openstack:01:d9a51732c3f",
"created_at": "2016-08-18T22:28:48.643434+11:11",
"extra": {},
"links": [
{
"href": "http://127.0.0.1:6385/v1/volume/connectors/9bf93e01-d728-47a3-ad4b-5e66a835037c",
"rel": "self"
},
{
"href": "http://127.0.0.1:6385/volume/connectors/9bf93e01-d728-47a3-ad4b-5e66a835037c",
"rel": "bookmark"
}
],
"node_uuid": "6d85703a-565d-469a-96ce-30b6de53079d",
"type": "iqn",
"updated_at": null,
"uuid": "9bf93e01-d728-47a3-ad4b-5e66a835037c"
}
Update a Volume connector.
A Volume connector can be updated only while a node associated with the Volume connector is powered off.
Normal response code: 200
Error codes: 400,401,403,404,409
Request¶
The BODY of the PATCH request must be a JSON PATCH document, adhering to RFC 6902.
Name |
In |
Type |
Description |
|---|---|---|---|
volume_connector_id |
path |
string |
The UUID of the Volume connector. |
Example Volume connector update request:
[
{
"path" : "/connector_id",
"value" : "iqn.2017-07.org.openstack:02:10190a4153e",
"op" : "replace"
}
]
Response¶
Name |
In |
Type |
Description |
|---|---|---|---|
uuid |
body |
string |
The UUID for the resource. |
type |
body |
string |
The type of Volume connector such as “iqn”, “ip”, “wwnn” and “wwpn”. |
connector_id |
body |
string |
The identifier of Volume connector. The identifier format depends on the
|
node_uuid |
body |
string |
UUID of the Node this resource belongs to. |
extra |
body |
object |
A set of one or more arbitrary metadata key and value pairs. |
links |
body |
array |
A list of relative links. Includes the self and bookmark links. |
Example Volume connector update response:
{
"connector_id": "iqn.2017-07.org.openstack:02:10190a4153e",
"created_at": "2016-08-18T22:28:48.643434+11:11",
"extra": {},
"links": [
{
"href": "http://127.0.0.1:6385/v1/volume/connectors/9bf93e01-d728-47a3-ad4b-5e66a835037c",
"rel": "self"
},
{
"href": "http://127.0.0.1:6385/volume/connectors/9bf93e01-d728-47a3-ad4b-5e66a835037c",
"rel": "bookmark"
}
],
"node_uuid": "6d85703a-565d-469a-96ce-30b6de53079d",
"type": "iqn",
"updated_at": "2016-08-18T22:28:49.653974+00:00",
"uuid": "9bf93e01-d728-47a3-ad4b-5e66a835037c"
}
Delete a Volume connector.
A Volume connector can be deleted only while a node associated with the Volume connector is powered off.
Normal response code: 204
Error codes: 400,401,403,404,409
Request¶
Name |
In |
Type |
Description |
|---|---|---|---|
volume_connector_id |
path |
string |
The UUID of the Volume connector. |
Return a list of Volume targets for all nodes.
By default, this query will return the UUID, node UUID, volume type, boot index, and volume ID for each Volume target.
Normal response code: 200
Error codes: 400,401,403,404
Request¶
Name |
In |
Type |
Description |
|---|---|---|---|
node (Optional) |
query |
string |
Filter the list of returned Volume targets, and only return the ones associated with this specific node (name or UUID), or an empty set if not found. |
fields (Optional) |
query |
array |
One or more fields to be returned in the response. For example, the following request returns only the GET /v1/nodes?fields=uuid,name
|
detail (Optional) |
query |
boolean |
Whether to show detailed information about the resource. This cannot be
set to True if |
limit (Optional) |
query |
integer |
Requests a page size of items. Returns a number of items up to a limit
value. Use the |
marker (Optional) |
query |
string |
The ID of the last-seen item. Use the |
sort_dir (Optional) |
query |
string |
Sorts the response by the requested sort
direction. A valid value is |
sort_key (Optional) |
query |
string |
Sorts the response by this attribute value.
Default is |
Response¶
Name |
In |
Type |
Description |
|---|---|---|---|
targets |
body |
array |
A collection of Volume target resources. |
uuid |
body |
string |
The UUID for the resource. |
volume_type |
body |
string |
The type of Volume target such as ‘iscsi’ and ‘fibre_channel’. |
properties |
body |
object |
A set of physical information of the volume such as the identifier (eg. IQN) and LUN number of the volume. This information is used to connect the node to the volume by the storage interface. The contents depend on the volume type. |
boot_index |
body |
string |
The boot index of the Volume target. “0” indicates that this volume is used as a boot volume. |
volume_id |
body |
string |
The identifier of the volume. This ID is used by storage interface to distinguish volumes. |
extra |
body |
object |
A set of one or more arbitrary metadata key and value pairs. |
node_uuid |
body |
string |
UUID of the Node this resource belongs to. |
links |
body |
array |
A list of relative links. Includes the self and bookmark links. |
next (Optional) |
body |
string |
A URL to request a next collection of the resource. This parameter is
returned when |
Example Volume target list response:
{
"targets": [
{
"boot_index": 0,
"links": [
{
"href": "http://127.0.0.1:6385/v1/volume/targets/bd4d008c-7d31-463d-abf9-6c23d9d55f7f",
"rel": "self"
},
{
"href": "http://127.0.0.1:6385/volume/targets/bd4d008c-7d31-463d-abf9-6c23d9d55f7f",
"rel": "bookmark"
}
],
"node_uuid": "6d85703a-565d-469a-96ce-30b6de53079d",
"uuid": "bd4d008c-7d31-463d-abf9-6c23d9d55f7f",
"volume_id": "04452bed-5367-4202-8bf5-de4335ac56d2",
"volume_type": "iscsi"
}
]
}
Example detailed Volume target list response:
{
"targets": [
{
"boot_index": 0,
"created_at": "2016-08-18T22:28:48.643434+11:11",
"extra": {},
"links": [
{
"href": "http://127.0.0.1:6385/v1/volume/targets/bd4d008c-7d31-463d-abf9-6c23d9d55f7f",
"rel": "self"
},
{
"href": "http://127.0.0.1:6385/volume/targets/bd4d008c-7d31-463d-abf9-6c23d9d55f7f",
"rel": "bookmark"
}
],
"node_uuid": "6d85703a-565d-469a-96ce-30b6de53079d",
"properties": {},
"updated_at": null,
"uuid": "bd4d008c-7d31-463d-abf9-6c23d9d55f7f",
"volume_id": "04452bed-5367-4202-8bf5-de4335ac56d2",
"volume_type": "iscsi"
}
]
}
Creates a new Volume target resource.
This method requires a Node UUID, volume type, volume ID, and boot index..
Normal response code: 201
Error codes: 400,401,403,404,409
Request¶
Name |
In |
Type |
Description |
|---|---|---|---|
node_uuid |
body |
string |
UUID of the Node this resource belongs to. |
volume_type |
body |
string |
The type of Volume target such as ‘iscsi’ and ‘fibre_channel’. |
properties (Optional) |
body |
object |
A set of physical information of the volume such as the identifier (eg. IQN) and LUN number of the volume. This information is used to connect the node to the volume by the storage interface. The contents depend on the volume type. |
boot_index |
body |
string |
The boot index of the Volume target. “0” indicates that this volume is used as a boot volume. |
volume_id |
body |
string |
The identifier of the volume. This ID is used by storage interface to distinguish volumes. |
extra (Optional) |
body |
object |
A set of one or more arbitrary metadata key and value pairs. |
uuid (Optional) |
body |
string |
The UUID for the resource. |
Example Volume target creation request:
{
"node_uuid": "6d85703a-565d-469a-96ce-30b6de53079d",
"volume_type": "iscsi",
"boot_index": 0,
"volume_id": "04452bed-5367-4202-8bf5-de4335ac56d2"
}
Response¶
Name |
In |
Type |
Description |
|---|---|---|---|
uuid |
body |
string |
The UUID for the resource. |
volume_type |
body |
string |
The type of Volume target such as ‘iscsi’ and ‘fibre_channel’. |
properties |
body |
object |
A set of physical information of the volume such as the identifier (eg. IQN) and LUN number of the volume. This information is used to connect the node to the volume by the storage interface. The contents depend on the volume type. |
boot_index |
body |
string |
The boot index of the Volume target. “0” indicates that this volume is used as a boot volume. |
volume_id |
body |
string |
The identifier of the volume. This ID is used by storage interface to distinguish volumes. |
extra |
body |
object |
A set of one or more arbitrary metadata key and value pairs. |
node_uuid |
body |
string |
UUID of the Node this resource belongs to. |
links |
body |
array |
A list of relative links. Includes the self and bookmark links. |
Example Volume target creation response:
{
"boot_index": 0,
"created_at": "2016-08-18T22:28:48.643434+11:11",
"extra": {},
"links": [
{
"href": "http://127.0.0.1:6385/v1/volume/targets/bd4d008c-7d31-463d-abf9-6c23d9d55f7f",
"rel": "self"
},
{
"href": "http://127.0.0.1:6385/volume/targets/bd4d008c-7d31-463d-abf9-6c23d9d55f7f",
"rel": "bookmark"
}
],
"node_uuid": "6d85703a-565d-469a-96ce-30b6de53079d",
"properties": {},
"updated_at": null,
"uuid": "bd4d008c-7d31-463d-abf9-6c23d9d55f7f",
"volume_id": "04452bed-5367-4202-8bf5-de4335ac56d2",
"volume_type": "iscsi"
}
Show details for the given Volume target.
Normal response code: 200
Error codes: 400,401,403,404
Request¶
Name |
In |
Type |
Description |
|---|---|---|---|
volume_target_id |
path |
string |
The UUID of the Volume target. |
fields (Optional) |
query |
array |
One or more fields to be returned in the response. For example, the following request returns only the GET /v1/nodes?fields=uuid,name
|
Response¶
Name |
In |
Type |
Description |
|---|---|---|---|
uuid |
body |
string |
The UUID for the resource. |
volume_type |
body |
string |
The type of Volume target such as ‘iscsi’ and ‘fibre_channel’. |
properties |
body |
object |
A set of physical information of the volume such as the identifier (eg. IQN) and LUN number of the volume. This information is used to connect the node to the volume by the storage interface. The contents depend on the volume type. |
boot_index |
body |
string |
The boot index of the Volume target. “0” indicates that this volume is used as a boot volume. |
volume_id |
body |
string |
The identifier of the volume. This ID is used by storage interface to distinguish volumes. |
extra |
body |
object |
A set of one or more arbitrary metadata key and value pairs. |
node_uuid |
body |
string |
UUID of the Node this resource belongs to. |
links |
body |
array |
A list of relative links. Includes the self and bookmark links. |
Example Volume target details:
{
"boot_index": 0,
"created_at": "2016-08-18T22:28:48.643434+11:11",
"extra": {},
"links": [
{
"href": "http://127.0.0.1:6385/v1/volume/targets/bd4d008c-7d31-463d-abf9-6c23d9d55f7f",
"rel": "self"
},
{
"href": "http://127.0.0.1:6385/volume/targets/bd4d008c-7d31-463d-abf9-6c23d9d55f7f",
"rel": "bookmark"
}
],
"node_uuid": "6d85703a-565d-469a-96ce-30b6de53079d",
"properties": {},
"updated_at": null,
"uuid": "bd4d008c-7d31-463d-abf9-6c23d9d55f7f",
"volume_id": "04452bed-5367-4202-8bf5-de4335ac56d2",
"volume_type": "iscsi"
}
Update a Volume target.
A Volume target can be updated only while a node associated with the Volume target is powered off.
Normal response code: 200
Error codes: 400,401,403,404,409
Request¶
The BODY of the PATCH request must be a JSON PATCH document, adhering to RFC 6902.
Name |
In |
Type |
Description |
|---|---|---|---|
volume_target_id |
path |
string |
The UUID of the Volume target. |
Example Volume target update request:
[
{
"path" : "/volume_id",
"value" : "7211f7d3-3f32-4efc-b64e-9b8e92e64a8e",
"op" : "replace"
}
]
Response¶
Name |
In |
Type |
Description |
|---|---|---|---|
uuid |
body |
string |
The UUID for the resource. |
volume_type |
body |
string |
The type of Volume target such as ‘iscsi’ and ‘fibre_channel’. |
properties |
body |
object |
A set of physical information of the volume such as the identifier (eg. IQN) and LUN number of the volume. This information is used to connect the node to the volume by the storage interface. The contents depend on the volume type. |
boot_index |
body |
string |
The boot index of the Volume target. “0” indicates that this volume is used as a boot volume. |
volume_id |
body |
string |
The identifier of the volume. This ID is used by storage interface to distinguish volumes. |
extra |
body |
object |
A set of one or more arbitrary metadata key and value pairs. |
node_uuid |
body |
string |
UUID of the Node this resource belongs to. |
links |
body |
array |
A list of relative links. Includes the self and bookmark links. |
Example Volume target update response:
{
"boot_index": 0,
"created_at": "2016-08-18T22:28:48.643434+11:11",
"extra": {},
"links": [
{
"href": "http://127.0.0.1:6385/v1/volume/targets/bd4d008c-7d31-463d-abf9-6c23d9d55f7f",
"rel": "self"
},
{
"href": "http://127.0.0.1:6385/volume/targets/bd4d008c-7d31-463d-abf9-6c23d9d55f7f",
"rel": "bookmark"
}
],
"node_uuid": "6d85703a-565d-469a-96ce-30b6de53079d",
"properties": {},
"updated_at": "2016-08-18T22:28:49.653974+00:00",
"uuid": "bd4d008c-7d31-463d-abf9-6c23d9d55f7f",
"volume_id": "7211f7d3-3f32-4efc-b64e-9b8e92e64a8e",
"volume_type": "iscsi"
}
Delete a Volume target.
A Volume target can be deleted only while a node associated with the Volume target is powered off.
Normal response code: 204
Error codes: 400,401,403,404,409
Request¶
Name |
In |
Type |
Description |
|---|---|---|---|
volume_target_id |
path |
string |
The UUID of the Volume target. |
Listing Volume resources by Node (nodes, volume)¶
Added in version 1.32.
Given a Node identifier (uuid or name), the API exposes the list of,
and details of, all Volume resources associated with that Node.
These endpoints do not allow modification of the Volume connectors and Volume
targets; that should be done by accessing the Volume resources under the
/v1/volume/connectors and /v1/volume/targets endpoint.
Return a list of links to all volume resources associated with node_ident.
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 |
|---|---|---|---|
connectors |
body |
array |
Links to a collection of Volume connector resources. |
targets |
body |
array |
Links to a collection of Volume target resources. |
links |
body |
array |
A list of relative links. Includes the self and bookmark links. |
Example Volume list response:
{
"connectors": [
{
"href": "http://127.0.0.1:6385/v1/nodes/6d85703a-565d-469a-96ce-30b6de53079d/volume/connectors",
"rel": "self"
},
{
"href": "http://127.0.0.1:6385/nodes/6d85703a-565d-469a-96ce-30b6de53079d/volume/connectors",
"rel": "bookmark"
}
],
"links": [
{
"href": "http://127.0.0.1:6385/v1/nodes/6d85703a-565d-469a-96ce-30b6de53079d/volume/",
"rel": "self"
},
{
"href": "http://127.0.0.1:6385/nodes/6d85703a-565d-469a-96ce-30b6de53079d/volume/",
"rel": "bookmark"
}
],
"targets": [
{
"href": "http://127.0.0.1:6385/v1/nodes/6d85703a-565d-469a-96ce-30b6de53079d/volume/targets",
"rel": "self"
},
{
"href": "http://127.0.0.1:6385/nodes/6d85703a-565d-469a-96ce-30b6de53079d/volume/targets",
"rel": "bookmark"
}
]
}
Return a list of bare metal Volume connectors associated with node_ident.
Normal response code: 200
Error codes: 400,401,403,404
Request¶
Name |
In |
Type |
Description |
|---|---|---|---|
node_ident |
path |
string |
The UUID or Name of the node. |
fields (Optional) |
query |
array |
One or more fields to be returned in the response. For example, the following request returns only the 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 |
marker (Optional) |
query |
string |
The ID of the last-seen item. Use the |
sort_dir (Optional) |
query |
string |
Sorts the response by the requested sort
direction. A valid value is |
sort_key (Optional) |
query |
string |
Sorts the response by this attribute value.
Default is |
Response¶
Name |
In |
Type |
Description |
|---|---|---|---|
connectors |
body |
array |
A collection of Volume connector resources. |
uuid |
body |
string |
The UUID for the resource. |
type |
body |
string |
The type of Volume connector such as “iqn”, “ip”, “wwnn” and “wwpn”. |
connector_id |
body |
string |
The identifier of Volume connector. The identifier format depends on the
|
node_uuid |
body |
string |
UUID of the Node this resource belongs to. |
extra |
body |
object |
A set of one or more arbitrary metadata key and value pairs. |
links |
body |
array |
A list of relative links. Includes the self and bookmark links. |
next (Optional) |
body |
string |
A URL to request a next collection of the resource. This parameter is
returned when |
Example list of Node’s Volume connectors:
{
"connectors": [
{
"connector_id": "iqn.2017-07.org.openstack:02:10190a4153e",
"links": [
{
"href": "http://127.0.0.1:6385/v1/volume/connectors/9bf93e01-d728-47a3-ad4b-5e66a835037c",
"rel": "self"
},
{
"href": "http://127.0.0.1:6385/volume/connectors/9bf93e01-d728-47a3-ad4b-5e66a835037c",
"rel": "bookmark"
}
],
"node_uuid": "6d85703a-565d-469a-96ce-30b6de53079d",
"type": "iqn",
"uuid": "9bf93e01-d728-47a3-ad4b-5e66a835037c"
}
]
}
Example detailed list of Node’s Volume connectors:
{
"connectors": [
{
"connector_id": "iqn.2017-07.org.openstack:02:10190a4153e",
"created_at": "2016-08-18T22:28:48.643434+11:11",
"extra": {},
"links": [
{
"href": "http://127.0.0.1:6385/v1/volume/connectors/9bf93e01-d728-47a3-ad4b-5e66a835037c",
"rel": "self"
},
{
"href": "http://127.0.0.1:6385/volume/connectors/9bf93e01-d728-47a3-ad4b-5e66a835037c",
"rel": "bookmark"
}
],
"node_uuid": "6d85703a-565d-469a-96ce-30b6de53079d",
"type": "iqn",
"updated_at": "2016-08-18T22:28:49.653974+00:00",
"uuid": "9bf93e01-d728-47a3-ad4b-5e66a835037c"
}
]
}
Return a list of bare metal Volume targets associated with node_ident.
Normal response code: 200
Error codes: 400,401,403,404
Request¶
Name |
In |
Type |
Description |
|---|---|---|---|
node_ident |
path |
string |
The UUID or Name of the node. |
fields (Optional) |
query |
array |
One or more fields to be returned in the response. For example, the following request returns only the 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 |
marker (Optional) |
query |
string |
The ID of the last-seen item. Use the |
sort_dir (Optional) |
query |
string |
Sorts the response by the requested sort
direction. A valid value is |
sort_key (Optional) |
query |
string |
Sorts the response by this attribute value.
Default is |
Response¶
Name |
In |
Type |
Description |
|---|---|---|---|
targets |
body |
array |
A collection of Volume target resources. |
uuid |
body |
string |
The UUID for the resource. |
volume_type |
body |
string |
The type of Volume target such as ‘iscsi’ and ‘fibre_channel’. |
properties |
body |
object |
A set of physical information of the volume such as the identifier (eg. IQN) and LUN number of the volume. This information is used to connect the node to the volume by the storage interface. The contents depend on the volume type. |
boot_index |
body |
string |
The boot index of the Volume target. “0” indicates that this volume is used as a boot volume. |
volume_id |
body |
string |
The identifier of the volume. This ID is used by storage interface to distinguish volumes. |
extra |
body |
object |
A set of one or more arbitrary metadata key and value pairs. |
node_uuid |
body |
string |
UUID of the Node this resource belongs to. |
links |
body |
array |
A list of relative links. Includes the self and bookmark links. |
next (Optional) |
body |
string |
A URL to request a next collection of the resource. This parameter is
returned when |
Example list of Node’s Volume targets:
{
"targets": [
{
"boot_index": 0,
"links": [
{
"href": "http://127.0.0.1:6385/v1/volume/targets/bd4d008c-7d31-463d-abf9-6c23d9d55f7f",
"rel": "self"
},
{
"href": "http://127.0.0.1:6385/volume/targets/bd4d008c-7d31-463d-abf9-6c23d9d55f7f",
"rel": "bookmark"
}
],
"node_uuid": "6d85703a-565d-469a-96ce-30b6de53079d",
"uuid": "bd4d008c-7d31-463d-abf9-6c23d9d55f7f",
"volume_id": "7211f7d3-3f32-4efc-b64e-9b8e92e64a8e",
"volume_type": "iscsi"
}
]
}
Example detailed list of Node’s Volume targets:
{
"targets": [
{
"boot_index": 0,
"created_at": "2016-08-18T22:28:48.643434+11:11",
"extra": {},
"links": [
{
"href": "http://127.0.0.1:6385/v1/volume/targets/bd4d008c-7d31-463d-abf9-6c23d9d55f7f",
"rel": "self"
},
{
"href": "http://127.0.0.1:6385/volume/targets/bd4d008c-7d31-463d-abf9-6c23d9d55f7f",
"rel": "bookmark"
}
],
"node_uuid": "6d85703a-565d-469a-96ce-30b6de53079d",
"properties": {},
"updated_at": "2016-08-18T22:28:49.653974+00:00",
"uuid": "bd4d008c-7d31-463d-abf9-6c23d9d55f7f",
"volume_id": "7211f7d3-3f32-4efc-b64e-9b8e92e64a8e",
"volume_type": "iscsi"
}
]
}
Drivers (drivers)¶
Changed in version 1.30: The REST API now also exposes information about dynamic drivers.
Ironic has two types of drivers: classic drivers and dynamic drivers.
A classic driver is a Python object containing all the logic to manage the
bare metal nodes enrolled within Ironic. A driver may be loaded within one or
more ironic-conductor services. Each driver contains a pre-determined set
of instantiated interfaces. Each type of interface (eg, power or boot)
performs a specific hardware function.
Dynamic drivers are supported via hardware types, which are Python classes
enabled via entry points. Unlike classic drivers, which have pre-determined
interfaces, a hardware type may support multiple types of interfaces. For
example, the ipmi hardware type may support multiple methods for enabling
node console. Which interface a node of a particular hardware type uses is
determined at runtime. This collection of interfaces is called a dynamic
driver. For more information about this, see the node API documentation.
The REST API exposes the list of drivers and which ironic-conductor
processes have loaded that driver via the Driver resource (/v1/drivers
endpoint). This can be useful for operators to validate their configuration in
a heterogeneous hardware environment. Each ironic-conductor process may
load one or more drivers, and does not necessarily need to load the same
classic drivers as another ironic-conductor. Each ironic-conductor
with the same hardware types must have the same hardware interfaces enabled.
The REST API also exposes details about each driver, such as what properties
must be supplied to a node’s driver_info for that driver to manage
hardware.
Lastly, some drivers may expose methods through a driver_vendor_passthru
endpoint, allowing one to interact with the driver directly (i.e., without
knowing a specific node identifier). For example, this is used by the ironic
python agent ramdisk to get the UUID of the node being deployed/cleaned by
using MAC addresses of the node’s network interfaces the agent has discovered.
Lists all drivers.
Added in version 1.77: Added fields selector to query for particular fields.
Normal response codes: 200
Request¶
Name |
In |
Type |
Description |
|---|---|---|---|
type (Optional) |
query |
string |
Only list drivers of this type. Options are “classic” or “dynamic”. |
detail (Optional) |
query |
boolean |
Whether to show detailed information about the drivers (e.g. the “boot_interface” field). |
fields (Optional) |
query |
array |
One or more fields to be returned in the response. For example, the following request returns only the GET /v1/nodes?fields=uuid,name
|
Response Parameters¶
The response BODY contains a single key, “drivers”, whose value is a list of drivers supported by this Ironic service.
Name |
In |
Type |
Description |
|---|---|---|---|
drivers |
body |
array |
A list of driver objects. |
name |
body |
string |
The name of the driver. |
hosts |
body |
array |
A list of active hosts that support this driver. |
type |
body |
string |
Type of this driver (“classic” or “dynamic”). |
links |
body |
array |
A list of relative links. Includes the self and bookmark links. |
properties |
body |
array |
A list of links to driver properties. |
Changed in version 1.30: If the request has the “detail” URL parameter set to true, each driver will also include the following fields.
Added in version 1.86: Introduced the default_firmware_interface and
enabled_firmware_interfaces fields.
Name |
In |
Type |
Description |
|---|---|---|---|
default_bios_interface |
body |
string |
The default bios interface used for a node with a dynamic driver, if no bios interface is specified for the node. |
default_boot_interface |
body |
string |
The default boot interface used for a node with a dynamic driver, if no boot interface is specified for the node. |
default_console_interface |
body |
string |
The default console interface used for a node with a dynamic driver, if no console interface is specified for the node. |
default_deploy_interface |
body |
string |
The default deploy interface used for a node with a dynamic driver, if no deploy interface is specified for the node. |
default_firmware_interface |
body |
string |
The default firmware interface used for a node with a dynamic driver, if no firmware interface is specified for the node. |
default_inspect_interface |
body |
string |
The default inspection interface used for a node with a dynamic driver, if no inspection interface is specified for the node. |
default_management_interface |
body |
string |
The default management interface used for a node with a dynamic driver, if no management interface is specified for the node. |
default_network_interface |
body |
string |
The default network interface used for a node with a dynamic driver, if no network interface is specified for the node. |
default_power_interface |
body |
string |
The default power interface used for a node with a dynamic driver, if no power interface is specified for the node. |
default_raid_interface |
body |
string |
The default RAID interface used for a node with a dynamic driver, if no RAID interface is specified for the node. |
default_rescue_interface |
body |
string |
The default rescue interface used for a node with a dynamic driver, if no rescue interface is specified for the node. |
default_storage_interface |
body |
string |
The default storage interface used for a node with a dynamic driver, if no storage interface is specified for the node. |
default_vendor_interface |
body |
string |
The default vendor interface used for a node with a dynamic driver, if no vendor interface is specified for the node. |
enabled_bios_interfaces |
body |
list |
The enabled bios interfaces for this driver. |
enabled_boot_interfaces |
body |
list |
The enabled boot interfaces for this driver. |
enabled_console_interfaces |
body |
list |
The enabled console interfaces for this driver. |
enabled_deploy_interfaces |
body |
list |
The enabled deploy interfaces for this driver. |
enabled_firmware_interfaces |
body |
list |
The enabled firmware interfaces for this driver. |
enabled_inspect_interfaces |
body |
list |
The enabled inspection interfaces for this driver. |
enabled_management_interfaces |
body |
list |
The enabled management interfaces for this driver. |
enabled_network_interfaces |
body |
list |
The enabled network interfaces for this driver. |
enabled_power_interfaces |
body |
list |
The enabled power interfaces for this driver. |
enabled_rescue_interfaces |
body |
list |
The enabled rescue interfaces for this driver. |
enabled_raid_interfaces |
body |
list |
The enabled RAID interfaces for this driver. |
enabled_storage_interfaces |
body |
list |
The enabled storage interfaces for this driver. |
enabled_vendor_interfaces |
body |
list |
The enabled vendor interfaces for this driver. |
Response Example¶
Example for a request with detail=false (the default):
{
"drivers": [
{
"hosts": [
"897ab1dad809"
],
"links": [
{
"href": "http://127.0.0.1:6385/v1/drivers/agent_ipmitool",
"rel": "self"
},
{
"href": "http://127.0.0.1:6385/drivers/agent_ipmitool",
"rel": "bookmark"
}
],
"name": "agent_ipmitool",
"properties": [
{
"href": "http://127.0.0.1:6385/v1/drivers/agent_ipmitool/properties",
"rel": "self"
},
{
"href": "http://127.0.0.1:6385/drivers/agent_ipmitool/properties",
"rel": "bookmark"
}
],
"type": "classic"
},
{
"hosts": [
"897ab1dad809"
],
"links": [
{
"href": "http://127.0.0.1:6385/v1/drivers/fake",
"rel": "self"
},
{
"href": "http://127.0.0.1:6385/drivers/fake",
"rel": "bookmark"
}
],
"name": "fake",
"properties": [
{
"href": "http://127.0.0.1:6385/v1/drivers/fake/properties",
"rel": "self"
},
{
"href": "http://127.0.0.1:6385/drivers/fake/properties",
"rel": "bookmark"
}
],
"type": "classic"
},
{
"hosts": [
"897ab1dad809"
],
"links": [
{
"href": "http://127.0.0.1:6385/v1/drivers/ipmi",
"rel": "self"
},
{
"href": "http://127.0.0.1:6385/drivers/ipmi",
"rel": "bookmark"
}
],
"name": "ipmi",
"properties": [
{
"href": "http://127.0.0.1:6385/v1/drivers/ipmi/properties",
"rel": "self"
},
{
"href": "http://127.0.0.1:6385/drivers/ipmi/properties",
"rel": "bookmark"
}
],
"type": "dynamic"
}
]
}
Example for a request with detail=true:
{
"drivers": [
{
"default_bios_interface": null,
"default_boot_interface": null,
"default_console_interface": null,
"default_deploy_interface": null,
"default_firmware_interface": null,
"default_inspect_interface": null,
"default_management_interface": null,
"default_network_interface": null,
"default_power_interface": null,
"default_raid_interface": null,
"default_rescue_interface": null,
"default_storage_interface": null,
"default_vendor_interface": null,
"enabled_bios_interfaces": null,
"enabled_boot_interfaces": null,
"enabled_console_interfaces": null,
"enabled_deploy_interfaces": null,
"enabled_firmware_interfaces": null,
"enabled_inspect_interfaces": null,
"enabled_management_interfaces": null,
"enabled_network_interfaces": null,
"enabled_power_interfaces": null,
"enabled_raid_interfaces": null,
"enabled_rescue_interfaces": null,
"enabled_storage_interfaces": null,
"enabled_vendor_interfaces": null,
"hosts": [
"897ab1dad809"
],
"links": [
{
"href": "http://127.0.0.1:6385/v1/drivers/agent_ipmitool",
"rel": "self"
},
{
"href": "http://127.0.0.1:6385/drivers/agent_ipmitool",
"rel": "bookmark"
}
],
"name": "agent_ipmitool",
"properties": [
{
"href": "http://127.0.0.1:6385/v1/drivers/agent_ipmitool/properties",
"rel": "self"
},
{
"href": "http://127.0.0.1:6385/drivers/agent_ipmitool/properties",
"rel": "bookmark"
}
],
"type": "classic"
},
{
"default_bios_interface": null,
"default_boot_interface": null,
"default_console_interface": null,
"default_deploy_interface": null,
"default_firmware_interface": null,
"default_inspect_interface": null,
"default_management_interface": null,
"default_network_interface": null,
"default_power_interface": null,
"default_raid_interface": null,
"default_rescue_interface": null,
"default_storage_interface": null,
"default_vendor_interface": null,
"enabled_bios_interfaces": null,
"enabled_boot_interfaces": null,
"enabled_console_interfaces": null,
"enabled_deploy_interfaces": null,
"enabled_firmware_interfaces": null,
"enabled_inspect_interfaces": null,
"enabled_management_interfaces": null,
"enabled_network_interfaces": null,
"enabled_power_interfaces": null,
"enabled_raid_interfaces": null,
"enabled_rescue_interfaces": null,
"enabled_storage_interfaces": null,
"enabled_vendor_interfaces": null,
"hosts": [
"897ab1dad809"
],
"links": [
{
"href": "http://127.0.0.1:6385/v1/drivers/fake",
"rel": "self"
},
{
"href": "http://127.0.0.1:6385/drivers/fake",
"rel": "bookmark"
}
],
"name": "fake",
"properties": [
{
"href": "http://127.0.0.1:6385/v1/drivers/fake/properties",
"rel": "self"
},
{
"href": "http://127.0.0.1:6385/drivers/fake/properties",
"rel": "bookmark"
}
],
"type": "classic"
},
{
"default_bios_interface": "no-bios",
"default_boot_interface": "pxe",
"default_console_interface": "no-console",
"default_deploy_interface": "direct",
"default_firmware_interface": "no-firmware",
"default_inspect_interface": "no-inspect",
"default_management_interface": "ipmitool",
"default_network_interface": "flat",
"default_power_interface": "ipmitool",
"default_raid_interface": "no-raid",
"default_rescue_interface": "no-rescue",
"default_storage_interface": "noop",
"default_vendor_interface": "no-vendor",
"enabled_bios_interfaces": [
"no-bios"
],
"enabled_boot_interfaces": [
"pxe"
],
"enabled_console_interfaces": [
"no-console"
],
"enabled_deploy_interfaces": [
"ansible",
"direct"
],
"enabled_firmware_interface": [
"no-firmware"
],
"enabled_inspect_interfaces": [
"no-inspect"
],
"enabled_management_interfaces": [
"ipmitool"
],
"enabled_network_interfaces": [
"flat",
"noop"
],
"enabled_power_interfaces": [
"ipmitool"
],
"enabled_raid_interfaces": [
"no-raid",
"agent"
],
"enabled_rescue_interfaces": [
"no-rescue"
],
"enabled_storage_interfaces": [
"noop"
],
"enabled_vendor_interfaces": [
"no-vendor"
],
"hosts": [
"897ab1dad809"
],
"links": [
{
"href": "http://127.0.0.1:6385/v1/drivers/ipmi",
"rel": "self"
},
{
"href": "http://127.0.0.1:6385/drivers/ipmi",
"rel": "bookmark"
}
],
"name": "ipmi",
"properties": [
{
"href": "http://127.0.0.1:6385/v1/drivers/ipmi/properties",
"rel": "self"
},
{
"href": "http://127.0.0.1:6385/drivers/ipmi/properties",
"rel": "bookmark"
}
],
"type": "dynamic"
}
]
}
Shows details for a driver.
Added in version 1.77: Added fields selector to query for particular fields.
Added in version 1.86: Introduced the default_firmware_interface and
enabled_firmware_interfaces fields.
Normal response codes: 200
Request¶
Name |
In |
Type |
Description |
|---|---|---|---|
driver_name |
path |
string |
The name of the driver. |
fields (Optional) |
query |
array |
One or more fields to be returned in the response. For example, the following request returns only the GET /v1/nodes?fields=uuid,name
|
Response Parameters¶
Name |
In |
Type |
Description |
|---|---|---|---|
name |
body |
string |
The name of the driver. |
hosts |
body |
array |
A list of active hosts that support this driver. |
type |
body |
string |
Type of this driver (“classic” or “dynamic”). |
default_bios_interface |
body |
string |
The default bios interface used for a node with a dynamic driver, if no bios interface is specified for the node. |
default_boot_interface |
body |
string |
The default boot interface used for a node with a dynamic driver, if no boot interface is specified for the node. |
default_console_interface |
body |
string |
The default console interface used for a node with a dynamic driver, if no console interface is specified for the node. |
default_deploy_interface |
body |
string |
The default deploy interface used for a node with a dynamic driver, if no deploy interface is specified for the node. |
default_firmware_interface |
body |
string |
The default firmware interface used for a node with a dynamic driver, if no firmware interface is specified for the node. |
default_inspect_interface |
body |
string |
The default inspection interface used for a node with a dynamic driver, if no inspection interface is specified for the node. |
default_management_interface |
body |
string |
The default management interface used for a node with a dynamic driver, if no management interface is specified for the node. |
default_network_interface |
body |
string |
The default network interface used for a node with a dynamic driver, if no network interface is specified for the node. |
default_power_interface |
body |
string |
The default power interface used for a node with a dynamic driver, if no power interface is specified for the node. |
default_raid_interface |
body |
string |
The default RAID interface used for a node with a dynamic driver, if no RAID interface is specified for the node. |
default_rescue_interface |
body |
string |
The default rescue interface used for a node with a dynamic driver, if no rescue interface is specified for the node. |
default_storage_interface |
body |
string |
The default storage interface used for a node with a dynamic driver, if no storage interface is specified for the node. |
default_vendor_interface |
body |
string |
The default vendor interface used for a node with a dynamic driver, if no vendor interface is specified for the node. |
enabled_bios_interfaces |
body |
list |
The enabled bios interfaces for this driver. |
enabled_boot_interfaces |
body |
list |
The enabled boot interfaces for this driver. |
enabled_console_interfaces |
body |
list |
The enabled console interfaces for this driver. |
enabled_deploy_interfaces |
body |
list |
The enabled deploy interfaces for this driver. |
enabled_firmware_interfaces |
body |
list |
The enabled firmware interfaces for this driver. |
enabled_inspect_interfaces |
body |
list |
The enabled inspection interfaces for this driver. |
enabled_management_interfaces |
body |
list |
The enabled management interfaces for this driver. |
enabled_network_interfaces |
body |
list |
The enabled network interfaces for this driver. |
enabled_power_interfaces |
body |
list |
The enabled power interfaces for this driver. |
enabled_raid_interfaces |
body |
list |
The enabled RAID interfaces for this driver. |
enabled_rescue_interfaces |
body |
list |
The enabled rescue interfaces for this driver. |
enabled_storage_interfaces |
body |
list |
The enabled storage interfaces for this driver. |
enabled_vendor_interfaces |
body |
list |
The enabled vendor interfaces for this driver. |
links |
body |
array |
A list of relative links. Includes the self and bookmark links. |
properties |
body |
array |
A list of links to driver properties. |
Response Example¶
{
"default_bios_interface": "no-bios",
"default_boot_interface": "pxe",
"default_console_interface": "no-console",
"default_deploy_interface": "direct",
"default_firmware_interface": "no-firmware",
"default_inspect_interface": "no-inspect",
"default_management_interface": "ipmitool",
"default_network_interface": "flat",
"default_power_interface": "ipmitool",
"default_raid_interface": "no-raid",
"default_rescue_interface": "no-rescue",
"default_storage_interface": "noop",
"default_vendor_interface": "no-vendor",
"enabled_bios_interfaces": [
"no-bios"
],
"enabled_boot_interfaces": [
"pxe"
],
"enabled_console_interfaces": [
"no-console"
],
"enabled_deploy_interfaces": [
"ansible",
"direct"
],
"enabled_firmware_interface": [
"no-firmware"
],
"enabled_inspect_interfaces": [
"no-inspect"
],
"enabled_management_interfaces": [
"ipmitool"
],
"enabled_network_interfaces": [
"flat",
"noop"
],
"enabled_power_interfaces": [
"ipmitool"
],
"enabled_raid_interfaces": [
"no-raid",
"agent"
],
"enabled_rescue_interfaces": [
"no-rescue"
],
"enabled_storage_interfaces": [
"noop"
],
"enabled_vendor_interfaces": [
"no-vendor"
],
"hosts": [
"897ab1dad809"
],
"links": [
{
"href": "http://127.0.0.1:6385/v1/drivers/ipmi",
"rel": "self"
},
{
"href": "http://127.0.0.1:6385/drivers/ipmi",
"rel": "bookmark"
}
],
"name": "ipmi",
"properties": [
{
"href": "http://127.0.0.1:6385/v1/drivers/ipmi/properties",
"rel": "self"
},
{
"href": "http://127.0.0.1:6385/drivers/ipmi/properties",
"rel": "bookmark"
}
],
"type": "dynamic"
}
Shows the required and optional parameters that driver_name expects to be
supplied in the driver_info field for every Node it manages.
To check if all required parameters have been supplied to a Node, you should
query the /v1/nodes/{node_ident}/validate endpoint.
Normal response codes: 200
Request¶
Name |
In |
Type |
Description |
|---|---|---|---|
driver_name |
path |
string |
The name of the driver. |
Response Example¶
The response BODY is a dictionary, but the keys are unique to each driver.
The structure of the response is property : description.
The following example is returned from the agent_ipmitool driver.
{
"deploy_forces_oob_reboot": "Whether Ironic should force a reboot of the Node via the out-of-band channel after deployment is complete. Provides compatibility with older deploy ramdisks. Defaults to False. Optional.",
"deploy_kernel": "UUID (from Glance) of the deployment kernel. Required.",
"deploy_ramdisk": "UUID (from Glance) of the ramdisk that is mounted at boot time. Required.",
"image_http_proxy": "URL of a proxy server for HTTP connections. Optional.",
"image_https_proxy": "URL of a proxy server for HTTPS connections. Optional.",
"image_no_proxy": "A comma-separated list of host names, IP addresses and domain names (with optional :port) that will be excluded from proxying. To denote a domain name, use a dot to prefix the domain name. This value will be ignored if ``image_http_proxy`` and ``image_https_proxy`` are not specified. Optional.",
"ipmi_address": "IP address or hostname of the node. Required.",
"ipmi_bridging": "bridging_type; default is \"no\". One of \"single\", \"dual\", \"no\". Optional.",
"ipmi_disable_boot_timeout": "By default ironic will send a raw IPMI command to disable the 60 second timeout for booting. Setting this option to False will NOT send that command; default value is True. Optional.",
"ipmi_force_boot_device": "Whether Ironic should specify the boot device to the BMC each time the server is turned on, eg. because the BMC is not capable of remembering the selected boot device across power cycles; default value is False. Optional.",
"ipmi_local_address": "local IPMB address for bridged requests. Used only if ipmi_bridging is set to \"single\" or \"dual\". Optional.",
"ipmi_password": "password. Optional.",
"ipmi_port": "remote IPMI RMCP port. Optional.",
"ipmi_priv_level": "privilege level; default is ADMINISTRATOR. One of ADMINISTRATOR, CALLBACK, OPERATOR, USER. Optional.",
"ipmi_protocol_version": "the version of the IPMI protocol; default is \"2.0\". One of \"1.5\", \"2.0\". Optional.",
"ipmi_target_address": "destination address for bridged request. Required only if ipmi_bridging is set to \"single\" or \"dual\".",
"ipmi_target_channel": "destination channel for bridged request. Required only if ipmi_bridging is set to \"single\" or \"dual\".",
"ipmi_terminal_port": "node's UDP port to connect to. Only required for console access.",
"ipmi_transit_address": "transit address for bridged request. Required only if ipmi_bridging is set to \"dual\".",
"ipmi_transit_channel": "transit channel for bridged request. Required only if ipmi_bridging is set to \"dual\".",
"ipmi_username": "username; default is NULL user. Optional."
}
Added in version 1.12.
Show the required and optional parameters that driver_name expects to be
supplied in the node’s raid_config field, if a RAID configuration change is
requested.
Normal response codes: 200
Request¶
Name |
In |
Type |
Description |
|---|---|---|---|
driver_name |
path |
string |
The name of the driver. |
Response Example¶
The response BODY is a dictionary, but the keys are unique to each driver.
The structure of the response is property : description.
The following example is returned from the agent_ipmitool driver.
{
"controller": "Controller to use for this logical disk. If not specified, the driver will choose a suitable RAID controller on the bare metal node. Optional.",
"disk_type": "The type of disk preferred. Valid values are 'hdd' and 'ssd'. If this is not specified, disk type will not be a selection criterion for choosing backing physical disks. Optional.",
"interface_type": "The interface type of disk. Valid values are 'sata', 'scsi' and 'sas'. If this is not specified, interface type will not be a selection criterion for choosing backing physical disks. Optional.",
"is_root_volume": "Specifies whether this disk is a root volume. By default, this is False. Optional.",
"number_of_physical_disks": "Number of physical disks to use for this logical disk. By default, the driver uses the minimum number of disks required for that RAID level. Optional.",
"physical_disks": "The physical disks to use for this logical disk. If not specified, the driver will choose suitable physical disks to use. Optional.",
"raid_level": "RAID level for the logical disk. Valid values are 'JBOD', '0', '1', '2', '5', '6', '1+0', '5+0' and '6+0'. Required.",
"share_physical_disks": "Specifies whether other logical disks can share physical disks with this logical disk. By default, this is False. Optional.",
"size_gb": "Size in GiB (Integer) for the logical disk. Use 'MAX' as size_gb if this logical disk is supposed to use the rest of the space available. Required.",
"volume_name": "Name of the volume to be created. If this is not specified, it will be auto-generated. Optional."
}
Driver Vendor Passthru (drivers)¶
Each driver MAY support vendor-specific extensions, called “passthru” methods.
Internally, Ironic’s driver API supports flexibly exposing functions via the
common HTTP methods GET, PUT, POST, and DELETE. To call a passthru method,
the query string must contain the name of the method. For example, if the
method name was my_passthru_method, the request would look like
/vendor_passthru?method=my_passthru_method. The contents of the HTTP
request are forwarded to the driver and validated there.
Ironic’s REST API provides a means to discover these methods, but does not provide support, testing, or documentation for these endpoints. The Ironic development team does not guarantee any compatibility within these methods between releases, though we encourage driver authors to provide documentation and support for them.
Besides the endpoints documented here, all other resources and endpoints
under the heading vendor_passthru should be considered unsupported APIs,
and could be changed without warning by the driver authors.
Retrieve a list of the available vendor passthru methods for the given Driver. The response will indicate which HTTP method(s) each vendor passthru method allows, whether the method call will be synchronous or asynchronous, and whether the response will include any attachment.
Normal response code: 200
Request¶
Name |
In |
Type |
Description |
|---|---|---|---|
driver_name |
path |
string |
The name of the driver. |
Response¶
The response BODY is a dictionary whose keys are the method names. The value of each item is itself a dictionary describing how to interact with that method.
Name |
In |
Type |
Description |
|---|---|---|---|
async |
body |
boolean |
If True the passthru function is invoked asynchronously; if False, synchronously. |
attach |
body |
boolean |
True if the return value will be attached to the response object, and False if the return value will be returned in the response body. |
description |
body |
string |
A description of what the method does, including any method parameters. |
http_methods |
body |
array |
A list of HTTP methods supported by the vendor function. |
The HTTP METHOD may be one of GET, POST, PUT, DELETE, depending on the driver and method.
This endpoint passes the request directly to the hardware driver. The HTTP BODY must be parseable JSON, which will be converted to parameters passed to that function. Unparsable JSON, missing parameters, or excess parameters will cause the request to be rejected with an HTTP 400 error.
Normal response code: 200 202
Error codes: 400
Request¶
Name |
In |
Type |
Description |
|---|---|---|---|
driver_name |
path |
string |
The name of the driver. |
method_name |
query |
string |
Driver specific method name. |
All other parameters should be passed in the BODY. Parameter list varies by method_name.
Response¶
Varies.
Node Bios (nodes)¶
Added in version 1.40.
Given a Node identifier (uuid or name), the API exposes the list of
all Bios settings associated with that Node.
These endpoints do not allow modification of the Bios settings; that should be
done by using clean steps.
Return a list of Bios settings associated with node_ident.
Added in version 1.74: Added additional fields from bios registry which can be retrieved using
?detail=True (see detailed response below).
Added fields selector to query for particular fields.
Normal response code: 200
Error codes: 404
Request¶
Name |
In |
Type |
Description |
|---|---|---|---|
node_ident |
path |
string |
The UUID or Name of the node. |
fields (Optional) |
query |
array |
One or more fields to be returned in the response. For example, the following request returns only the GET /v1/nodes?fields=uuid,name
|
detail (Optional) |
query |
boolean |
Whether to show detailed information about the resource. This cannot be
set to True if |
Response¶
Name |
In |
Type |
Description |
|---|---|---|---|
bios |
body |
array |
Optional list of one or more Bios settings. It includes following fields “created_at”, “updated_at”, “links”, “name”, “value”, “attribute_type”, “allowable_values”, “lower_bound”, “max_length”, “min_length”, “read_only”, “reset_required”, “unique”, “upper_bound” |
created_at |
body |
string |
The UTC date and time when the resource was created, ISO 8601 format. |
updated_at |
body |
string |
The UTC date and time when the resource was updated, ISO 8601 format. May be “null”. |
links |
body |
array |
A list of relative links. Includes the self and bookmark links. |
name |
body |
string |
The name of a Bios setting for a Node, eg. “virtualization”. |
value |
body |
string |
The value of a Bios setting for a Node, eg. “on”. |
Example list of a Node’s Bios settings:
{
"bios": [
{
"created_at": "2016-08-18T22:28:49.653974+00:00",
"updated_at": "2016-08-18T22:28:49.653974+00:00",
"links": [
{
"href": "http://127.0.0.1:6385/v1/nodes/6d85703a-565d-469a-96ce-30b6de53079d/bios/virtualization",
"rel": "self"
},
{
"href": "http://127.0.0.1:6385/v1/nodes/6d85703a-565d-469a-96ce-30b6de53079d/bios/virtualization",
"rel": "bookmark"
}
],
"name": "Virtualization",
"value": "Enabled"
}
]
}
Return a list of detailed Bios settings associated with node_ident.
The detailed list includes the BIOS Attribute Registry information
retrieved via Redfish.
Added in version 1.74: Introduced
Normal response code: 200
Error codes: 404
Request¶
Name |
In |
Type |
Description |
|---|---|---|---|
node_ident |
path |
string |
The UUID or Name of the node. |
Response¶
Name |
In |
Type |
Description |
|---|---|---|---|
bios |
body |
array |
Optional list of one or more Bios settings. It includes following fields “created_at”, “updated_at”, “links”, “name”, “value”, “attribute_type”, “allowable_values”, “lower_bound”, “max_length”, “min_length”, “read_only”, “reset_required”, “unique”, “upper_bound” |
created_at |
body |
string |
The UTC date and time when the resource was created, ISO 8601 format. |
updated_at |
body |
string |
The UTC date and time when the resource was updated, ISO 8601 format. May be “null”. |
links |
body |
array |
A list of relative links. Includes the self and bookmark links. |
name |
body |
string |
The name of a Bios setting for a Node, eg. “virtualization”. |
value |
body |
string |
The value of a Bios setting for a Node, eg. “on”. |
attribute_type |
body |
string |
A string describing the type of the Bios setting. May be |
allowable_values |
body |
array |
A list of allowable values, otherwise |
lower_bound |
body |
integer |
The lowest allowed integer value. May be |
max_length |
body |
integer |
The maximum string length of the value. May be |
min_length |
body |
integer |
The minimum string length of the value. May be |
read_only |
body |
boolean |
This Bios setting is read only and can’t be changed. May be None. |
reset_required |
body |
boolean |
After setting this Bios setting a node reboot is required. May be None. |
unique |
body |
boolean |
This Bios setting is unique to this node. May be |
upper_bound |
body |
integer |
The highest allowed integer value. May be |
Example list of a Node’s Bios settings:
{
"bios": [
{
"created_at": "2016-08-18T22:28:49.653974+00:00",
"updated_at": "2016-08-18T22:28:49.653974+00:00",
"links": [
{
"href": "http://127.0.0.1:6385/v1/nodes/6d85703a-565d-469a-96ce-30b6de53079d/bios/virtualization",
"rel": "self"
},
{
"href": "http://127.0.0.1:6385/v1/nodes/6d85703a-565d-469a-96ce-30b6de53079d/bios/virtualization",
"rel": "bookmark"
}
],
"name": "Virtualization",
"value": "Enabled",
"attribute_type": "Enumeration",
"allowable_values": ["Enabled", "Disabled"],
"lower_bound": null,
"max_length": null,
"min_length": null,
"read_only": false,
"reset_required": null,
"unique": null,
"upper_bound": null
}
]
}
Return the content of the specific bios bios_setting associated with
node_ident.
Added in version 1.74: Introduced fields from the BIOS registry.
Normal response code: 200
Error codes: 404
Request¶
Name |
In |
Type |
Description |
|---|---|---|---|
node_ident |
path |
string |
The UUID or Name of the node. |
bios_setting |
path |
string |
The name of the Bios setting. |
Response¶
Name |
In |
Type |
Description |
|---|---|---|---|
<key> |
body |
dictionary |
Dictionary containing the definition of a Bios setting. It includes the following fields “created_at”, “updated_at”, “links”, “name”, “value”. |
created_at |
body |
string |
The UTC date and time when the resource was created, ISO 8601 format. |
updated_at |
body |
string |
The UTC date and time when the resource was updated, ISO 8601 format. May be “null”. |
links |
body |
array |
A list of relative links. Includes the self and bookmark links. |
name |
body |
string |
The name of a Bios setting for a Node, eg. “virtualization”. |
value |
body |
string |
The value of a Bios setting for a Node, eg. “on”. |
attribute_type |
body |
string |
A string describing the type of the Bios setting. May be |
allowable_values |
body |
array |
A list of allowable values, otherwise |
lower_bound |
body |
integer |
The lowest allowed integer value. May be |
max_length |
body |
integer |
The maximum string length of the value. May be |
min_length |
body |
integer |
The minimum string length of the value. May be |
read_only |
body |
boolean |
This Bios setting is read only and can’t be changed. May be None. |
reset_required |
body |
boolean |
After setting this Bios setting a node reboot is required. May be None. |
unique |
body |
boolean |
This Bios setting is unique to this node. May be |
upper_bound |
body |
integer |
The highest allowed integer value. May be |
Example details of a Node’s Bios setting details:
{
"virtualization": {
"created_at": "2016-08-18T22:28:49.653974+00:00",
"updated_at": "2016-08-18T22:28:49.653974+00:00",
"links": [
{
"href": "http://127.0.0.1:6385/v1/nodes/6d85703a-565d-469a-96ce-30b6de53079d/bios/virtualization",
"rel": "self"
},
{
"href": "http://127.0.0.1:6385/v1/nodes/6d85703a-565d-469a-96ce-30b6de53079d/bios/virtualization",
"rel": "bookmark"
}
],
"name": "Virtualization",
"value": "Enabled",
"attribute_type": "Enumeration",
"allowable_values": ["Enabled", "Disabled"],
"lower_bound": null,
"max_length": null,
"min_length": null,
"read_only": false,
"reset_required": null,
"unique": null,
"upper_bound": null
}
}
Node Firmware (nodes)¶
Added in version 1.86.
Given a Node identifier (uuid or name), the API exposes the list of
all Firmware Components associated with that Node.
These endpoints do not allow modification of the Firmware Components; that
should be done by using clean steps.
Return a list of Firmware Components associated with node_ident.
Normal response code: 200
Error codes: 404
Request¶
Name |
In |
Type |
Description |
|---|---|---|---|
node_ident |
path |
string |
The UUID or Name of the node. |
Response¶
Name |
In |
Type |
Description |
|---|---|---|---|
firmware |
body |
array |
List of Firmware Components of the node. It includes following fields “created_at”, “updated_at”, “component”, “initial_version”, “current_version”, “last_version_flashed” |
created_at |
body |
string |
The UTC date and time when the resource was created, ISO 8601 format. |
updated_at |
body |
string |
The UTC date and time when the resource was updated, ISO 8601 format. May be “null”. |
component |
body |
string |
The Firmware Component of a Node, eg. “bios”. |
initial_version |
body |
string |
The initial version of a Firmware Component. |
current_version |
body |
string |
The current version of a Firmware Component. |
last_version_flashed |
body |
string |
The last version flashed of a Firmware Component. |
Example list of a Node’s Firmware Components:
{
"firmware": [
{
"created_at": "2016-08-18T22:28:49.653974+00:00",
"updated_at": "2016-08-18T22:28:49.653974+00:00",
"component": "BMC",
"initial_version": "v1.0.0",
"current_version": "v1.2.0",
"last_version_flashed": "v1.2.0"
},
{
"created_at": "2016-08-18T22:28:49.653974+00:00",
"updated_at": "2016-08-18T22:28:49.653974+00:00",
"component": "BIOS",
"initial_version": "v1.0.0",
"current_version": "v1.1.5",
"last_version_flashed": "v1.1.5"
}
]
}
Conductors (conductors)¶
Added in version 1.49.
Listing Conductor resources is done through the conductors resource.
Conductor resources are read-only, they can not be created, updated, or removed.
Return a list of conductors known by the Bare Metal service.
By default, this query will return the hostname, conductor group, and alive
status for each Conductor. When detail is set to True in the query string,
will return the full representation of the resource.
Normal response code: 200
Request¶
Name |
In |
Type |
Description |
|---|---|---|---|
fields (Optional) |
query |
array |
One or more fields to be returned in the response. For example, the following request returns only the GET /v1/conductors?fields=hostname,alive
|
limit (Optional) |
query |
integer |
Requests a page size of items. Returns a number of items up to a limit
value. Use the |
marker (Optional) |
query |
string |
The ID of the last-seen item. Use the |
sort_dir (Optional) |
query |
string |
Sorts the response by the requested sort
direction. A valid value is |
sort_key (Optional) |
query |
string |
Sorts the response by this attribute value.
Default is |
detail (Optional) |
query |
boolean |
Whether to show detailed information about the resource. This cannot be
set to True if |
Response¶
Name |
In |
Type |
Description |
|---|---|---|---|
hostname |
body |
array |
The hostname of this conductor. |
conductor_group |
body |
string |
The conductor group for a node. Case-insensitive string up to 255
characters, containing |
alive |
body |
boolean |
The conductor status indicates whether a conductor is considered alive or not. |
drivers |
body |
array |
A list of driver objects. |
links |
body |
array |
A list of relative links. Includes the self and bookmark links. |
Example Conductor list response:
{
"conductors": [
{
"hostname": "compute1.localdomain",
"conductor_group": "",
"links": [
{
"href": "http://127.0.0.1:6385/v1/conductors/compute1.localdomain",
"rel": "self"
},
{
"href": "http://127.0.0.1:6385/conductors/compute1.localdomain",
"rel": "bookmark"
}
],
"alive": false
},
{
"hostname": "compute2.localdomain",
"conductor_group": "",
"links": [
{
"href": "http://127.0.0.1:6385/v1/conductors/compute2.localdomain",
"rel": "self"
},
{
"href": "http://127.0.0.1:6385/conductors/compute2.localdomain",
"rel": "bookmark"
}
],
"alive": true
}
]
}
Example detailed Conductor list response:
{
"conductors": [
{
"links": [
{
"href": "http://127.0.0.1:6385/v1/conductors/compute1.localdomain",
"rel": "self"
},
{
"href": "http://127.0.0.1:6385/conductors/compute1.localdomain",
"rel": "bookmark"
}
],
"created_at": "2018-08-07T08:39:21+00:00",
"hostname": "compute1.localdomain",
"conductor_group": "",
"updated_at": "2018-11-30T07:07:23+00:00",
"alive": false,
"drivers": [
"ipmi"
]
},
{
"links": [
{
"href": "http://127.0.0.1:6385/v1/conductors/compute2.localdomain",
"rel": "self"
},
{
"href": "http://127.0.0.1:6385/conductors/compute2.localdomain",
"rel": "bookmark"
}
],
"created_at": "2018-12-05T07:03:19+00:00",
"hostname": "compute2.localdomain",
"conductor_group": "",
"updated_at": "2018-12-05T07:03:21+00:00",
"alive": true,
"drivers": [
"ipmi"
]
}
]
}
Shows details for a conductor. By default, this will return the full
representation of the resource; an optional fields parameter can be
supplied to return only the specified set.
Normal response codes: 200
Error codes: 400,403,404,406
Request¶
Name |
In |
Type |
Description |
|---|---|---|---|
hostname |
path |
string |
The hostname of the conductor. |
fields (Optional) |
query |
array |
One or more fields to be returned in the response. For example, the following request returns only the GET /v1/conductors?fields=hostname,alive
|
Response¶
Name |
In |
Type |
Description |
|---|---|---|---|
hostname |
body |
array |
The hostname of this conductor. |
conductor_group |
body |
string |
The conductor group for a node. Case-insensitive string up to 255
characters, containing |
alive |
body |
boolean |
The conductor status indicates whether a conductor is considered alive or not. |
drivers |
body |
array |
A list of driver objects. |
links |
body |
array |
A list of relative links. Includes the self and bookmark links. |
Example JSON representation of a Conductor:
{
"links": [
{
"href": "http://127.0.0.1:6385/v1/conductors/compute2.localdomain",
"rel": "self"
},
{
"href": "http://127.0.0.1:6385/conductors/compute2.localdomain",
"rel": "bookmark"
}
],
"created_at": "2018-12-05T07:03:19+00:00",
"hostname": "compute2.localdomain",
"conductor_group": "",
"updated_at": "2018-12-05T07:03:21+00:00",
"alive": true,
"drivers": [
"ipmi"
]
}
Allocations (allocations)¶
The Allocation resource represents a request to find and allocate a Node for deployment.
Added in version 1.52: Allocation API was introduced.
Creates an allocation.
A Node can be requested by its resource class and traits. Additionally, Nodes
can be pre-filtered on the client side, and the resulting list of UUIDs and/or
names can be submitted as candidate_nodes. Otherwise all nodes are
considered.
A Node is suitable for an Allocation if all of the following holds:
provision_stateisavailablepower_stateis notnullmaintenanceisfalseinstance_uuidisnullresource_classmatches requested onetraitslist contains all of the requested ones
The allocation process is asynchronous. The new Allocation is returned in
the allocating state, and the process continues in the background. If it
succeeds, the node_uuid field is populated with the Node’s UUID, and the
Node’s instance_uuid field is set to the Allocation’s UUID.
If you want to backfill an allocation for an already deployed node, you can
pass the UUID or name of this node to node. In this case the allocation
is created immediately, bypassing the normal allocation process. Other
parameters must be missing or match the provided node.
Added in version 1.52: Allocation API was introduced.
Added in version 1.58: Added support for backfilling allocations.
Added in version 1.60: Introduced the owner field.
Added in version 1.79: A node with the same name as the allocation name is moved to the
start of the derived candidate list.
Normal response codes: 201
Error response codes: 400, 401, 403, 409, 503
Request¶
Name |
In |
Type |
Description |
|---|---|---|---|
resource_class |
body |
string |
The requested resource class for the allocation. Can only be missing when
backfilling an allocation (will be set to the node’s |
candidate_nodes (Optional) |
body |
array |
The list of nodes (names or UUIDs) that should be considered for this allocation. If not provided, all available nodes will be considered. |
name (Optional) |
body |
string |
The unique name of the Allocation. |
traits (Optional) |
body |
array |
The list of requested traits for the allocation. |
uuid (Optional) |
body |
string |
The UUID for the resource. |
extra (Optional) |
body |
object |
A set of one or more arbitrary metadata key and value pairs. |
node (Optional) |
body |
string |
The node UUID or name to create the allocation against, bypassing the normal allocation process. Warning This field must not be used to request a normal allocation
with one candidate node, use |
owner (Optional) |
body |
string |
A string or UUID of the tenant who owns the object. |
Request Example¶
{
"name": "allocation-1",
"resource_class": "bm-large"
}
Response Parameters¶
Name |
In |
Type |
Description |
|---|---|---|---|
uuid |
body |
string |
The UUID for the resource. |
candidate_nodes |
body |
array |
A list of UUIDs of the nodes that are candidates for this allocation. |
last_error |
body |
string |
The error message for the allocation if it is in the |
name |
body |
string |
The unique name of the allocation. |
node_uuid |
body |
string |
The UUID of the node assigned to the allocation. Will be |
resource_class |
body |
string |
The resource class requested for the allocation. Can be |
state |
body |
string |
The current state of the allocation. One of:
|
traits |
body |
array |
The list of the traits requested for the allocation. |
owner (Optional) |
body |
string |
A string or UUID of the tenant who owns the object. |
extra |
body |
object |
A set of one or more arbitrary metadata key and value pairs. |
created_at |
body |
string |
The UTC date and time when the resource was created, ISO 8601 format. |
updated_at |
body |
string |
The UTC date and time when the resource was updated, ISO 8601 format. May be “null”. |
links |
body |
array |
A list of relative links. Includes the self and bookmark links. |
Response Example¶
{
"candidate_nodes": [],
"created_at": "2019-02-20T09:43:58+00:00",
"extra": {},
"last_error": null,
"links": [
{
"href": "http://127.0.0.1:6385/v1/allocations/5344a3e2-978a-444e-990a-cbf47c62ef88",
"rel": "self"
},
{
"href": "http://127.0.0.1:6385/allocations/5344a3e2-978a-444e-990a-cbf47c62ef88",
"rel": "bookmark"
}
],
"name": "allocation-1",
"node_uuid": null,
"owner": null,
"resource_class": "bm-large",
"state": "allocating",
"traits": [],
"updated_at": null,
"uuid": "5344a3e2-978a-444e-990a-cbf47c62ef88"
}
Lists all Allocations.
Added in version 1.52: Allocation API was introduced.
Added in version 1.60: Introduced the owner field.
Normal response codes: 200
Error response codes: 400, 401, 403, 404
Request¶
Name |
In |
Type |
Description |
|---|---|---|---|
node (Optional) |
query |
string |
Filter the list of allocations by the node UUID or name. |
resource_class (Optional) |
query |
string |
Filter the list of returned nodes, and only return the ones with the specified resource class. |
state (Optional) |
query |
string |
Filter the list of allocations by the allocation state, one of |
owner (Optional) |
body |
string |
A string or UUID of the tenant who owns the object. |
fields (Optional) |
query |
array |
One or more fields to be returned in the response. For example, the following request returns only the 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 |
marker (Optional) |
query |
string |
The ID of the last-seen item. Use the |
sort_dir (Optional) |
query |
string |
Sorts the response by the requested sort
direction. A valid value is |
sort_key (Optional) |
query |
string |
Sorts the response by this attribute value.
Default is |
Response Parameters¶
Name |
In |
Type |
Description |
|---|---|---|---|
uuid |
body |
string |
The UUID for the resource. |
candidate_nodes |
body |
array |
A list of UUIDs of the nodes that are candidates for this allocation. |
last_error |
body |
string |
The error message for the allocation if it is in the |
name |
body |
string |
The unique name of the allocation. |
node_uuid |
body |
string |
The UUID of the node assigned to the allocation. Will be |
resource_class |
body |
string |
The resource class requested for the allocation. Can be |
state |
body |
string |
The current state of the allocation. One of:
|
traits |
body |
array |
The list of the traits requested for the allocation. |
owner (Optional) |
body |
string |
A string or UUID of the tenant who owns the object. |
extra |
body |
object |
A set of one or more arbitrary metadata key and value pairs. |
created_at |
body |
string |
The UTC date and time when the resource was created, ISO 8601 format. |
updated_at |
body |
string |
The UTC date and time when the resource was updated, ISO 8601 format. May be “null”. |
links |
body |
array |
A list of relative links. Includes the self and bookmark links. |
Response Example¶
{
"allocations": [
{
"candidate_nodes": [],
"created_at": "2019-02-20T09:43:58+00:00",
"extra": {},
"last_error": null,
"links": [
{
"href": "http://127.0.0.1:6385/v1/allocations/5344a3e2-978a-444e-990a-cbf47c62ef88",
"rel": "self"
},
{
"href": "http://127.0.0.1:6385/allocations/5344a3e2-978a-444e-990a-cbf47c62ef88",
"rel": "bookmark"
}
],
"name": "allocation-1",
"node_uuid": "6d85703a-565d-469a-96ce-30b6de53079d",
"owner": null,
"resource_class": "bm-large",
"state": "active",
"traits": [],
"updated_at": "2019-02-20T09:43:58+00:00",
"uuid": "5344a3e2-978a-444e-990a-cbf47c62ef88"
},
{
"candidate_nodes": [],
"created_at": "2019-02-20T09:43:58+00:00",
"extra": {},
"last_error": "Failed to process allocation eff80f47-75f0-4d41-b1aa-cf07c201adac: no available nodes match the resource class bm-large.",
"links": [
{
"href": "http://127.0.0.1:6385/v1/allocations/eff80f47-75f0-4d41-b1aa-cf07c201adac",
"rel": "self"
},
{
"href": "http://127.0.0.1:6385/allocations/eff80f47-75f0-4d41-b1aa-cf07c201adac",
"rel": "bookmark"
}
],
"name": "allocation-2",
"node_uuid": null,
"owner": null,
"resource_class": "bm-large",
"state": "error",
"traits": [
"CUSTOM_GOLD"
],
"updated_at": "2019-02-20T09:43:58+00:00",
"uuid": "eff80f47-75f0-4d41-b1aa-cf07c201adac"
}
]
}
Shows details for an Allocation.
Added in version 1.52: Allocation API was introduced.
Added in version 1.60: Introduced the owner field.
Normal response codes: 200
Error response codes: 400, 401, 403, 404
Request¶
Name |
In |
Type |
Description |
|---|---|---|---|
fields (Optional) |
query |
array |
One or more fields to be returned in the response. For example, the following request returns only the GET /v1/nodes?fields=uuid,name
|
allocation_id |
path |
string |
The UUID or name of the allocation. |
Response Parameters¶
Name |
In |
Type |
Description |
|---|---|---|---|
uuid |
body |
string |
The UUID for the resource. |
candidate_nodes |
body |
array |
A list of UUIDs of the nodes that are candidates for this allocation. |
last_error |
body |
string |
The error message for the allocation if it is in the |
name |
body |
string |
The unique name of the allocation. |
node_uuid |
body |
string |
The UUID of the node assigned to the allocation. Will be |
resource_class |
body |
string |
The resource class requested for the allocation. Can be |
state |
body |
string |
The current state of the allocation. One of:
|
traits |
body |
array |
The list of the traits requested for the allocation. |
owner (Optional) |
body |
string |
A string or UUID of the tenant who owns the object. |
extra |
body |
object |
A set of one or more arbitrary metadata key and value pairs. |
created_at |
body |
string |
The UTC date and time when the resource was created, ISO 8601 format. |
updated_at |
body |
string |
The UTC date and time when the resource was updated, ISO 8601 format. May be “null”. |
links |
body |
array |
A list of relative links. Includes the self and bookmark links. |
Response Example¶
{
"candidate_nodes": [],
"created_at": "2019-02-20T09:43:58+00:00",
"extra": {},
"last_error": null,
"links": [
{
"href": "http://127.0.0.1:6385/v1/allocations/5344a3e2-978a-444e-990a-cbf47c62ef88",
"rel": "self"
},
{
"href": "http://127.0.0.1:6385/allocations/5344a3e2-978a-444e-990a-cbf47c62ef88",
"rel": "bookmark"
}
],
"name": "allocation-1",
"node_uuid": "6d85703a-565d-469a-96ce-30b6de53079d",
"owner": null,
"resource_class": "bm-large",
"state": "active",
"traits": [],
"updated_at": "2019-02-20T09:43:58+00:00",
"uuid": "5344a3e2-978a-444e-990a-cbf47c62ef88"
}
Updates an allocation. Allows updating only name and extra fields.
Added in version 1.57: Allocation update API was introduced.
Normal response codes: 200
Error response codes: 400, 401, 403, 404, 409, 503
Request¶
The BODY of the PATCH request must be a JSON PATCH document, adhering to RFC 6902.
Name |
In |
Type |
Description |
|---|---|---|---|
allocation_id |
path |
string |
The UUID or name of the allocation. |
name (Optional) |
body |
string |
The unique name of the Allocation. |
extra (Optional) |
body |
object |
A set of one or more arbitrary metadata key and value pairs. |
Request Example¶
[
{
"op": "add",
"path": "/extra/foo",
"value": "bar"
}
]
Response Parameters¶
Name |
In |
Type |
Description |
|---|---|---|---|
uuid |
body |
string |
The UUID for the resource. |
candidate_nodes |
body |
array |
A list of UUIDs of the nodes that are candidates for this allocation. |
last_error |
body |
string |
The error message for the allocation if it is in the |
name |
body |
string |
The unique name of the allocation. |
node_uuid |
body |
string |
The UUID of the node assigned to the allocation. Will be |
resource_class |
body |
string |
The resource class requested for the allocation. Can be |
state |
body |
string |
The current state of the allocation. One of:
|
traits |
body |
array |
The list of the traits requested for the allocation. |
owner (Optional) |
body |
string |
A string or UUID of the tenant who owns the object. |
extra |
body |
object |
A set of one or more arbitrary metadata key and value pairs. |
created_at |
body |
string |
The UTC date and time when the resource was created, ISO 8601 format. |
updated_at |
body |
string |
The UTC date and time when the resource was updated, ISO 8601 format. May be “null”. |
links |
body |
array |
A list of relative links. Includes the self and bookmark links. |
Response Example¶
{
"node_uuid": null,
"uuid": "241db410-7b04-4b1c-87ae-4e336435db08",
"links": [
{
"href": "http://10.66.169.122/v1/allocations/241db410-7b04-4b1c-87ae-4e336435db08",
"rel": "self"
},
{
"href": "http://10.66.169.122/allocations/241db410-7b04-4b1c-87ae-4e336435db08",
"rel": "bookmark"
}
],
"extra":
{
"foo": "bar"
},
"last_error": null,
"created_at": "2019-06-04T07:46:25+00:00",
"owner": null,
"resource_class": "CUSTOM_GOLD",
"updated_at": "2019-06-06T03:28:19.496960+00:00",
"traits": [],
"state": "error",
"candidate_nodes": [],
"name": "test_allocation"
}
Deletes an Allocation.
If the Allocation has a Node associated, the Node’s instance_uuid is reset.
The deletion will fail if the Allocation has a Node assigned and the Node is
active and not in the maintenance mode.
Added in version 1.52: Allocation API was introduced.
Normal response codes: 204
Error response codes: 400, 401, 403, 404, 409, 503
Request¶
Name |
In |
Type |
Description |
|---|---|---|---|
allocation_id |
path |
string |
The UUID or name of the allocation. |
Node Allocation (allocations, nodes)¶
Given a Node identifier (uuid or name), the API allows to get and
delete the associated allocation.
Added in version 1.52: Allocation API was introduced.
Shows details for an allocation.
Added in version 1.52: Allocation API was introduced.
Normal response codes: 200
Error response codes: 400, 401, 403, 404
Request¶
Name |
In |
Type |
Description |
|---|---|---|---|
node_ident |
path |
string |
The UUID or Name of the node. |
fields (Optional) |
query |
array |
One or more fields to be returned in the response. For example, the following request returns only the GET /v1/nodes?fields=uuid,name
|
Response Parameters¶
Name |
In |
Type |
Description |
|---|---|---|---|
uuid |
body |
string |
The UUID for the resource. |
candidate_nodes |
body |
array |
A list of UUIDs of the nodes that are candidates for this allocation. |
last_error |
body |
string |
The error message for the allocation if it is in the |
name |
body |
string |
The unique name of the allocation. |
node_uuid |
body |
string |
The UUID of the node assigned to the allocation. Will be |
resource_class |
body |
string |
The resource class requested for the allocation. Can be |
state |
body |
string |
The current state of the allocation. One of:
|
traits |
body |
array |
The list of the traits requested for the allocation. |
extra |
body |
object |
A set of one or more arbitrary metadata key and value pairs. |
created_at |
body |
string |
The UTC date and time when the resource was created, ISO 8601 format. |
updated_at |
body |
string |
The UTC date and time when the resource was updated, ISO 8601 format. May be “null”. |
links |
body |
array |
A list of relative links. Includes the self and bookmark links. |
Response Example¶
{
"candidate_nodes": [],
"created_at": "2019-02-20T09:43:58+00:00",
"extra": {},
"last_error": null,
"links": [
{
"href": "http://127.0.0.1:6385/v1/allocations/5344a3e2-978a-444e-990a-cbf47c62ef88",
"rel": "self"
},
{
"href": "http://127.0.0.1:6385/allocations/5344a3e2-978a-444e-990a-cbf47c62ef88",
"rel": "bookmark"
}
],
"name": "allocation-1",
"node_uuid": "6d85703a-565d-469a-96ce-30b6de53079d",
"owner": null,
"resource_class": "bm-large",
"state": "active",
"traits": [],
"updated_at": "2019-02-20T09:43:58+00:00",
"uuid": "5344a3e2-978a-444e-990a-cbf47c62ef88"
}
Deletes the allocation of this node and resets its instance_uuid.
The deletion will fail if the allocation the node is active and not in
the maintenance mode.
Added in version 1.52: Allocation API was introduced.
Normal response codes: 204
Error response codes: 400, 401, 403, 404, 409, 503
Request¶
Name |
In |
Type |
Description |
|---|---|---|---|
node_ident |
path |
string |
The UUID or Name of the node. |
Deploy Templates (deploy_templates)¶
The Deploy Template resource represents a collection of Deploy Steps that may
be executed during deployment of a node. A deploy template is matched for a
node if at the time of deployment, the template’s name matches a trait in the
node’s instance_info.traits.
Added in version 1.55: Deploy Template API was introduced.
Creates a deploy template.
Added in version 1.55: Deploy Template API was introduced.
Normal response codes: 201
Error response codes: 400, 401, 403, 409
Request¶
Name |
In |
Type |
Description |
|---|---|---|---|
name |
body |
string |
The unique name of the deploy template. |
steps |
body |
array |
The deploy steps of the deploy template. Must be a list of dictionaries containing at least one deploy step. See Request Step for step parameters. |
uuid (Optional) |
body |
string |
The UUID for the resource. |
extra (Optional) |
body |
object |
A set of one or more arbitrary metadata key and value pairs. |
Request Step¶
Name |
In |
Type |
Description |
|---|---|---|---|
interface |
body |
string |
The name of the driver interface. |
step |
body |
string |
The name of the deploy step method on the driver interface. |
args |
body |
object |
A dictionary of arguments that are passed to the deploy step method. |
priority |
body |
integer |
A non-negative integer priority for the step. A value of |
Request Example¶
{
"extra": {},
"name": "CUSTOM_HYPERTHREADING_ON",
"steps": [
{
"interface": "bios",
"step": "apply_configuration",
"args": {
"settings": [
{
"name": "LogicalProc",
"value": "Enabled"
}
]
},
"priority": 150
}
]
}
Response Parameters¶
Name |
In |
Type |
Description |
|---|---|---|---|
uuid |
body |
string |
The UUID for the resource. |
name |
body |
string |
The unique name of the deploy template. |
steps |
body |
array |
The deploy steps of the deploy template. Must be a list of dictionaries containing at least one deploy step. See Request Step for step parameters. |
extra |
body |
object |
A set of one or more arbitrary metadata key and value pairs. |
created_at |
body |
string |
The UTC date and time when the resource was created, ISO 8601 format. |
updated_at |
body |
string |
The UTC date and time when the resource was updated, ISO 8601 format. May be “null”. |
links |
body |
array |
A list of relative links. Includes the self and bookmark links. |
Response Example¶
{
"created_at": "2016-08-18T22:28:48.643434+11:11",
"extra": {},
"links": [
{
"href": "http://10.60.253.180:6385/v1/deploy_templates/bbb45f41-d4bc-4307-8d1d-32f95ce1e920",
"rel": "self"
},
{
"href": "http://10.60.253.180:6385/deploy_templates/bbb45f41-d4bc-4307-8d1d-32f95ce1e920",
"rel": "bookmark"
}
],
"name": "CUSTOM_HYPERTHREADING_ON",
"steps": [
{
"args": {
"settings": [
{
"name": "LogicalProc",
"value": "Enabled"
}
]
},
"interface": "bios",
"priority": 150,
"step": "apply_configuration"
}
],
"updated_at": null,
"uuid": "bbb45f41-d4bc-4307-8d1d-32f95ce1e920"
}
Lists all deploy templates.
Added in version 1.55: Deploy Template API was introduced.
Normal response codes: 200
Error response codes: 400, 401, 403, 404
Request¶
Name |
In |
Type |
Description |
|---|---|---|---|
fields (Optional) |
query |
array |
One or more fields to be returned in the response. For example, the following request returns only the 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 |
marker (Optional) |
query |
string |
The ID of the last-seen item. Use the |
sort_dir (Optional) |
query |
string |
Sorts the response by the requested sort
direction. A valid value is |
sort_key (Optional) |
query |
string |
Sorts the response by this attribute value.
Default is |
detail (Optional) |
query |
boolean |
Whether to show detailed information about the resource. This cannot be
set to True if |
Response Parameters¶
Name |
In |
Type |
Description |
|---|---|---|---|
uuid |
body |
string |
The UUID for the resource. |
name |
body |
string |
The unique name of the deploy template. |
steps |
body |
array |
The deploy steps of the deploy template. Must be a list of dictionaries containing at least one deploy step. See Request Step for step parameters. |
extra |
body |
object |
A set of one or more arbitrary metadata key and value pairs. |
created_at |
body |
string |
The UTC date and time when the resource was created, ISO 8601 format. |
updated_at |
body |
string |
The UTC date and time when the resource was updated, ISO 8601 format. May be “null”. |
links |
body |
array |
A list of relative links. Includes the self and bookmark links. |
Response Example¶
Example deploy template list response:
{
"deploy_templates": [
{
"links": [
{
"href": "http://10.60.253.180:6385/v1/deploy_templates/bbb45f41-d4bc-4307-8d1d-32f95ce1e920",
"rel": "self"
},
{
"href": "http://10.60.253.180:6385/deploy_templates/bbb45f41-d4bc-4307-8d1d-32f95ce1e920",
"rel": "bookmark"
}
],
"name": "CUSTOM_HYPERTHREADING_ON",
"uuid": "bbb45f41-d4bc-4307-8d1d-32f95ce1e920"
}
]
}
Example detailed deploy template list response:
{
"deploy_templates": [
{
"created_at": "2016-08-18T22:28:48.643434+11:11",
"extra": {},
"links": [
{
"href": "http://10.60.253.180:6385/v1/deploy_templates/bbb45f41-d4bc-4307-8d1d-32f95ce1e920",
"rel": "self"
},
{
"href": "http://10.60.253.180:6385/deploy_templates/bbb45f41-d4bc-4307-8d1d-32f95ce1e920",
"rel": "bookmark"
}
],
"name": "CUSTOM_HYPERTHREADING_ON",
"steps": [
{
"args": {
"settings": [
{
"name": "LogicalProc",
"value": "Enabled"
}
]
},
"interface": "bios",
"priority": 150,
"step": "apply_configuration"
}
],
"updated_at": null,
"uuid": "bbb45f41-d4bc-4307-8d1d-32f95ce1e920"
}
]
}
Shows details for a deploy template.
Added in version 1.55: Deploy Template API was introduced.
Normal response codes: 200
Error response codes: 400, 401, 403, 404
Request¶
Name |
In |
Type |
Description |
|---|---|---|---|
fields (Optional) |
query |
array |
One or more fields to be returned in the response. For example, the following request returns only the GET /v1/nodes?fields=uuid,name
|
deploy_template_id |
path |
string |
The UUID or name of the deploy template. |
Response Parameters¶
Name |
In |
Type |
Description |
|---|---|---|---|
uuid |
body |
string |
The UUID for the resource. |
name |
body |
string |
The unique name of the deploy template. |
steps |
body |
array |
The deploy steps of the deploy template. Must be a list of dictionaries containing at least one deploy step. See Request Step for step parameters. |
extra |
body |
object |
A set of one or more arbitrary metadata key and value pairs. |
created_at |
body |
string |
The UTC date and time when the resource was created, ISO 8601 format. |
updated_at |
body |
string |
The UTC date and time when the resource was updated, ISO 8601 format. May be “null”. |
links |
body |
array |
A list of relative links. Includes the self and bookmark links. |
Response Example¶
{
"created_at": "2016-08-18T22:28:48.643434+11:11",
"extra": {},
"links": [
{
"href": "http://10.60.253.180:6385/v1/deploy_templates/bbb45f41-d4bc-4307-8d1d-32f95ce1e920",
"rel": "self"
},
{
"href": "http://10.60.253.180:6385/deploy_templates/bbb45f41-d4bc-4307-8d1d-32f95ce1e920",
"rel": "bookmark"
}
],
"name": "CUSTOM_HYPERTHREADING_ON",
"steps": [
{
"args": {
"settings": [
{
"name": "LogicalProc",
"value": "Enabled"
}
]
},
"interface": "bios",
"priority": 150,
"step": "apply_configuration"
}
],
"updated_at": null,
"uuid": "bbb45f41-d4bc-4307-8d1d-32f95ce1e920"
}
Update a deploy template.
Added in version 1.55: Deploy Template API was introduced.
Normal response code: 200
Error response codes: 400, 401, 403, 404, 409
Request¶
The BODY of the PATCH request must be a JSON PATCH document, adhering to RFC 6902.
Request¶
Name |
In |
Type |
Description |
|---|---|---|---|
deploy_template_id |
path |
string |
The UUID or name of the deploy template. |
[
{
"path" : "/name",
"value" : "CUSTOM_HT_ON",
"op" : "replace"
}
]
Response¶
Name |
In |
Type |
Description |
|---|---|---|---|
uuid |
body |
string |
The UUID for the resource. |
name |
body |
string |
The unique name of the deploy template. |
steps |
body |
array |
The deploy steps of the deploy template. Must be a list of dictionaries containing at least one deploy step. See Request Step for step parameters. |
extra |
body |
object |
A set of one or more arbitrary metadata key and value pairs. |
created_at |
body |
string |
The UTC date and time when the resource was created, ISO 8601 format. |
updated_at |
body |
string |
The UTC date and time when the resource was updated, ISO 8601 format. May be “null”. |
links |
body |
array |
A list of relative links. Includes the self and bookmark links. |
{
"created_at": "2016-08-18T22:28:48.643434+11:11",
"extra": {},
"links": [
{
"href": "http://10.60.253.180:6385/v1/deploy_templates/bbb45f41-d4bc-4307-8d1d-32f95ce1e920",
"rel": "self"
},
{
"href": "http://10.60.253.180:6385/deploy_templates/bbb45f41-d4bc-4307-8d1d-32f95ce1e920",
"rel": "bookmark"
}
],
"name": "CUSTOM_HT_ON",
"steps": [
{
"args": {
"settings": [
{
"name": "LogicalProc",
"value": "Enabled"
}
]
},
"interface": "bios",
"priority": 150,
"step": "apply_configuration"
}
],
"updated_at": "2016-08-18T22:28:49.653974+00:00",
"uuid": "bbb45f41-d4bc-4307-8d1d-32f95ce1e920"
}
Deletes a deploy template.
Added in version 1.55: Deploy Template API was introduced.
Normal response codes: 204
Error response codes: 400, 401, 403, 404
Request¶
Name |
In |
Type |
Description |
|---|---|---|---|
deploy_template_id |
path |
string |
The UUID or name of the deploy template. |
Runbooks (runbooks)¶
The Runbook resource represents a collection of steps that define a series of actions to be executed on a node. Runbooks enable users to perform complex operations in a predefined, automated manner. A runbook is matched for a node if the runbook’s name matches a trait in the node.
Added in version 1.92: Runbook API was introduced.
Creates a runbook.
Added in version 1.92: Runbook API was introduced.
Normal response codes: 201
Error response codes: 400, 401, 403, 409
Request¶
Name |
In |
Type |
Description |
|---|---|---|---|
name |
body |
string |
The unique name of the runbook. It must be prefixed with |
steps |
body |
array |
The runbook steps of the runbook template. Must be a list of dictionaries containing at least one runbook step. See Request Runbook Step for step parameters. |
disable_ramdisk (Optional) |
body |
boolean |
Whether to boot ramdisk while using a runbook for cleaning or servicing operation. |
uuid (Optional) |
body |
string |
The UUID for the resource. |
extra (Optional) |
body |
object |
A set of one or more arbitrary metadata key and value pairs. |
Request Runbook Step¶
Name |
In |
Type |
Description |
|---|---|---|---|
interface |
body |
string |
The name of the driver interface. |
step |
body |
string |
The name of the runbook step method on the driver interface. |
args |
body |
object |
A dictionary of arguments that are passed to the runbook step method. |
order |
body |
integer |
A non-negative integer order for the step. |
Request Example¶
{
"extra": {},
"name": "CUSTOM_AWESOME",
"steps": [
{
"interface": "bios",
"step": "apply_configuration",
"args": {
"settings": [
{
"name": "LogicalProc",
"value": "Enabled"
}
]
},
"order": 1
}
]
}
Response Parameters¶
Name |
In |
Type |
Description |
|---|---|---|---|
uuid |
body |
string |
The UUID for the resource. |
name |
body |
string |
The unique name of the runbook. It must be prefixed with |
steps |
body |
array |
The runbook steps of the runbook template. Must be a list of dictionaries containing at least one runbook step. See Request Runbook Step for step parameters. |
disable_ramdisk (Optional) |
body |
boolean |
If set to |
extra |
body |
object |
A set of one or more arbitrary metadata key and value pairs. |
public (Optional) |
body |
boolean |
Indicates whether a runbook is available for public use or not.
This must be |
owner (Optional) |
body |
string |
The unique identifier of the runbook owner.
This must be |
created_at |
body |
string |
The UTC date and time when the resource was created, ISO 8601 format. |
updated_at |
body |
string |
The UTC date and time when the resource was updated, ISO 8601 format. May be “null”. |
links |
body |
array |
A list of relative links. Includes the self and bookmark links. |
Response Example¶
{
"created_at": "2024-08-18T22:28:48.643434+11:11",
"extra": {},
"links": [
{
"href": "http://10.60.253.180:6385/v1/runbooks/fc6b1709-8dd5-86b0-2d34-5203d1c29127",
"rel": "self"
},
{
"href": "http://10.60.253.180:6385/runbooks/fc6b1709-8dd5-86b0-2d34-5203d1c29127",
"rel": "bookmark"
}
],
"name": "CUSTOM_AWESOME",
"public": false,
"owner": null,
"steps": [
{
"args": {
"settings": [
{
"name": "LogicalProc",
"value": "Enabled"
}
]
},
"interface": "bios",
"order": 1,
"step": "apply_configuration"
}
],
"updated_at": null,
"uuid": "fc6b1709-8dd5-86b0-2d34-5203d1c29127"
}
Lists all runbooks.
Added in version 1.92: Runbook API was introduced.
Normal response codes: 200
Error response codes: 400, 401, 403, 404
Request¶
Name |
In |
Type |
Description |
|---|---|---|---|
fields (Optional) |
query |
array |
One or more fields to be returned in the response. For example, the following request returns only the 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 |
marker (Optional) |
query |
string |
The ID of the last-seen item. Use the |
sort_dir (Optional) |
query |
string |
Sorts the response by the requested sort
direction. A valid value is |
sort_key (Optional) |
query |
string |
Sorts the response by this attribute value.
Default is |
detail (Optional) |
query |
boolean |
Whether to show detailed information about the resource. This cannot be
set to True if |
Response Parameters¶
Name |
In |
Type |
Description |
|---|---|---|---|
uuid |
body |
string |
The UUID for the resource. |
name |
body |
string |
The unique name of the runbook. It must be prefixed with |
disable_ramdisk (Optional) |
body |
boolean |
If set to |
steps |
body |
array |
The runbook steps of the runbook template. Must be a list of dictionaries containing at least one runbook step. See Request Runbook Step for step parameters. |
extra |
body |
object |
A set of one or more arbitrary metadata key and value pairs. |
public (Optional) |
body |
boolean |
Indicates whether a runbook is available for public use or not.
This must be |
owner (Optional) |
body |
string |
The unique identifier of the runbook owner.
This must be |
created_at |
body |
string |
The UTC date and time when the resource was created, ISO 8601 format. |
updated_at |
body |
string |
The UTC date and time when the resource was updated, ISO 8601 format. May be “null”. |
links |
body |
array |
A list of relative links. Includes the self and bookmark links. |
Response Example¶
Example runbook list response:
{
"runbooks": [
{
"links": [
{
"href": "http://10.60.253.180:6385/v1/runbooks/fc6b1709-8dd5-86b0-2d34-5203d1c29127",
"rel": "self"
},
{
"href": "http://10.60.253.180:6385/runbooks/fc6b1709-8dd5-86b0-2d34-5203d1c29127",
"rel": "bookmark"
}
],
"name": "CUSTOM_AWESOME",
"uuid": "fc6b1709-8dd5-86b0-2d34-5203d1c29127"
}
]
}
Example detailed runbook list response:
{
"runbooks": [
{
"created_at": "2024-08-18T22:28:48.643434+11:11",
"disable_ramdisk": false,
"extra": {},
"links": [
{
"href": "http://10.60.253.180:6385/v1/runbooks/fc6b1709-8dd5-86b0-2d34-5203d1c29127",
"rel": "self"
},
{
"href": "http://10.60.253.180:6385/runbooks/fc6b1709-8dd5-86b0-2d34-5203d1c29127",
"rel": "bookmark"
}
],
"name": "CUSTOM_AWESOME",
"public": false,
"owner": null,
"steps": [
{
"args": {
"settings": [
{
"name": "LogicalProc",
"value": "Enabled"
}
]
},
"interface": "bios",
"order": 1,
"step": "apply_configuration"
}
],
"updated_at": null,
"uuid": "fc6b1709-8dd5-86b0-2d34-5203d1c29127"
}
]
}
Shows details for a runbook.
Added in version 1.92: Runbook API was introduced.
Normal response codes: 200
Error response codes: 400, 401, 403, 404
Request¶
Name |
In |
Type |
Description |
|---|---|---|---|
fields (Optional) |
query |
array |
One or more fields to be returned in the response. For example, the following request returns only the GET /v1/nodes?fields=uuid,name
|
runbook_id |
path |
string |
The UUID or name of the runbook. |
Response Parameters¶
Name |
In |
Type |
Description |
|---|---|---|---|
uuid |
body |
string |
The UUID for the resource. |
name |
body |
string |
The unique name of the runbook. It must be prefixed with |
steps |
body |
array |
The runbook steps of the runbook template. Must be a list of dictionaries containing at least one runbook step. See Request Runbook Step for step parameters. |
disable_ramdisk (Optional) |
body |
boolean |
If set to |
extra |
body |
object |
A set of one or more arbitrary metadata key and value pairs. |
public (Optional) |
body |
boolean |
Indicates whether a runbook is available for public use or not.
This must be |
owner (Optional) |
body |
string |
The unique identifier of the runbook owner.
This must be |
created_at |
body |
string |
The UTC date and time when the resource was created, ISO 8601 format. |
updated_at |
body |
string |
The UTC date and time when the resource was updated, ISO 8601 format. May be “null”. |
links |
body |
array |
A list of relative links. Includes the self and bookmark links. |
Response Example¶
{
"created_at": "2024-08-18T22:28:48.643434+11:11",
"disable_ramdisk": false,
"extra": {},
"links": [
{
"href": "http://10.60.253.180:6385/v1/runbooks/fc6b1709-8dd5-86b0-2d34-5203d1c29127",
"rel": "self"
},
{
"href": "http://10.60.253.180:6385/runbooks/fc6b1709-8dd5-86b0-2d34-5203d1c29127",
"rel": "bookmark"
}
],
"name": "CUSTOM_AWESOME",
"public": false,
"owner": null,
"steps": [
{
"args": {
"settings": [
{
"name": "LogicalProc",
"value": "Enabled"
}
]
},
"interface": "bios",
"order": 1,
"step": "apply_configuration"
}
],
"updated_at": null,
"uuid": "fc6b1709-8dd5-86b0-2d34-5203d1c29127"
}
Update a runbook.
Added in version 1.92: Runbook API was introduced.
Normal response code: 200
Error response codes: 400, 401, 403, 404, 409
Request¶
The BODY of the PATCH request must be a JSON PATCH document, adhering to RFC 6902.
Request¶
Name |
In |
Type |
Description |
|---|---|---|---|
runbook_id |
path |
string |
The UUID or name of the runbook. |
[
{
"path" : "/name",
"value" : "CUSTOM_AWESOME2",
"op" : "replace"
}
]
Response¶
Name |
In |
Type |
Description |
|---|---|---|---|
uuid |
body |
string |
The UUID for the resource. |
name |
body |
string |
The unique name of the runbook. It must be prefixed with |
steps |
body |
array |
The runbook steps of the runbook template. Must be a list of dictionaries containing at least one runbook step. See Request Runbook Step for step parameters. |
disable_ramdisk (Optional) |
body |
boolean |
If set to |
extra |
body |
object |
A set of one or more arbitrary metadata key and value pairs. |
public (Optional) |
body |
boolean |
Indicates whether a runbook is available for public use or not.
This must be |
owner (Optional) |
body |
string |
The unique identifier of the runbook owner.
This must be |
created_at |
body |
string |
The UTC date and time when the resource was created, ISO 8601 format. |
updated_at |
body |
string |
The UTC date and time when the resource was updated, ISO 8601 format. May be “null”. |
links |
body |
array |
A list of relative links. Includes the self and bookmark links. |
{
"created_at": "2024-08-18T22:28:48.643434+11:11",
"extra": {},
"links": [
{
"href": "http://10.60.253.180:6385/v1/runbooks/fc6b1709-8dd5-86b0-2d34-5203d1c29127",
"rel": "self"
},
{
"href": "http://10.60.253.180:6385/runbooks/fc6b1709-8dd5-86b0-2d34-5203d1c29127",
"rel": "bookmark"
}
],
"name": "CUSTOM_AWESOME2",
"public": false,
"owner": null,
"steps": [
{
"args": {
"settings": [
{
"name": "LogicalProc",
"value": "Enabled"
}
]
},
"interface": "bios",
"order": 1,
"step": "apply_configuration"
}
],
"updated_at": "2024-08-18T22:28:49.653974+00:00",
"uuid": "fc6b1709-8dd5-86b0-2d34-5203d1c29127"
}
Deletes a runbook.
Added in version 1.92: Runbook API was introduced.
Normal response codes: 204
Error response codes: 400, 401, 403, 404
Request¶
Name |
In |
Type |
Description |
|---|---|---|---|
runbook_id |
path |
string |
The UUID or name of the runbook. |
History of nodes¶
Added in version 1.78.
Identifying history of events from nodes is available via API version 1.78 via
the v1/nodes/{node_ident}/history endpoint. In default policy
configuration, only “System” scoped users as well as owners who are listed
owners of associated nodes can list and retrieve nodes.
Normal response code: 200
Error codes: 400,401,403,404
Request¶
Name |
In |
Type |
Description |
|---|---|---|---|
node_ident |
path |
string |
The UUID or Name of the node. |
detail (Optional) |
query |
boolean |
Whether to show detailed information about the resource. This cannot be
set to True if |
marker (Optional) |
query |
string |
The ID of the last-seen item. Use the |
limit (Optional) |
query |
integer |
Requests a page size of items. Returns a number of items up to a limit
value. Use the |
Response¶
Name |
In |
Type |
Description |
|---|---|---|---|
history |
body |
array |
History events attached to this node. |
Example list of history events from a node:
{
"history": [
{
"uuid": "e5840e39-b4ba-4a93-8071-cff9aa2c9633",
"created_at": "2021-09-15T17:45:04.686541+00:00",
"severity": "ERROR",
"event": "Something is wrong",
"links": [
{
"href": "http://localhost/v1/nodes/1be26c0b-03f2-4d2e-ae87-c02d7f33c123/history/e5840e39-b4ba-4a93-8071-cff9aa2c9633",
"rel": "self"
}
]
}
]
}
Request¶
Name |
In |
Type |
Description |
|---|---|---|---|
node_ident |
path |
string |
The UUID or Name of the node. |
history_event_uuid |
path |
string |
The UUID of a history event. |
Response¶
Name |
In |
Type |
Description |
|---|---|---|---|
uuid |
body |
string |
The UUID for the resource. |
created_at |
body |
string |
The UTC date and time when the resource was created, ISO 8601 format. |
user |
body |
string |
The UUID value representing the user whom appears to have caused the recorded event. |
severity |
body |
string |
Severity indicator for the event being returned. Typically this will indicate if this was an Error or Informational entry. |
event |
body |
string |
The event message body which has been logged related to the node for this error. |
event_type |
body |
string |
Short descriptive string to indicate where the error occurred at to enable API users/System Operators to be able to identify repeated issues in a particular area of operation, such as ‘deployment’, ‘console’, ‘cleaning’, ‘monitoring’. |
conductor |
body |
array |
The hostname of this conductor. |
Deleting history entries for a node¶
Due to the nature of an immutable history record, records cannot be deleted via the REST API. Records and ultimately expired history records are managed by the conductor.
Node inventory¶
Added in version 1.81.
Given a Node identifier, the API provides access to the introspection data
associated to the Node via v1/nodes/{node_ident}/inventory endpoint.
The format inventory comes from ironic-python-agent and is currently documented in the agent inventory documentation.
Normal response code: 200
- Error codes:
404 (NodeNotFound, InventoryNotRecorded)
Request¶
Name |
In |
Type |
Description |
|---|---|---|---|
node_ident |
path |
string |
The UUID or Name of the node. |
Response¶
Name |
In |
Type |
Description |
|---|---|---|---|
inventory (Optional) |
body |
JSON |
Inventory of this node. |
plugin_data (Optional) |
body |
JSON |
Plugin data of this node. |
Example of inventory from a node:
{
"inventory": {
"interfaces":[
{
"name":"eth0",
"mac_address":"52:54:00:90:35:d6",
"ipv4_address":"192.168.122.128",
"ipv6_address":"fe80::5054:ff:fe90:35d6%eth0",
"has_carrier":true,
"lldp":null,
"vendor":"0x1af4",
"product":"0x0001"
}
],
"cpu":{
"model_name":"QEMU Virtual CPU version 2.5+",
"frequency":null,
"count":1,
"architecture":"x86_64"
}
},
"plugin_data":{
"macs":[
"52:54:00:90:35:d6"
],
"local_gb":10,
"cpu_arch":"x86_64",
"memory_mb":2048
}
}
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.
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 |
marker (Optional) |
query |
string |
The ID of the last-seen item. Use the |
sort_dir (Optional) |
query |
string |
Sorts the response by the requested sort
direction. A valid value is |
sort_key (Optional) |
query |
string |
Sorts the response by this attribute value.
Default is |
Response Parameters¶
Name |
In |
Type |
Description |
|---|---|---|---|
uuid |
body |
string |
The UUID for the resource. |
chassis |
body |
array |
A |
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"
}
]
}
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 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 |
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"
}
Updates a chassis.
Normal response codes: 200
Request¶
The BODY of the PATCH request must be a JSON PATCH document, adhering to RFC 6902.
Name |
In |
Type |
Description |
|---|---|---|---|
chassis_id |
path |
string |
The UUID of the chassis. |
description (Optional) |
body |
string |
Descriptive text about the Ironic service. |
extra (Optional) |
body |
object |
A set of one or more arbitrary metadata key and value pairs. |
Request Example¶
[
{
"op": "replace",
"path": "/description",
"value": "Updated Chassis"
}
]
Response Parameters¶
Name |
In |
Type |
Description |
|---|---|---|---|
description |
body |
string |
Descriptive text about the Ironic service. |
links |
body |
array |
A list of relative links. Includes the self and bookmark links. |
extra |
body |
object |
A set of one or more arbitrary metadata key and value pairs. |
created_at |
body |
string |
The UTC date and time when the resource was created, ISO 8601 format. |
updated_at |
body |
string |
The UTC date and time when the resource was updated, ISO 8601 format. May be “null”. |
chassis |
body |
array |
A |
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"
}
Deletes a chassis.
Request¶
Name |
In |
Type |
Description |
|---|---|---|---|
chassis_id |
path |
string |
The UUID of the chassis. |
Creates a chassis.
Error response codes:201,413,415,405,404,403,401,400,503,409,
Request¶
Name |
In |
Type |
Description |
|---|---|---|---|
uuid (Optional) |
body |
string |
The UUID for the resource. |
description (Optional) |
body |
string |
Descriptive text about the Ironic service. |
extra (Optional) |
body |
object |
A set of one or more arbitrary metadata key and value pairs. |
Request Example¶
{
"description": "Sample chassis"
}
Response Parameters¶
Name |
In |
Type |
Description |
|---|---|---|---|
description |
body |
string |
Descriptive text about the Ironic service. |
links |
body |
array |
A list of relative links. Includes the self and bookmark links. |
extra |
body |
object |
A set of one or more arbitrary metadata key and value pairs. |
created_at |
body |
string |
The UTC date and time when the resource was created, ISO 8601 format. |
updated_at |
body |
string |
The UTC date and time when the resource was updated, ISO 8601 format. May be “null”. |
nodes |
body |
array |
Links to the collection of nodes contained in this chassis. |
uuid |
body |
string |
The UUID for the resource. |
Response Example¶
{
"created_at": "2016-08-18T22:28:48.643434+11:11",
"description": "Sample chassis",
"extra": {},
"links": [
{
"href": "http://127.0.0.1:6385/v1/chassis/dff29d23-1ded-43b4-8ae1-5eebb3e30de1",
"rel": "self"
},
{
"href": "http://127.0.0.1:6385/chassis/dff29d23-1ded-43b4-8ae1-5eebb3e30de1",
"rel": "bookmark"
}
],
"nodes": [
{
"href": "http://127.0.0.1:6385/v1/chassis/dff29d23-1ded-43b4-8ae1-5eebb3e30de1/nodes",
"rel": "self"
},
{
"href": "http://127.0.0.1:6385/chassis/dff29d23-1ded-43b4-8ae1-5eebb3e30de1/nodes",
"rel": "bookmark"
}
],
"updated_at": null,
"uuid": "dff29d23-1ded-43b4-8ae1-5eebb3e30de1"
}
Lists all chassis.
Added in version 1.43: Added the detail boolean request parameter. When specified True this
causes the response to include complete details about each chassis.
Normal response codes: 200
Request¶
Name |
In |
Type |
Description |
|---|---|---|---|
limit (Optional) |
query |
integer |
Requests a page size of items. Returns a number of items up to a limit
value. Use the |
marker (Optional) |
query |
string |
The ID of the last-seen item. Use the |
sort_dir (Optional) |
query |
string |
Sorts the response by the requested sort
direction. A valid value is |
sort_key (Optional) |
query |
string |
Sorts the response by this attribute value.
Default is |
fields (Optional) |
query |
array |
One or more fields to be returned in the response. For example, the following request returns only the GET /v1/nodes?fields=uuid,name
|
detail (Optional) |
query |
boolean |
Whether to show detailed information about the resource. This cannot be
set to True if |
Response Parameters¶
Name |
In |
Type |
Description |
|---|---|---|---|
description |
body |
string |
Descriptive text about the Ironic service. |
links |
body |
array |
A list of relative links. Includes the self and bookmark links. |
extra |
body |
object |
A set of one or more arbitrary metadata key and value pairs. |
created_at |
body |
string |
The UTC date and time when the resource was created, ISO 8601 format. |
updated_at |
body |
string |
The UTC date and time when the resource was updated, ISO 8601 format. May be “null”. |
nodes |
body |
array |
Links to the collection of nodes contained in this chassis. |
uuid |
body |
string |
The UUID for the resource. |
Response Example¶
{
"chassis": [
{
"description": "Sample chassis",
"links": [
{
"href": "http://127.0.0.1:6385/v1/chassis/dff29d23-1ded-43b4-8ae1-5eebb3e30de1",
"rel": "self"
},
{
"href": "http://127.0.0.1:6385/chassis/dff29d23-1ded-43b4-8ae1-5eebb3e30de1",
"rel": "bookmark"
}
],
"uuid": "dff29d23-1ded-43b4-8ae1-5eebb3e30de1"
}
]
}
Utility¶
This section describes two API endpoints used by the ironic-python-agent
ramdisk as it communicates with the Bare Metal service. These were previously
exposed as vendor passthrough methods, however, as ironic-python-agent has
become the standard ramdisk agent, these methods have been made a part of the
official REST API.
Note
Operators are reminded not to expose the Bare Metal Service’s API to
unsecured networks. Both API endpoints listed below are available to
unauthenticated clients because the default method for booting the
ironic-python-agent ramdisk does not provide the agent with keystone
credentials.
Note
It is possible to include keys in your ramdisk, or pass keys in via the
boot method, if your driver supports it; if that is done, you may configure
these endpoints to require authentication by changing the policy rules
baremetal:driver:ipa_lookup and baremetal:node:ipa_heartbeat.
In light of that, operators are recommended to ensure that this endpoint is
only available on the provisioning and cleaning networks.
Added in version 1.22.
A /lookup method is exposed at the root of the REST API. This should only
be used by the ironic-python-agent ramdisk to retrieve required
configuration data from the Bare Metal service.
By default, /v1/lookup will only match Nodes that are expected to be
running the ironic-python-agent ramdisk (for instance, because the Bare
Metal service has just initiated a deployment). It can not be used as a
generic search mechanism, though this behaviour may be changed by setting
the [api] restrict_lookup = false configuration option for the ironic-api
service.
The query string should include either or both a node_uuid or an
addresses query parameter. If a matching Node is found, information about
that Node shall be returned.
Normal response codes: 200
Error response codes: 400 404
Request¶
Name |
In |
Type |
Description |
|---|---|---|---|
node_uuid (Optional) |
query |
string |
Optional Node UUID. |
addresses (Optional) |
query |
array |
Optional list of one or more Port addresses. |
Response¶
Returns only the information about the corresponding Node that the
ironic-python-agent process requires.
Name |
In |
Type |
Description |
|---|---|---|---|
node |
body |
JSON |
JSON document containing the Node fields “uuid”, “properties”, “instance_info”, and “driver_internal_info”; used by the ironic-python-agent process as it operates on the Node. |
config |
body |
JSON |
JSON document of configuration data for the ironic-python-agent process. |
Response Example¶
{
"config": {
"heartbeat_timeout": 300,
"metrics": {
"backend": "noop",
"global_prefix": null,
"prepend_host": false,
"prepend_host_reverse": true,
"prepend_uuid": false
},
"metrics_statsd": {
"statsd_host": "localhost",
"statsd_port": 8125
}
},
"node": {
"driver_internal_info": {
"clean_steps": null
},
"instance_info": {},
"links": [
{
"href": "http://127.0.0.1:6385/v1/nodes/6d85703a-565d-469a-96ce-30b6de53079d",
"rel": "self"
},
{
"href": "http://127.0.0.1:6385/nodes/6d85703a-565d-469a-96ce-30b6de53079d",
"rel": "bookmark"
}
],
"properties": {},
"uuid": "6d85703a-565d-469a-96ce-30b6de53079d"
}
}
Added in version 1.22.
A /heartbeat method is exposed at the root of the REST API. This is used
as a callback from within the ironic-python-agent ramdisk, so that an
active ramdisk may periodically contact the Bare Metal service and provide
the current URL at which to contact the agent.
Normal response codes: 202
Error response codes: 400 404
Added in version 1.36: agent_version parameter for passing the version of
the Ironic Python Agent to Ironic during heartbeat
Added in version 1.62: agent_token parameter for passing the token of
the Ironic Python Agent to Ironic during heartbeat
Request¶
Name |
In |
Type |
Description |
|---|---|---|---|
node_ident |
path |
string |
The UUID or Name of the node. |
callback_url |
query |
string |
The URL of an active ironic-python-agent ramdisk, sent back to the Bare Metal service and stored temporarily during a provisioning action. |
agent_version |
query |
string |
The version of the ironic-python-agent ramdisk, sent back to the Bare Metal service and stored during provisioning. |
agent_token |
query |
string |
The token of the ironic-python-agent ramdisk, sent to the Bare Metal service for authentication purposes. |
