Browse Source

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>
changes/94/619994/1
Gergely Csatari 3 years ago
parent
commit
bd5238a330
  1. 187
      doc/source/api/admin.rst
  2. 10
      doc/source/api/index.rst
  3. 90
      doc/source/api/project.rst
  4. 10
      doc/source/index.rst

187
doc/source/api/admin.rst

@ -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.

10
doc/source/api/index.rst

@ -1,10 +0,0 @@
==================
API Documentation
==================
.. toctree::
:maxdepth: 2
admin
project

90
doc/source/api/project.rst

@ -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)

10
doc/source/index.rst

@ -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…
Cancel
Save