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
|
library/index
|
||||||
contributor/index
|
contributor/index
|
||||||
configuration/index
|
configuration/index
|
||||||
api/index
|
api-ref/index
|
||||||
notification/index
|
notification/index
|
||||||
cli/index
|
cli/index
|
||||||
user/index
|
user/index
|
||||||
admin/index
|
admin/index
|
||||||
reference/index
|
reference/index
|
||||||
|
|
||||||
Experimental API documentation
|
|
||||||
==============================
|
|
||||||
|
|
||||||
.. toctree::
|
|
||||||
:maxdepth: 2
|
|
||||||
|
|
||||||
api-ref/index
|
|
||||||
|
|
||||||
Indices and tables
|
Indices and tables
|
||||||
==================
|
==================
|
||||||
|
|
||||||
|
|
Loading…
Reference in New Issue