RESTful Web API (v1)

API Versioning

Starting with the Kilo release ironic supports versioning of API. Version is defined as a string of 2 integers separated by a dot: X.Y. Here X is a major version, always equal to 1 at the moment of writing, Y is a minor version. Server minor version is increased every time the API behavior is changed (note Exceptions from Versioning). Nova versioning documentation has a nice guide on when to bump an API version.

Server indicates its minimum and maximum supported API versions in the X-OpenStack-Ironic-API-Minimum-Version and X-OpenStack-Ironic-API-Maximum-Version headers respectively, returned with every response. Client may request a specific API version by providing X-OpenStack-Ironic-API-Version header with request.

If no version is requested by the client, minimum supported version - 1.1, is assumed. The client is only exposed to those API features that are supported in the requested (explicitly or implicitly) API version (again note Exceptions from Versioning, they are not covered by this rule).

We recommend clients requiring stable API to always request a specific version of API. However, a special value latest can be requested instead, which always requests the newest supported API version.

API Versions History

1.16
Add ability to filter nodes by driver.

1.15

Add ability to do manual cleaning when a node is in the manageable provision state via PUT v1/nodes/<identifier>/states/provision, target:clean, clean_steps:[...].

1.14

Make the following endpoints discoverable via Ironic API: * ‘/v1/nodes/<UUID or logical name>/states’ * ‘/v1/drivers/<driver name>/properties’

1.13

Add a new verb abort to the API used to abort nodes in CLEANWAIT state.

1.12

This API version adds the following abilities:

  • Get/set node.target_raid_config and to get node.raid_config.
  • Retrieve the logical disk properties for the driver.

1.11 (breaking change)

Newly registered nodes begin in the enroll provision state by default, instead of available. To get them to the available state, the manage action must first be run to verify basic hardware control. On success the node moves to manageable provision state. Then the provide action must be run. Automated cleaning of the node is done and the node is made available.

1.10

Logical node names support all RFC 3986 unreserved characters. Previously only valid fully qualified domain names could be used.

1.9

Add ability to filter nodes by provision state.

1.8

Add ability to return a subset of resource fields.

1.7

Add node clean_step field.

1.6

Add Hardware Inspection process: introduce inspecting and inspectfail provision states, and inspect action that can be used when a node is in manageable provision state.

1.5

Add logical node names that can be used to address a node in addition to the node UUID. Name is expected to be a valid fully qualified domain name in this version of API.

1.4

Add manageable state and manage transition, which can be used to move a node to manageable state from available. The node cannot be deployed in managable state. This change is mostly a preparation for future inspection work and introduction of enroll provision state.

1.3

Add node driver_internal_info field.

1.2 (breaking change)

Renamed NOSTATE (None in Python, null in JSON) node state to available. This is needed to reduce confusion around None state, especially when future additions to the state machine land.

1.1

This was the initial version when API versioning was introduced. Includes the following changes from Kilo release cycle:

  • Add node maintenance_reason field and an API endpoint to set/unset the node maintenance mode.
  • Add sync and async support for vendor passthru methods.
  • Vendor passthru endpoints support different HTTP methods, not only POST.
  • Make vendor methods discoverable via the Ironic API.
  • Add logic to store the config drive passed by Nova.

This has been the minimum supported version since versioning was introduced.

1.0

This version denotes Juno API and was never explicitly supported, as API versioning was not implemented in Juno, and 1.1 became the minimum supported version in Kilo.

Exceptions from Versioning

The following API-visible things are not covered by the API versioning:

  • Current node state is always exposed as it is, even if not supported by the requested API version, with exception of available state, which is returned in version 1.1 as None (in Python) or null (in JSON).
  • Data within free-form JSON attributes: properties, driver_info, instance_info, driver_internal_info fields on a node object; extra fields on all objects.
  • Addition of new drivers.
  • All vendor passthru methods.

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.
  • fields (list) – Optional, a list with a specified set of fields of the resource to be returned.
Return type:

ChassisCollection
GET /v1/chassis/(chassis_uuid)

Retrieve information about the given chassis.

Parameters:
  • chassis_uuid (uuid) – UUID of a chassis.
  • fields (list) – Optional, a list with a specified set of fields of the resource to be returned.
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)/raid/logical_disk_properties

Returns the logical disk properties for the driver.

Parameters:
  • driver_name (unicode) – Name of the driver.
Returns:

A dictionary containing the properties that can be mentioned for logical disks and a textual description for them.
Raises:

