openstack/ironic
Code Issues Proposed changes

Updated API Spec for new Drivers

Browse Source 
Updates the API specification to match the new
driver definitions.

Renamed management configuration to driver
configuration, and removed control and deployment
sections.

Change-Id: I561d72e935b12c2810c9a0835fe36028e88a86d9
This commit is contained in:
Martyn Taylor 2013-06-07 12:48:09 +01:00
parent 8375fb9547
commit 7826d1e129
1 changed files with 90 additions and 206 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

218
doc/source/dev/api-spec-v1.rst
View File

@ -97,8 +97,8 @@ of the resource itself.
For example, if a client wanted to change the deployment configuration for a For example, if a client wanted to change the deployment configuration for a
specific node, the client could update the deployment part of the node's specific node, the client could update the deployment part of the node's
ManagementConfiguration_ with the new parameters directly at: DriverConfiguration_ with the new parameters directly at:
/nodes/1/management_configuration/deploy /nodes/1/driver_configuration/deploy
Security Security
--------- ---------
@ -133,7 +133,7 @@ Top Level Resources
Sub Resources Sub Resources
--------------- ---------------
- ManagementConfiguration_ - DriverConfiguration_
- MetaData_ - MetaData_
- State_ - State_
@ -348,8 +348,8 @@ chassis
The chassis this node belongs to see: Chassis_ The chassis this node belongs to see: Chassis_
ports ports
A list of available ports for this node see: Port_ A list of available ports for this node see: Port_
management_configuration driver_configuration
This node's management configuration see: ManagementConfiguration_ This node's driver configuration see: DriverConfiguration_
Example Example
^^^^^^^^ ^^^^^^^^
@ -412,9 +412,8 @@ JSON structure of a node::
} }
] ]
}, },
"management_configuration": { "driver_configuration": {
"type": "management_configuration", "type": "driver_configuration",
"control": {
"driver": { "driver": {
"links": [{ "links": [{
"rel": "self", "rel": "self",
@ -428,42 +427,19 @@ JSON structure of a node::
"parameters": { "parameters": {
"ipmi_username": "admin", "ipmi_username": "admin",
"ipmi_password": "password", "ipmi_password": "password",
"links": [{
"rel": "self",
"href": "http://localhost:8080/v1.0/nodes/1/management_configuration/control/parameters"
}, {
"rel": "bookmark",
"href": "http://localhost:8080/nodes/1/management_configuration/control/parameters"
}
]
}
},
"deployment": {
"driver": {
"links": [{
"rel": "self",
"href": "http://localhost:8080/v1.0/drivers/1"
}, {
"rel": "bookmark",
"href": "http://localhost:8080/drivers/1"
}
]
},
"parameters": {
"image_source": "glance://image-uuid", "image_source": "glance://image-uuid",
"deploy_image_source": "glance://deploy-image-uuid", "deploy_image_source": "glance://deploy-image-uuid",
"links": [{ "links": [{
"rel": "self", "rel": "self",
"href": "http://localhost:8080/v1.0/nodes/1/management_configuration/control/parameters" "href": "http://localhost:8080/v1.0/nodes/1/driver_configuration/parameters"
}, { }, {
"rel": "bookmark", "rel": "bookmark",
"href": "http://localhost:8080/nodes/1/management_configuration/control/parameters" "href": "http://localhost:8080/nodes/1/driver_configuration/control/parameters"
} }
] ]
} }
} }
} }
}
Chassis Chassis
-------- --------
@ -625,25 +601,16 @@ required_fields
optional_fields optional_fields
An array containing optional fields for this driver An array containing optional fields for this driver
DriverFunctions
^^^^^^^^^^^^^^^^
Drivers can have one of two types of functionality, control or deployment. You
must enter a driver or the correct function into the relevant pieces of the
management configuration resource. For example, you must enter a driver with
function "control" into the control piece of the management configuration.
Example Driver Example Driver
^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^
JSON structure of a driver:: JSON structure of a driver::
{ {
"id": "fake-driver-id", "id": "ipmi_pxe",
"type": "driver", "type": "driver",
"name": "ipmi", "name": "ipmi_pxe",
"function": "control", "description": "Uses pxe for booting and impi for power management",
"description": "power on/off using ipmi",
"meta-data": { "meta-data": {
"foo": "bar", "foo": "bar",
"links": [{ "links": [{
@ -658,7 +625,9 @@ JSON structure of a driver::
"required_fields": [ "required_fields": [
"ipmi_address", "ipmi_address",
"ipmi_password", "ipmi_password",
"ipmi_username" "ipmi_username",
"image_source",
"deploy_image_source",
], ],
"optional_fields": [ "optional_fields": [
"ipmi_terminal_port", "ipmi_terminal_port",
@ -742,182 +711,97 @@ JSON structure of an image::
] ]
} }
ManagementConfiguration DriverConfiguration
------------------------ ------------------------
The Management Configuration is a sub resource (see: SubResource_) that The Configuration is a sub resource (see: SubResource_) that
contains information about how to manage a particular node. contains information about how to manage a particular node.
This resource makes up part of the node resource description and can only be This resource makes up part of the node resource description and can only be
accessed from within a node URL structure. For example: accessed from within a node URL structure. For example:
/nodes/1/management_configuration. The ManagementConfiguration essentially /nodes/1/driver_configuration. The DriverConfiguration essentially
defines the control and deployment driver setup. defines the driver setup.
An empty management configuration resource will be created upon node creation. An empty driver configuration resource will be created upon node creation.
Therefore only PUT and GET are defined on ManagementConfiguration resources. Therefore only PUT and GET are defined on DriverConfiguration resources.
Sections of the ManagementConfiguration also support GET and PUT operations. The Parameters resource is not introspected by Ironic; they are passed directly
Such as the Control, Deployment, and Parameters sections. to the respective drivers. Each driver defines a set of Required and Optional
fields, which are validated when the resource is set to a non-empty value.
The Control Parameters and Deployment Parameters resources are not introspected Supplying partial or invalid data will result in an error and no data will be
by Ironic; they are passed directly to the respective drivers. Each driver saved. PUT an empty resource, such as '{}' to /nodes/1/driver_configuration
defines a set of Required and Optional fields, which are validated when the to erase the existing data.
resource is set to a non-empty value. Supplying partial or invalid data will
result in an error and no data will be saved. PUT an empty resource to erase
the existing data. Changing the Control or Deployment section of the
ManagementConfiguration will erase any existing Parameter section for that
resource.
Updating both the driver and driver parameters at once is allowed.
For example::
PUT to /nodes/1/management_configuration/control
{ "id": "ipmi", "parameters": { "ipmi_username": "foo", ...} }
Management Configuration Usage: driver configuration Usage:
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
======= ================================== ========== ======= ================================== ================================
Verb Path Response Verb Path Response
======= ================================== ========== ======= ================================== ================================
GET /nodes/1/management_configuration Retrieve a node's management GET /nodes/1/driver_configuration Retrieve a node's driver
configuration configuration
PUT /nodes/1/management_configuration Update a node's management PUT /nodes/1/driver_configuration Update a node's driver
configuration configuration
======= ================================== ========== ======= ================================== ================================
Management Configuration / Control Usage: driver configuration / Parameters Usage:
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
======= ========================================== ==========
Verb Path Response
======= ========================================== ==========
GET /nodes/1/management_configuration/control Retrieve a node's
management control
configuration
PUT /nodes/1/management_configuration/control Update a node's
management control
configuration
======= ========================================== ==========
Management Configuration / Deployment Usage:
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
====== ============================================ ==========
Verb Path Response
====== ============================================ ==========
GET /nodes/1/management_configuration/deployment Retrieve a node's
management deployment
configuration
PUT /nodes/1/management_configuration/deployment Update a node's
management deployment
configuration
====== ============================================ ==========
Management Configuration / Control / Parameters Usage:
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
====== ===================================================== ========== ====== ============================================= ==================
Verb Path Response Verb Path Response
====== ===================================================== ========== ====== ============================================= ==================
GET /nodes/1/management_configuration/control/parameters Retrieve a node's GET /nodes/1/driver_configuration/parameters Retrieve a node's
management control driver parameters
paramters PUT /nodes/1/driver_configuration/parameters Update a node's
PUT /nodes/1/management_configuration/control/parameters Update a node's driver parameters
management control ====== ============================================= ==================
paramters
====== ===================================================== ==========
Management Configuration / deployment / parameters Usage:
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
====== ======================================================== ==========
Verb Path Response
====== ======================================================== ==========
GET /nodes/1/management_configuration/deployment/parameters Retrieve a node's
management deployment
paramters
PUT /nodes/1/management_configuration/deployment/parameters Update a node's
management deployment
paramters
====== ======================================================== ==========
Fields Fields
^^^^^^^ ^^^^^^^
type type
The type of this resource, i.e. management_configuration, deployment, The type of this resource, i.e. driver_configuration, deployment,
control, parameters control, parameters
control
The control sub resource for specifying node control driver and parameters
deployment
The deployment sub resource for specifying node deployment driver and
paramters
driver driver
Link to the driver resource for a deployment or control sub resource Link to the driver resource for a deployment or control sub resource
paramters paramters
The parameters sub resource responsible for setting the driver paramters The parameters sub resource responsible for setting the driver paramters.
for a control or deployment. The required and optional parameters are The required and optional parameters are specified on the driver resource.
specified on the driver resource. see: Driver_ see: Driver_
Example Example
^^^^^^^^ ^^^^^^^^
JSON structure of a management_configuration:: JSON structure of a driver_configuration::
{ {
"type": "management_configuration", "type": "driver_configuration",
"control": {
"driver": { "driver": {
"links": [{ "links": [{
"rel": "self", "rel": "self",
"href": "http://localhost:8080/v1/drivers/ipmi" "href": "http://localhost:8080/v1/drivers/1"
}, { }, {
"rel": "bookmark", "rel": "bookmark",
"href": "http://localhost:8080/drivers/ipmi" "href": "http://localhost:8080/drivers/1"
} }
] ]
}, },
"parameters": { "parameters": {
"ipmi_username": "admin", "ipmi_username": "admin",
"ipmi_password": "password", "ipmi_password": "password",
"links": [{
"rel": "self",
"href": "http://localhost:8080/v1.0/nodes/1/management_configuration/control/parameters"
}, {
"rel": "bookmark",
"href": "http://localhost:8080/nodes/1/management_configuration/control/parameters"
}
]
}
},
"deployment": {
"driver": {
"links": [{
"rel": "self",
"href": "http://localhost:8080/v1.0/drivers/pxe"
}, {
"rel": "bookmark",
"href": "http://localhost:8080/drivers/pxe"
}
]
},
"parameters": {
"image_source": "glance://image-uuid", "image_source": "glance://image-uuid",
"deploy_image_source": "glance://deploy-image-uuid", "deploy_image_source": "glance://deploy-image-uuid",
"links": [{ "links": [{
"rel": "self", "rel": "self",
"href": "http://localhost:8080/version/1/nodes/1/management_configuration/control/parameters" "href": "http://localhost:8080/v1.0/nodes/1/driver_configuration/parameters"
}, { }, {
"rel": "bookmark", "rel": "bookmark",
"href": "http://localhost:8080/nodes/1/management_configuration/control/parameters" "href": "http://localhost:8080/nodes/1/driver_configuration/control/parameters"
} }
] ]
} }
} }
}
State State
------ ------