diff --git a/doc/source/api/admin.rst b/doc/source/api/admin.rst new file mode 100644 index 0000000..131d476 --- /dev/null +++ b/doc/source/api/admin.rst @@ -0,0 +1,182 @@ +.. _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 | Default workflow support types: | No | Yes | +| | | 'pre', 'host' or 'post' | | | ++-------------------+----------------------+--------------------------------------------+-------------+-----------+ +| 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 new file mode 100644 index 0000000..8fdaf72 --- /dev/null +++ b/doc/source/api/index.rst @@ -0,0 +1,10 @@ +================== + API Documentation +================== + +.. toctree:: + :maxdepth: 2 + + admin + project + diff --git a/doc/source/api/project.rst b/doc/source/api/project.rst new file mode 100644 index 0000000..299d72e --- /dev/null +++ b/doc/source/api/project.rst @@ -0,0 +1,90 @@ +.. _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 3ec7ee0..237daf4 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -17,6 +17,7 @@ Contents: library/index contributor/index configuration/index + api/index cli/index user/index admin/index