RESTful Web API (v1)¶
Chassis¶
-
GET
/v1/chassis
¶ Retrieve a list of chassis.
Parameters: - marker (
uuid
) – pagination marker for large data sets. - limit (
int
) – maximum number of resources to return in a single result. - sort_key (
unicode
) – column to sort results by. Default: id. - sort_dir (
unicode
) – direction to sort. “asc” or “desc”. Default: asc.
Return type: - marker (
-
GET
/v1/chassis/
(chassis_uuid)¶ Retrieve information about the given chassis.
Parameters: - chassis_uuid (
uuid
) – UUID of a chassis.
Return type: - chassis_uuid (
-
POST
/v1/chassis
¶ Create a new chassis.
Parameters: - chassis (
Chassis
) – a chassis within the request body.
Return type: - chassis (
-
DELETE
/v1/chassis
¶ Delete a chassis.
Parameters: - chassis_uuid (
uuid
) – UUID of a chassis.
- chassis_uuid (
-
PATCH
/v1/chassis
¶ Update an existing chassis.
Parameters: - chassis_uuid (
uuid
) – UUID of a chassis. - patch (list(
ChassisPatchType
)) – a json PATCH document to apply to this chassis.
Return type: - chassis_uuid (
-
GET
/v1/chassis/detail
¶ Retrieve a list of chassis with detail.
Parameters: - marker (
uuid
) – pagination marker for large data sets. - limit (
int
) – maximum number of resources to return in a single result. - sort_key (
unicode
) – column to sort results by. Default: id. - sort_dir (
unicode
) – direction to sort. “asc” or “desc”. Default: asc.
Return type: - marker (
-
type
ChassisCollection
¶ API representation of a collection of chassis.
Data samples:
- Json
{ "chassis": [ { "description": "Sample chassis", "links": [ { "href": "http://localhost:6385/v1/chassis/eaaca217-e7d8-47b4-bb41-3f99f20eed89", "rel": "self" }, { "href": "http://localhost:6385/chassis/eaaca217-e7d8-47b4-bb41-3f99f20eed89", "rel": "bookmark" } ], "uuid": "eaaca217-e7d8-47b4-bb41-3f99f20eed89" } ] }
-
chassis
¶ Type: list(Chassis) A list containing chassis objects
-
type
Chassis
¶ API representation of a chassis.
This class enforces type checking and value constraints, and converts between the internal object model and the API representation of a chassis.
Data samples:
- Json
{ "created_at": "2000-01-01T12:00:00", "description": "Sample chassis", "extra": {}, "links": [ { "href": "http://localhost:6385/v1/chassis/eaaca217-e7d8-47b4-bb41-3f99f20eed89", "rel": "self" }, { "href": "http://localhost:6385/chassis/eaaca217-e7d8-47b4-bb41-3f99f20eed89", "rel": "bookmark" } ], "nodes": [ { "href": "http://localhost:6385/v1/chassis/eaaca217-e7d8-47b4-bb41-3f99f20eed89/nodes", "rel": "self" }, { "href": "http://localhost:6385/chassis/eaaca217-e7d8-47b4-bb41-3f99f20eed89/nodes", "rel": "bookmark" } ], "updated_at": "2000-01-01T12:00:00", "uuid": "eaaca217-e7d8-47b4-bb41-3f99f20eed89" }
-
description
¶ Type: unicode The description of the chassis
-
extra
¶ Type: dict(unicode: json) The metadata of the chassis
-
links
¶ Type: list(Link) A list containing a self link and associated chassis links
-
nodes
¶ Type: list(Link) Links to the collection of nodes contained in this chassis
-
uuid
¶ Type: uuid The UUID of the chassis
Drivers¶
-
GET
/v1/drivers
¶ Retrieve a list of drivers.
Return type: DriverList
-
GET
/v1/drivers/
(driver_name)¶ Retrieve a single driver. :type driver_name:
unicode
Return type: Driver
-
GET
/v1/drivers/properties
¶ Retrieve property information of the given driver.
Parameters: - driver_name (
unicode
) – name of the driver.
Returns: dictionary with <property name>:<property description> entries.
Raises: DriverNotFound (HTTP 404) if the driver name is invalid or the driver cannot be loaded.
Return type: unicode
- driver_name (
-
GET
/v1/drivers/
(driver_name)/vendor_passthru/methods
¶ Retrieve information about vendor methods of the given driver.
Parameters: - driver_name (
unicode
) – name of the driver.
Returns: dictionary with <vendor method name>:<method metadata> entries.
Raises: DriverNotFound if the driver name is invalid or the driver cannot be loaded.
Return type: unicode
- driver_name (
-
type
DriverList
¶ API representation of a list of drivers.
Data samples:
- Json
{ "drivers": [ { "hosts": [ "fake-host" ], "name": "sample-driver" } ] }
-
drivers
¶ Type: list(Driver) A list containing drivers objects
-
type
Driver
¶ API representation of a driver.
Data samples:
- Json
{ "hosts": [ "fake-host" ], "name": "sample-driver" }
-
hosts
¶ Type: list(unicode) A list of active conductors that support this driver
-
links
¶ Type: list(Link) A list containing self and bookmark links
-
name
¶ Type: unicode The name of the driver
Links¶
Nodes¶
-
GET
/v1/nodes
¶ Retrieve a list of nodes.
Parameters: - chassis_uuid (
uuid
) – Optional UUID of a chassis, to get only nodes for that chassis. - instance_uuid (
uuid
) – Optional UUID of an instance, to find the node associated with that instance. - associated (
boolean
) – Optional boolean whether to return a list of associated or unassociated nodes. May be combined with other parameters. - maintenance (
boolean
) – Optional boolean value that indicates whether to get nodes in maintenance mode (“True”), or not in maintenance mode (“False”). - marker (
uuid
) – pagination marker for large data sets. - limit (
int
) – maximum number of resources to return in a single result. - sort_key (
unicode
) – column to sort results by. Default: id. - sort_dir (
unicode
) – direction to sort. “asc” or “desc”. Default: asc.
Return type: - chassis_uuid (
-
GET
/v1/nodes/
(node_ident)¶ Retrieve information about the given node.
Parameters: - node_ident (
uuid_or_name
) – UUID or logical name of a node.
Return type: - node_ident (
-
POST
/v1/nodes
¶ Create a new node.
Parameters: - node (
Node
) – a node within the request body.
Return type: - node (
-
DELETE
/v1/nodes
¶ Delete a node.
Parameters: - node_ident (
uuid_or_name
) – UUID or logical name of a node.
- node_ident (
-
PATCH
/v1/nodes
¶ Update an existing node.
Parameters: - node_ident (
uuid_or_name
) – UUID or logical name of a node. - patch (list(
NodePatchType
)) – a json PATCH document to apply to this node.
Return type: - node_ident (
-
GET
/v1/nodes/detail
¶ Retrieve a list of nodes with detail.
Parameters: - chassis_uuid (
uuid
) – Optional UUID of a chassis, to get only nodes for that chassis. - instance_uuid (
uuid
) – Optional UUID of an instance, to find the node associated with that instance. - associated (
boolean
) – Optional boolean whether to return a list of associated or unassociated nodes. May be combined with other parameters. - maintenance (
boolean
) – Optional boolean value that indicates whether to get nodes in maintenance mode (“True”), or not in maintenance mode (“False”). - marker (
uuid
) – pagination marker for large data sets. - limit (
int
) – maximum number of resources to return in a single result. - sort_key (
unicode
) – column to sort results by. Default: id. - sort_dir (
unicode
) – direction to sort. “asc” or “desc”. Default: asc.
Return type: - chassis_uuid (
-
GET
/v1/nodes/validate
¶ Validate the driver interfaces, using the node’s UUID or name.
Note that the ‘node_uuid’ interface is deprecated in favour of the ‘node’ interface
Parameters: - node (
uuid_or_name
) – UUID or name of a node. - node_uuid (
uuid
) – UUID of a node.
Return type: unicode
- node (
-
PUT
/v1/nodes/
(node_ident)/maintenance
¶ Put the node in maintenance mode.
Parameters: - node_ident (
uuid_or_name
) – the UUID or logical_name of a node. - reason (
unicode
) – Optional, the reason why it’s in maintenance.
- node_ident (
-
DELETE
/v1/nodes/
(node_ident)/maintenance
¶ Remove the node from maintenance mode.
Parameters: - node_ident (
uuid_or_name
) – the UUID or logical name of a node.
- node_ident (
-
GET
/v1/nodes/
(node_ident)/management/boot_device
¶ Get the current boot device for a node.
Parameters: - node_ident (
uuid_or_name
) – the UUID or logical name of a node.
Returns: a json object containing:
boot_device: the boot device, one of ironic.common.boot_devices
or None if it is unknown.persistent: Whether the boot device will persist to all future boots or not, None if it is unknown. Return type: unicode
- node_ident (
-
PUT
/v1/nodes/
(node_ident)/management/boot_device
¶ Set the boot device for a node.
Set the boot device to use on next reboot of the node.
Parameters: - node_ident (
uuid_or_name
) – the UUID or logical name of a node. - boot_device (
unicode
) – the boot device, one ofironic.common.boot_devices
. - persistent (
boolean
) – Boolean value. True if the boot device will persist to all future boots, False if not. Default: False.
- node_ident (
-
GET
/v1/nodes/
(node_ident)/management/boot_device/supported
¶ Get a list of the supported boot devices.
Parameters: - node_ident (
uuid_or_name
) – the UUID or logical name of a node.
Returns: A json object with the list of supported boot devices.
Return type: unicode
- node_ident (
-
GET
/v1/nodes/
(node_ident)/states
¶ List the states of the node.
Parameters: - node_ident (
uuid_or_name
) – the UUID or logical_name of a node.
Return type: - node_ident (
-
PUT
/v1/nodes/
(node_ident)/states/power
¶ Set the power state of the node.
Parameters: - node_ident (
uuid_or_name
) – the UUID or logical name of a node. - target (
unicode
) – The desired power state of the node.
Raises: ClientSideError (HTTP 409) if a power operation is already in progress.
Raises: InvalidStateRequested (HTTP 400) if the requested target state is not valid or if the node is in CLEANING state.
- node_ident (
-
PUT
/v1/nodes/
(node_ident)/states/provision
¶ Asynchronous trigger the provisioning of the node.
This will set the target provision state of the node, and a background task will begin which actually applies the state change. This call will return a 202 (Accepted) indicating the request was accepted and is in progress; the client should continue to GET the status of this node to observe the status of the requested action.
Parameters: - node_ident (
uuid_or_name
) – UUID or logical name of a node. - target (
unicode
) – The desired provision state of the node. - configdrive (
unicode
) – Optional. A gzipped and base64 encoded configdrive. Only valid when setting provision state to “active”.
Raises: NodeLocked (HTTP 409) if the node is currently locked.
Raises: ClientSideError (HTTP 409) if the node is already being provisioned.
Raises: InvalidStateRequested (HTTP 400) if the requested transition is not possible from the current state.
Raises: NotAcceptable (HTTP 406) if the API version specified does not allow the requested state transition.
- node_ident (
-
GET
/v1/nodes/
(node_ident)/states/console
¶ Get connection information about the console.
Parameters: - node_ident (
uuid_or_name
) – UUID or logical name of a node.
Return type: - node_ident (
-
PUT
/v1/nodes/
(node_ident)/states/console
¶ Start and stop the node console.
Parameters: - node_ident (
uuid_or_name
) – UUID or logical name of a node. - enabled (
boolean
) – Boolean value; whether to enable or disable the console.
- node_ident (
-
GET
/v1/nodes/
(node_ident)/vendor_passthru/methods
¶ Retrieve information about vendor methods of the given node.
Parameters: - node_ident (
uuid_or_name
) – UUID or logical name of a node.
Returns: dictionary with <vendor method name>:<method metadata> entries.
Raises: NodeNotFound if the node is not found.
Return type: unicode
- node_ident (
-
type
ConsoleInfo
¶ API representation of the console information for a node.
Data samples:
- Json
{ "console_enabled": true, "console_info": { "type": "shellinabox", "url": "http://<hostname>:4201" } }
-
console_enabled
¶ Type: boolean The console state: if the console is enabled or not.
-
console_info
¶ Type: dict(unicode: json) The console information. It typically includes the url to access the console and the type of the application that hosts the console.
-
type
Node
¶ API representation of a bare metal node.
This class enforces type checking and value constraints, and converts between the internal object model and the API representation of a node.
Data samples:
- Json
{ "chassis_uuid": "edcad704-b2da-41d5-96d9-afd580ecfa12", "console_enabled": false, "created_at": "2000-01-01T12:00:00", "driver": "fake", "driver_info": {}, "driver_internal_info": {}, "extra": {}, "inspection_finished_at": null, "inspection_started_at": "2000-01-01T12:00:00", "instance_info": {}, "instance_uuid": "dcf1fbc5-93fc-4596-9395-b80572f6267b", "last_error": null, "links": [ { "href": "http://localhost:6385/v1/nodes/1be26c0b-03f2-4d2e-ae87-c02d7f33c123", "rel": "self" }, { "href": "http://localhost:6385/nodes/1be26c0b-03f2-4d2e-ae87-c02d7f33c123", "rel": "bookmark" } ], "maintenance": false, "maintenance_reason": null, "name": "database16-dc02", "ports": [ { "href": "http://localhost:6385/v1/nodes/1be26c0b-03f2-4d2e-ae87-c02d7f33c123/ports", "rel": "self" }, { "href": "http://localhost:6385/nodes/1be26c0b-03f2-4d2e-ae87-c02d7f33c123/ports", "rel": "bookmark" } ], "power_state": "power on", "properties": { "cpus": "1", "local_gb": "10", "memory_mb": "1024" }, "provision_state": "active", "provision_updated_at": "2000-01-01T12:00:00", "reservation": null, "target_power_state": null, "target_provision_state": null, "updated_at": "2000-01-01T12:00:00", "uuid": "1be26c0b-03f2-4d2e-ae87-c02d7f33c123" }
-
chassis_uuid
¶ Type: uuid The UUID of the chassis this node belongs
-
console_enabled
¶ Type: boolean Indicates whether the console access is enabled or disabled on the node.
-
driver
¶ Type: unicode The driver responsible for controlling the node
-
driver_info
¶ Type: dict(unicode: json) This node’s driver configuration
-
driver_internal_info
¶ Type: dict(unicode: json) This driver’s internal configuration
-
extra
¶ Type: dict(unicode: json) This node’s meta data
-
inspection_finished_at
¶ Type: datetime The UTC date and time when the last hardware inspection finished successfully.
-
inspection_started_at
¶ Type: datetime The UTC date and time when the hardware inspection was started
-
instance_info
¶ Type: dict(unicode: json) This node’s instance info.
-
instance_uuid
¶ Type: uuid The UUID of the instance in nova-compute
-
last_error
¶ Type: unicode Any error from the most recent (last) asynchronous transaction that started but failed to finish.
-
links
¶ Type: list(Link) A list containing a self link and associated node links
-
maintenance
¶ Type: boolean Indicates whether the node is in maintenance mode.
-
maintenance_reason
¶ Type: unicode Indicates reason for putting a node in maintenance mode.
-
name
¶ Type: unicode The logical name for this node
-
ports
¶ Type: list(Link) Links to the collection of ports on this node
-
power_state
¶ Type: unicode Represent the current (not transition) power state of the node
-
properties
¶ Type: dict(unicode: json) The physical characteristics of this node
-
provision_state
¶ Type: unicode Represent the current (not transition) provision state of the node
-
provision_updated_at
¶ Type: datetime The UTC date and time of the last provision state change
-
reservation
¶ Type: unicode The hostname of the conductor that holds an exclusive lock on the node.
-
target_power_state
¶ Type: unicode The user modified desired power state of the node.
-
target_provision_state
¶ Type: unicode The user modified desired provision state of the node.
-
uuid
¶ Type: uuid Unique UUID for this node
-
type
NodeCollection
¶ API representation of a collection of nodes.
Data samples:
- Json
{ "nodes": [ { "instance_uuid": "dcf1fbc5-93fc-4596-9395-b80572f6267b", "links": [ { "href": "http://localhost:6385/v1/nodes/1be26c0b-03f2-4d2e-ae87-c02d7f33c123", "rel": "self" }, { "href": "http://localhost:6385/nodes/1be26c0b-03f2-4d2e-ae87-c02d7f33c123", "rel": "bookmark" } ], "maintenance": false, "name": "database16-dc02", "power_state": "power on", "provision_state": "active", "uuid": "1be26c0b-03f2-4d2e-ae87-c02d7f33c123" } ] }
-
nodes
¶ Type: list(Node) A list containing nodes objects
-
type
NodeStates
¶ API representation of the states of a node.
Data samples:
- Json
{ "console_enabled": false, "last_error": null, "power_state": "power on", "provision_state": null, "provision_updated_at": null, "target_power_state": "power on", "target_provision_state": "active" }
-
console_enabled
¶ Type: boolean Indicates whether the console access is enabled or disabled on the node.
-
last_error
¶ Type: unicode Any error from the most recent (last) asynchronous transaction that started but failed to finish.
-
power_state
¶ Type: unicode Represent the current (not transition) power state of the node
-
provision_state
¶ Type: unicode Represent the current (not transition) provision state of the node
-
provision_updated_at
¶ Type: datetime The UTC date and time of the last provision state change
-
target_power_state
¶ Type: unicode The user modified desired power state of the node.
-
target_provision_state
¶ Type: unicode The user modified desired provision state of the node.
Ports¶
-
GET
/v1/ports
¶ Retrieve a list of ports.
Note that the ‘node_uuid’ interface is deprecated in favour of the ‘node’ interface
Parameters: - node (
uuid_or_name
) – UUID or name of a node, to get only ports for that node. - node_uuid (
uuid
) – UUID of a node, to get only ports for that node. - address (
macaddress
) – MAC address of a port, to get the port which has this MAC address. - marker (
uuid
) – pagination marker for large data sets. - limit (
int
) – maximum number of resources to return in a single result. - sort_key (
unicode
) – column to sort results by. Default: id. - sort_dir (
unicode
) – direction to sort. “asc” or “desc”. Default: asc.
Return type: - node (
-
GET
/v1/ports/
(port_uuid)¶ Retrieve information about the given port.
Parameters: - port_uuid (
uuid
) – UUID of a port.
Return type: - port_uuid (
-
POST
/v1/ports
¶ Create a new port.
Parameters: - port (
Port
) – a port within the request body.
Return type: - port (
-
DELETE
/v1/ports
¶ Delete a port.
Parameters: - port_uuid (
uuid
) – UUID of a port.
- port_uuid (
-
PATCH
/v1/ports
¶ Update an existing port.
Parameters: - port_uuid (
uuid
) – UUID of a port. - patch (list(
PortPatchType
)) – a json PATCH document to apply to this port.
Return type: - port_uuid (
-
GET
/v1/ports/detail
¶ Retrieve a list of ports with detail.
Note that the ‘node_uuid’ interface is deprecated in favour of the ‘node’ interface
Parameters: - node (
uuid_or_name
) – UUID or name of a node, to get only ports for that node. - node_uuid (
uuid
) – UUID of a node, to get only ports for that node. - address (
macaddress
) – MAC address of a port, to get the port which has this MAC address. - marker (
uuid
) – pagination marker for large data sets. - limit (
int
) – maximum number of resources to return in a single result. - sort_key (
unicode
) – column to sort results by. Default: id. - sort_dir (
unicode
) – direction to sort. “asc” or “desc”. Default: asc.
Return type: - node (
-
type
PortCollection
¶ API representation of a collection of ports.
Data samples:
- Json
{ "ports": [ { "address": "fe:54:00:77:07:d9", "links": [ { "href": "http://localhost:6385/v1/ports/27e3153e-d5bf-4b7e-b517-fb518e17f34c", "rel": "self" }, { "href": "http://localhost:6385/ports/27e3153e-d5bf-4b7e-b517-fb518e17f34c", "rel": "bookmark" } ], "uuid": "27e3153e-d5bf-4b7e-b517-fb518e17f34c" } ] }
-
ports
¶ Type: list(Port) A list containing ports objects
-
type
Port
¶ API representation of a port.
This class enforces type checking and value constraints, and converts between the internal object model and the API representation of a port.
Data samples:
- Json
{ "address": "fe:54:00:77:07:d9", "created_at": "2015-06-14T13:32:47.137135", "extra": { "foo": "bar" }, "links": [ { "href": "http://localhost:6385/v1/ports/27e3153e-d5bf-4b7e-b517-fb518e17f34c", "rel": "self" }, { "href": "http://localhost:6385/ports/27e3153e-d5bf-4b7e-b517-fb518e17f34c", "rel": "bookmark" } ], "node_uuid": "7ae81bb3-dec3-4289-8d6c-da80bd8001ae", "updated_at": "2015-06-14T13:32:47.137137", "uuid": "27e3153e-d5bf-4b7e-b517-fb518e17f34c" }
-
address
¶ Type: macaddress MAC Address for this port
-
extra
¶ Type: dict(unicode: json) This port’s meta data
-
links
¶ Type: list(Link) A list containing a self link and associated port links
-
node_uuid
¶ Type: uuid The UUID of the node this port belongs to
-
uuid
¶ Type: uuid Unique UUID for this port