Browse Source

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 <gergely.csatari@nokia.com>
changes/02/616902/11
Gergely Csatari 3 years ago
parent
commit
b3b534de79
  1. 1
      doc/requirements.txt
  2. 32
      doc/source/api-ref/conf.py
  3. 8
      doc/source/api-ref/index.rst
  4. 28
      doc/source/api-ref/v1/index.rst
  5. 138
      doc/source/api-ref/v1/maintenance.inc
  6. 148
      doc/source/api-ref/v1/parameters.yaml
  7. 71
      doc/source/api-ref/v1/project.inc
  8. 3
      doc/source/api-ref/v1/samples/create-maintenance-session-post-200.json
  9. 17
      doc/source/api-ref/v1/samples/create-maintenance-session-post.json
  10. 3
      doc/source/api-ref/v1/samples/get-maintenance-session-get-200.json
  11. 3
      doc/source/api-ref/v1/samples/get-maintenance-sessions-get-200.json
  12. 4
      doc/source/api-ref/v1/samples/get-project-maintenance-session-post-200.json
  13. 5
      doc/source/api-ref/v1/samples/input-from-project-to-maintenance-session-put.json
  14. 95
      doc/source/api-ref/v1/status.yaml
  15. 1
      doc/source/conf.py
  16. 8
      doc/source/index.rst

1
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

32
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'

8
doc/source/api-ref/index.rst

@ -0,0 +1,8 @@
####################
Host Maintenance API
####################
.. toctree::
:maxdepth: 2
v1/index

28
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

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

148
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

71
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

3
doc/source/api-ref/v1/samples/create-maintenance-session-post-200.json

@ -0,0 +1,3 @@
{
"session_id": "695030ee-1c4d-11e8-a9b0-0242ac110002"
}

17
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"}]
}

3
doc/source/api-ref/v1/samples/get-maintenance-session-get-200.json

@ -0,0 +1,3 @@
{
"state": "MAINTENANCE_DONE"
}

3
doc/source/api-ref/v1/samples/get-maintenance-sessions-get-200.json

@ -0,0 +1,3 @@
{
"session_id": ["695030ee-1c4d-11e8-a9b0-0242ac110002"]
}

4
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"]
}

5
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"
}

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

1
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',
]

8
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
==================

Loading…
Cancel
Save