openstack/senlin
Code Issues Proposed changes

Nodes API doc

Browse Source 
This patch adds API docs for operations related to node(s).

Change-Id: I1208dde4469994c5d0df5c7b4591a5135b2cc526
This commit is contained in:
tengqm
2016-05-13 03:51:11 -04:00
parent 1acca0222c
commit 2a84245d0c
12 changed files with 587 additions and 7 deletions
Download Patch File Download Diff File Expand all files Collapse all files

8
api-ref/source/clusters.inc
View File

@@ -51,7 +51,7 @@ Response Parameters
- domain: domain
in: cluster
- id: cluster_id
- init_at: cluster_init_at
- init_at: init_at
- max_size: max_size
- metadata: metadata
in: cluster
@@ -141,7 +141,7 @@ Response Parameters
- domain: domain
in: cluster
- id: cluster_id
- init_at: cluster_init_at
- init_at: init_at
- max_size: max_size
- metadata: metadata
in: cluster
@@ -209,7 +209,7 @@ Response Parameters
- domain: domain
in: cluster
- id: cluster_id
- init_at: cluster_init_at
- init_at: init_at
- max_size: max_size
- metadata: metadata
in: cluster
@@ -295,7 +295,7 @@ Response Parameters
- domain: domain
in: cluster
- id: cluster_id
- init_at: cluster_init_at
- init_at: init_at
- max_size: max_size
- metadata: metadata
in: cluster

4
api-ref/source/index.rst
View File

@@ -5,12 +5,14 @@ Clustering API
==============
.. include:: versions.inc
.. include:: policy_types.inc
.. include:: profile_types.inc
.. include:: profiles.inc
.. include:: policy_types.inc
.. include:: policies.inc
.. include:: clusters.inc
.. include:: cluster_policies.inc
.. include:: nodes.inc
.. include:: receivers.inc
.. include:: events.inc
.. include:: webhooks.inc
.. include:: actions.inc

406
api-ref/source/nodes.inc Normal file
View File

