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 verbabort
to the API used to abort nodes inCLEANWAIT
state.
1.12
This API version adds the following abilities:
- Get/set
node.target_raid_config
and to getnode.raid_config
.- Retrieve the logical disk properties for the driver.
1.11 (breaking change)
Newly registered nodes begin in theenroll
provision state by default, instead ofavailable
. To get them to theavailable
state, themanage
action must first be run to verify basic hardware control. On success the node moves tomanageable
provision state. Then theprovide
action must be run. Automated cleaning of the node is done and the node is madeavailable
.
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 nodeclean_step
field.
1.6
Add Hardware Inspection process: introduceinspecting
andinspectfail
provision states, andinspect
action that can be used when a node is inmanageable
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
Addmanageable
state andmanage
transition, which can be used to move a node tomanageable
state fromavailable
. The node cannot be deployed inmanagable
state. This change is mostly a preparation for future inspection work and introduction ofenroll
provision state.
1.3
Add nodedriver_internal_info
field.
1.2 (breaking change)
Renamed NOSTATE (None
in Python,null
in JSON) node state toavailable
. This is needed to reduce confusion aroundNone
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 asNone
(in Python) ornull
(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: - marker (
-
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_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)/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
- 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
-
properties
¶ Type: list(Link) A list containing links to driver properties
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”). - 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: - 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. - fields (
list
) – Optional, a list with a specified set of fields of the resource to be returned.
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”). - 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: - 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 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.
- node_ident (
-
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.
- 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", "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.
-
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
-
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: - node (
-
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_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": "2017-05-03T08:39:09.374844", "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-05-03T08:39:09.374859", "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