diff --git a/api-ref/source/baremetal-api-v1-chassis.inc b/api-ref/source/baremetal-api-v1-chassis.inc index 46a1b78345..54b4ddbc16 100644 --- a/api-ref/source/baremetal-api-v1-chassis.inc +++ b/api-ref/source/baremetal-api-v1-chassis.inc @@ -4,7 +4,13 @@ Chassis (chassis) ================= -Chassis operations. +The Chassis resource type was originally conceived as a means to group Node +resources. Support for this continues to exist in the REST API, however, it is +very minimal. The Chassis object does not provide any functionality today +aside from a means to list a group of Nodes. + +Use of this resource is discouraged, and may be deprecated and removed in a +future release. List chassis with details @@ -14,11 +20,9 @@ List chassis with details Lists all chassis with details. - Normal response codes: 200 Error response codes:413,405,404,403,401,400,503, - Request ------- @@ -29,7 +33,6 @@ Request - sort_dir: sort_dir - sort_key: sort_key - Response Parameters ------------------- @@ -40,8 +43,6 @@ Response Parameters - description: description - extra: extra - - Response Example ---------------- @@ -49,15 +50,6 @@ Response Example :language: javascript - - - - - - - - - Show chassis details ==================== @@ -65,11 +57,9 @@ Show chassis details Shows details for a chassis. - Normal response codes: 200 Error response codes:413,405,404,403,401,400,503, - Request ------- @@ -77,7 +67,6 @@ Request - fields: fields - Response Parameters ------------------- @@ -88,24 +77,12 @@ Response Parameters - description: description - extra: extra - - Response Example ---------------- .. literalinclude:: samples/chassis-show-response.json :language: javascript - - - - - - - - - - Update chassis ============== @@ -113,11 +90,9 @@ Update chassis Updates a chassis. - Normal response codes: 200 Error response codes:413,415,405,404,403,401,400,503,409, - Request ------- @@ -133,8 +108,6 @@ Request Example .. literalinclude:: samples/chassis-update-request.json :language: javascript - - Response Parameters ------------------- @@ -149,8 +122,6 @@ Response Parameters - nodes: nodes - uuid: uuid - - Response Example ---------------- @@ -158,17 +129,6 @@ Response Example :language: javascript - - - - - - - - - - - Delete chassis ============== @@ -178,25 +138,9 @@ Deletes a chassis. Error response codes:204,413,415,405,404,403,401,400,503,409, - Request ------- - - - - - - - - - - - - - - - Create chassis ============== @@ -206,7 +150,6 @@ Creates a chassis. Error response codes:201,413,415,405,404,403,401,400,503,409, - Request ------- @@ -222,8 +165,6 @@ Request Example .. literalinclude:: samples/chassis-create-request.json :language: javascript - - Response Parameters ------------------- @@ -237,19 +178,6 @@ Response Parameters - nodes: nodes - uuid: uuid - - - - - - - - - - - - - List chassis ============ @@ -257,11 +185,9 @@ List chassis Lists all chassis. - Normal response codes: 200 Error response codes:413,405,404,403,401,400,503, - Request ------- @@ -273,7 +199,6 @@ Request - sort_key: sort_key - fields: fields - Response Parameters ------------------- @@ -284,20 +209,8 @@ Response Parameters - description: description - extra: extra - - Response Example ---------------- .. literalinclude:: samples/chassis-list-response.json :language: javascript - - - - - - - - - - diff --git a/api-ref/source/baremetal-api-v1-node-management.inc b/api-ref/source/baremetal-api-v1-node-management.inc new file mode 100644 index 0000000000..289ab743a7 --- /dev/null +++ b/api-ref/source/baremetal-api-v1-node-management.inc @@ -0,0 +1,393 @@ +.. -*- rst -*- + +======================= +Node Management (nodes) +======================= + +Nodes can be managed through several sub-resources. + +Maintenance mode can be set by the operator, with an optional "reason" stored +by Ironic. + +The supplied ``driver_info`` can be validated to ensure that the selected +``driver`` has all the information it requires to manage the Node. + +A Node can be rebooted, turned on, or turned off by requesting a change to its +power state. This is handled asynchronously and tracked in the ``target_power_state`` +field after the request is received. + +A Node's boot device can be changed, and the set of supported boot devices +can be queried. + +A request to change a Node's provision state is also tracked asynchronously; +the ``target_provision_state`` represents the requested state. A Node +may transition through several discrete ``provision_state`` steps before arriving +at the requested state. This can vary between drivers and based on configuration. + +For example, a Node in the ``available`` state can have an instance deployed to it +by requesting the provision state of ``active``. During this transition, the Node's +``provision_state`` will temporarily be set to ``deploying``, and depending on the driver, +it may also be ``wait call-back``. When the transitions are complete, ``target_provision_state`` +will be set to ``None`` and ``provision_state`` will be set to ``active```. +To destroy the instance, request the provision state of ``delete``. During this +transition, the Node may or may not go through a ``cleaning`` state, +depending on the service configuration. + + +Validate Node +=============== + +.. rest_method:: GET /v1/nodes/{node_ident}/validate + +Request that Ironic validate whether the Node's ``driver`` has enough information +to manage the Node. This polls each ``interface`` on the driver, and returns +the status of that ``interface`` as an element in the response. Note that each +``driver`` may require different information to be supplied, and not all drivers +support all interfaces. + +Normal response codes: 200 + +.. TODO: add error codes + +Request +------- + +.. rest_parameters:: parameters.yaml + + - node_ident: node_ident + +Response +-------- + +Each element in the response will contain a "result" variable, which will have +a value of "true" or "false", indicating that the interface either has or does +not have sufficient information to function. A value of ``null`` indicates that +the Node's driver does not support that interface. + +.. rest_parameters:: parameters.yaml + + - power: v_power + - boot: v_boot + - deploy: v_deploy + - console: v_console + - management: v_management + - inspect: v_inspect + - raid: v_raid + +**Example node validation response:** + +.. literalinclude:: samples/node-validate-response.json + :language: javascript + + +Set Maintenance Flag +============================= + +.. rest_method:: PUT /v1/nodes/{node_ident}/maintenance + +Request that Ironic set the maintenance flag on the Node. This will disable +certain automatic actions that the Node's driver may take, and remove +the Node from Nova's available resource pool. + +Normal response code: 202 + +.. TODO: Add link to user / operator documentation on the Maintenance flag + +Request +------- + +.. rest_parameters:: parameters.yaml + + - node_ident: node_ident + - reason: reason + +**Example request: mark a node for maintenance:** + +.. literalinclude:: samples/node-maintenance-request.json + +Clear Maintenance Flag +============================== + +.. rest_method:: DELETE /v1/nodes/{node_ident}/maintenance + +The maintenance flag is unset by sending a DELETE request to this endpoint. +If the request is accepted, Ironic will also clear the ``maintenance_reason`` +field. + +Normal response code: 202 + +.. TODO: Add link to user / operator documentation on the Maintenance flag + +Request +------- + +.. rest_parameters:: parameters.yaml + + - node_ident: node_ident + +Set Boot Device +=============== + +.. rest_method:: PUT /v1/nodes/{node_ident}/management/boot_device + +Set the boot device for the given Node, and set it persistently or for one-time +boot. The exact behaviour of this depends on the hardware driver. + +.. note:: In some drivers, eg. the ``*_ipmitool`` family, this method initiates a synchronous call + to the hardware management device (BMC). It should be used with caution! This + is `a known bug `_. + +.. note:: Some drivers do not support one-time boot, and always set the boot device + persistently. + +Normal response code: 204 + +.. TODO: add error codes + +Request +------- + +.. rest_parameters:: parameters.yaml + + - node_ident: node_ident + - boot_device: boot_device + - persistent: persistent + +**Example JSON request body to set boot device:** + +.. literalinclude:: samples/node-get-or-set-boot-device.json + + +Get Boot Device +=============== + +.. rest_method:: GET /v1/nodes/{node_ident}/management/boot_device + +Get the current boot device for the given Node. + +.. note:: In some drivers, eg. the ``*_ipmitool`` family, this method initiates a synchronous call + to the hardware management device (BMC). It should be used with caution! This + is `a known bug `_. + +Normal response code: 200 + +.. TODO: add error codes + +Request +------- + +.. rest_parameters:: parameters.yaml + + - node_ident: node_ident + +Response +-------- + +.. rest_parameters:: parameters.yaml + + - boot_device: boot_device + - persistent: persistent + +**Example JSON response to get boot device:** + +.. literalinclude:: samples/node-get-or-set-boot-device.json + + +Get Supported Boot Devices +=========================== + +.. rest_method:: GET /v1/nodes/{node_ident}/management/boot_device/supported + +Retrieve the acceptable set of supported boot devices for a specific Node. + +Normal response code: 200 + +.. TODO: add error codes + +Request +------- + +.. rest_parameters:: parameters.yaml + + - node_ident: node_ident + +Response +-------- + +.. rest_parameters:: parameters.yaml + + - supported_boot_devices: supported_boot_devices + +**Example response listing supported boot devices:** + +.. literalinclude:: samples/node-get-supported-boot-devices-response.json + + +Node State Summary +================== + +.. rest_method:: GET /v1/nodes/{node_ident}/states + +Get a summary of the Node's current power, provision, raid, and console status. + +Normal response code: 200 + +Request +------- + +.. rest_parameters:: parameters.yaml + + - node_ident: node_ident + +Response +-------- + +.. rest_parameters:: parameters.yaml + + - power_state: power_state + - target_power_state: target_power_state + - provision_state: provision_state + - target_provision_state: target_provision_state + - provision_updated_at: provision_updated_at + - last_error: last_error + - console_enabled: console_enabled + - raid_config: raid_config + - target_raid_config: target_raid_config + +**Example node state:** + +.. literalinclude:: samples/node-get-state-response.json + + +Change Node Power State +======================= + +.. rest_method:: PUT /v1/nodes/{node_ident}/states/power + +Request a change to the Node's power state. + +Normal response code: 202 + +Error codes: + - 409 (NodeLocked, ClientError) + - 400 (InvalidState) + - 406 (NotAcceptable) + - 503 (NoFreeConductorWorkers) + +Request +------- + +.. rest_parameters:: parameters.yaml + + - node_ident: node_ident + - target: power_state + +**Example request to power off a Node:** + +.. literalinclude:: samples/node-set-power-off.json + + +Change Node Provision State +=========================== + +.. rest_method:: PUT /v1/nodes/{node_ident}/states/provision + +Request a change to the Node's provision state. + +Acceptable target states depend on the Node's current provision state. More +detailed documentation of the Ironic State Machine is available +`in the developer docs `_. + +Normal response code: 202 + +Error codes: + - 409 (NodeLocked, ClientError) + - 400 (InvalidState, NodeInMaintenance) + - 406 (NotAcceptable) + - 503 (NoFreeConductorWorkers) + +Request +------- + +.. rest_parameters:: parameters.yaml + + - node_ident: node_ident + - target: requested_provision_state + - configdrive: configdrive + - clean_steps: clean_steps + +**Example request to deploy a Node, using a configdrive served via local webserver:** + +.. literalinclude:: samples/node-set-active-state.json + +**Example request to clean a Node, with custom clean step:** + +.. literalinclude:: samples/node-set-clean-state.json + + +Set RAID Config +=============== + +.. rest_method:: PUT /v1/nodes/{node_ident}/states/raid + +Store the supplied configuration on the Node's ``target_raid_config`` property. +This property must be structured JSON, and will be validated by the driver upon receipt. The request +schema is defined in the `documentation for the RAID feature `_ + +.. note:: Calling this API only stores the requested configuration; it will be applied the next time + that the Node transitions through the ``cleaning`` phase. + +Added in API microversion: 1.12 + +Normal response code: 204 + +.. TODO: add more description, response code, sample response + +Request +------- + +.. rest_parameters:: parameters.yaml + + - node_ident: node_ident + - target_raid_config: target_raid_config + +**Example requested RAID config:** + +.. literalinclude:: samples/node-set-raid-request.json + +.. TODO: add more description, response code, sample response + +Get Console +=========== + +.. rest_method:: GET /v1/nodes/{node_ident}/states/console + +Get connection information about the console. + +.. TODO: add more description, response code, sample response + +Request +------- + +.. rest_parameters:: parameters.yaml + + - node_ident: node_ident + +.. TODO: add more description, response code, sample response + +Start/Stop Console +=================== + +.. rest_method:: PUT /v1/nodes/{node_ident}/states/console + +Start or stop the serial console. + +.. TODO: add more description, response code, sample response + +Request +------- + +.. rest_parameters:: parameters.yaml + + - node_ident: node_ident + - enabled: console_enabled diff --git a/api-ref/source/baremetal-api-v1-node-passthru.inc b/api-ref/source/baremetal-api-v1-node-passthru.inc new file mode 100644 index 0000000000..a9efeb7f01 --- /dev/null +++ b/api-ref/source/baremetal-api-v1-node-passthru.inc @@ -0,0 +1,84 @@ +.. -*- rst -*- + +============================ +Node Vendor Passthru (nodes) +============================ + +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=reset_bmc``. The contents of the HTTP request are +forwarded to the Node's 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/nodes/{node_ident}/vendor_passthru/methods + +Retrieve a list of the available vendor passthru methods for the given Node. 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 + +.. TODO: add error codes + +Request +------- + +.. rest_parameters:: parameters.yaml + + - node_ident: node_ident + +Response +-------- + +**Example passthru methods listing:** + +.. literalinclude:: samples/node-vendor-passthru-response.json + + +Call a Method +============= + +.. rest_method:: METHOD /v1/nodes/{node_ident}/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 + +.. TODO: add error codes + +Request +------- + +.. rest_parameters:: parameters.yaml + + - node_ident: node_ident + - method_name: method_name + +All other parameters should be passed in the BODY. Parameter list varies by method_name. + +Response +-------- + +Varies. \ No newline at end of file diff --git a/api-ref/source/baremetal-api-v1-nodes.inc b/api-ref/source/baremetal-api-v1-nodes.inc index 03e35f4904..6bb3f5c20f 100644 --- a/api-ref/source/baremetal-api-v1-nodes.inc +++ b/api-ref/source/baremetal-api-v1-nodes.inc @@ -4,213 +4,373 @@ Nodes (nodes) ============= +List, Searching, Creating, Updating, and Deleting of bare metal Node resources +are done through the ``/v1/nodes`` resource. There are also several sub-resources, +which allow further actions to be performed on a bare metal Node. +A Node is the canonical representation of a discretely allocatable server, +capable of running an Operating System. Each Node must be associated with a +``driver``; this informs Ironic what protocol to use when managing the Node. +Beginning with API microversion 1.6, a Node may be referenced both by its UUID +and by a unique human-readable "name" in any request. Throughout this +documentation, this is referred to as the ``node_ident``. Responses clearly +indicate whether a given field is a ``uuid`` or a ``name``. -Show node details -================= -.. rest_method:: GET /v1/nodes/{node_id} - -Shows details for a node. - - -Normal response codes: 200 -Error response codes:413,405,404,403,401,400,503, - - -Request -------- - -.. rest_parameters:: parameters.yaml - - - node_id: node_id - - fields: fields - - - - -Response Example ----------------- - -.. literalinclude:: samples/node-show-response.json - :language: javascript - - - - - - - - - - - -Update node -=========== - -.. rest_method:: PATCH /v1/nodes/{node_id} - -Updates a node. - - -Normal response codes: 200 -Error response codes:413,415,405,404,403,401,400,503,409, - - -Request -------- - -.. rest_parameters:: parameters.yaml - - - node_id: node_id - - - - -Response Example ----------------- - -.. literalinclude:: samples/node-show-response.json - :language: javascript - - - - - - - - - - - - - -Delete node -=========== - -.. rest_method:: DELETE /v1/nodes/{node_id} - -Deletes a node. - -Error response codes:204,413,415,405,404,403,401,400,503,409, - - -Request -------- - -.. rest_parameters:: parameters.yaml - - - node_id: node_id - - - - - - - - - - - - - - - -List nodes with details -======================= - -.. rest_method:: GET /v1/nodes/detail - -Lists all nodes with details. - - -Normal response codes: 200 -Error response codes:413,405,404,403,401,400,503, - - -Request -------- - - - - - -Response Example ----------------- - -.. literalinclude:: samples/nodes-list-details-response.json - :language: javascript - - - - - - - - - - - -Create node +Create Node =========== .. rest_method:: POST /v1/nodes -Creates a node. +Creates a new Node resource. -Error response codes:201,413,415,405,404,403,401,400,503,409, +This method requires that a ``driver`` be supplied in the request body. Most +subresources of a Node (eg, ``properties``, ``driver_info``, etc) may be +supplied when the Node is created, or the resource may be updated later. +API microversion 1.2 introduced the new ``available`` state name, which replaced +``None`` as the status of an unprovisioned Node. All clients should be updated to +use the new ``available`` state name. + +Nodes in the ``available`` state may have workloads provisioned on them; they are +"available" for use. + +API microversion 1.11 changed the default initial state of newly-created Nodes +from ``available`` to ``enroll``. This provides users a workflow to verify the +manageability of a Node and perform necessary operational functions (eg, building +a RAID array) before making the Node available for provisioning. + +Normal response codes: 201 + +.. TODO: add error codes Request ------- +.. rest_parameters:: parameters.yaml + + - driver: r_driver_name + +**Example Node creation request:** + +.. literalinclude:: samples/node-create-request.json + :language: javascript + +Response +-------- + +The response will contain the complete Node record, with the supplied data, +and any defaults added for non-specified fields. Most fields default to "null" +or "". + +API microversion 1.5 introduced the ``name`` field. + +API microversion 1.7 introduced the ``clean_step`` field` + +API microversion 1.12 introduced support for the ``raid_config`` and +``target_raid_config`` fields. + +The list and example below are representative of the response as of API microversion 1.16. + +.. rest_parameters:: parameters.yaml + + - uuid: node_uuid + - name: node_name + - power_state: power_state + - target_power_state: target_power_state + - provision_state: provision_state + - target_provision_state: target_provision_state + - maintenance: maintenance + - maintenance_reason: maintenance_reason + - last_error: last_error + - reservation: reservation + - driver: driver_name + - driver_info: driver_info + - driver_internal_info: driver_internal_info + - properties: n_properties + - instance_info: instance_info + - instance_uuid: instance_uuid + - chassis_uuid: chassis_uuid + - extra: extra + - console_enabled: console_enabled + - raid_config: raid_config + - target_raid_config: target_raid_config + - clean_step: clean_step + - links: links + - ports: n_ports + - states: n_states + +**Example JSON representation of a Node:** + +.. literalinclude:: samples/node-create-response.json + :language: javascript - - - - - - - - - - - - - -List nodes +List Nodes ========== .. rest_method:: GET /v1/nodes -Lists all nodes. +Return a list of bare metal Nodes, with some useful information about +each Node. Some filtering is possible by passing in flags with the request. +By default, this query will return the name, uuid, instance uuid, power state, +provision state, and maintenance setting for each Node. + +API microversion 1.8 added the ``fields`` Request parameter. When specified, +this causes the content of the Response to include only the specified fields, +rather than the default set. + +API microversion 1.9 added the ``provision_state`` Request parameter, allowing +the list of returned Nodes to be filtered by their current state. + +API microversion 1.16 added the ``driver`` Request parameter, allowing +the list of returned Nodes to be filtered by their driver name. Normal response codes: 200 -Error response codes:413,405,404,403,401,400,503, +.. TODO: add error codes Request ------- +.. rest_parameters:: parameters.yaml + - instance_uuid: r_instance_uuid + - maintenance: r_maintenance + - associated: r_associated + - provision_state: r_provision_state + - driver: r_driver + - fields: fields + - limit: limit + - marker: marker + - sort_dir: sort_dir + - sort_key: sort_key +Response +-------- +.. rest_parameters:: parameters.yaml -Response Example ----------------- + - uuid: uuid + - name: node_name + - instance_uuid: instance_uuid + - power_state: power_state + - provision_state: provision_state + - maintenance: maintenance + - links: links + +**Example list of Nodes:** .. literalinclude:: samples/nodes-list-response.json :language: javascript +List Nodes Detailed +=================== + +.. rest_method:: GET /v1/nodes/detail + +Return a list of bare metal Nodes with complete details. Some filtering is +possible by passing in flags with the request. + +This method is particularly useful to locate the Node associated to a given +Nova instance, eg. with a request to ``v1/nodes/detail?instance_uuid={NOVA INSTANCE UUID}`` + +Normal response codes: 200 + +.. TODO: add error codes + +Request +------- + +.. rest_parameters:: parameters.yaml + + - instance_uuid: r_instance_uuid + - maintenance: r_maintenance + - associated: r_associated + - provision_state: r_provision_state + - driver: r_driver + - limit: limit + - marker: marker + - sort_dir: sort_dir + - sort_key: sort_key + +Response +-------- + +.. rest_parameters:: parameters.yaml + + - uuid: node_uuid + - name: node_name + - power_state: power_state + - target_power_state: target_power_state + - provision_state: provision_state + - target_provision_state: target_provision_state + - maintenance: maintenance + - maintenance_reason: maintenance_reason + - last_error: last_error + - reservation: reservation + - driver: driver_name + - driver_info: driver_info + - driver_internal_info: driver_internal_info + - properties: n_properties + - instance_info: instance_info + - instance_uuid: instance_uuid + - chassis_uuid: chassis_uuid + - extra: extra + - console_enabled: console_enabled + - raid_config: raid_config + - target_raid_config: target_raid_config + - clean_step: clean_step + - links: links + - ports: n_ports + - states: n_states + +**Example detailed list of Nodes:** + +.. literalinclude:: samples/nodes-list-details-response.json + :language: javascript +Show Node Details +================= + +.. rest_method:: GET /v1/nodes/{node_ident} + +Shows details for a node. By default, this will return the full representation +of the resource; an optional ``fields`` parameter can be supplied to return +only the specified set. + +Normal response codes: 200 + +.. TODO: add error codes + +Request +------- + +.. rest_parameters:: parameters.yaml + + - node_ident: node_ident + - fields: fields + +Response +-------- + +.. rest_parameters:: parameters.yaml + + - uuid: node_uuid + - name: node_name + - power_state: power_state + - target_power_state: target_power_state + - provision_state: provision_state + - target_provision_state: target_provision_state + - maintenance: maintenance + - maintenance_reason: maintenance_reason + - last_error: last_error + - reservation: reservation + - driver: driver_name + - driver_info: driver_info + - driver_internal_info: driver_internal_info + - properties: n_properties + - instance_info: instance_info + - instance_uuid: instance_uuid + - chassis_uuid: chassis_uuid + - extra: extra + - console_enabled: console_enabled + - raid_config: raid_config + - target_raid_config: target_raid_config + - clean_step: clean_step + - links: links + - ports: n_ports + - states: n_states + +**Example JSON representation of a Node:** + +.. literalinclude:: samples/node-show-response.json + :language: javascript +Update Node +=========== + +.. rest_method:: PATCH /v1/nodes/{node_ident} + +Updates the information stored about a Node. + +Note that this endpoint can not be used to request state changes, which are +managed through sub-resources. + +Normal response codes: 200 + +.. TODO: add error codes + +Request +------- + +The BODY of the PATCH request must be a JSON PATCH document, adhering to +`RFC 6902 `_. + +.. rest_parameters:: parameters.yaml + + - node_ident: node_ident + +**Example PATCH document updating Node driver_info:** + +.. literalinclude:: samples/node-update-driver-info-request.json + +Response +-------- + +.. rest_parameters:: parameters.yaml + + - uuid: node_uuid + - name: node_name + - power_state: power_state + - target_power_state: target_power_state + - provision_state: provision_state + - target_provision_state: target_provision_state + - maintenance: maintenance + - maintenance_reason: maintenance_reason + - last_error: last_error + - reservation: reservation + - driver: driver_name + - driver_info: driver_info + - driver_internal_info: driver_internal_info + - properties: n_properties + - instance_info: instance_info + - instance_uuid: instance_uuid + - chassis_uuid: chassis_uuid + - extra: extra + - console_enabled: console_enabled + - raid_config: raid_config + - target_raid_config: target_raid_config + - clean_step: clean_step + - links: links + - ports: n_ports + - states: n_states + +**Example JSON representation of a Node:** + +.. literalinclude:: samples/node-update-driver-info-response.json + :language: javascript +Delete Node +=========== +.. rest_method:: DELETE /v1/nodes/{node_ident} +Deletes a node. + +Normal response codes: 204 + +.. TODO: add error codes + +Request +------- + +.. rest_parameters:: parameters.yaml + + - node_ident: node_ident \ No newline at end of file diff --git a/api-ref/source/baremetal-api-v1-ports.inc b/api-ref/source/baremetal-api-v1-ports.inc index 73efb58d5f..6846abf260 100644 --- a/api-ref/source/baremetal-api-v1-ports.inc +++ b/api-ref/source/baremetal-api-v1-ports.inc @@ -24,7 +24,7 @@ Request .. rest_parameters:: parameters.yaml - - port_id: port_id + - port_id: uuid - fields: fields @@ -61,7 +61,7 @@ Request .. rest_parameters:: parameters.yaml - - port_id: port_id + - port_id: uuid @@ -97,7 +97,7 @@ Request .. rest_parameters:: parameters.yaml - - port_id: port_id + - port_id: uuid diff --git a/api-ref/source/baremetal-api-versions.inc b/api-ref/source/baremetal-api-versions.inc new file mode 100644 index 0000000000..4b74dd6403 --- /dev/null +++ b/api-ref/source/baremetal-api-versions.inc @@ -0,0 +1,78 @@ +.. -*- rst -*- + +============ +API versions +============ + +Concepts +======== + +In order to bring new features to users over time, the Ironic API +supports versioning. There are two kinds of versions in Ironic. + +- ''major versions'', which have dedicated urls. +- ''microversions'', which can be requested through the use of the + ``X-OpenStack-Ironic-API-Version`` header. + +Beginning with the Kilo release, all API requests support the +``X-OpenStack-Ironic-API-Version`` header. This header SHOULD be supplied +with every request; in the absence of this header, each request is treated +as though coming from an older pre-Kilo client. This was done to preserve +backwards compatibility as we introduced new features in the server. + +List API versions +================= + +.. rest_method:: GET / + +This fetches all the information about all known major API versions in the +deployment. Links to more specific information will be provided for each major +API version, as well as information about supported min and max microversions. + +Normal response codes: 200 + +Request +------- + +Response Example +---------------- + +.. rest_parameters:: parameters.yaml + + - description: description + - versions: versions + - version: version + - id: id + - links: links + - min_version: x-openstack-ironic-api-min-version + +.. literalinclude:: samples/api-root-response.json + :language: javascript + + +Show v1 API +=========== + +.. rest_method:: GET /v1/ + +Show all the resources within the Ironic v1 API. + +Normal response codes: 200 + +Request +------- + +Response Example +---------------- + +.. rest_parameters:: parameters.yaml + + - id: id + - links: links + - openstack-request-id: openstack-request-id + - x-openstack-ironic-api-version: header_version + - x-openstack-ironic-api-min-version: x-openstack-ironic-api-min-version + - x-openstack-ironic-api-max-version: x-openstack-ironic-api-max-version + +.. literalinclude:: samples/api-v1-root-response.json + :language: javascript \ No newline at end of file diff --git a/api-ref/source/index.rst b/api-ref/source/index.rst index da5a1cb388..dbe36f040d 100644 --- a/api-ref/source/index.rst +++ b/api-ref/source/index.rst @@ -4,10 +4,21 @@ Bare Metal API ================ +This documentation describes the REST API for the Ironic service, beginning with the +5.1.0 (Mitaka) release. + +Version negotiation is implemented in the server. When the negotiated version +is not the current maximum version, both request and response may not match what +is presented in this document. Significant changes may be noted inline. + + .. rest_expand_all:: -.. include:: baremetal-api-v1-chassis.inc -.. include:: baremetal-api-v1-drivers.inc +.. include:: baremetal-api-versions.inc .. include:: baremetal-api-v1-nodes.inc +.. include:: baremetal-api-v1-node-management.inc +.. include:: baremetal-api-v1-node-passthru.inc .. include:: baremetal-api-v1-ports.inc +.. include:: baremetal-api-v1-drivers.inc +.. include:: baremetal-api-v1-chassis.inc diff --git a/api-ref/source/parameters.yaml b/api-ref/source/parameters.yaml index 1ce2bbd19f..c07174f2b9 100644 --- a/api-ref/source/parameters.yaml +++ b/api-ref/source/parameters.yaml @@ -1,17 +1,54 @@ # variables in header -x-openstack-request-id: +header_version: + description: | + Specific API microversion used to generate this response. + in: header + required: true + type: string +openstack-request-id: description: > - foo + A unique ID for tracking the request. The request ID associated with the request + appears in the log lines for that request. By default, the middleware configuration + ensures that the request ID appears in the log files. in: header required: false type: string +x-openstack-ironic-api-max-version: + description: | + Maximum API microversion supported by this endpoint, eg. "1.16" + in: header + required: true + type: string +x-openstack-ironic-api-min-version: + description: | + Minimum API microversion supported by this endpoint, eg. "1.1" + in: header + required: true + type: string +x-openstack-ironic-api-version: + description: > + A request SHOULD include this header to indicate to the Ironic API service what + version the client supports. The server will transform the response object into + compliance with the requested version, if it is supported, or return a + 406 Not Supported error. + If this header is not supplied, the server will default to ``min_version`` + in all responses. + in: header + required: true + type: string # variables in path -driver_name: +chassis_ident: + description: | + The UUID of the chassis. + in: path + required: true + type: string +driver_ident: description: | The name of the driver. in: path - required: false + required: true type: string node_id: description: | @@ -19,24 +56,31 @@ node_id: in: path required: false type: string -port_id: +node_ident: + description: | + The UUID or Name of the node. + in: path + required: true + type: string +port_ident: description: | The UUID of the port. in: path - required: false + required: true type: string -# variables in query + +# variables common to all query strings fields: description: | - One or more chassis fields to be returned in the response. + One or more fields to be returned in the response. - For example, the following request returns only the ``description`` - field for each chassis: + For example, the following request returns only the ``uuid`` + and ``name`` fields for each node: :: - GET /v1/chassis?fields=description + GET /v1/nodes?fields=uuid,name in: query required: false type: array @@ -59,6 +103,51 @@ marker: in: query required: false type: string + +# variables in the vendor_passthru query string +method_name: + description: | + Driver specific method name. + in: query + required: true + type: string + +# variables in the node query string +r_associated: + description: | + Filter the list of returned nodes and only return which are, or are not, + associated with an ``instance_uuid``. + in: query + required: false + type: boolean +r_driver: + description: | + Filter the list of returned nodes, and only return those with the specified + ``driver``. + in: query + required: false + type: string +r_instance_uuid: + description: | + Filter the list of returned nodes, and only return the node with this + specific instance UUID, or an empty set if not found. + in: query + required: false + type: string +r_maintenance: + description: | + Filter the list of returned nodes and only return those with + ``maintenance`` set to ``True`` or ``False``. + in: query + required: false + type: boolean +r_provision_state: + description: | + Filter the list of returned nodes, and only return those with the specified + ``provision_state``. + in: query + required: false + type: string sort_dir: description: | Sorts the response by the requested sort @@ -82,19 +171,55 @@ sort_key: required: false type: string -# variables in body + +# variables in API response body +boot_device: + description: | + The boot device for a Node, eg. "pxe" or "disk". + in: body + required: true + type: string chassis: description: | A ``chassis`` object. in: body required: true type: array -chassis_1: +chassis_uuid: description: | - A list of chassis objects. + UUID of the chassis associated with this Node. May be empty or None. in: body required: true + type: string +clean_step: + description: | + The current clean step. Introduced with the cleaning feature. + in: body + required: false + type: string +clean_steps: + description: | + 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. + in: body + required: false type: array +configdrive: + description: | + A gzip'ed and base-64 encoded config drive, to be written to a partition + on the Node's boot disk. This parameter is only accepted when setting the + state to "active". + in: body + required: false + type: string or gzip+b64 blob +console_enabled: + description: | + Indicates whether console access is enabled or disabled on this node. + in: body + required: true + type: boolean created_at: description: | The date and time when the resource was created. @@ -115,13 +240,26 @@ created_at: type: string description: description: | - A description for the chassis. + Descriptive text about the Ironic service. + in: body + required: true + type: string +driver_info: + description: | + All the metadata required by the driver to manage this Node. List of fields + varies between drivers, and can be retrieved from the ``/v1/drivers//properties`` resource. + in: body + required: true + type: JSON +driver_internal_info: + description: | + Internal metadata set and stored by the Node's driver. This field is read-only. in: body required: false - type: string -description_1: + type: JSON +driver_name: description: | - A description for the chassis. + The name of the driver. in: body required: true type: string @@ -134,43 +272,120 @@ drivers: extra: description: | A set of one or more arbitrary metadata key and - value pairs for the chassis. + value pairs. in: body required: false type: object -extra_1: - description: | - A set of zero or more arbitrary metadata key and - value pairs for the chassis. - in: body - required: true - type: object hosts: description: | A list of active hosts that support this driver. in: body required: true type: array -links: +id: description: | - A list that contains a self link and associated - chassis links. + Major API version, eg, "v1" in: body required: true - type: array -links_1: + type: string +inspection_finished_at: + description: | + The date and time when the inspection process started. + May be "null" + in: body + required: true + type: string +inspection_started_at: + description: | + The date and time when the inspection process started. + May be "null" + in: body + required: true + type: string +instance_info: + description: | + Information used to customize the deployed image. May include root partition + size, a base 64 encoded config drive, and other metadata. Note that this field + is erased automatically when the instance is deleted (this is done by requesting + the Node provision state be changed to DELETED). + in: body + required: true + type: JSON +instance_uuid: + description: | + UUID of the Nova instance associated with this Node. + in: body + required: true + type: string +last_error: + description: | + Any error from the most recent (last) transaction that started but failed to finish. + in: body + required: true + type: string +links: description: | A list of relative links. Includes the self and bookmark links. in: body required: true type: array +maintenance: + description: | + Whether or not this Node is currently in "maintenance mode". Setting a Node + into maintenance mode removes it from the available resource pool and halts + some internal automation. This can happen manually (eg, via an API request) + or automatically when Ironic detects a hardware fault that prevents communication + with the machine. + in: body + required: true + type: boolean +maintenance_reason: + description: | + User-settable description of the reason why this Node was placed into + maintenance mode + in: body + required: false + type: string +n_ports: + description: | + Links to the collection of ports on this node + in: body + required: true + type: array +n_properties: + description: | + Physical characteristics of this Node. Populated by ironic-inspector during + inspection. May be edited via the REST API at any time. + in: body + required: true + type: JSON +n_states: + description: | + Links to the collection of states. Note that this resource is also used to + request state transitions. + in: body + required: true + type: array name: description: | The name of the driver. in: body required: true type: string +node_name: + description: | + Human-readable identifier for the Node resource. May be undefined. Certain + words are reserved. Added in API microversion 1.5 + in: body + required: false + type: string +node_uuid: + description: | + UUID of the Node resource. + in: body + required: true + type: string nodes: description: | Links to the collection of nodes contained in @@ -178,12 +393,103 @@ nodes: in: body required: true type: array +persistent: + description: | + Whether the boot device should be set only for the next reboot, or + persistently. + in: body + required: true + type: boolean +power_state: + description: | + The current power state of this Node. Usually, "power on" or "power off", but may be "None" + if Ironic is unable to determine the power state (eg, due to hardware failure). + in: body + required: true + type: string properties: description: | A list of links to driver properties. in: body required: true type: array +provision_state: + description: | + The current provisioning state of this Node. + in: body + required: true + type: string +provision_updated_at: + description: | + The date and time when the provision_state last changed. + ``null`` if the node is not being provisioned. + in: body + required: true + type: string +r_driver_name: + description: | + The name of the driver used to manage this Node. + in: body + required: true + type: string +raid_config: + description: | + Represents the current RAID configuration of the node. Introduced with + the cleaning feature. + in: body + required: false + type: JSON +reason: + description: | + Specify the reason for setting the Node into maintenance mode. + in: body + required: false + type: string +requested_provision_state: + description: | + One of the provisioning verbs: manage, provide, inspect, clean, active, + rebuild, delete (deleted), abort. + in: body + required: true + type: string +reservation: + description: | + The ``name`` of an Ironic Conductor host which is holding a lock on this node, + if a lock is held. Usually "null", but this field can be useful for debugging. + in: body + required: true + type: string +supported_boot_devices: + description: | + List of boot devices which this Node's driver supports. + in: body + required: true + type: array +target_power_state: + description: | + If a power state transition has been requested, this field represents the + requested (ie, "target") state. + in: body + required: true + type: string +target_provision_state: + description: | + If a provisioning action has been requested, this field represents the + requested (ie, "target") state. Note that a Node may go through several + states during its transition to this target state. For instance, when requesting + an instance be deployed to an AVAILABLE Node, the Node may go through the following + state change progression: AVAILABLE -> DEPLOYING -> DEPLOYWAIT -> DEPLOYING -> ACTIVE + in: body + required: true + type: string +target_raid_config: + description: | + Represents the requested RAID configuration of the node, which will be + applied when the Node next transitions through the CLEANING state. Introduced + with the cleaning feature. + in: body + required: true + type: JSON updated_at: description: | The date and time when the resource was updated. @@ -207,8 +513,64 @@ updated_at: type: string uuid: description: | - The UUID for the chassis. + The UUID for the resource. in: body required: true type: string +# variables returned from node-validate +v_boot: + description: | + Status of the "boot" interface + in: body + required: true + type: object +v_console: + description: | + Status of the "console" interface + in: body + required: true + type: object +v_deploy: + description: | + Status of the "deploy" interface + in: body + required: true + type: object +v_inspect: + description: | + Status of the "inspect" interface + in: body + required: true + type: object +v_management: + description: | + Status of the "management" interface + in: body + required: true + type: object +v_power: + description: | + Status of the "power" interface + in: body + required: true + type: object +v_raid: + description: | + Status of the "raid" interface + in: body + required: true + type: object + +version: + description: | + Versioning of this API response, eg. "1.16". + in: body + required: true + type: string +versions: + description: | + Array of information about currently supported versions. + in: body + required: true + type: array \ No newline at end of file diff --git a/api-ref/source/samples/api-root-response.json b/api-ref/source/samples/api-root-response.json new file mode 100644 index 0000000000..3a860c34df --- /dev/null +++ b/api-ref/source/samples/api-root-response.json @@ -0,0 +1,30 @@ +{ + "name" : "OpenStack Ironic API", + "description" : "Ironic is an OpenStack project which aims to provision baremetal machines.", + "default_version" : { + "status" : "CURRENT", + "version" : "1.16", + "links" : [ + { + "rel" : "self", + "href" : "http://127.0.0.1:6385/v1/" + } + ], + "id" : "v1", + "min_version" : "1.1" + }, + "versions" : [ + { + "status" : "CURRENT", + "links" : [ + { + "href" : "http://127.0.0.1:6385/v1/", + "rel" : "self" + } + ], + "id" : "v1", + "version" : "1.16", + "min_version" : "1.1" + } + ] +} diff --git a/api-ref/source/samples/api-v1-root-response.json b/api-ref/source/samples/api-v1-root-response.json new file mode 100644 index 0000000000..9fcb56b910 --- /dev/null +++ b/api-ref/source/samples/api-v1-root-response.json @@ -0,0 +1,60 @@ +{ + "chassis" : [ + { + "rel" : "self", + "href" : "http://127.0.0.1:6385/v1/chassis/" + }, + { + "href" : "http://127.0.0.1:6385/chassis/", + "rel" : "bookmark" + } + ], + "links" : [ + { + "href" : "http://127.0.0.1:6385/v1/", + "rel" : "self" + }, + { + "rel" : "describedby", + "type" : "text/html", + "href" : "http://docs.openstack.org/developer/ironic/dev/api-spec-v1.html" + } + ], + "nodes" : [ + { + "rel" : "self", + "href" : "http://127.0.0.1:6385/v1/nodes/" + }, + { + "rel" : "bookmark", + "href" : "http://127.0.0.1:6385/nodes/" + } + ], + "ports" : [ + { + "href" : "http://127.0.0.1:6385/v1/ports/", + "rel" : "self" + }, + { + "rel" : "bookmark", + "href" : "http://127.0.0.1:6385/ports/" + } + ], + "media_types" : [ + { + "type" : "application/vnd.openstack.ironic.v1+json", + "base" : "application/json" + } + ], + "drivers" : [ + { + "rel" : "self", + "href" : "http://127.0.0.1:6385/v1/drivers/" + }, + { + "href" : "http://127.0.0.1:6385/drivers/", + "rel" : "bookmark" + } + ], + "id" : "v1" +} \ No newline at end of file diff --git a/api-ref/source/samples/driver-get-response.json b/api-ref/source/samples/driver-get-response.json index d1053fb875..5bc24e5b92 100644 --- a/api-ref/source/samples/driver-get-response.json +++ b/api-ref/source/samples/driver-get-response.json @@ -1,6 +1,30 @@ { - "hosts": [ - "fake-host" - ], - "name": "sample-driver" -} + "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" + } + ] + } + ] +} \ No newline at end of file diff --git a/api-ref/source/samples/node-create-request.json b/api-ref/source/samples/node-create-request.json new file mode 100644 index 0000000000..d922203025 --- /dev/null +++ b/api-ref/source/samples/node-create-request.json @@ -0,0 +1,4 @@ +{ + "driver": "agent_ipmitool", + "name": "test_node" +} diff --git a/api-ref/source/samples/node-create-response.json b/api-ref/source/samples/node-create-response.json new file mode 100644 index 0000000000..4e52c8f963 --- /dev/null +++ b/api-ref/source/samples/node-create-response.json @@ -0,0 +1,58 @@ +{ + "last_error" : null, + "extra" : {}, + "reservation" : null, + "driver" : "agent_ipmitool", + "instance_info" : {}, + "created_at" : "2016-05-04T22:59:49.300836+00:00", + "raid_config" : {}, + "uuid" : "14deb747-127c-4fe4-be9d-906c43006cd4", + "maintenance_reason" : null, + "target_provision_state" : null, + "ports" : [ + { + "rel" : "self", + "href" : "http://127.0.0.1:6385/v1/nodes/14deb747-127c-4fe4-be9d-906c43006cd4/ports" + }, + { + "rel" : "bookmark", + "href" : "http://127.0.0.1:6385/nodes/14deb747-127c-4fe4-be9d-906c43006cd4/ports" + } + ], + "power_state" : null, + "instance_uuid" : null, + "name" : "test_node_", + "properties" : {}, + "clean_step" : {}, + "console_enabled" : false, + "driver_internal_info" : {}, + "target_power_state" : null, + "inspection_started_at" : null, + "provision_state" : "enroll", + "provision_updated_at" : null, + "driver_info" : {}, + "inspection_finished_at" : null, + "updated_at" : null, + "links" : [ + { + "rel" : "self", + "href" : "http://127.0.0.1:6385/v1/nodes/14deb747-127c-4fe4-be9d-906c43006cd4" + }, + { + "href" : "http://127.0.0.1:6385/nodes/14deb747-127c-4fe4-be9d-906c43006cd4", + "rel" : "bookmark" + } + ], + "target_raid_config" : {}, + "maintenance" : false, + "states" : [ + { + "href" : "http://127.0.0.1:6385/v1/nodes/14deb747-127c-4fe4-be9d-906c43006cd4/states", + "rel" : "self" + }, + { + "href" : "http://127.0.0.1:6385/nodes/14deb747-127c-4fe4-be9d-906c43006cd4/states", + "rel" : "bookmark" + } + ] +} diff --git a/api-ref/source/samples/node-get-or-set-boot-device.json b/api-ref/source/samples/node-get-or-set-boot-device.json new file mode 100644 index 0000000000..cb0141173a --- /dev/null +++ b/api-ref/source/samples/node-get-or-set-boot-device.json @@ -0,0 +1,4 @@ +{ + "boot_device": "pxe", + "persistent": false +} diff --git a/api-ref/source/samples/node-get-state-response.json b/api-ref/source/samples/node-get-state-response.json new file mode 100644 index 0000000000..b33c8dfbad --- /dev/null +++ b/api-ref/source/samples/node-get-state-response.json @@ -0,0 +1,11 @@ +{ + "last_error" : "", + "target_raid_config" : {}, + "target_power_state" : null, + "console_enabled" : false, + "target_provision_state" : null, + "provision_updated_at" : null, + "power_state" : "power off", + "raid_config" : {}, + "provision_state" : "available" +} diff --git a/api-ref/source/samples/node-get-supported-boot-devices-response.json b/api-ref/source/samples/node-get-supported-boot-devices-response.json new file mode 100644 index 0000000000..cf72fdfe8e --- /dev/null +++ b/api-ref/source/samples/node-get-supported-boot-devices-response.json @@ -0,0 +1,9 @@ +{ + "supported_boot_devices" : [ + "pxe", + "disk", + "cdrom", + "bios", + "safe" + ] +} diff --git a/api-ref/source/samples/node-maintenance-request.json b/api-ref/source/samples/node-maintenance-request.json new file mode 100644 index 0000000000..3cea207b56 --- /dev/null +++ b/api-ref/source/samples/node-maintenance-request.json @@ -0,0 +1,3 @@ +{ + "reason": "Replacing the hard drive" +} \ No newline at end of file diff --git a/api-ref/source/samples/node-set-active-state.json b/api-ref/source/samples/node-set-active-state.json new file mode 100644 index 0000000000..f89115ce4f --- /dev/null +++ b/api-ref/source/samples/node-set-active-state.json @@ -0,0 +1,4 @@ +{ + "target": "active", + "configdrive": "http://127.0.0.1/images/test-node-config-drive.iso.gz" +} \ No newline at end of file diff --git a/api-ref/source/samples/node-set-clean-state.json b/api-ref/source/samples/node-set-clean-state.json new file mode 100644 index 0000000000..0171a20f16 --- /dev/null +++ b/api-ref/source/samples/node-set-clean-state.json @@ -0,0 +1,12 @@ +{ + "target": "clean", + "clean_steps": [ + { + 'interface': 'deploy', + 'step': 'upgrade_firmware', + 'args': { + 'force': True + } + } + ] +} \ No newline at end of file diff --git a/api-ref/source/samples/node-set-power-off.json b/api-ref/source/samples/node-set-power-off.json new file mode 100644 index 0000000000..5602f053dd --- /dev/null +++ b/api-ref/source/samples/node-set-power-off.json @@ -0,0 +1,3 @@ +{ + "target": "power off" +} \ No newline at end of file diff --git a/api-ref/source/samples/node-set-power-state.json b/api-ref/source/samples/node-set-power-state.json new file mode 100644 index 0000000000..11833351b0 --- /dev/null +++ b/api-ref/source/samples/node-set-power-state.json @@ -0,0 +1,3 @@ +{ + "target": "power on" +} \ No newline at end of file diff --git a/api-ref/source/samples/node-set-raid-request.json b/api-ref/source/samples/node-set-raid-request.json new file mode 100644 index 0000000000..7bb7612d38 --- /dev/null +++ b/api-ref/source/samples/node-set-raid-request.json @@ -0,0 +1,9 @@ +{ + "logical_disks" : [ + { + "size_gb" : 100, + "is_root_volume" : true, + "raid_level" : "1" + } + ] +} diff --git a/api-ref/source/samples/node-show-response.json b/api-ref/source/samples/node-show-response.json index 34cc5f7de4..2e4bf1d029 100644 --- a/api-ref/source/samples/node-show-response.json +++ b/api-ref/source/samples/node-show-response.json @@ -1,63 +1,71 @@ { - "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" + "target_provision_state" : null, + "instance_info" : {}, + "updated_at" : "2016-05-05T00:28:40+00:00", + "maintenance_reason" : null, + "inspection_started_at" : null, + "target_power_state" : null, + "ports" : [ + { + "rel" : "self", + "href" : "http://127.0.0.1:6385/v1/nodes/ecddf26d-8c9c-4ddf-8f45-fd57e09ccddb/ports" + }, + { + "href" : "http://127.0.0.1:6385/nodes/ecddf26d-8c9c-4ddf-8f45-fd57e09ccddb/ports", + "rel" : "bookmark" + } + ], + "maintenance" : false, + "driver" : "fake", + "provision_state" : "available", + "reservation" : null, + "uuid" : "ecddf26d-8c9c-4ddf-8f45-fd57e09ccddb", + "extra" : { + "foo" : "bar" + }, + "driver_internal_info" : {}, + "states" : [ + { + "href" : "http://127.0.0.1:6385/v1/nodes/ecddf26d-8c9c-4ddf-8f45-fd57e09ccddb/states", + "rel" : "self" + }, + { + "rel" : "bookmark", + "href" : "http://127.0.0.1:6385/nodes/ecddf26d-8c9c-4ddf-8f45-fd57e09ccddb/states" + } + ], + "target_raid_config" : {}, + "console_enabled" : false, + "clean_step" : {}, + "last_error" : null, + "links" : [ + { + "rel" : "self", + "href" : "http://127.0.0.1:6385/v1/nodes/ecddf26d-8c9c-4ddf-8f45-fd57e09ccddb" + }, + { + "rel" : "bookmark", + "href" : "http://127.0.0.1:6385/nodes/ecddf26d-8c9c-4ddf-8f45-fd57e09ccddb" + } + ], + "provision_updated_at" : null, + "name" : "test_node", + "properties" : { + "local_gb" : 10, + "cpu_arch" : "x86_64", + "cpus" : 1, + "memory_mb" : 1024 + }, + "power_state" : "power off", + "created_at" : "2016-04-20T16:51:03+00:00", + "instance_uuid" : null, + "raid_config" : {}, + "driver_info" : { + "ipmi_password" : "***", + "ipmi_username" : "ADMIN", + "ipmi_address" : "1.2.3.4", + "deploy_kernel" : "http://127.0.0.1/images/kernel", + "deploy_ramdisk" : "http://127.0.0.1/images/ramdisk" + }, + "inspection_finished_at" : null } diff --git a/api-ref/source/samples/node-update-driver-info-request.json b/api-ref/source/samples/node-update-driver-info-request.json new file mode 100644 index 0000000000..7c4fe53bac --- /dev/null +++ b/api-ref/source/samples/node-update-driver-info-request.json @@ -0,0 +1,12 @@ +[ + { + "op" : "replace", + "path" : "/driver_info/ipmi_username", + "value" : "OPERATOR" + }, + { + "value" : "10.0.0.123", + "op" : "replace", + "path" : "/driver_info/ipmi_address" + } +] diff --git a/api-ref/source/samples/node-update-driver-info-response.json b/api-ref/source/samples/node-update-driver-info-response.json new file mode 100644 index 0000000000..6f9a6cf2f0 --- /dev/null +++ b/api-ref/source/samples/node-update-driver-info-response.json @@ -0,0 +1,71 @@ +{ + "properties" : { + "memory_mb" : 1024, + "cpus" : 1, + "local_gb" : 10, + "cpu_arch" : "x86_64" + }, + "maintenance_reason" : null, + "instance_info" : {}, + "states" : [ + { + "rel" : "self", + "href" : "http://127.0.0.1:6385/v1/nodes/ecddf26d-8c9c-4ddf-8f45-fd57e09ccddb/states" + }, + { + "href" : "http://127.0.0.1:6385/nodes/ecddf26d-8c9c-4ddf-8f45-fd57e09ccddb/states", + "rel" : "bookmark" + } + ], + "driver_internal_info" : {}, + "power_state" : "power off", + "console_enabled" : false, + "last_error" : null, + "target_raid_config" : {}, + "maintenance" : false, + "provision_state" : "available", + "uuid" : "ecddf26d-8c9c-4ddf-8f45-fd57e09ccddb", + "links" : [ + { + "rel" : "self", + "href" : "http://127.0.0.1:6385/v1/nodes/ecddf26d-8c9c-4ddf-8f45-fd57e09ccddb" + }, + { + "href" : "http://127.0.0.1:6385/nodes/ecddf26d-8c9c-4ddf-8f45-fd57e09ccddb", + "rel" : "bookmark" + } + ], + "clean_step" : {}, + "created_at" : "2016-04-20T16:51:03+00:00", + "instance_uuid" : null, + "target_power_state" : null, + "driver_info" : { + "ipmi_address" : "10.0.0.123", + "deploy_ramdisk" : "http://127.0.0.1/images/ramdisk", + "deploy_kernel" : "http://127.0.0.1/images/kernel", + "ipmi_password" : "***", + "ipmi_username" : "OPERATOR" + }, + "inspection_started_at" : null, + "raid_config" : {}, + "inspection_finished_at" : null, + "reservation" : null, + "target_provision_state" : null, + "extra" : { + "foo" : "bar" + }, + "driver" : "fake", + "name" : "test_node", + "updated_at" : "2016-05-05T18:43:41+00:00", + "ports" : [ + { + "href" : "http://127.0.0.1:6385/v1/nodes/ecddf26d-8c9c-4ddf-8f45-fd57e09ccddb/ports", + "rel" : "self" + }, + { + "rel" : "bookmark", + "href" : "http://127.0.0.1:6385/nodes/ecddf26d-8c9c-4ddf-8f45-fd57e09ccddb/ports" + } + ], + "provision_updated_at" : null +} diff --git a/api-ref/source/samples/node-validate-response.json b/api-ref/source/samples/node-validate-response.json new file mode 100644 index 0000000000..8f466845c5 --- /dev/null +++ b/api-ref/source/samples/node-validate-response.json @@ -0,0 +1,27 @@ +{ + "management" : { + "result" : true + }, + "inspect" : { + "result" : null, + "reason" : "not supported" + }, + "power" : { + "result" : true + }, + "raid" : { + "result" : true + }, + "boot" : { + "result" : false, + "reason" : "Cannot validate image information for node ecddf26d-8c9c-4ddf-8f45-fd57e09ccddb because one or more parameters are missing from its instance_info.. Missing are: ['ramdisk', 'kernel', 'image_source']" + }, + "console" : { + "result" : false, + "reason" : "Missing 'ipmi_terminal_port' parameter in node's driver_info." + }, + "deploy" : { + "reason" : "Cannot validate image information for node ecddf26d-8c9c-4ddf-8f45-fd57e09ccddb because one or more parameters are missing from its instance_info.. Missing are: ['ramdisk', 'kernel', 'image_source']", + "result" : false + } +} diff --git a/api-ref/source/samples/node-vendor-passthru-response.json b/api-ref/source/samples/node-vendor-passthru-response.json new file mode 100644 index 0000000000..28fb22c4c3 --- /dev/null +++ b/api-ref/source/samples/node-vendor-passthru-response.json @@ -0,0 +1,26 @@ +{ + "bmc_reset" : { + "async" : true, + "description" : "", + "http_methods" : [ + "POST" + ], + "attach" : false + }, + "send_raw" : { + "description" : "", + "attach" : false, + "http_methods" : [ + "POST" + ], + "async" : true + }, + "heartbeat" : { + "async" : true, + "attach" : false, + "http_methods" : [ + "POST" + ], + "description" : "" + } +} diff --git a/api-ref/source/samples/nodes-list-details-response.json b/api-ref/source/samples/nodes-list-details-response.json index 17487fd3c0..3a26d2bd6d 100644 --- a/api-ref/source/samples/nodes-list-details-response.json +++ b/api-ref/source/samples/nodes-list-details-response.json @@ -1,64 +1,75 @@ { - "nodes": [ - { - "chassis_uuid": "633f9f21-5bd5-4166-b811-1eb01490c4ab", - "clean_step": {}, - "console_enabled": false, - "created_at": "2016-04-23T10:52:43+00:00", - "driver": "pxe_ssh", - "driver_info": { - "deploy_kernel": "aadebece-ce44-4cf6-a9e8-545f0e8ac9f3", - "deploy_ramdisk": "cfe6f9ce-b2e6-4a7a-9246-0cc7eeb89a71", - "ssh_address": "localhost", - "ssh_key_filename": "/opt/stack/data/ironic/ssh_keys/ironic_key", - "ssh_port": 22, - "ssh_username": "ubuntu", - "ssh_virt_type": "virsh" + "nodes" : [ + { + "reservation" : null, + "driver" : "agent_ipmitool", + "uuid" : "ecddf26d-8c9c-4ddf-8f45-fd57e09ccddb", + "extra" : { + "foo" : "bar" + }, + "provision_updated_at" : null, + "provision_state" : "available", + "clean_step" : {}, + "maintenance" : false, + "driver_internal_info" : {}, + "console_enabled" : false, + "raid_config" : {}, + "target_raid_config" : {}, + "inspection_started_at" : null, + "instance_info" : {}, + "states" : [ + { + "rel" : "self", + "href" : "http://127.0.0.1:6385/v1/nodes/ecddf26d-8c9c-4ddf-8f45-fd57e09ccddb/states" }, - "driver_internal_info": {}, - "extra": {}, - "inspection_finished_at": null, - "inspection_started_at": null, - "instance_info": {}, - "instance_uuid": null, - "last_error": null, - "links": [ - { - "href": "http://localhost:6385/v1/nodes/277c9fe9-a385-4e45-9399-660f3287e48c", - "rel": "self" - }, - { - "href": "http://localhost:6385/nodes/277c9fe9-a385-4e45-9399-660f3287e48c", - "rel": "bookmark" - } - ], - "maintenance": false, - "maintenance_reason": null, - "name": "node-0", - "ports": [ - { - "href": "http://localhost:6385/v1/nodes/277c9fe9-a385-4e45-9399-660f3287e48c/ports", - "rel": "self" - }, - { - "href": "http://localhost:6385/nodes/277c9fe9-a385-4e45-9399-660f3287e48c/ports", - "rel": "bookmark" - } - ], - "power_state": "power off", - "properties": { - "cpu_arch": "x86_64", - "cpus": 1, - "local_gb": 10, - "memory_mb": 1024 + { + "href" : "http://127.0.0.1:6385/nodes/ecddf26d-8c9c-4ddf-8f45-fd57e09ccddb/states", + "rel" : "bookmark" + } + ], + "last_error" : null, + "properties" : { + "cpus" : 1, + "memory_mb" : 1024, + "local_gb" : 10, + "cpu_arch" : "x86_64" + }, + "links" : [ + { + "rel" : "self", + "href" : "http://127.0.0.1:6385/v1/nodes/ecddf26d-8c9c-4ddf-8f45-fd57e09ccddb" }, - "provision_state": "available", - "provision_updated_at": null, - "reservation": null, - "target_power_state": null, - "target_provision_state": null, - "updated_at": "2016-04-23T10:53:37+00:00", - "uuid": "277c9fe9-a385-4e45-9399-660f3287e48c" - } - ] + { + "rel" : "bookmark", + "href" : "http://127.0.0.1:6385/nodes/ecddf26d-8c9c-4ddf-8f45-fd57e09ccddb" + } + ], + "name" : "test_node", + "ports" : [ + { + "rel" : "self", + "href" : "http://127.0.0.1:6385/v1/nodes/ecddf26d-8c9c-4ddf-8f45-fd57e09ccddb/ports" + }, + { + "rel" : "bookmark", + "href" : "http://127.0.0.1:6385/nodes/ecddf26d-8c9c-4ddf-8f45-fd57e09ccddb/ports" + } + ], + "created_at" : "2016-04-20T16:51:03+00:00", + "updated_at" : "2016-05-04T23:24:20+00:00", + "maintenance_reason" : null, + "inspection_finished_at" : null, + "driver_info" : { + "deploy_kernel" : "http://127.0.0.1/images/kernel", + "ipmi_address" : "1.2.3.4", + "deploy_ramdisk" : "http://127.0.0.1/images/ramdisk", + "ipmi_password" : "******", + "ipmi_username" : "ADMIN", + }, + "instance_uuid" : null, + "power_state" : "power off", + "target_power_state" : null, + "target_provision_state" : null + } + ] } diff --git a/api-ref/source/samples/nodes-list-response.json b/api-ref/source/samples/nodes-list-response.json index 8acb802052..a516ed54f3 100644 --- a/api-ref/source/samples/nodes-list-response.json +++ b/api-ref/source/samples/nodes-list-response.json @@ -1,22 +1,22 @@ { - "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" : [ + { + "provision_state" : "available", + "name" : "test_node", + "maintenance" : false, + "uuid" : "ecddf26d-8c9c-4ddf-8f45-fd57e09ccddb", + "links" : [ + { + "href" : "http://127.0.0.1:6385/v1/nodes/ecddf26d-8c9c-4ddf-8f45-fd57e09ccddb", + "rel" : "self" + }, + { + "href" : "http://127.0.0.1:6385/nodes/ecddf26d-8c9c-4ddf-8f45-fd57e09ccddb", + "rel" : "bookmark" + } + ], + "instance_uuid" : null, + "power_state" : "power off" + } + ] } diff --git a/tox.ini b/tox.ini index 3436eba711..0863a7b198 100644 --- a/tox.ini +++ b/tox.ini @@ -72,10 +72,6 @@ commands = # NOTE(sdague): this target does not use constraints because # upstream infra does not yet support it. Once that's fixed, we can # drop the install_command. -# -# we do not used -W here because we are doing some slightly tricky -# things to build a single page document, and as such, we are ok -# ignoring the duplicate stanzas warning. whitelist_externals = bash install_command = pip install -U --force-reinstall {opts} {packages} commands =