From c763e0de0756259706f64d13d7214fe26bb3c9a1 Mon Sep 17 00:00:00 2001 From: Scott Rifenbark Date: Tue, 25 Sep 2018 15:04:39 -0700 Subject: [PATCH] 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 Signed-off-by: Abraham Arce --- api-ref/source/api-ref-patching-v1-update.rst | 433 ++++++++++++++++++ api-ref/source/index.rst | 2 + 2 files changed, 435 insertions(+) create mode 100644 api-ref/source/api-ref-patching-v1-update.rst diff --git a/api-ref/source/api-ref-patching-v1-update.rst b/api-ref/source/api-ref-patching-v1-update.rst new file mode 100644 index 00000000..7e5770ac --- /dev/null +++ b/api-ref/source/api-ref-patching-v1-update.rst @@ -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:
  • ``idle``: The patch agent is in an idle state, ready for installation requests.
  • ``installing``: The patch agent is installing or removing patches as needed.
  • ``install-failed``: The installation failed on the host.
  • ``install-rejected``: The host is unlocked. Lock the node, and run the command again.
" + "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. diff --git a/api-ref/source/index.rst b/api-ref/source/index.rst index 435e2c8c..53fe2db4 100644 --- a/api-ref/source/index.rst +++ b/api-ref/source/index.rst @@ -6,3 +6,5 @@ StarlingX Installation/Update/Patching/Backup/Restore .. toctree:: :maxdepth: 2 + + api-ref-patching-v1-update