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:

ChassisCollection

GET /v1/chassis/(chassis_uuid)

Retrieve information about the given chassis.

Parameters:
  • chassis_uuid (uuid) – UUID of a chassis.
Return type:

Chassis

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

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:

ChassisCollection

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

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

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

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

Type:list(Link)

A list containing self and bookmark links

name
Type:unicode

The name of the driver

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:

NodeCollection

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

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

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:

NodeCollection

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

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

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 of ironic.common.boot_devices.
  • persistent (boolean) – Boolean value. True if the boot device will persist to all future boots, False if not. Default: False.
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

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:

NodeStates

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.

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.

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:

ConsoleInfo

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

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.

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:

PortCollection

GET /v1/ports/(port_uuid)

Retrieve information about the given port.

Parameters:
  • port_uuid (uuid) – UUID of a port.
Return type:

Port

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

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:

PortCollection

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-05-06T16:48:15.887287",
    "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-05-06T16:48:15.887289",
    "uuid": "27e3153e-d5bf-4b7e-b517-fb518e17f34c"
}
address
Type:macaddress

MAC Address for this port

extra
Type:dict(unicode: json)

This port’s meta data

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

Table Of Contents

Previous topic

Vendor Methods

Next topic

Pluggable Drivers

This Page