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>
This commit is contained in:
parent
f990b57944
commit
b3b534de79
|
@ -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
|
||||
|
|
|
@ -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'
|
|
@ -0,0 +1,8 @@
|
|||
####################
|
||||
Host Maintenance API
|
||||
####################
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
|
||||
v1/index
|
|
@ -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
|
|
@ -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.
|
|
@ -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
|
|
@ -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
|
|
@ -0,0 +1,3 @@
|
|||
{
|
||||
"session_id": "695030ee-1c4d-11e8-a9b0-0242ac110002"
|
||||
}
|
|
@ -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"}]
|
||||
}
|
|
@ -0,0 +1,3 @@
|
|||
{
|
||||
"state": "MAINTENANCE_DONE"
|
||||
}
|
|
@ -0,0 +1,3 @@
|
|||
{
|
||||
"session_id": ["695030ee-1c4d-11e8-a9b0-0242ac110002"]
|
||||
}
|
|
@ -0,0 +1,4 @@
|
|||
{
|
||||
"instance_ids": ["109e14d9-6566-42b3-93e4-76605f264d8f",
|
||||
"71285107-f0fc-4428-a8b2-0b3edd64bcad"]
|
||||
}
|
|
@ -0,0 +1,5 @@
|
|||
{
|
||||
"instance_actions": {"109e14d9-6566-42b3-93e4-76605f264d8f": "MIGRATE",
|
||||
"71285107-f0fc-4428-a8b2-0b3edd64bcad": "MIGRATE"},
|
||||
"state": "ACK_PLANNED_MAINTENANCE"
|
||||
}
|
|
@ -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.
|
|
@ -23,6 +23,7 @@ sys.path.insert(0, os.path.abspath('../..'))
|
|||
extensions = [
|
||||
'sphinx.ext.autodoc',
|
||||
'openstackdocstheme',
|
||||
'os_api_ref',
|
||||
#'sphinx.ext.intersphinx',
|
||||
]
|
||||
|
||||
|
|
|
@ -24,6 +24,14 @@ Contents:
|
|||
admin/index
|
||||
reference/index
|
||||
|
||||
Experimental API documentation
|
||||
==============================
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
|
||||
api-ref/index
|
||||
|
||||
Indices and tables
|
||||
==================
|
||||
|
||||
|
|
Loading…
Reference in New Issue