From b3b534de79274b4a550865edb157ae00d7a5fa64 Mon Sep 17 00:00:00 2001 From: Gergely Csatari Date: Fri, 9 Nov 2018 13:53:14 +0100 Subject: [PATCH] Building api documentation with os-api-ref under the doc folder This change adds the usage of os-api-ref to the building of the API documentation, but under the doc folder, so it is possible to publish the result to readthedocs.org. This change replaces [1] until the documentation is published to readthedocs.org. Once Fenix becomes an official OpenStack project [1] can be implemented. For the moment I will abandon [1]. [1]: https://review.openstack.org/#/c/616868/ Story: 2004292 Task: #27862 Change-Id: I3144f812d0afd41d500ec7cd8fd4ba1d9c202366 Signed-off-by: Gergely Csatari --- doc/requirements.txt | 1 + doc/source/api-ref/conf.py | 32 ++++ doc/source/api-ref/index.rst | 8 + doc/source/api-ref/v1/index.rst | 28 ++++ doc/source/api-ref/v1/maintenance.inc | 138 ++++++++++++++++ doc/source/api-ref/v1/parameters.yaml | 148 ++++++++++++++++++ doc/source/api-ref/v1/project.inc | 71 +++++++++ .../create-maintenance-session-post-200.json | 3 + .../create-maintenance-session-post.json | 17 ++ .../get-maintenance-session-get-200.json | 3 + .../get-maintenance-sessions-get-200.json | 3 + ...-project-maintenance-session-post-200.json | 4 + ...om-project-to-maintenance-session-put.json | 5 + doc/source/api-ref/v1/status.yaml | 95 +++++++++++ doc/source/conf.py | 1 + doc/source/index.rst | 8 + 16 files changed, 565 insertions(+) create mode 100644 doc/source/api-ref/conf.py create mode 100644 doc/source/api-ref/index.rst create mode 100644 doc/source/api-ref/v1/index.rst create mode 100644 doc/source/api-ref/v1/maintenance.inc create mode 100644 doc/source/api-ref/v1/parameters.yaml create mode 100644 doc/source/api-ref/v1/project.inc create mode 100644 doc/source/api-ref/v1/samples/create-maintenance-session-post-200.json create mode 100644 doc/source/api-ref/v1/samples/create-maintenance-session-post.json create mode 100644 doc/source/api-ref/v1/samples/get-maintenance-session-get-200.json create mode 100644 doc/source/api-ref/v1/samples/get-maintenance-sessions-get-200.json create mode 100644 doc/source/api-ref/v1/samples/get-project-maintenance-session-post-200.json create mode 100644 doc/source/api-ref/v1/samples/input-from-project-to-maintenance-session-put.json create mode 100644 doc/source/api-ref/v1/status.yaml diff --git a/doc/requirements.txt b/doc/requirements.txt index afd3597..ce60719 100644 --- a/doc/requirements.txt +++ b/doc/requirements.txt @@ -1,4 +1,5 @@ sphinx!=1.6.6,!=1.6.7,>=1.6.2 # BSD openstackdocstheme>=1.18.1 # Apache-2.0 +os-api-ref>=1.0.0 # Apache-2.0 # releasenotes reno>=2.5.0 # Apache-2.0 diff --git a/doc/source/api-ref/conf.py b/doc/source/api-ref/conf.py new file mode 100644 index 0000000..1fddf94 --- /dev/null +++ b/doc/source/api-ref/conf.py @@ -0,0 +1,32 @@ +# This file is not used until the api-ref directory is part of +# the doc folder and the Fenix documentation is published to +# readthedocs.org +# When Fenix API documentation will be published to [1] and the +# documentation is builded according to [2] this file will be used +# again. +# +# [1]: https://docs.openstack.org/rocky/api/ +# [2]: https://docs.openstack.org/doc-contrib-guide/api-guides.html + +extensions = [ + 'os_api_ref', + 'openstackdocstheme' +] + +# The prefix and repo name like +repository_name = 'openstack/fenix' +# Set Launchpad bug tag, default is empty +bug_tag = '' +# The launchpad project name like +bug_project = 'fenix' + +html_theme = 'openstackdocs' +html_theme_options = { + "sidebar_mode": "toc", +} + +# The master toctree document. +master_doc = 'index' + +# Must set this variable to include year, month, day, hours, and minutes. +html_last_updated_fmt = '%Y-%m-%d %H:%M' \ No newline at end of file diff --git a/doc/source/api-ref/index.rst b/doc/source/api-ref/index.rst new file mode 100644 index 0000000..6af2316 --- /dev/null +++ b/doc/source/api-ref/index.rst @@ -0,0 +1,8 @@ +#################### +Host Maintenance API +#################### + +.. toctree:: + :maxdepth: 2 + + v1/index diff --git a/doc/source/api-ref/v1/index.rst b/doc/source/api-ref/v1/index.rst new file mode 100644 index 0000000..f502630 --- /dev/null +++ b/doc/source/api-ref/v1/index.rst @@ -0,0 +1,28 @@ +:tocdepth: 2 + +####################### +Host Maintenance API v1 +####################### + +.. rest_expand_all:: + +##### +Admin +##### + +These APIs are meant for infrastructure admin who is in charge of triggering +the rolling maintenance and upgrade workflows. + +.. include:: maintenance.inc + +####### +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. + +.. include:: project.inc diff --git a/doc/source/api-ref/v1/maintenance.inc b/doc/source/api-ref/v1/maintenance.inc new file mode 100644 index 0000000..e7e6c98 --- /dev/null +++ b/doc/source/api-ref/v1/maintenance.inc @@ -0,0 +1,138 @@ +.. -*- rst -*- + +=========== +Maintenance +=========== + +Create maintenance session +========================== + +.. rest_method:: 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. + +Planned future functionality +---------------------------- + +'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 before maintenance +starts, on each host or after the maintenance. + +Request +------- + +.. rest_parameters:: parameters.yaml + + - hosts: hosts + - state: workflow-state + - maintenance_at: maintenance-workflow-start-time + - workflow: workflow-name + - metadata: metadata + - download: upgrade-list + - actions: action-plugins + - actions.plugin: action-plugin-name + - actions.type: action-plugin-type + - actions.metadata: action-metadata + +.. literalinclude:: samples/create-maintenance-session-post.json + :language: javascript + +Response codes +-------------- + +.. rest_status_code:: success status.yaml + + - 200: create-maintenance-session-post + +.. rest_status_code:: error status.yaml + + - 404 + +Update maintenance session (planned future functionality) +========================================================= + +.. rest_method:: POST /v1/maintenance/{session_id}/ + +Update existing maintenance session. This can be used to continue a failed +session. + +Request +------- + +.. rest_parameters:: parameters.yaml + + - session_id: session_id + +Get maintenance sessions +======================== + +.. rest_method:: GET /v1/maintenance/ + +Get all ongoing maintenance sessions. + +Response codes +-------------- + +.. rest_status_code:: success status.yaml + + - 200: get-maintenance-sessions-get + +.. rest_status_code:: error status.yaml + + - 404 + +Get maintenance session +======================= + +.. rest_method:: GET /v1/maintenance/{session_id}/ + +Get a maintenance session state. + +Request +------- + +.. rest_parameters:: parameters.yaml + + - session_id: session_id + +Response codes +-------------- + +.. rest_status_code:: success status.yaml + + - 200: get-maintenance-session-get + +.. rest_status_code:: error status.yaml + + - 404 + +Delete maintenance session +========================== + +.. rest_method:: DELETE /v1/maintenance/{session_id}/ + +Delete a maintenance session. Usually called after the session is successfully +finished. + + +.. rest_status_code:: success status.yaml + + - 200 + +.. rest_status_code:: error status.yaml + + - 404 + +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-ref/v1/parameters.yaml b/doc/source/api-ref/v1/parameters.yaml new file mode 100644 index 0000000..3c986b2 --- /dev/null +++ b/doc/source/api-ref/v1/parameters.yaml @@ -0,0 +1,148 @@ +############################################################################# +# Variables in header # +############################################################################# + +############################################################################# +# Variables in path # +############################################################################# + +session_id: + description: | + Session ID + in: path + required: false + type: string + min_version: \> 1 + +uuid-path: + description: | + uuid + in: path + required: true + type: string + +############################################################################# +# Variables in query # +############################################################################# + +############################################################################# +# Variables in body # +############################################################################# +action-metadata: + description: | + Metadata; hints to plug-ins + in: body + required: true + type: dictionary + min_version: \> 1 + +action-plugin-name: + description: | + plug-in name. Default workflow executes plug-ins in an alphabetical order + in: body + required: true + type: string + min_version: \> 1 + +action-plugin-type: + description: | + Type of the workflow. Possible values are: + + * pre: executed before the host type actions + * post: executed after the host type actions + * host: executed for every host + + in: body + required: true + type: integer + min_version: \> 1 + +action-plugins: + description: | + List of action plug-ins. + in: body + required: true + type: list of dictionaries + min_version: \> 1 + +hosts: + description: | + Hosts to be maintained. An empty list can indicate hosts are to be + discovered. + in: body + required: true + type: list of strings + +instance-actions: + description: | + instance ID : action string + in: body + required: true + type: dictionary + +instance-ids: + description: | + List of instance IDs. + in: body + required: true + type: list of strings + +maintenance-workflow-start-time: + description: | + Maintenance workflow start time. + in: body + required: true + type: string + +metadata: + description: | + Metadata; like hints to projects + in: body + required: true + type: dictionary + +upgrade-list: + description: | + List of needed SW upgrades + in: body + required: false + type: list of dictionaries + min_version: \> 1 + +uuid: + description: | + uuid + in: body + required: true + type: string + +uuid-list: + description: | + list of UUID strings + in: body + required: true + type: string + +workflow-name: + description: | + Maintenance workflow to be used. + in: body + required: true + type: string + +workflow-state: + description: | + Maintenance workflow state. + in: body + required: true + type: string + +workflow-state-reply: + description: | + 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. + in: body + required: true + type: string diff --git a/doc/source/api-ref/v1/project.inc b/doc/source/api-ref/v1/project.inc new file mode 100644 index 0000000..dc1ddce --- /dev/null +++ b/doc/source/api-ref/v1/project.inc @@ -0,0 +1,71 @@ +.. -*- rst -*- + +======= +Project +======= + +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 +=============================== + +.. rest_method:: GET /v1/maintenance/{session_id}/{project_id}/ + +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. + +Request +------- + +.. rest_parameters:: parameters.yaml + + - session_id: uuid-path + - project_id: uuid-path + +Response codes +-------------- + +.. rest_status_code:: success status.yaml + + - 200: get-project-maintenance-session-post + +.. rest_status_code:: error status.yaml + + - 404 + +Input from project to maintenance session +========================================= + +.. rest_method:: PUT /v1/maintenance/{session_id}/{project_id}/ + +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. + +Request +------- + +.. rest_parameters:: parameters.yaml + + - session_id: uuid-path + - project_id: uuid-path + - instance_actions: instance-actions + - state: workflow-state-reply + +.. literalinclude:: samples/input-from-project-to-maintenance-session-put.json + :language: javascript + +Response codes +-------------- + +.. rest_status_code:: success status.yaml + + - 200 diff --git a/doc/source/api-ref/v1/samples/create-maintenance-session-post-200.json b/doc/source/api-ref/v1/samples/create-maintenance-session-post-200.json new file mode 100644 index 0000000..15da70a --- /dev/null +++ b/doc/source/api-ref/v1/samples/create-maintenance-session-post-200.json @@ -0,0 +1,3 @@ +{ + "session_id": "695030ee-1c4d-11e8-a9b0-0242ac110002" +} diff --git a/doc/source/api-ref/v1/samples/create-maintenance-session-post.json b/doc/source/api-ref/v1/samples/create-maintenance-session-post.json new file mode 100644 index 0000000..24c15a8 --- /dev/null +++ b/doc/source/api-ref/v1/samples/create-maintenance-session-post.json @@ -0,0 +1,17 @@ +{ + "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"}] +} \ No newline at end of file diff --git a/doc/source/api-ref/v1/samples/get-maintenance-session-get-200.json b/doc/source/api-ref/v1/samples/get-maintenance-session-get-200.json new file mode 100644 index 0000000..3aad3bd --- /dev/null +++ b/doc/source/api-ref/v1/samples/get-maintenance-session-get-200.json @@ -0,0 +1,3 @@ +{ + "state": "MAINTENANCE_DONE" +} diff --git a/doc/source/api-ref/v1/samples/get-maintenance-sessions-get-200.json b/doc/source/api-ref/v1/samples/get-maintenance-sessions-get-200.json new file mode 100644 index 0000000..113df91 --- /dev/null +++ b/doc/source/api-ref/v1/samples/get-maintenance-sessions-get-200.json @@ -0,0 +1,3 @@ +{ + "session_id": ["695030ee-1c4d-11e8-a9b0-0242ac110002"] +} diff --git a/doc/source/api-ref/v1/samples/get-project-maintenance-session-post-200.json b/doc/source/api-ref/v1/samples/get-project-maintenance-session-post-200.json new file mode 100644 index 0000000..510f7b3 --- /dev/null +++ b/doc/source/api-ref/v1/samples/get-project-maintenance-session-post-200.json @@ -0,0 +1,4 @@ +{ + "instance_ids": ["109e14d9-6566-42b3-93e4-76605f264d8f", + "71285107-f0fc-4428-a8b2-0b3edd64bcad"] +} diff --git a/doc/source/api-ref/v1/samples/input-from-project-to-maintenance-session-put.json b/doc/source/api-ref/v1/samples/input-from-project-to-maintenance-session-put.json new file mode 100644 index 0000000..e99af1c --- /dev/null +++ b/doc/source/api-ref/v1/samples/input-from-project-to-maintenance-session-put.json @@ -0,0 +1,5 @@ +{ + "instance_actions": {"109e14d9-6566-42b3-93e4-76605f264d8f": "MIGRATE", + "71285107-f0fc-4428-a8b2-0b3edd64bcad": "MIGRATE"}, + "state": "ACK_PLANNED_MAINTENANCE" +} diff --git a/doc/source/api-ref/v1/status.yaml b/doc/source/api-ref/v1/status.yaml new file mode 100644 index 0000000..2149aee --- /dev/null +++ b/doc/source/api-ref/v1/status.yaml @@ -0,0 +1,95 @@ +200: + default: | + Request was successful. + image-data-200: | + The service lists the image data in the response body. + create-maintenance-session-post: | + .. rest_parameters:: parameters.yaml + + - session_id: uuid + + .. literalinclude:: samples/create-maintenance-session-post-200.json + :language: javascript + + get-maintenance-sessions-get: | + .. rest_parameters:: parameters.yaml + + - session_id: uuid-list + + .. literalinclude:: samples/get-maintenance-sessions-get-200.json + :language: javascript + + get-maintenance-session-get: | + .. rest_parameters:: parameters.yaml + + - state: workflow-state + + .. literalinclude:: samples/get-maintenance-session-get-200.json + :language: javascript + + get-project-maintenance-session-post: | + .. rest_parameters:: parameters.yaml + + - instance_ids: instance-ids + + .. literalinclude:: samples/get-project-maintenance-session-post-200.json + :language: javascript + +201: + default: | + Request has been fulfilled and new resource created. +202: + default: | + Request is accepted, but processing may take some time. +203: + default: | + Returned information is not full set, but a subset. +204: + default: | + Request fulfilled but service does not return anything. +300: + default: | + The resource corresponds to more than one representation. +400: + default: | + Some content in the request was invalid. +401: + default: | + User must authenticate before making a request. +403: + default: | + Policy does not allow current user to do this operation. +404: + default: | + The requested resource could not be found. +405: + default: | + Method is not valid for this endpoint and resource. +409: + default: | + This resource has an action in progress that would conflict with this request. +413: + default: | + This operation cannot be completed. + image-data-413: | + The payload cannot be accepted. Possible causes include: + * The backend storage is full. + * This request added to your existing image data exceeds your total + storage quota for images. + * The image payload submitted with this request exceeds the maximum + allowable image size. +415: + default: | + The entity of the request is in a format not supported by the requested + resource for the method. +500: + default: | + Something went wrong with the service which prevents it from fulfilling + the request. +501: + default: | + The service does not have the functionality required to fulfill this + request. +503: + default: | + The service cannot handle the request right now. \ No newline at end of file diff --git a/doc/source/conf.py b/doc/source/conf.py index 6d3ff27..a9b9a6f 100755 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -23,6 +23,7 @@ sys.path.insert(0, os.path.abspath('../..')) extensions = [ 'sphinx.ext.autodoc', 'openstackdocstheme', + 'os_api_ref', #'sphinx.ext.intersphinx', ] diff --git a/doc/source/index.rst b/doc/source/index.rst index c452605..48c3eca 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -24,6 +24,14 @@ Contents: admin/index reference/index +Experimental API documentation +============================== + +.. toctree:: + :maxdepth: 2 + + api-ref/index + Indices and tables ==================