x/trio2o
Code Issues Proposed changes

Documentation on pod and pod binding

Browse Source 
1. What is the problem
Pod and pod binding functions have been implemented, but the documentation
is not there.

2. What is the solution for the problem
Pod and pod binding have four main public functions respectively. For pod,
there are four public functions: 1) get pod list. 2) show a single pod in
detail. 3) create a pod. 4) delete a pod. Likewise, pod binding has four
similar public functions to pod. The file /tricircle/doc/source/api_v1.rst
includes the request and response explanation about each function.

3. What the features need to be implemented to the Tricircle to
realize the solution
None.

Change-Id: Ic530326bb00556b5b9e8d4e4699eaa35ebf01e61
This commit is contained in:
Dongfeng Huang 2016-08-17 15:44:41 +08:00
parent 707c914e30
commit 38d35143db
1 changed files with 486 additions and 109 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

617
doc/source/api_v1.rst
View File

@ -1,158 +1,535 @@
================
Tricircle API v1
================
This API describes the ways of interacting with Tricircle service via
HTTP protocol using Representational State Transfer(ReST).
Application Root [/]
====================
Application Root provides links to all possible API methods for Tricircle. URLs
for other resources described below are relative to Application Root.
API v1 Root [/v1/]
==================
All API v1 URLs are relative to API v1 root.
Pod [/pods/{pod_id}]
=======================
A pod represents a region in Keystone. When operating a pod, Tricircle
The Tricircle Admin API
=======================
This Admin API describes the ways of interacting with the Tricircle service
via HTTP protocol using Representational State Transfer(ReST).
API Versions
============
In order to bring new features to users over time, versioning is supported
by the Tricircle. The latest version of the Tricircle is v1.0.
The Version APIs work the same as other APIs as they still require
authentication.
+------------------+----------------+-----+-----------------------------------------------+
|**GET** |/ | |List All Major versions |
| | | | |
|**GET** |/{api_version} | |Show Details of Specific API Version |
+------------------+----------------+-----+-----------------------------------------------+
Service URLs
============
All API calls through the rest of this document require authentication with
the OpenStack Identity service. They also require a base service url that can
be got from the OpenStack Tricircle endpoint. This will be the root url that
every call below will be added to build a full path.
For instance, if the Tricircle service url is http://127.0.0.1:19999/v1.0 then
the full API call for /pods is http://127.0.0.1:19999/v1.0/pods.
As such, for the rest of this document we will leave out the root url where
GET /pods really means GET {tricircle_service_url}/pods.
Pod
===
A pod represents a region in Keystone. When operating a pod, the Tricircle
decides the correct endpoints to send request based on the region of the pod.
Considering the 2-layers architecture of Tricircle, we also have 2 kinds of
pods: top pod and bottom pod. A pod has the following attributes:
- pod_id
- pod_name
- pod_az_name
- dc_name
- az_name
Considering the 2-layers architecture of the Tricircle, we also have two kinds
of pods: top pod and bottom pod.
**pod_id** is automatically generated when creating a site.
+------------------+---------+-----------------------------------+------------------------+
|**GET** |/pods | |Retrieve Pod List |
+------------------+---------+-----------------------------------+------------------------+
**pod_name** is specified by user but **MUST** match the region name
registered in Keystone. When creating a bottom pod, Tricircle automatically
creates a host aggregate and assigns the new availability zone id to
This fetches all the pods including top pod and bottom pod(s).
**az_name**. When **az_name** is empty, that means this pod is top region,
no host aggregate will be generated. If **az_name** is not empty, that means
this pod will belong to this availability zone. Multiple pods with same
**az_name** means that these pods are under same availability zone.
Normal Response Code: 200
**pod_az_name** is the az name in the bottom pod, it could be empty, if empty,
then no az parameter will be added to the request to the bottom pod. If the
**pod_az_name** is different than **az_name**, then the az parameter will be
replaced to the **pod_az_name** when the request is forwarded to regarding
bottom pod.
**Response**
**dc_name** is the name of the data center where the pod is located.
Pods contains a list of pod instance whose attributes are described in the
following table.
URL Parameters
--------------
- pod_id: Pod id
+-----------+-------+---------------+-----------------------------------------------------+
|Name |In | Type | Description |
+===========+=======+===============+=====================================================+
|pod_id |body | string |pod_id is a uuid attribute of the pod object. |
+-----------+-------+---------------+-----------------------------------------------------+
|pod_name |body | string |pod_name is specified by user but must match the |
| | | |region name registered in Keystone. When creating a |
| | | |bottom pod, the Tricircle automatically creates a |
| | | |host aggregation and assigns the new availability |
| | | |zone id to it. |
+-----------+-------+---------------+-----------------------------------------------------+
|az_name |body | string |When az_name is empty, it means this pod is a top |
| | | |region, no host aggregation will be generated. If |
| | | |az_name is not empty, it means the pod will belong |
| | | |to this availability zone. Multiple pods with the |
| | | |same az_name means that these pods are under the same|
| | | |availability zone. |
+-----------+-------+---------------+-----------------------------------------------------+
|pod_az_name|body | string |pod_az_name is the az name in the bottom pod, it |
| | | |could be empty. If it's empty, then no az parameter |
| | | |will be added to the request to the bottom pod. If |
| | | |the pod_az_name is different from az_name, then the |
| | | |az parameter will be replaced with the pod_az_name |
| | | |when the request is forwarded to relevant bottom pod.|
+-----------+-------+---------------+-----------------------------------------------------+
|dc_name |body | string |dc_name is the name of the data center where the pod |
| | | |is located at. |
+-----------+-------+---------------+-----------------------------------------------------+
Models
------
::
**Response Example**
{
"pod_id": "302e02a6-523c-4a92-a8d1-4939b31a788c",
"pod_name": "pod1",
"pod_az_name": "az1",
"dc_name": "data center 1",
"az_name": "az1"
}
This is an example of response information for GET /pods.
Retrieve Pod List [GET]
------------------------
- URL: /pods
- Status: 200
- Returns: List of Pods
Response
::
{
"pods": [
{
"pod_id": "f91ca3a5-d5c6-45d6-be4c-763f5a2c4aa3",
"pod_name": "RegionOne",
"dc_name": "",
"pod_az_name": "",
"pod_id": "1a51bee7-10f0-47e8-bb4a-70f51394069c",
"az_name": "",
"pod_name": "RegionOne"
},
{
"pod_id": "302e02a6-523c-4a92-a8d1-4939b31a788c",
"pod_name": "pod1",
"pod_az_name": "az1",
"dc_name": "data center 1",
"az_name": "az1"
"dc_name": "",
"pod_az_name": "",
"pod_id": "22cca6ad-b791-4805-af14-923c5224fcd2",
"az_name": "az2",
"pod_name": "Pod2"
},
{
"dc_name": "",
"pod_az_name": "",
"pod_id": "3c22e5d4-5fed-45ed-a1e9-d532668cedc2",
"az_name": "az1",
"pod_name": "Pod1"
}
]
}
Retrieve a Single Pod [GET]
----------------------------
- URL: /pods/pod_id
- Status: 200
- Returns: Pod
+------------------+-------------------+-----------------------+-------------------------------+
|**GET** |/pods/{pod_id} | |Retrieve a Single Pod |
+------------------+-------------------+-----------------------+-------------------------------+
This fetches a single pod such as a top pod or a bottom pod.
Normal Response Code: 200
**Request**
+-----------+-------+---------------+-----------------------------------------------------+
|Name |In | Type | Description |
+===========+=======+===============+=====================================================+
|pod_id |path | string |pod_id is a uuid attribute of the pod object. |
+-----------+-------+---------------+-----------------------------------------------------+
**Response**
Here are two kinds of pods, including top pod and bottom pod. az_name is one
of its attributes. If the az_name is empty, it means a top pod otherwise it
means a bottom pod. All of its attributes are described in the following table.
+-----------+-------+---------------+-----------------------------------------------------+
|Name |In | Type | Description |
+===========+=======+===============+=====================================================+
|pod_id |body | string |pod_id is a uuid attribute of the pod object. |
+-----------+-------+---------------+-----------------------------------------------------+
|pod_name |body | string |pod_name is specified by user but must match the |
| | | |region name registered in Keystone. When creating a |
| | | |bottom pod, the Tricircle automatically creates a |
| | | |host aggregation and assigns the new availability |
| | | |zone id to it. |
+-----------+-------+---------------+-----------------------------------------------------+
|az_name |body | string |When az_name is empty, it means this pod is a top |
| | | |region, no host aggregation will be generated. If |
| | | |az_name is not empty, it means the pod will belong |
| | | |to this availability zone. Multiple pods with the |
| | | |same az_name means that these pods are under the same|
| | | |availability zone. |
+-----------+-------+---------------+-----------------------------------------------------+
|pod_az_name|body | string |pod_az_name is the az name in the bottom pod, it |
| | | |could be empty. If it's empty, then no az parameter |
| | | |will be added to the request to the bottom pod. If |
| | | |the pod_az_name is different from az_name, then the |
| | | |az parameter will be replaced with the pod_az_name |
| | | |when the request is forwarded to relevant bottom pod.|
+-----------+-------+---------------+-----------------------------------------------------+
|dc_name |body | string |dc_name is the name of the data center where the pod |
| | | |is located at. |
+-----------+-------+---------------+-----------------------------------------------------+
**Response Example**
This is an example of response information for GET /pods/{pod_id}.
Response
::
{
"pod": {
"pod_id": "302e02a6-523c-4a92-a8d1-4939b31a788c",
"pod_name": "pod1",
"pod_az_name": "az1",
"dc_name": "data center 1",
"az_name": "az1"
}
}
Create a Pod [POST]
--------------------
- URL: /pods
- Status: 201
- Returns: Created Pod
Request (application/json)
::
# for the pod represent the region where the Tricircle is running
{
"pod": {
"pod_name": "RegionOne",
}
}
# for the bottom pod which is managed by Tricircle
{
"pod": {
"pod_name": "pod1",
"pod_az_name": "az1",
"dc_name": "data center 1",
"az_name": "az1"
}
}
Response
::
# for the pod represent the region where the Tricircle is running
{
"pod": {
"pod_id": "302e02a6-523c-4a92-a8d1-4939b31a788c",
"pod_name": "RegionOne",
"pod_az_name": "",
"dc_name": "",
"az_name": ""
"pod_az_name": "",
"pod_id": "3c22e5d4-5fed-45ed-a1e9-d532668cedc2",
"az_name": "az1",
"pod_name": "Pod1"
}
}
# for the bottom pod which is managed by Tricircle
+---------------+-------+------------------------------------+--------------------+
|**POST** |/pods | |Create a Pod |
+---------------+-------+------------------------------------+--------------------+
This creates a pod such as a top pod or a bottom pod.
Normal Response Code: 200
**Request**
Some essential attributes of the pod instance are required and described
in the following table.
+-----------+-------+---------------+-----------------------------------------------------+
|Name |In | Type | Description |
+===========+=======+===============+=====================================================+
|pod_name |body | string |pod_name is specified by user but must match the |
| | | |region name registered in Keystone. When creating a |
| | | |bottom pod, the Tricircle automatically creates a |
| | | |host aggregation and assigns the new availability |
| | | |zone id to it. |
+-----------+-------+---------------+-----------------------------------------------------+
|az_name |body | string |When az_name is empty, it means this pod is a top |
| | | |region, no host aggregation will be generated. If |
| | | |az_name is not empty, it means the pod will belong |
| | | |to this availability zone. Multiple pods with the |
| | | |same az_name means that these pods are under the same|
| | | |availability zone. |
+-----------+-------+---------------+-----------------------------------------------------+
|pod_az_name|body | string |pod_az_name is the az name in the bottom pod, it |
| | | |could be empty. If it's empty, then no az parameter |
| | | |will be added to the request to the bottom pod. If |
| | | |the pod_az_name is different from az_name, then the |
| | | |az parameter will be replaced with the pod_az_name |
| | | |when the request is forwarded to relevant bottom pod.|
+-----------+-------+---------------+-----------------------------------------------------+
|dc_name |body | string |dc_name is the name of the data center where the pod |
| | | |is located at. |
+-----------+-------+---------------+-----------------------------------------------------+
**Response**
An id is assigned to a pod instance when it's created. All of its attributes
are listed below.
+-----------+-------+---------------+-----------------------------------------------------+
|Name |In | Type | Description |
+===========+=======+===============+=====================================================+
|pod_id |body | string |pod_id is automatically generated when creating a pod|
+-----------+-------+---------------+-----------------------------------------------------+
|pod_name |body | string |pod_name is specified by user but must match the |
| | | |region name registered in Keystone. When creating a |
| | | |bottom pod, the Tricircle automatically creates a |
| | | |host aggregation and assigns the new availability |
| | | |zone id to it. |
+-----------+-------+---------------+-----------------------------------------------------+
|az_name |body | string |When az_name is empty, it means this pod is a top |
| | | |region, no host aggregation will be generated. If |
| | | |az_name is not empty, it means the pod will belong |
| | | |to this availability zone. Multiple pods with the |
| | | |same az_name means that these pods are under the same|
| | | |availability zone. |
+-----------+-------+---------------+-----------------------------------------------------+
|pod_az_name|body | string |pod_az_name is the az name in the bottom pod, it |
| | | |could be empty. If it's empty, then no az parameter |
| | | |will be added to the request to the bottom pod. If |
| | | |the pod_az_name is different from az_name, then the |
| | | |az parameter will be replaced with the pod_az_name |
| | | |when the request is forwarded to relevant bottom pod.|
+-----------+-------+---------------+-----------------------------------------------------+
|dc_name |body | string |dc_name is the name of the data center where the pod |
| | | |is located at. |
+-----------+-------+---------------+-----------------------------------------------------+
**Request Example**
This is an example of request information for POST /pods.
::
{
"pod": {
"pod_id": "302e02a6-523c-4a92-a8d1-4939b31a788c",
"pod_name": "pod1",
"pod_name": "Pod3",
"az_name": "az1",
"pod_az_name": "az1",
"dc_name": "data center 1"
}
}
**Response Example**
This is an example of response information for POST /pods.
::
{
"pod": {
"dc_name": "data center 1",
"az_name": "az1"
"pod_az_name": "az1",
"pod_id": "e02e03b8-a94f-4eb1-991e-a8a271cc2313",
"az_name": "az1",
"pod_name": "Pod3"
}
}
+------------------+-----------------+------------------------+-------------------------+
|**DELETE** |/pods/{pod_id} | |Delete a Pod |
+------------------+-----------------+------------------------+-------------------------+
This deletes a pod such as a top pod or a bottom pod from availability-zone.
Normal Response Code: 200
**Request**
+-----------+-------+---------------+-----------------------------------------------------+
|Name |In | Type | Description |
+===========+=======+===============+=====================================================+
|pod_id |path | string |pod_id is a uuid attribute of the pod object. |
+-----------+-------+---------------+-----------------------------------------------------+
**Response**
There is no response. But we can list all the pods to verify whether the
specific pod has been deleted or not.
Pod Binding
===========
A pod binding represents a mapping relationship between tenant and pod. Pods
are classified into different categories. A tenant will be bound to different
pod groups for different purposes.
+------------------+------------+---------------------+-------------------------------------+
|**GET** |/bindings | |Retrieve Pod Binding List |
+------------------+------------+---------------------+-------------------------------------+
This fetches all the pod bindings.
Normal Response Code: 200
**Response**
Pod bindings contain one or more binding instances whose attributes
are listed in the following table.
+-------------+-------+---------------+-----------------------------------------------------+
|Name |In | Type | Description |
+=============+=======+===============+=====================================================+
|tenant_id |body | string |tenant_id is automatically generated when adding a |
| | | |uuid of a project object in KeyStone. "Tenant" is an |
| | | |old term for a project in Keystone. Starting in API |
| | | |version 3, "project" is the preferred term. |
| | | |Accordingly, project_id is used instead of tenant_id.|
+-------------+-------+---------------+-----------------------------------------------------+
|pod_id |body | string |pod_id is a uuid attribute of the pod object. |
+-------------+-------+---------------+-----------------------------------------------------+
|id |body | string |id is a uuid attribute of the pod binding. It is |
| | | |automatically generated when new binding relation |
| | | |happens between tenant and pod. |
+-------------+-------+---------------+-----------------------------------------------------+
|created_at |body | date |created time of the pod binding. |
+-------------+-------+---------------+-----------------------------------------------------+
|updated_at |body | date |updated time of the pod binding. |
+-------------+-------+---------------+-----------------------------------------------------+
**Response Example**
This is an example of response information for GET /bindings.
::
{
"pod_bindings": [
{
"updated_at": null,
"tenant_id": "1782b3310f144836aa73c1ac5117d8da",
"created_at": "2016-06-03 07:37:50",
"id": "6ba7510c-baeb-44ad-8815-c4d229b52e46",
"pod_id": "22cca6ad-b791-4805-af14-923c5224fcd2"
},
{
"updated_at": null,
"tenant_id": "1782b3310f144836aa73c1ac5117d8da",
"created_at": "2016-06-03 07:37:06",
"id": "f0a54f30-6208-499d-b087-0ac64f6f2756",
"pod_id": "3c22e5d4-5fed-45ed-a1e9-d532668cedc2"
}
]
}
+------------------+---------------+-------------+---------------------------------------+
|**GET** |/bindings/{id} | |Retrieve a Single Pod Binding |
+------------------+---------------+-------------+---------------------------------------+
This fetches a single pod binding.
Normal Response Code: 200
**Request**
+-------------+-------+---------------+-----------------------------------------------------+
|Name |In | Type | Description |
+=============+=======+===============+=====================================================+
|id |path | string |id is a uuid attribute of the pod binding. It is |
| | | |automatically generated when new binding relation |
| | | |happens between tenant and pod. |
+-------------+-------+---------------+-----------------------------------------------------+
**Response**
Pod binding represents a mapping relationship between tenant and pod. All
of its attributes are described in the following table.
+-------------+-------+---------------+-----------------------------------------------------+
|Name |In | Type | Description |
+=============+=======+===============+=====================================================+
|tenant_id |body | string |tenant_id is automatically generated when adding a |
| | | |uuid of a project object in KeyStone. "Tenant" is an |
| | | |old term for a project in Keystone. Starting in API |
| | | |version 3, "project" is the preferred term. |
| | | |Accordingly, project_id is used instead of tenant_id.|
+-------------+-------+---------------+-----------------------------------------------------+
|pod_id |body | string |pod_id is a uuid attribute of the pod object. |
+-------------+-------+---------------+-----------------------------------------------------+
|id |body | string |id is a uuid attribute of the pod binding. It is |
| | | |automatically generated when new binding relation |
| | | |happens between tenant and pod. |
+-------------+-------+---------------+-----------------------------------------------------+
|created_at |body | date |created time of the pod binding. |
+-------------+-------+---------------+-----------------------------------------------------+
|updated_at |body | date |updated time of the pod binding. |
+-------------+-------+---------------+-----------------------------------------------------+
**Response Example**
This is an example of response information for GET /bindings/{id}.
::
{
"pod_binding": {
"updated_at": null,
"tenant_id": "1782b3310f144836aa73c1ac5117d8da",
"created_at": "2016-06-03 07:37:06",
"id": "f0a54f30-6208-499d-b087-0ac64f6f2756",
"pod_id": "3c22e5d4-5fed-45ed-a1e9-d532668cedc2"
}
}
+---------------+-----------+--------------------+------------------------------------------+
|**POST** |/bindings | |Create a Pod Binding |
+---------------+-----------+--------------------+------------------------------------------+
This creates a pod binding.
Normal Response Code: 200
**Request**
Some essential attributes of the pod binding instance are required and
described in the following table.
+-------------+-------+---------------+-----------------------------------------------------+
|Name |In | Type | Description |
+=============+=======+===============+=====================================================+
|tenant_id |body | string |tenant_id is automatically generated when adding a |
| | | |uuid of a project object in KeyStone. "Tenant" is an |
| | | |old term for a project in Keystone. Starting in API |
| | | |version 3, "project" is the preferred term. |
| | | |Accordingly, project_id is used instead of tenant_id.|
+-------------+-------+---------------+-----------------------------------------------------+
|pod_id |body | string |pod_id is a uuid attribute of the pod object. |
+-------------+-------+---------------+-----------------------------------------------------+
**Response**
An id is assigned to a pod binding instance when it is created, and some other
attribute values are given meanwhile. All of its fields are listed below.
+-------------+-------+---------------+-----------------------------------------------------+
|Name |In | Type | Description |
+=============+=======+===============+=====================================================+
|tenant_id |body | string |tenant_id is automatically generated when adding a |
| | | |uuid of a project object in KeyStone. "Tenant" is an |
| | | |old term for a project in Keystone. Starting in API |
| | | |version 3, "project" is the preferred term. |
| | | |Accordingly, project_id is used instead of tenant_id.|
+-------------+-------+---------------+-----------------------------------------------------+
|pod_id |body | string |pod_id is a uuid attribute of the pod object. |
+-------------+-------+---------------+-----------------------------------------------------+
|id |body | string |id is a uuid attribute of the pod binding. It is |
| | | |automatically generated when new binding relation |
| | | |happens between tenant and pod. |
+-------------+-------+---------------+-----------------------------------------------------+
|created_at |body | date |created time of the pod binding. |
+-------------+-------+---------------+-----------------------------------------------------+
|updated_at |body | date |updated time of the pod binding. |
+-------------+-------+---------------+-----------------------------------------------------+
**Request Example**
This is an example of request information for POST /bindings.
::
{
"pod_binding": {
"tenant_id": "1782b3310f144836aa73c1ac5117d8da",
"pod_id": "e02e03b8-a94f-4eb1-991e-a8a271cc2313"
}
}
**Response Example**
This is an example of response information for POST /bindings.
::
{
"pod_binding": {
"updated_at": null,
"tenant_id": "1782b3310f144836aa73c1ac5117d8da",
"created_at": "2016-08-18 14:06:33",
"id": "b17ac347-c898-4cea-a09d-7b0a6ec34f56",
"pod_id": "e02e03b8-a94f-4eb1-991e-a8a271cc2313"
}
}
+---------------+----------------+---------------+------------------------------------------+
|**DELETE** |/bindings/{id} | |Delete a Pod Binding |
+---------------+----------------+---------------+------------------------------------------+
This deletes a pod binding.
Normal Response Code: 200
**Request**
+-----------+-------+---------------+-----------------------------------------------------+
|Name |In | Type | Description |
+===========+=======+===============+=====================================================+
|id |path | string |id is a uuid attribute of the pod binding. It is |
| | | |automatically generated when new binding relation |
| | | |happens between tenant and pod. |
+-----------+-------+---------------+-----------------------------------------------------+
**Response**
There is no response. But we can list all the pod bindings to verify
whether the specific pod binding has been deleted or not.