From bd5238a330a738a06f4b24ec330871acd636b312 Mon Sep 17 00:00:00 2001 From: Gergely Csatari Date: Mon, 26 Nov 2018 10:49:50 +0100 Subject: [PATCH] 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 --- doc/source/api/admin.rst | 187 ------------------------------------- doc/source/api/index.rst | 10 -- doc/source/api/project.rst | 90 ------------------ doc/source/index.rst | 10 +- 4 files changed, 1 insertion(+), 296 deletions(-) delete mode 100644 doc/source/api/admin.rst delete mode 100644 doc/source/api/index.rst delete mode 100644 doc/source/api/project.rst diff --git a/doc/source/api/admin.rst b/doc/source/api/admin.rst deleted file mode 100644 index 2331402..0000000 --- a/doc/source/api/admin.rst +++ /dev/null @@ -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// - - -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// - -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// - -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. diff --git a/doc/source/api/index.rst b/doc/source/api/index.rst deleted file mode 100644 index 8fdaf72..0000000 --- a/doc/source/api/index.rst +++ /dev/null @@ -1,10 +0,0 @@ -================== - API Documentation -================== - -.. toctree:: - :maxdepth: 2 - - admin - project - diff --git a/doc/source/api/project.rst b/doc/source/api/project.rst deleted file mode 100644 index 299d72e..0000000 --- a/doc/source/api/project.rst +++ /dev/null @@ -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/// - -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/// - -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) diff --git a/doc/source/index.rst b/doc/source/index.rst index 48c3eca..8ab782a 100644 --- a/doc/source/index.rst +++ b/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 ==================