Removal of the original API documentation
This change removes the original API documentation and moves the os_api_ref based one to its place. Change-Id: If1ebfc434c28a0bf4be05f09bd3b0260d1ffd2b9 Signed-off-by: Gergely Csatari <gergely.csatari@nokia.com>
This commit is contained in:
parent
b3b534de79
commit
bd5238a330
|
@ -1,187 +0,0 @@
|
|||
.. _admin:
|
||||
|
||||
=====
|
||||
Admin
|
||||
=====
|
||||
|
||||
These APIs are meant for infrastructure admin who is in charge of triggering
|
||||
the rolling maintenance and upgrade workflows.
|
||||
|
||||
Create maintenance session
|
||||
==========================
|
||||
|
||||
:POST: /v1/maintenance/
|
||||
|
||||
Create a new maintenance session. You can specify a list of 'hosts' to be
|
||||
maintained or have an empty list to indicate those should be self-discovered.
|
||||
You need to have an initial state for the workflow in 'state'. 'workflow'
|
||||
indicates the name of a Python plug-in to be used in the maintenance.
|
||||
|
||||
--Not yet implemented--
|
||||
|
||||
'download' can contain a list of URLs from where the needed software changes
|
||||
are downloaded. It can also provide plug-ins to be used.
|
||||
|
||||
'actions' can contain a list of action plug-ins to be called during the workflow
|
||||
plug-in execution. It is up to workflow plug-in implementation to support
|
||||
different type of plug-ins or to decide how they are executed. Fenix default
|
||||
workflow supported types and execution order is defined below.
|
||||
|
||||
Request
|
||||
-------
|
||||
|
||||
+-------------------+----------------------+--------------------------------------------+-------------+-----------+
|
||||
| Name | Type | Description | Implemented | Mandatory |
|
||||
+===================+======================+============================================+=============+===========+
|
||||
| hosts | list of strings | Hosts to be maintained. An empty list can | Yes | Yes |
|
||||
| | | indicate hosts are to be discovered. | | |
|
||||
+-------------------+----------------------+--------------------------------------------+-------------+-----------+
|
||||
| state | string | Maintenance workflow state | Yes | Yes |
|
||||
+-------------------+----------------------+--------------------------------------------+-------------+-----------+
|
||||
| maintenance_at | time string | Maintenance workflow start time | Yes | Yes |
|
||||
+-------------------+----------------------+--------------------------------------------+-------------+-----------+
|
||||
| workflow | string | Maintenance workflow to be used | Yes | Yes |
|
||||
+-------------------+----------------------+--------------------------------------------+-------------+-----------+
|
||||
| metadata | dictionary | Metadata; like hints to projects | Yes | Yes |
|
||||
+-------------------+----------------------+--------------------------------------------+-------------+-----------+
|
||||
| download | list of string | List of needed SW upgrades | No | No |
|
||||
+-------------------+----------------------+--------------------------------------------+-------------+-----------+
|
||||
| actions | list of dictionaries | List of action plug-ins | No | Yes |
|
||||
+-------------------+----------------------+--------------------------------------------+-------------+-----------+
|
||||
| actions.plugin | string | plug-in name. Default workflow executes | No | Yes |
|
||||
| | | plug-ins in an alphabetical order | | |
|
||||
+-------------------+----------------------+--------------------------------------------+-------------+-----------+
|
||||
| actions.type | string | Type of the workflow. Possible values are: | No | Yes |
|
||||
| | | | | |
|
||||
| | | * pre: executed before the host type | | |
|
||||
| | | actions | | |
|
||||
| | | * host: executed for every host | | |
|
||||
| | | * post: executed after the host type | | |
|
||||
| | | actions | | |
|
||||
+-------------------+----------------------+--------------------------------------------+-------------+-----------+
|
||||
| actions.metadata | dictionary | Metadata; hints to plug-ins | No | Yes |
|
||||
+-------------------+----------------------+--------------------------------------------+-------------+-----------+
|
||||
|
||||
Example:
|
||||
|
||||
.. code-block:: json
|
||||
|
||||
{
|
||||
"hosts": ["overcloud-novacompute-1.opnfvlf.org",
|
||||
"overcloud-novacompute-2.opnfvlf.org",
|
||||
"overcloud-novacompute-3.opnfvlf.org"],
|
||||
"state": "MAINTENANCE",
|
||||
"maintenance_at": "2018-02-28 06:06:03",
|
||||
"metadata": {"openstack_release": "Queens"},
|
||||
"workflow": "default",
|
||||
"download": ["https://my.sw.upgrades.com/SW1.tar.gz",
|
||||
"https://my.sw.upgrades.com/ESW1.tar.gz",
|
||||
"https://my.sw.upgrades.com/plugins1.tar.gz"],
|
||||
"actions": [
|
||||
{"plugin": "prepare", "type": "pre"},
|
||||
{"plugin": "esw_upgrade", "type": "host", "metadata": {"upgrade": "ESW1"}},
|
||||
{"plugin": "os_upgrade", "type": "host", "metadata": {"upgrade": "SW1"}},
|
||||
{"plugin": "finalize", "type": "post"}]
|
||||
}
|
||||
|
||||
Response
|
||||
--------
|
||||
|
||||
Normal response codes: OK(200)
|
||||
|
||||
+------------+--------+-------------+
|
||||
| Name | Type | Description |
|
||||
+============+========+=============+
|
||||
| session_id | string | UUID |
|
||||
+------------+--------+-------------+
|
||||
|
||||
Example:
|
||||
|
||||
.. code-block:: json
|
||||
|
||||
{
|
||||
"session_id": "695030ee-1c4d-11e8-a9b0-0242ac110002"
|
||||
}
|
||||
|
||||
|
||||
Update maintenance session
|
||||
==========================
|
||||
|
||||
--Not yet implemented--
|
||||
|
||||
Update existing maintenance session. This can be used to continue a failed
|
||||
session.
|
||||
|
||||
:PUT: /v1/maintenance/<session_id>/
|
||||
|
||||
|
||||
Get maintenance sessions
|
||||
========================
|
||||
|
||||
Get all ongoing maintenance sessions.
|
||||
|
||||
:GET: /v1/maintenance/
|
||||
|
||||
Response
|
||||
--------
|
||||
|
||||
Normal response codes: OK(200)
|
||||
|
||||
+------------+-----------------+----------------------+
|
||||
| Name | Type | Description |
|
||||
+============+=================+======================+
|
||||
| session_id | list of strings | list of UUID strings |
|
||||
+------------+-----------------+----------------------+
|
||||
|
||||
Example:
|
||||
|
||||
.. code-block:: json
|
||||
|
||||
{
|
||||
"session_id": ["695030ee-1c4d-11e8-a9b0-0242ac110002"]
|
||||
}
|
||||
|
||||
Get maintenance session
|
||||
=======================
|
||||
|
||||
Get a maintenance session state.
|
||||
|
||||
:GET: /v1/maintenance/<session_id>/
|
||||
|
||||
Response
|
||||
--------
|
||||
|
||||
Normal response codes: OK(200)
|
||||
|
||||
+----------------+-----------------+---------------------------------+
|
||||
| Name | Type | Description |
|
||||
+================+=================+=================================+
|
||||
| state | string | Maintenance workflow state |
|
||||
+----------------+-----------------+---------------------------------+
|
||||
|
||||
.. code-block:: json
|
||||
|
||||
{
|
||||
"state": "MAINTENANCE_DONE"
|
||||
}
|
||||
|
||||
|
||||
Delete maintenance session
|
||||
==========================
|
||||
|
||||
Delete a maintenance session. Usually called after the session is successfully
|
||||
finished.
|
||||
|
||||
:DELETE: /v1/maintenance/<session_id>/
|
||||
|
||||
Normal response codes: OK(200)
|
||||
|
||||
|
||||
Future
|
||||
======
|
||||
|
||||
On top of some expected changes mentioned above, it will also be handy to get
|
||||
detailed information about the steps run already in the maintenance session.
|
||||
This will be helpful when need to figure out any correcting actions to
|
||||
successfully finish a failed session. There is ongoing work to have everything
|
||||
kept in a database and that will be a key feature to enable these changes.
|
|
@ -1,10 +0,0 @@
|
|||
==================
|
||||
API Documentation
|
||||
==================
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
|
||||
admin
|
||||
project
|
||||
|
|
@ -1,90 +0,0 @@
|
|||
.. _project:
|
||||
|
||||
=======
|
||||
Project
|
||||
=======
|
||||
|
||||
These APIs are meant for projects having instances on top of the infrastructure
|
||||
under corresponding rolling maintenance or upgrade session. Usage of these APIs
|
||||
expects there is an application manager (VNFM) that can interact with Fenix
|
||||
workflow via these APIs. If this is not the case, workflow should have a default
|
||||
behavior for instances owned by projects, that are not interacting with Fenix.
|
||||
|
||||
These APIs are generic for any cloud as instance ID should be something that can
|
||||
be matched to virtual machines or containers regardless of the cloud underneath.
|
||||
|
||||
Get project maintenance session
|
||||
===============================
|
||||
|
||||
Get project instances belonging to the current state of maintenance session.
|
||||
the Project-manager receives an AODH event alarm telling about different
|
||||
maintenance states. Event data field length is very limited, so instances cannot
|
||||
be given as a list in the event. Instead, there will be an URL given to below
|
||||
API to get a project-specific list of instances.
|
||||
|
||||
:GET /v1/maintenance/<session_id>/<projet_id>/
|
||||
|
||||
Response
|
||||
--------
|
||||
|
||||
Normal response codes: OK(200)
|
||||
|
||||
+--------------+-----------------+----------------------+
|
||||
| Name | Type | Description |
|
||||
+==============+=================+======================+
|
||||
| instance_ids | list of strings | List of instance IDs |
|
||||
+--------------+-----------------+----------------------+
|
||||
|
||||
Example:
|
||||
|
||||
.. code-block:: json
|
||||
|
||||
{
|
||||
"instance_ids": ["109e14d9-6566-42b3-93e4-76605f264d8f",
|
||||
"71285107-f0fc-4428-a8b2-0b3edd64bcad"]
|
||||
}
|
||||
|
||||
|
||||
Input from project to maintenance session
|
||||
=========================================
|
||||
|
||||
Project having instances on top of the infrastructure handled by a maintenance
|
||||
session might need to make own action for its instances on top of a host going
|
||||
into maintenance next, or reply an admin action to be done. This is, as the host
|
||||
can go down or even be removed and the instances should be then running safely
|
||||
somewhere else. Project manager receives an AODH event alarm telling which
|
||||
instances are affected and when the project is ready, it makes its own action or
|
||||
replies back an action which needs the admin privileges.
|
||||
|
||||
:PUT /v1/maintenance/<session_id>/<projet_id>/
|
||||
|
||||
Request
|
||||
-------
|
||||
|
||||
+------------------+------------+-------------------------------------------------+
|
||||
| Name | Type | Description |
|
||||
+==================+============+=================================================+
|
||||
| instance_actions | dictionary | instance ID : action string |
|
||||
+------------------+------------+-------------------------------------------------+
|
||||
| state | string | There can have different values depending on |
|
||||
| | | what is the maintenance session state to reply |
|
||||
| | | to. In the below example, the maintenance state |
|
||||
| | | is 'PLANNED_MAINTENANCE' and the reply state is |
|
||||
| | | formed by adding 'ACK\_' or 'NACK\_' as the |
|
||||
| | | prefix to reply value |
|
||||
+------------------+------------+-------------------------------------------------+
|
||||
|
||||
Example:
|
||||
|
||||
.. code-block:: json
|
||||
|
||||
{
|
||||
"instance_actions": {"109e14d9-6566-42b3-93e4-76605f264d8f": "MIGRATE",
|
||||
"71285107-f0fc-4428-a8b2-0b3edd64bcad": "MIGRATE"},
|
||||
"state": "ACK_PLANNED_MAINTENANCE"
|
||||
}
|
||||
|
||||
Response
|
||||
--------
|
||||
|
||||
Normal response codes: OK(200)
|
|
@ -17,21 +17,13 @@ Contents:
|
|||
library/index
|
||||
contributor/index
|
||||
configuration/index
|
||||
api/index
|
||||
api-ref/index
|
||||
notification/index
|
||||
cli/index
|
||||
user/index
|
||||
admin/index
|
||||
reference/index
|
||||
|
||||
Experimental API documentation
|
||||
==============================
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
|
||||
api-ref/index
|
||||
|
||||
Indices and tables
|
||||
==================
|
||||
|
||||
|
|
Loading…
Reference in New Issue