UnsupportedDriverExtension if the driver doesn’t support RAID configuration.
Raises:

NotAcceptable, if requested version of the API is less than 1.12.
Raises:

DriverNotFound, if driver is not loaded on any of the conductors.
Return type:

json
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

properties
Type:list(Link)

A list containing links to driver properties

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”).
  • provision_state (unicode) – Optional string value to get only nodes in that provision state.
  • 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.
  • driver (unicode) – Optional string value to get only nodes using that driver.
  • fields (list) – Optional, a list with a specified set of fields of the resource to be returned.
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.
  • fields (list) – Optional, a list with a specified set of fields of the resource to be returned.
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”).
  • provision_state (unicode) – Optional string value to get only nodes in that provision state.
  • 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.
  • driver (unicode) – Optional string value to get only nodes using that driver.
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 or verb.
  • configdrive (unicode) – Optional. A gzipped and base64 encoded configdrive. Only valid when setting provision state to “active”.
  • clean_steps (json) –

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

    { 'interface': <driver_interface>,
  'step': <name_of_clean_step>,
  'args': {<arg1>: <value1>, ..., <argn>: <valuen>} }

    For example (this isn’t a real example, this cleaning step doesn’t exist):

    { 'interface': 'deploy',
  'step': 'upgrade_firmware',
  'args': {'force': True} }

    This is required (and only valid) when target is “clean”.
Raises:

NodeLocked (HTTP 409) if the node is currently locked.
Raises:

ClientSideError (HTTP 409) if the node is already being provisioned.
Raises:

InvalidParameterValue (HTTP 400), if validation of clean_steps or power driver interface fails.
Raises:

InvalidStateRequested (HTTP 400) if the requested transition is not possible from the current state.
Raises:

NodeInMaintenance (HTTP 400), if operation cannot be performed because the node is in maintenance mode.
Raises:

NoFreeConductorWorker (HTTP 503) if no workers are available.
Raises:

NotAcceptable (HTTP 406) if the API version specified does not allow the requested state transition.
PUT /v1/nodes/(node_ident)/states/raid

Set the target raid config of the node.

Parameters:
  • node_ident (uuid_or_name) – the UUID or logical name of a node.
  • target_raid_config (json) – Desired target RAID configuration of the node. It may be an empty dictionary as well.
Raises:

UnsupportedDriverExtension, if the node’s driver doesn’t support RAID configuration.
Raises:

InvalidParameterValue, if validation of target raid config fails.
Raises:

NotAcceptable, if requested version of the API is less than 1.12.
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",
    "clean_step": {},
    "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",
    "raid_config": null,
    "reservation": null,
    "states": [
        {
            "href": "http://localhost:6385/v1/nodes/1be26c0b-03f2-4d2e-ae87-c02d7f33c123/states",
            "rel": "self"
        },
        {
            "href": "http://localhost:6385/nodes/1be26c0b-03f2-4d2e-ae87-c02d7f33c123/states",
            "rel": "bookmark"
        }
    ],
    "target_power_state": null,
    "target_provision_state": null,
    "target_raid_config": 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

clean_step
Type:dict(unicode: json)

The current clean step

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

raid_config
Type:dict(unicode: json)

Represents the current RAID configuration of the node

reservation
Type:unicode

The hostname of the conductor that holds an exclusive lock on the node.

states
Type:list(Link)

Links to endpoint for retrieving and setting node states

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.

target_raid_config
Type:dict(unicode: json)

The user modified RAID configuration 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,
    "raid_config": null,
    "target_power_state": "power on",
    "target_provision_state": "active",
    "target_raid_config": null
}
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

raid_config
Type:dict(unicode: json)

Represents the RAID configuration that the node is configured with.

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.

target_raid_config
Type:dict(unicode: json)

The desired RAID configuration, to be used the next time the node is configured.

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.
  • fields (list) – Optional, a list with a specified set of fields of the resource to be returned.
Return type:

PortCollection
GET /v1/ports/(port_uuid)

Retrieve information about the given port.

Parameters:
  • port_uuid (uuid) – UUID of a port.
  • fields (list) – Optional, a list with a specified set of fields of the resource to be returned.
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": "2017-04-10T18:35:24.142860",
    "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": "2017-04-10T18:35:24.142864",
    "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

ironic-dbsync

Next topic

Pluggable Drivers

Project Source

This Page

Navigation

© Copyright OpenStack Foundation. Created using Sphinx 1.2.3.