x/trio2o
Code Issues Proposed changes
trio2o/doc/source/api_v1.rst
joehuang 180f68eac8 Remove networking related code from the Trio2o 
1. What is the problem?
Networking related code is still in the repository of
the Trio2o project.

2. What is the solution to the problem?
According to the blueprint for the Trio2o cleaning:
https://blueprints.launchpad.net/trio2o/+spec/trio2o-code-cleaning
Networking related code which is forked from the Tricircle
repository should be removed from the Trio2o repository.
After the cleanning, the Trio2o should be able to run independently.
There are lots of things to clean and update, and have to do it in
one huge patch, otherwise the code in Trio2o will not be able to run
and tested properply:
1). Remove netwoking operaion from server controller
2). Update devstack script
3). Update installation guide
4). Update README
5). Remove network folder and network related unit tests
6). Rename Tricircle to Trio2o in all source code

THE MEANING OF FILE OPERATION:
D: delete a file
R: rename a file to another name
A: add a new file
C: copy a file

3. What the features need to be implemented to the Tricircle to realize
the solution?
No new features.

Change-Id: I0b48ee38280e25ba6294ca3d5b7a0673cb368ed4
Signed-off-by: joehuang <joehuang@huawei.com>
2016-11-14 02:12:48 -05:00

536 lines
28 KiB
ReStructuredText
Raw Blame History

=======================
The Trio2o Admin API
=======================
This Admin API describes the ways of interacting with the Trio2o 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 Trio2o. The latest version of the Trio2o 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 Trio2o endpoint. This will be the root url that
every call below will be added to build a full path.
For instance, if the Trio2o 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 {trio2o_service_url}/pods.
Pod
===
A pod represents a region in Keystone. When operating a pod, the Trio2o
decides the correct endpoints to send request based on the region of the pod.
Considering the 2-layers architecture of the Trio2o, we also have two kinds
of pods: top pod and bottom pod.
+------------------+---------+-----------------------------------+------------------------+
|**GET** |/pods | |Retrieve Pod List |
+------------------+---------+-----------------------------------+------------------------+
This fetches all the pods including top pod and bottom pod(s).
Normal Response Code: 200
**Response**
Pods contains a list of pod instance whose 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 Trio2o 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.
::
{
"pods": [
{
"dc_name": "",
"pod_az_name": "",
"pod_id": "1a51bee7-10f0-47e8-bb4a-70f51394069c",
"az_name": "",
"pod_name": "RegionOne"
},
{
"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"
}
]
}
+------------------+-------------------+-----------------------+-------------------------------+
|**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 Trio2o 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}.
::
{
"pod": {
"dc_name": "",
"pod_az_name": "",
"pod_id": "3c22e5d4-5fed-45ed-a1e9-d532668cedc2",
"az_name": "az1",
"pod_name": "Pod1"
}
}
+---------------+-------+------------------------------------+--------------------+
|**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 Trio2o 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 Trio2o 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_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",
"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.
View Git Blame Copy Permalink