Update the api-ref documentation for Drivers
This updates the API documentation for the Drivers resource class, replacing many of the samples and adding more verbiage to each property. It's not perfect, but this is vastly more correct than the current docs. Co-Authored-By: Vladyslav Drok <vdrok@mirantis.com> Change-Id: Ibe045bea539b8fd2f02d7be37e09cc74f09b8df1
This commit is contained in:
Devananda van der Veen
Vladyslav Drok
parent
14e48ec273
commit
3c20a9bae6
97
api-ref/source/baremetal-api-v1-driver-passthru.inc
Normal file
97
api-ref/source/baremetal-api-v1-driver-passthru.inc
Normal file
@ -0,0 +1,97 @@
|
||||
.. -*- rst -*-
|
||||
|
||||
================================
|
||||
Driver Vendor Passthru (drivers)
|
||||
================================
|
||||
|
||||
Each driver MAY support vendor-specific extensions, called "passthru" methods.
|
||||
|
||||
Internally, Ironic's driver API supports flexibly exposing functions via the
|
||||
common HTTP methods GET, PUT, POST, and DELETE. To call a passthru method,
|
||||
the query string must contain the name of the method, eg.
|
||||
``/vendor_passthru?method=lookup``. The contents of the HTTP request are
|
||||
forwarded to the driver and validated there.
|
||||
|
||||
Ironic's REST API provides a means to discover these methods, but does not
|
||||
provide support, testing, or documentation for these endpoints. The Ironic
|
||||
development team does not guarantee any compatibility within these methods
|
||||
between releases, though we encourage driver authors to provide documentation
|
||||
and support for them.
|
||||
|
||||
Besides the endpoints documented here, all other resources and endpoints
|
||||
under the heading ``vendor_passthru`` should be considered unsupported APIs,
|
||||
and could be changed without warning by the driver authors.
|
||||
|
||||
|
||||
List Methods
|
||||
============
|
||||
|
||||
.. rest_method:: GET /v1/drivers/{driver_name}/vendor_passthru/methods
|
||||
|
||||
Retrieve a list of the available vendor passthru methods for the given Driver.
|
||||
The response will indicate which HTTP method(s) each vendor passthru method
|
||||
allows, whether the method call will be synchronous or asynchronous, and
|
||||
whether the response will include any attachment.
|
||||
|
||||
Normal response code: 200
|
||||
|
||||
Request
|
||||
-------
|
||||
|
||||
.. rest_parameters:: parameters.yaml
|
||||
|
||||
- driver_name: driver_ident
|
||||
|
||||
Response Parameters
|
||||
-------------------
|
||||
|
||||
.. rest_parameters:: parameters.yaml
|
||||
|
||||
- async: passthru_async
|
||||
- attach: passthru_attach
|
||||
- description: passthru_description
|
||||
- http_methods: passthru_http_methods
|
||||
|
||||
Response Example
|
||||
----------------
|
||||
|
||||
The response BODY is a dictionary whose keys are a ``method_name``. The value
|
||||
of each item is itself a dictionary describing how to interact with that
|
||||
method.
|
||||
|
||||
.. literalinclude:: samples/driver-passthru-methods-response.json
|
||||
:language: javascript
|
||||
|
||||
|
||||
Call a Method
|
||||
=============
|
||||
|
||||
.. rest_method:: METHOD /v1/drivers/{driver_name}/vendor_passthru?method={method_name}
|
||||
|
||||
The HTTP METHOD may be one of GET, POST, PUT, DELETE, depending on the driver
|
||||
and method.
|
||||
|
||||
This endpoint passes the request directly to the Node's hardware driver. The
|
||||
HTTP BODY must be parseable JSON, which will be converted to parameters passed
|
||||
to that function. Unparseable JSON, missing parameters, or excess parameters
|
||||
will cause the request to be rejected with an HTTP 400 error.
|
||||
|
||||
Normal response code: 200 202
|
||||
|
||||
Error codes: 400
|
||||
|
||||
Request
|
||||
-------
|
||||
|
||||
.. rest_parameters:: parameters.yaml
|
||||
|
||||
- driver_name: driver_ident
|
||||
- method_name: method_name
|
||||
|
||||
All other parameters should be passed in the BODY. Parameter list varies by
|
||||
method_name.
|
||||
|
||||
Response
|
||||
--------
|
||||
|
||||
Varies.
|
||||
@ -4,101 +4,28 @@
|
||||
Drivers (drivers)
|
||||
=================
|
||||
|
||||
A driver is a Python object containing all the logic to manage the bare metal
|
||||
nodes enrolled within Ironic. A driver may be loaded within one or more
|
||||
``ironic-conductor`` services. Each driver contains a pre-determined set of
|
||||
instantiated interfaces. Each type of interface (eg, ``power`` or ``boot``)
|
||||
performs a specific hardware function.
|
||||
|
||||
The REST API exposes the list of drivers and which ``ironic-conductor``
|
||||
processes have loaded that driver via the Driver resource (``/v1/drivers``
|
||||
endpoint). This can be useful for operators to validate their configuration in
|
||||
a heterogeneous hardware environment. Each ``ironic-conductor`` process may
|
||||
load one or more drivers, and does not necessarily need to load the same
|
||||
drivers as another ``ironic-conductor``.
|
||||
|
||||
The REST API also exposes details about each driver, such as what properties
|
||||
must be supplied to a node's ``driver_info`` for that driver to manage
|
||||
hardware.
|
||||
|
||||
Show driver details
|
||||
===================
|
||||
|
||||
.. rest_method:: GET /v1/drivers/{driver_name}
|
||||
|
||||
Shows details for a driver.
|
||||
|
||||
|
||||
Normal response codes: 200
|
||||
Error response codes:413,405,404,403,401,400,503,
|
||||
|
||||
|
||||
Request
|
||||
-------
|
||||
|
||||
.. rest_parameters:: parameters.yaml
|
||||
|
||||
- driver_name: driver_name
|
||||
|
||||
|
||||
Response Parameters
|
||||
-------------------
|
||||
|
||||
.. rest_parameters:: parameters.yaml
|
||||
|
||||
- hosts: hosts
|
||||
- name: name
|
||||
|
||||
|
||||
|
||||
Response Example
|
||||
----------------
|
||||
|
||||
.. literalinclude:: samples/driver-get-response.json
|
||||
:language: javascript
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
Show driver properties
|
||||
======================
|
||||
|
||||
.. rest_method:: GET /v1/drivers/{driver_name}/properties
|
||||
|
||||
Shows properties for a driver.
|
||||
|
||||
|
||||
Normal response codes: 200
|
||||
Error response codes:413,405,404,403,401,400,503,
|
||||
|
||||
|
||||
Request
|
||||
-------
|
||||
|
||||
.. rest_parameters:: parameters.yaml
|
||||
|
||||
- driver_name: driver_name
|
||||
|
||||
|
||||
Response Parameters
|
||||
-------------------
|
||||
|
||||
.. rest_parameters:: parameters.yaml
|
||||
|
||||
- hosts: hosts
|
||||
- name: name
|
||||
- links: links
|
||||
- properties: properties
|
||||
|
||||
|
||||
|
||||
Response Example
|
||||
----------------
|
||||
|
||||
.. literalinclude:: samples/driver-get-response.json
|
||||
:language: javascript
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
Lastly, some drivers may expose methods through a ``driver_vendor_passthru``
|
||||
endpoint, allowing one to interact with the driver directly (i.e., without
|
||||
knowing a specific node identifier). For example, this is used by the ironic
|
||||
python agent ramdisk to get the UUID of the node being deployed/cleaned by
|
||||
using MAC addresses of the node's network interfaces the agent has discovered.
|
||||
|
||||
|
||||
List drivers
|
||||
@ -108,26 +35,24 @@ List drivers
|
||||
|
||||
Lists all drivers.
|
||||
|
||||
|
||||
Normal response codes: 200
|
||||
Error response codes:413,405,404,403,401,400,503,
|
||||
|
||||
|
||||
Request
|
||||
-------
|
||||
|
||||
|
||||
|
||||
Response Parameters
|
||||
-------------------
|
||||
|
||||
The response BODY contains a single key, "drivers", whose value is a list of
|
||||
drivers supported by this Ironic service.
|
||||
|
||||
.. rest_parameters:: parameters.yaml
|
||||
|
||||
- drivers: drivers
|
||||
- name: driver_name
|
||||
- hosts: hosts
|
||||
- name: name
|
||||
|
||||
|
||||
- links: links
|
||||
- properties: driver_property_links
|
||||
|
||||
Response Example
|
||||
----------------
|
||||
@ -136,13 +61,69 @@ Response Example
|
||||
:language: javascript
|
||||
|
||||
|
||||
Show driver details
|
||||
===================
|
||||
|
||||
.. rest_method:: GET /v1/drivers/{driver_name}
|
||||
|
||||
Shows details for a driver.
|
||||
|
||||
Normal response codes: 200
|
||||
|
||||
Request
|
||||
-------
|
||||
|
||||
.. rest_parameters:: parameters.yaml
|
||||
|
||||
- driver_name: driver_ident
|
||||
|
||||
Response Parameters
|
||||
-------------------
|
||||
|
||||
.. rest_parameters:: parameters.yaml
|
||||
|
||||
- name: driver_name
|
||||
- hosts: hosts
|
||||
- links: links
|
||||
- properties: driver_property_links
|
||||
|
||||
Response Example
|
||||
----------------
|
||||
|
||||
.. literalinclude:: samples/driver-get-response.json
|
||||
:language: javascript
|
||||
|
||||
|
||||
Show driver properties
|
||||
======================
|
||||
|
||||
.. rest_method:: GET /v1/drivers/{driver_name}/properties
|
||||
|
||||
Shows the required and optional parameters that ``driver_name`` expects to be
|
||||
supplied in the ``driver_info`` field for every Node it manages.
|
||||
|
||||
To check if all required parameters have been supplied to a Node, you should
|
||||
query the ``/v1/nodes/{node_ident}/validate`` endpoint.
|
||||
|
||||
Normal response codes: 200
|
||||
|
||||
Request
|
||||
-------
|
||||
|
||||
.. rest_parameters:: parameters.yaml
|
||||
|
||||
- driver_name: driver_ident
|
||||
|
||||
Response Example
|
||||
----------------
|
||||
|
||||
The response BODY is a dictionary, but the keys are unique to each driver.
|
||||
The structure of the response is ``property`` : ``description``.
|
||||
|
||||
The following example is returned from the ``agent_ipmitool`` driver.
|
||||
|
||||
.. literalinclude:: samples/driver-property-response.json
|
||||
:language: javascript
|
||||
|
||||
|
||||
Show driver logical disk properties
|
||||
@ -150,93 +131,28 @@ Show driver logical disk properties
|
||||
|
||||
.. rest_method:: GET /v1/drivers/{driver_name}/raid/logical_disk_properties
|
||||
|
||||
Shows logical disk properties for a driver.
|
||||
Show the required and optional parameters that ``driver_name`` expects to be
|
||||
supplied in the node's ``raid_config`` field, if a RAID configuration change is
|
||||
requested.
|
||||
|
||||
This resource was added in API microversion 1.12.
|
||||
|
||||
Normal response codes: 200
|
||||
Error response codes:413,405,404,403,401,400,503,
|
||||
|
||||
|
||||
Request
|
||||
-------
|
||||
|
||||
.. rest_parameters:: parameters.yaml
|
||||
|
||||
- driver_name: driver_name
|
||||
|
||||
|
||||
Response Parameters
|
||||
-------------------
|
||||
|
||||
.. rest_parameters:: parameters.yaml
|
||||
|
||||
- hosts: hosts
|
||||
- name: name
|
||||
- links: links
|
||||
- properties: properties
|
||||
|
||||
|
||||
- driver_name: driver_ident
|
||||
|
||||
Response Example
|
||||
----------------
|
||||
|
||||
.. literalinclude:: samples/driver-get-response.json
|
||||
:language: javascript
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
Show driver vendor methods
|
||||
==========================
|
||||
|
||||
.. rest_method:: GET /v1/drivers/{driver_name}/vendor_passthru/methods
|
||||
|
||||
Shows vendor methods for a driver.
|
||||
|
||||
|
||||
Normal response codes: 200
|
||||
Error response codes:413,405,404,403,401,400,503,
|
||||
|
||||
|
||||
Request
|
||||
-------
|
||||
|
||||
.. rest_parameters:: parameters.yaml
|
||||
|
||||
- driver_name: driver_name
|
||||
|
||||
|
||||
Response Parameters
|
||||
-------------------
|
||||
|
||||
.. rest_parameters:: parameters.yaml
|
||||
|
||||
- hosts: hosts
|
||||
- name: name
|
||||
- links: links
|
||||
- properties: properties
|
||||
|
||||
|
||||
|
||||
Response Example
|
||||
----------------
|
||||
|
||||
.. literalinclude:: samples/driver-get-response.json
|
||||
:language: javascript
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
The response BODY is a dictionary, but the keys are unique to each driver.
|
||||
The structure of the response is ``property`` : ``description``.
|
||||
|
||||
The following example is returned from the ``agent_ipmitool`` driver.
|
||||
|
||||
.. literalinclude:: samples/driver-logical-disk-properties-response.json
|
||||
:language: javascript
|
||||
@ -21,5 +21,6 @@ is presented in this document. Significant changes may be noted inline.
|
||||
.. include:: baremetal-api-v1-ports.inc
|
||||
.. include:: baremetal-api-v1-nodes-ports.inc
|
||||
.. include:: baremetal-api-v1-drivers.inc
|
||||
.. include:: baremetal-api-v1-driver-passthru.inc
|
||||
.. include:: baremetal-api-v1-chassis.inc
|
||||
|
||||
|
||||
@ -274,9 +274,15 @@ driver_name:
|
||||
in: body
|
||||
required: true
|
||||
type: string
|
||||
driver_property_links:
|
||||
description: |
|
||||
A list of links to driver properties. Added in API microversion 1.14.
|
||||
in: body
|
||||
required: true
|
||||
type: array
|
||||
drivers:
|
||||
description: |
|
||||
A list of ``drivers`` objects.
|
||||
A list of driver objects.
|
||||
in: body
|
||||
required: true
|
||||
type: array
|
||||
@ -406,6 +412,32 @@ nodes:
|
||||
in: body
|
||||
required: true
|
||||
type: array
|
||||
passthru_async:
|
||||
description: |
|
||||
If True the passthru function is invoked asynchronously; if False,
|
||||
synchronously.
|
||||
in: body
|
||||
required: true
|
||||
type: boolean
|
||||
passthru_attach:
|
||||
description: |
|
||||
True if the return value will be attached to the response object, and False
|
||||
if the return value will be returned in the response body.
|
||||
in: body
|
||||
required: true
|
||||
type: boolean
|
||||
passthru_description:
|
||||
description: |
|
||||
A description of what the method does, including any method parameters.
|
||||
in: body
|
||||
required: true
|
||||
type: string
|
||||
passthru_http_methods:
|
||||
description: |
|
||||
A list of HTTP methods supported by the vendor function.
|
||||
in: body
|
||||
required: true
|
||||
type: array
|
||||
persistent:
|
||||
description: |
|
||||
Whether the boot device should be set only for the next reboot, or
|
||||
|
||||
@ -1,30 +1,26 @@
|
||||
{
|
||||
"drivers": [
|
||||
{
|
||||
"properties": [
|
||||
{
|
||||
"href": "http://127.0.0.1:6385/v1/drivers/agent_ipmitool/properties",
|
||||
"rel": "self"
|
||||
},
|
||||
{
|
||||
"href": "http://127.0.0.1:6385/drivers/agent_ipmitool/properties",
|
||||
"rel": "bookmark"
|
||||
}
|
||||
],
|
||||
"hosts": [
|
||||
"localhost"
|
||||
],
|
||||
"name": "agent_ipmitool",
|
||||
"links": [
|
||||
{
|
||||
"rel": "self",
|
||||
"href": "http://127.0.0.1:6385/v1/drivers/agent_ipmitool"
|
||||
},
|
||||
{
|
||||
"rel": "bookmark",
|
||||
"href": "http://127.0.0.1:6385/drivers/agent_ipmitool"
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
"links" : [
|
||||
{
|
||||
"rel" : "self",
|
||||
"href" : "http://127.0.0.1:6385/v1/drivers/agent_ipmitool"
|
||||
},
|
||||
{
|
||||
"href" : "http://127.0.0.1:6385/drivers/agent_ipmitool",
|
||||
"rel" : "bookmark"
|
||||
}
|
||||
],
|
||||
"name" : "agent_ipmitool",
|
||||
"properties" : [
|
||||
{
|
||||
"rel" : "self",
|
||||
"href" : "http://127.0.0.1:6385/v1/drivers/agent_ipmitool/properties"
|
||||
},
|
||||
{
|
||||
"rel" : "bookmark",
|
||||
"href" : "http://127.0.0.1:6385/drivers/agent_ipmitool/properties"
|
||||
}
|
||||
],
|
||||
"hosts" : [
|
||||
"localhost"
|
||||
]
|
||||
}
|
||||
|
||||
@ -0,0 +1,12 @@
|
||||
{
|
||||
"share_physical_disks" : "Specifies whether other logical disks can share physical disks with this logical disk. By default, this is False. Optional.",
|
||||
"controller" : "Controller to use for this logical disk. If not specified, the driver will choose a suitable RAID controller on the bare metal node. Optional.",
|
||||
"disk_type" : "The type of disk preferred. Valid values are 'hdd' and 'ssd'. If this is not specified, disk type will not be a selection criterion for choosing backing physical disks. Optional.",
|
||||
"physical_disks" : "The physical disks to use for this logical disk. If not specified, the driver will choose suitable physical disks to use. Optional.",
|
||||
"volume_name" : "Name of the volume to be created. If this is not specified, it will be auto-generated. Optional.",
|
||||
"number_of_physical_disks" : "Number of physical disks to use for this logical disk. By default, the driver uses the minimum number of disks required for that RAID level. Optional.",
|
||||
"raid_level" : "RAID level for the logical disk. Valid values are '0', '1', '2', '5', '6', '1+0', '5+0' and '6+0'. Required.",
|
||||
"size_gb" : "Size in GiB (Integer) for the logical disk. Use 'MAX' as size_gb if this logical disk is supposed to use the rest of the space available. Required.",
|
||||
"interface_type" : "The interface type of disk. Valid values are 'sata', 'scsi' and 'sas'. If this is not specified, interface type will not be a selection criterion for choosing backing physical disks. Optional.",
|
||||
"is_root_volume" : "Specifies whether this disk is a root volume. By default, this is False. Optional."
|
||||
}
|
||||
10
api-ref/source/samples/driver-passthru-methods-response.json
Normal file
10
api-ref/source/samples/driver-passthru-methods-response.json
Normal file
@ -0,0 +1,10 @@
|
||||
{
|
||||
"lookup" : {
|
||||
"http_methods" : [
|
||||
"POST"
|
||||
],
|
||||
"attach" : false,
|
||||
"description" : "",
|
||||
"async" : false
|
||||
}
|
||||
}
|
||||
22
api-ref/source/samples/driver-property-response.json
Normal file
22
api-ref/source/samples/driver-property-response.json
Normal file
@ -0,0 +1,22 @@
|
||||
{
|
||||
"ipmi_force_boot_device" : "Whether Ironic should specify the boot device to the BMC each time the server is turned on, eg. because the BMC is not capable of remembering the selected boot device across power cycles; default value is False. Optional.",
|
||||
"deploy_forces_oob_reboot" : "Whether Ironic should force a reboot of the Node via the out-of-band channel after deployment is complete. Provides compatiblity with older deploy ramdisks. Defaults to False. Optional.",
|
||||
"ipmi_target_address" : "destination address for bridged request. Required only if ipmi_bridging is set to \"single\" or \"dual\".",
|
||||
"image_https_proxy" : "URL of a proxy server for HTTPS connections. Optional.",
|
||||
"ipmi_password" : "password. Optional.",
|
||||
"ipmi_bridging" : "bridging_type; default is \"no\". One of \"single\", \"dual\", \"no\". Optional.",
|
||||
"deploy_kernel" : "UUID (from Glance) of the deployment kernel. Required.",
|
||||
"ipmi_address" : "IP address or hostname of the node. Required.",
|
||||
"image_no_proxy" : "A comma-separated list of host names, IP addresses and domain names (with optional :port) that will be excluded from proxying. To denote a doman name, use a dot to prefix the domain name. This value will be ignored if ``image_http_proxy`` and ``image_https_proxy`` are not specified. Optional.",
|
||||
"ipmi_local_address" : "local IPMB address for bridged requests. Used only if ipmi_bridging is set to \"single\" or \"dual\". Optional.",
|
||||
"ipmi_transit_channel" : "transit channel for bridged request. Required only if ipmi_bridging is set to \"dual\".",
|
||||
"ipmi_transit_address" : "transit address for bridged request. Required only if ipmi_bridging is set to \"dual\".",
|
||||
"ipmi_username" : "username; default is NULL user. Optional.",
|
||||
"deploy_ramdisk" : "UUID (from Glance) of the ramdisk that is mounted at boot time. Required.",
|
||||
"ipmi_target_channel" : "destination channel for bridged request. Required only if ipmi_bridging is set to \"single\" or \"dual\".",
|
||||
"ipmi_terminal_port" : "node's UDP port to connect to. Only required for console access.",
|
||||
"image_http_proxy" : "URL of a proxy server for HTTP connections. Optional.",
|
||||
"ipmi_priv_level" : "privilege level; default is ADMINISTRATOR. One of ADMINISTRATOR, CALLBACK, OPERATOR, USER. Optional.",
|
||||
"ipmi_protocol_version" : "the version of the IPMI protocol; default is \"2.0\". One of \"1.5\", \"2.0\". Optional.",
|
||||
"ipmi_port" : "remote IPMI RMCP port. Optional."
|
||||
}
|
||||
@ -1,10 +1,30 @@
|
||||
{
|
||||
"drivers": [
|
||||
{
|
||||
"hosts": [
|
||||
"fake-host"
|
||||
],
|
||||
"name": "sample-driver"
|
||||
}
|
||||
]
|
||||
"drivers" : [
|
||||
{
|
||||
"hosts" : [
|
||||
"localhost"
|
||||
],
|
||||
"links" : [
|
||||
{
|
||||
"href" : "http://127.0.0.1:6385/v1/drivers/agent_ipmitool",
|
||||
"rel" : "self"
|
||||
},
|
||||
{
|
||||
"href" : "http://127.0.0.1:6385/drivers/agent_ipmitool",
|
||||
"rel" : "bookmark"
|
||||
}
|
||||
],
|
||||
"name" : "agent_ipmitool",
|
||||
"properties" : [
|
||||
{
|
||||
"rel" : "self",
|
||||
"href" : "http://127.0.0.1:6385/v1/drivers/agent_ipmitool/properties"
|
||||
},
|
||||
{
|
||||
"href" : "http://127.0.0.1:6385/drivers/agent_ipmitool/properties",
|
||||
"rel" : "bookmark"
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
|
||||
Loading…
Reference in New Issue
Block a user