@@ -0,0 +1,406 @@
.. -*- rst -*-
=====
Nodes
=====
Lists all nodes, and creates, shows information for, updates, deletes a node.
List nodes
==========
.. rest_method:: GET /v1/nodes
Lists all nodes.
Normal response codes: 200
Error response codes:
- badRequest (400)
- unauthorized (401)
- forbidden (403)
- serviceUnvailable (503)
Request Parameters
------------------
.. rest_parameters:: parameters.yaml
- OpenStack-API-Version: microversion
- limit: limit
- marker: marker
- sort: sort
- global_project: global_project
- cluster_id: cluster_id
in: query
optional: true
- name: name_query
- status: status_query
Response Parameters
-------------------
.. rest_parameters:: parameters.yaml
- nodes: nodes
- cluster_id: cluster_id
in: node
- created_at: created_at
in: node
- data: node_data
- domain: domain
in: node
- id: node_id
- index: index
- init_at: init_at
in: node
- metadata: metadata
in: node
- name: name
in: node
- physical_id: physical_id
- profile_id: node_profile_id
- profile_name: node_profile_name
- project: project
in: node
- role: role
- status: node_status
- status_reason: status_reason
in: node
- updated_at: updated_at
in: node
- user: user
in: node
Response Example
----------------
.. literalinclude:: samples/node-list-response.json
:language: javascript
Create node
===========
.. rest_method:: POST /v1/nodes
Creates a node.
Normal response codes: 202
Error response codes:
- badRequest (400)
- unauthorized (401)
- forbidden (403)
- serviceUnvailable (503)
Request Parameters
------------------
.. rest_parameters:: parameters.yaml
- OpenStack-API-Version: microversion
- node: node
- role: role
optional: true
- profile_id: profile_id_url
in: node
- cluster_id: cluster_id_url
in: node
optional: true
- name: name
in: node
optional: true
- metadata: metadata
in: node
optional: true
Request Example
---------------
.. literalinclude:: samples/node-create-request.json
:language: javascript
Response Parameters
-------------------
.. rest_parameters:: parameters.yaml
- location: location
- node: node
- cluster_id: cluster_id
in: node
- created_at: created_at
in: node
- data: node_data
- domain: domain
in: node
- id: node_id
- index: index
- init_at: init_at
in: node
- metadata: metadata
in: node
- name: name
in: node
- physical_id: physical_id
- profile_id: node_profile_id
- profile_name: node_profile_name
- project: project
in: node
- role: role
- status: node_status
- status_reason: status_reason
in: node
- updated_at: updated_at
in: node
- user: user
in: node
Response Example
----------------
.. literalinclude:: samples/node-create-response.json
:language: javascript
Show node details
=================
.. rest_method:: GET /v1/nodes/{node_id}
Shows details about a node.
Normal response codes: 200
Error response codes:
- badRequest (400)
- unauthorized (401)
- forbidden (403)
- notFound (404)
- serviceUnvailable (503)
Request Parameters
------------------
.. rest_parameters:: parameters.yaml
- OpenStack-API-Version: microversion
- node_id: node_id_url
- show_details: show_details
optional: true
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: 202
Error response codes:
- badRequest (400)
- unauthorized (401)
- forbidden (403)
- notFound (404)
- serviceUnvailable (503)
Request
-------
.. rest_parameters:: parameters.yaml
- OpenStack-API-Version: microversion
- node_id: node_id_url
- node: node
- name: name
in: node
optional: true
- profile_id: profile_id_url
in: node
optional: true
- role: role
optional: true
- metadata: metadata
in: node
optional: true
Request Example
---------------
.. literalinclude:: samples/node-update-request.json
:language: javascript
Response Parameters
-------------------
.. rest_parameters:: parameters.yaml
- location: location
- node: node
- cluster_id: cluster_id
in: node
- created_at: created_at
in: node
- data: node_data
- domain: domain
in: node
- id: node_id
- index: index
- init_at: init_at
in: node
- metadata: metadata
in: node
- name: name
in: node
- physical_id: physical_id
- profile_id: node_profile_id
- profile_name: node_profile_name
- project: project
in: node
- role: role
- status: node_status
- status_reason: status_reason
in: node
- updated_at: updated_at
in: node
- user: user
in: node
Response Example
----------------
.. literalinclude:: samples/node-show-response.json
:language: javascript
Delete node
===========
.. rest_method:: DELETE /v1/nodes/{node_id}
Deletes a node.
Normal response codes: 202
Error response codes:
- badRequest (400)
- unauthorized (401)
- forbidden (403)
- notFound (404)
- serviceUnvailable (503)
Request Parameters
------------------
.. rest_parameters:: parameters.yaml
- OpenStack-API-Version: microversion
- node_id: node_id_url
Response Parameters
-------------------
.. rest_parameters:: parameters.yaml
- location: location
Check a Node's Health
=====================
.. rest_method:: POST /v1/nodes/{node_id}/actions
Check the health status of the specified node.
Normal response codes: 202
Error response codes:
- badRequest (400)
- unauthorized (401)
- forbidden (403)
- notFound (404)
- serviceUnvailable (503)
Request Parameters
------------------
.. rest_parameters:: parameters.yaml
- node_id: node_id_url
- action: action_request
The ``action_name`` in the body must be ``check``.
Request Example
---------------
.. literalinclude:: samples/node-check-request.json
:language: javascript
Response Parameters
-------------------
.. rest_parameters:: parameters.yaml
- location: location
Recover a Node to Healthy Status
================================
.. rest_method:: POST /v1/nodes/{node_id}/actions
Recover the specified node to its healthy status.
Normal response codes: 202
Error response codes:
- badRequest (400)
- unauthorized (401)
- forbidden (403)
- notFound (404)
- serviceUnvailable (503)
Request Parameters
------------------
.. rest_parameters:: parameters.yaml
- node_id: node_id_url
- action: action_request
The ``action_name`` in the body must be ``recover``.
Request Example
---------------
.. literalinclude:: samples/node-recover-request.json
:language: javascript
Response Parameters
-------------------
.. rest_parameters:: parameters.yaml
- location: location

80
api-ref/source/parameters.yaml
View File

@@ -317,11 +317,17 @@ global_project:
call returns all resources from all projects. Default is ``false``, which
returns only resources in the current project.
cluster_init_at:
index:
type: integer
in: node
description: |
An integer that uniquely identifies a node within its owning cluster.
init_at:
type: string
in: cluster
description: |
The date and time when the cluster object was initialized. The date and
The date and time when the object was initialized. The date and
time stamp format is ISO8601: ``CCYY-MM-DDThh:mm:ssZ``. For example:
``2016-01-18T00:00:00Z``
@@ -396,6 +402,55 @@ name_query:
description: |
Filters the response by the ``name`` property of the resource.
node:
type: object
in: body
description: |
A structured description of a node object.
node_data:
type: object
in: node
description: |
A map containing key-value pairs associated with a node object.
node_id:
type: UUID
in: node
description: |
A UUID string that uniquely identifies a node object.
node_id_url:
type: string
in: URL
description: |
The name, short-ID or UUID of a node object.
node_profile_id:
type: UUID
in: node
description: |
The UUID of the profile object referenced by the current node object.
node_profile_name:
type: string
in: node
description: |
The name of the profile object referenced by the current node object.
node_status:
type: string
in: node
description: |
The string representation of the current status of the node object.
nodes:
type: list
in: body
description: |
A list of node objects.
obj_id:
type: UUID
in: event
@@ -439,6 +494,12 @@ obj_type_query:
Use this filter multiple times to filter by multiple objects. A valid
value is ``CLUSTER`` or ``NODE``.
physical_id:
type: UUID
in: node
description: |
The UUID of the physical resource represented by the node object.
policy_type:
type: object
in: body
@@ -686,6 +747,12 @@ request_id:
A unique ID for tracking service request. The request ID associated
with the request by default appears in the service logs.
role:
type: string
in: node
description: |
A string describing the role played by a node inside a cluster.
scale_count:
type: integer
in: action
@@ -696,6 +763,15 @@ scale_count:
The interpretation is depending on the action requested. Default value is
1.
show_details:
type: bool
in: query
optional: true
default: false
description: |
A boolean indicating whether the detailed information about the physical
resource associated with the node object will be returned.
sort:
type: string
in: query

