stx-update: API Ref Doc Content
Added API reference manual to the api-ref/source dir for stx-update. This represents the converted old-style files to the newer OpenStack supported RST files. This change was introduced and abandoned: https://review.openstack.org/#/c/605278/ Reason was a confussion during the split of the old API into the new API scheme. Change-Id: Ic64509c2fd51a659f156e6cbc847e160d4c339e3 Signed-off-by: Scott Rifenbark <srifenbark@gmail.com> Signed-off-by: Abraham Arce <abraham.arce.moreno@intel.com>
This commit is contained in:
Scott Rifenbark
Abraham Arce
parent
db68a25ea7
commit
c763e0de07
433
api-ref/source/api-ref-patching-v1-update.rst
Normal file
433
api-ref/source/api-ref-patching-v1-update.rst
Normal file
@ -0,0 +1,433 @@
|
|||||||
|
====================================================
|
||||||
|
Patching API v1
|
||||||
|
====================================================
|
||||||
|
|
||||||
|
Manage the patching of hosts with the StarlingX Patching API. This
|
||||||
|
includes upload, application, installation, removal, deletion, and
|
||||||
|
querying.
|
||||||
|
|
||||||
|
The typical port used for the Patching REST API is 15491. However,
|
||||||
|
proper technique would be to look up the patching service endpoint
|
||||||
|
in Keystone.
|
||||||
|
|
||||||
|
------------
|
||||||
|
API versions
|
||||||
|
------------
|
||||||
|
|
||||||
|
***********************************************************
|
||||||
|
Lists information about all StarlingX Patching API versions
|
||||||
|
***********************************************************
|
||||||
|
|
||||||
|
.. rest_method:: GET /
|
||||||
|
|
||||||
|
**Normal response codes**
|
||||||
|
|
||||||
|
200, 300
|
||||||
|
|
||||||
|
**Error response codes**
|
||||||
|
|
||||||
|
serviceUnavailable (503), badRequest (400), unauthorized (401),
|
||||||
|
forbidden (403), badMethod (405), overLimit (413), itemNotFound (404)
|
||||||
|
|
||||||
|
::
|
||||||
|
|
||||||
|
"StarlingX Patching API, Available versions: /v1"
|
||||||
|
|
||||||
|
This operation does not accept a request body.
|
||||||
|
|
||||||
|
-------
|
||||||
|
Patches
|
||||||
|
-------
|
||||||
|
|
||||||
|
The patches used by the patching service to update individual hosts in
|
||||||
|
the cloud.
|
||||||
|
|
||||||
|
****************************************
|
||||||
|
Lists all patches in the patching system
|
||||||
|
****************************************
|
||||||
|
|
||||||
|
.. rest_method:: GET /v1/query
|
||||||
|
|
||||||
|
Supported query values are ``all``, ``available``, or ``applied``.
|
||||||
|
|
||||||
|
**Normal response codes**
|
||||||
|
|
||||||
|
200
|
||||||
|
|
||||||
|
**Error response codes**
|
||||||
|
|
||||||
|
serviceUnavailable (503), badRequest (400), unauthorized (401),
|
||||||
|
forbidden (403), badMethod (405), overLimit (413), itemNotFound (404)
|
||||||
|
|
||||||
|
**Response parameters**
|
||||||
|
|
||||||
|
.. csv-table::
|
||||||
|
:header: "Parameter", "Style", "Type", "Description"
|
||||||
|
:widths: 20, 20, 20, 60
|
||||||
|
|
||||||
|
"pd (Optional)", "plain", "xsd:list", "The list of patches present in the patching system."
|
||||||
|
"patch (Optional)", "plain", "xsd:list", "A patch present in the patching system."
|
||||||
|
"status (Optional)", "plain", "xsd:string", "The status of the patch."
|
||||||
|
"sw_version (Optional)", "plain", "xsd:string", "The software version for which the patch is intended."
|
||||||
|
"install_instructions (Optional)", "plain", "xsd:string", "Instructions on how to install the patch."
|
||||||
|
"description (Optional)", "plain", "xsd:string", "The description of any updates present in this patch."
|
||||||
|
"warnings (Optional)", "plain", "xsd:string", "Any warnings associated with the usage of the patch."
|
||||||
|
"summary (Optional)", "plain", "xsd:string", "A brief summary of the patch."
|
||||||
|
"repostate (Optional)", "plain", "xsd:string", "Whether this patch`s content`s have been added to the patching repository; ``Applied`` or ``Available``."
|
||||||
|
"patchstate (Optional)", "plain", "xsd:string", "The state of this patch`s application to hosts; ``Available``, ``Partial-Apply``, ``Applied``, or ``Partial-Removed``."
|
||||||
|
"requires (Optional)", "plain", "xsd:list", "A list of patch ids required for this patch to be installed."
|
||||||
|
|
||||||
|
::
|
||||||
|
|
||||||
|
{
|
||||||
|
'pd':{
|
||||||
|
'TS_15.12_PATCH_0002':{
|
||||||
|
'status': 'REL',
|
||||||
|
'sw_version': '15.12',
|
||||||
|
'patchstate': 'Partial-Remove',
|
||||||
|
'description': 'Fixes the following Issues:\n compute-4 and storage-0 multiple resets after DOR\n Alarms bogged down for 1 hour after DOR\n Guest Heartbeat cannot be enabled from horizon',
|
||||||
|
'warnings': '',
|
||||||
|
'summary': 'TS_15.12 Patch 0002',
|
||||||
|
'repostate': 'Available',
|
||||||
|
'install_instructions': '',
|
||||||
|
'requires': []
|
||||||
|
},
|
||||||
|
'TS_15.12_PATCH_0001':{
|
||||||
|
'status': 'REL',
|
||||||
|
'sw_version': '15.12',
|
||||||
|
'patchstate': 'Applied',
|
||||||
|
'description': 'Fixes the following Issues:\n hbsClient instrumentation can cause server reset or hang after long soaks',
|
||||||
|
'warnings': '',
|
||||||
|
'summary': 'TS_15.12 Patch 0001',
|
||||||
|
'repostate': 'Applied',
|
||||||
|
'install_instructions': 'No special install instructions.',
|
||||||
|
'requires': []
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
This operation does not accept a request body.
|
||||||
|
|
||||||
|
*************************************************
|
||||||
|
Shows detailed information about a specific patch
|
||||||
|
*************************************************
|
||||||
|
|
||||||
|
.. rest_method:: GET /v1/show/{patch_id}
|
||||||
|
|
||||||
|
**Normal response codes**
|
||||||
|
|
||||||
|
200
|
||||||
|
|
||||||
|
**Error response codes**
|
||||||
|
|
||||||
|
serviceUnavailable (503), badRequest (400), unauthorized (401),
|
||||||
|
forbidden (403), badMethod (405), overLimit (413), itemNotFound (404)
|
||||||
|
|
||||||
|
**Response parameters**
|
||||||
|
|
||||||
|
.. csv-table::
|
||||||
|
:header: "Parameter", "Style", "Type", "Description"
|
||||||
|
:widths: 20, 20, 20, 60
|
||||||
|
|
||||||
|
"contents (Optional)", "plain", "xsd:list", "The RPMs contained within the patch."
|
||||||
|
"patch (Optional)", "plain", "xsd:list", "A patch present in the patching system."
|
||||||
|
"pkg (Optional)", "plain", "xsd:string", "A package included in a patch."
|
||||||
|
"error (Optional)", "plain", "xsd:string", "Any errors associated with the patch."
|
||||||
|
"metadata (Optional)", "plain", "xsd:list", "Metadata associated with the patch."
|
||||||
|
"status (Optional)", "plain", "xsd:string", "The status of the patch."
|
||||||
|
"sw_version (Optional)", "plain", "xsd:string", "The software version for which the patch is intended."
|
||||||
|
"install_instructions (Optional)", "plain", "xsd:string", "Instructions on how to install the patch."
|
||||||
|
"description (Optional)", "plain", "xsd:string", "The description of any updates present in this patch."
|
||||||
|
"warnings (Optional)", "plain", "xsd:string", "Any warnings associated with the usage of the patch."
|
||||||
|
"summary (Optional)", "plain", "xsd:string", "A brief summary of the patch."
|
||||||
|
"repostate (Optional)", "plain", "xsd:string", "Whether the patch content has been added to the patching repository; ``Applied`` or ``Available``."
|
||||||
|
"patchstate (Optional)", "plain", "xsd:string", "The state of the patch regarding application to hosts; ``Available``, ``Partial-Apply``, ``Applied``, or ``Partial-Removed``."
|
||||||
|
"requires (Optional)", "plain", "xsd:list", "A list of patch ids required for this patch to be installed."
|
||||||
|
|
||||||
|
::
|
||||||
|
|
||||||
|
{
|
||||||
|
"contents": {
|
||||||
|
"TS_15.12_PATCH_0002": [
|
||||||
|
"python-horizon-2013.2.3-r118.x86_64.rpm",
|
||||||
|
"sysinv-1.0-r81.x86_64.rpm"
|
||||||
|
]
|
||||||
|
},
|
||||||
|
"error": "",
|
||||||
|
"metadata": {
|
||||||
|
"TS_15.12_PATCH_0002": {
|
||||||
|
"description": "Fixes the following Issues:\n compute-4 and storage-0 multiple resets after DOR",
|
||||||
|
"install_instructions": "",
|
||||||
|
"patchstate": "Partial-Remove",
|
||||||
|
"repostate": "Available",
|
||||||
|
"requires": [],
|
||||||
|
"status": "DEV",
|
||||||
|
"summary": "TS_15.12 Patch 0002",
|
||||||
|
"sw_version": "15.12",
|
||||||
|
"warnings": ""
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
This operation does not accept a request body.
|
||||||
|
|
||||||
|
**************************************
|
||||||
|
Uploads a patch to the patching system
|
||||||
|
**************************************
|
||||||
|
|
||||||
|
.. rest_method:: POST /v1/upload
|
||||||
|
|
||||||
|
**NOTE:** You can add only a single patch per request.
|
||||||
|
|
||||||
|
**Normal response codes**
|
||||||
|
|
||||||
|
200
|
||||||
|
|
||||||
|
**Error response codes**
|
||||||
|
|
||||||
|
badMediaType (415)
|
||||||
|
|
||||||
|
**Response parameters**
|
||||||
|
|
||||||
|
.. csv-table::
|
||||||
|
:header: "Parameter", "Style", "Type", "Description"
|
||||||
|
:widths: 20, 20, 20, 60
|
||||||
|
|
||||||
|
"info (Optional)", "plain", "xsd:string", "Any information regarding the request processing."
|
||||||
|
"warning (Optional)", "plain", "xsd:string", "Any warnings generated during the request processing."
|
||||||
|
"error (Optional)", "plain", "xsd:string", "Any errors generated during the request processing."
|
||||||
|
|
||||||
|
::
|
||||||
|
|
||||||
|
{
|
||||||
|
"info": "TS_15.12_PATCH_0001 is now available\n",
|
||||||
|
"warning": "",
|
||||||
|
"error": ""
|
||||||
|
}
|
||||||
|
|
||||||
|
**********************************************
|
||||||
|
Applies a patch that is in the Available state
|
||||||
|
**********************************************
|
||||||
|
|
||||||
|
.. rest_method:: POST /v1/apply/{patch_id}
|
||||||
|
|
||||||
|
**Normal response codes**
|
||||||
|
|
||||||
|
200
|
||||||
|
|
||||||
|
**Error response codes**
|
||||||
|
|
||||||
|
badMediaType (415)
|
||||||
|
|
||||||
|
**Response parameters**
|
||||||
|
|
||||||
|
.. csv-table::
|
||||||
|
:header: "Parameter", "Style", "Type", "Description"
|
||||||
|
:widths: 20, 20, 20, 60
|
||||||
|
|
||||||
|
"info (Optional)", "plain", "xsd:string", "Any information regarding the request processing."
|
||||||
|
"warning (Optional)", "plain", "xsd:string", "Any warnings generated during the request processing."
|
||||||
|
"error (Optional)", "plain", "xsd:string", "Any errors generated during the request processing."
|
||||||
|
|
||||||
|
::
|
||||||
|
|
||||||
|
{
|
||||||
|
"info": "TS_15.12_PATCH_0001 has been applied\n",
|
||||||
|
"warning": "",
|
||||||
|
"error": ""
|
||||||
|
}
|
||||||
|
|
||||||
|
This operation does not accept a request body.
|
||||||
|
|
||||||
|
********************************************
|
||||||
|
Removes a patch that is in the Applied state
|
||||||
|
********************************************
|
||||||
|
|
||||||
|
.. rest_method:: POST /v1/remove/{patch_id}
|
||||||
|
|
||||||
|
**Normal response codes**
|
||||||
|
|
||||||
|
200
|
||||||
|
|
||||||
|
**Error response codes**
|
||||||
|
|
||||||
|
badMediaType (415)
|
||||||
|
|
||||||
|
**Response parameters**
|
||||||
|
|
||||||
|
.. csv-table::
|
||||||
|
:header: "Parameter", "Style", "Type", "Description"
|
||||||
|
:widths: 20, 20, 20, 60
|
||||||
|
|
||||||
|
"info (Optional)", "plain", "xsd:string", "Any information regarding the request processing."
|
||||||
|
"warning (Optional)", "plain", "xsd:string", "Any warnings generated during the request processing."
|
||||||
|
"error (Optional)", "plain", "xsd:string", "Any errors generated during the request processing."
|
||||||
|
|
||||||
|
::
|
||||||
|
|
||||||
|
{
|
||||||
|
"info": "TS_15.12_PATCH_0001 has been removed from the repo\n",
|
||||||
|
"warning": "",
|
||||||
|
"error": ""
|
||||||
|
}
|
||||||
|
|
||||||
|
This operation does not accept a request body.
|
||||||
|
|
||||||
|
**********************************************
|
||||||
|
Deletes a patch that is in the Available state
|
||||||
|
**********************************************
|
||||||
|
|
||||||
|
.. rest_method:: POST /v1/delete/{patch_id}
|
||||||
|
|
||||||
|
**Normal response codes**
|
||||||
|
|
||||||
|
200
|
||||||
|
|
||||||
|
**Error response codes**
|
||||||
|
|
||||||
|
badMediaType (415)
|
||||||
|
|
||||||
|
**Response parameters**
|
||||||
|
|
||||||
|
.. csv-table::
|
||||||
|
:header: "Parameter", "Style", "Type", "Description"
|
||||||
|
:widths: 20, 20, 20, 60
|
||||||
|
|
||||||
|
"info (Optional)", "plain", "xsd:string", "Any information regarding the request processing."
|
||||||
|
"warning (Optional)", "plain", "xsd:string", "Any warnings generated during the request processing."
|
||||||
|
"error (Optional)", "plain", "xsd:string", "Any errors generated during the request processing."
|
||||||
|
|
||||||
|
::
|
||||||
|
|
||||||
|
{
|
||||||
|
"info": "TS_15.12_PATCH_0001 has been deleted\n",
|
||||||
|
"warning": "",
|
||||||
|
"error": ""
|
||||||
|
}
|
||||||
|
|
||||||
|
This operation does not accept a request body.
|
||||||
|
|
||||||
|
------
|
||||||
|
Hosts
|
||||||
|
------
|
||||||
|
|
||||||
|
Hosts are the physical hosts or servers for the system as viewed by the
|
||||||
|
patching service.
|
||||||
|
|
||||||
|
******************************************************
|
||||||
|
Lists all host entities and their patching information
|
||||||
|
******************************************************
|
||||||
|
|
||||||
|
.. rest_method:: GET /v1/query_hosts
|
||||||
|
|
||||||
|
**Normal response codes**
|
||||||
|
|
||||||
|
200
|
||||||
|
|
||||||
|
**Error response codes**
|
||||||
|
|
||||||
|
serviceUnavailable (503), badRequest (400), unauthorized (401),
|
||||||
|
forbidden (403), badMethod (405), overLimit (413), itemNotFound (404)
|
||||||
|
|
||||||
|
**Response parameters**
|
||||||
|
|
||||||
|
.. csv-table::
|
||||||
|
:header: "Parameter", "Style", "Type", "Description"
|
||||||
|
:widths: 20, 20, 20, 60
|
||||||
|
|
||||||
|
"data (Optional)", "plain", "xsd:list", "The list of host entities."
|
||||||
|
"requires_reboot (Optional)", "plain", "xsd:boolean", "Indicates whether the host requires a reboot."
|
||||||
|
"nodetype (Optional)", "plain", "xsd:string", "The type of the host; ``controller``, ``compute`` or ``storage``."
|
||||||
|
"missing_pkgs (Optional)", "plain", "xsd:list", "The list of packages missing from this host."
|
||||||
|
"ip (Optional)", "plain", "xsd:string", "The ip address of the host."
|
||||||
|
"hostname (Optional)", "plain", "xsd:string", "The name of the host."
|
||||||
|
"installed (Optional)", "plain", "xsd:list", "The packages installed on this host by the patching system."
|
||||||
|
"secs_since_ack (Optional)", "plain", "xsd:integer", "The number of seconds since the host last reported its status."
|
||||||
|
"patch_failed (Optional)", "plain", "xsd:boolean", "Indicates whether a patch installation has failed on the host."
|
||||||
|
"stale_details (Optional)", "plain", "xsd:boolean", "Indicates whether the details of this host are out of date."
|
||||||
|
"patch_current (Optional)", "plain", "xsd:boolean", "Indicates whether the host is up to date regarding patches."
|
||||||
|
"to_remove (Optional)", "plain", "xsd:list", "The list of packages that are to be removed from the host."
|
||||||
|
"sw_version (Optional)", "plain", "xsd:string", "The software version running on the host."
|
||||||
|
"state (Optional)", "plain", "xsd:string", "The state of the patch agent: <ul><li>``idle``: The patch agent is in an idle state, ready for installation requests. </li><li>``installing``: The patch agent is installing or removing patches as needed. </li><li>``install-failed``: The installation failed on the host. </li><li>``install-rejected``: The host is unlocked. Lock the node, and run the command again. </li></ul>"
|
||||||
|
"subfunctions (Optional)", "plain", "xsd:list", "The list of host subfunctions."
|
||||||
|
|
||||||
|
::
|
||||||
|
|
||||||
|
{
|
||||||
|
'data': [
|
||||||
|
{
|
||||||
|
'hostname': 'controller-0',
|
||||||
|
'nodetype': 'controller',
|
||||||
|
'patch_failed': False,
|
||||||
|
'ip': u'192.168.204.3',
|
||||||
|
'requires_reboot': False,
|
||||||
|
'installed': {},
|
||||||
|
'secs_since_ack': 18,
|
||||||
|
'missing_pkgs': [],
|
||||||
|
'patch_current': True,
|
||||||
|
'stale_details': False,
|
||||||
|
'to_remove': [],
|
||||||
|
'state': 'idle',
|
||||||
|
'subfunctions': [
|
||||||
|
'controller'
|
||||||
|
],
|
||||||
|
'sw_version': '15.12'
|
||||||
|
},
|
||||||
|
{ 'hostname': 'compute-0',
|
||||||
|
'nodetype': 'compute',
|
||||||
|
'patch_failed': False,
|
||||||
|
'ip': u'192.168.204.27',
|
||||||
|
'requires_reboot': False,
|
||||||
|
'installed': {},
|
||||||
|
'secs_since_ack': 18,
|
||||||
|
'missing_pkgs': [],
|
||||||
|
'patch_current': True,
|
||||||
|
'stale_details': False,
|
||||||
|
'to_remove': [],
|
||||||
|
'state': 'idle',
|
||||||
|
'subfunctions': [
|
||||||
|
'compute'
|
||||||
|
],
|
||||||
|
'sw_version': '15.12'
|
||||||
|
}
|
||||||
|
]
|
||||||
|
}
|
||||||
|
|
||||||
|
This operation does not accept a request body.
|
||||||
|
|
||||||
|
**********************************************************
|
||||||
|
Trigger an asynchronous host install on the specified host
|
||||||
|
**********************************************************
|
||||||
|
|
||||||
|
.. rest_method:: POST /v1/host_install_async/{hostname}
|
||||||
|
|
||||||
|
The host must be in the Locked-Disabled-Online state.
|
||||||
|
|
||||||
|
**Normal response codes**
|
||||||
|
|
||||||
|
200
|
||||||
|
|
||||||
|
**Error response codes**
|
||||||
|
|
||||||
|
serviceUnavailable (503), badRequest (400), unauthorized (401),
|
||||||
|
forbidden (403), badMethod (405), overLimit (413), badMediaType (415)
|
||||||
|
|
||||||
|
**Response parameters**
|
||||||
|
|
||||||
|
.. csv-table::
|
||||||
|
:header: "Parameter", "Style", "Type", "Description"
|
||||||
|
:widths: 20, 20, 20, 60
|
||||||
|
|
||||||
|
"info (Optional)", "plain", "xsd:string", "Any information regarding the request processing."
|
||||||
|
"warning (Optional)", "plain", "xsd:string", "Any warnings generated during the request processing."
|
||||||
|
"error (Optional)", "plain", "xsd:string", "Any errors generated during the request processing."
|
||||||
|
|
||||||
|
::
|
||||||
|
|
||||||
|
{
|
||||||
|
"info": "Patch installation request sent to compute-0.\n",
|
||||||
|
"warning": "",
|
||||||
|
"error": ""
|
||||||
|
}
|
||||||
|
|
||||||
|
This operation does not accept a request body.
|
||||||
@ -6,3 +6,5 @@ StarlingX Installation/Update/Patching/Backup/Restore
|
|||||||
|
|
||||||
.. toctree::
|
.. toctree::
|
||||||
:maxdepth: 2
|
:maxdepth: 2
|
||||||
|
|
||||||
|
api-ref-patching-v1-update
|
||||||
|
|||||||
Loading…
Reference in New Issue
Block a user