6
api-ref/source/samples/cluster-update-policy-request.json Normal file
View File

@@ -0,0 +1,6 @@
{
"update_policy": {
"policy_id": "dp01",
"enabled": false
}
}

3
api-ref/source/samples/node-check-request.json Normal file
View File

@@ -0,0 +1,3 @@
{
"check": {}
}

9
api-ref/source/samples/node-create-request.json Normal file
View File

@@ -0,0 +1,9 @@
{
"node": {
"cluster_id": null,
"metadata": {},
"name": "node009",
"profile_id": "mystack",
"role": "master"
}
}

22
api-ref/source/samples/node-create-response.json Normal file
View File

@@ -0,0 +1,22 @@
{
"node": {
"cluster_id": null,
"created_at": null,
"data": {},
"domain": null,
"id": "0df0931b-e251-4f2e-8719-4ebfda3627ba",
"index": -1,
"init_at": "2015-03-05T08:53:15",
"metadata": {},
"name": "node009",
"physical_id": "",
"profile_id": "edc63d0a-2ca4-48fa-9854-27926da76a4a",
"profile_name": "mystack",
"project": "6e18cc2bdbeb48a5b3cad2dc499f6804",
"role": "master",
"status": "INIT",
"status_reason": "Initializing",
"updated_at": null,
"user": "5e5bf8027826429c96af157f68dc9072"
}
}

24
api-ref/source/samples/node-list-response.json Normal file
View File

@@ -0,0 +1,24 @@
{
"nodes": [
{
"cluster_id": "e395be1e-8d8e-43bb-bd6c-943eccf76a6d",
"created_at": "2016-05-13T07:02:20",
"data": {},
"domain": null,
"id": "82fe28e0-9fcb-42ca-a2fa-6eb7dddd75a1",
"index": 2,
"init_at": "2016-05-13T07:02:04",
"metadata": {},
"name": "node-e395be1e-002",
"physical_id": "66a81d68-bf48-4af5-897b-a3bfef7279a8",
"profile_id": "d8a48377-f6a3-4af4-bbbb-6e8bcaa0cbc0",
"profile_name": "pcirros",
"project": "eee0b7c083e84501bdd50fb269d2a10e",
"role": "",
"status": "ACTIVE",
"status_reason": "Creation succeeded",
"updated_at": null,
"user": "ab79b9647d074e46ac223a8fa297b846"
}
]
}

5
api-ref/source/samples/node-recover-request.json Normal file
View File

@@ -0,0 +1,5 @@
{
"recover": {
"operation": "rebuild"
}
}

22
api-ref/source/samples/node-show-response.json Normal file
View File

@@ -0,0 +1,22 @@
{
"node": {
"cluster_id": null,
"created_at": "2015-02-10T12:03:16",
"data": {},
"domain": null,
"id": "d5779bb0-f0a0-49c9-88cc-6f078adb5a0b",
"index": -1,
"init_at": "2015-02-10T12:03:13",
"metadata": {},
"name": "node1",
"physical_id": "f41537fa-22ab-4bea-94c0-c874e19d0c80",
"profile_id": "edc63d0a-2ca4-48fa-9854-27926da76a4a",
"profile_name": "mystack",
"project": "6e18cc2bdbeb48a5b3cad2dc499f6804",
"role": null,
"status": "ACTIVE",
"status_reason": "Creation succeeded",
"updated_at": "2015-03-04T04:58:27",
"user": "5e5bf8027826429c96af157f68dc9072"
}
}

5
api-ref/source/samples/node-update-request.json Normal file
View File

@@ -0,0 +1,5 @@
{
"node": {
"name": "new_node_name"
}
}