From 3cdb385dacf1a8122e448cac67e4bab1ce01ec5d Mon Sep 17 00:00:00 2001 From: Karen Bradshaw Date: Wed, 25 May 2016 12:35:09 -0400 Subject: [PATCH] api-ref, os-services.inc Verified parameters, examples, body text. Included v2.11 sample files for GET and PUT os-services. Part of: bp/api-ref-in-rst Change-Id: Ice4fb525d62230b2e20f01789a0aec396835b56b --- api-ref/source/os-services.inc | 170 ++++++++++++++++++++------------- api-ref/source/parameters.yaml | 49 ++++++---- 2 files changed, 134 insertions(+), 85 deletions(-) diff --git a/api-ref/source/os-services.inc b/api-ref/source/os-services.inc index d91eb5a6ec95..ba981426fc69 100644 --- a/api-ref/source/os-services.inc +++ b/api-ref/source/os-services.inc @@ -1,7 +1,4 @@ .. -*- rst -*- -.. needs:parameter_verification -.. needs:example_verification -.. needs:body_verification ================================ Compute services (os-services) @@ -21,7 +18,7 @@ List Compute Services Lists all running Compute services. -Includes reasons, if available, for why any services were disabled. +Provides details why any services were disabled. Normal response codes: 200 @@ -33,61 +30,19 @@ Response .. rest_parameters:: parameters.yaml - services: services - - id: id + - id: service_id_body - binary: binary - - disabled_reason: disabled_reason - - host: host + - disabled_reason: disabled_reason_body + - host: host_name_body - state: service_state - status: service_status - updated_at: updated - forced_down: forced_down - zone: OS-EXT-AZ:availability_zone -**Example List Compute Services: JSON response** +**Example List Compute Services** -.. literalinclude:: ../../doc/api_samples/os-services/services-list-get-resp.json - :language: javascript - -Enable Scheduling For A Compute Service -======================================= - -.. rest_method:: PUT /os-services/enable - -Enables scheduling for a Compute service. - -Specify the service by its host name and binary name. - -Normal response codes: 200 - -Error response codes: badRequest(400), unauthorized(401), forbidden(403), itemNotFound(404) - -Request -------- - -.. rest_parameters:: parameters.yaml - - - - host: host - - binary: binary - -**Example Enable Scheduling For A Compute Service: JSON request** - -.. literalinclude:: ../../doc/api_samples/os-services/service-enable-put-req.json - :language: javascript - -Response --------- - -.. rest_parameters:: parameters.yaml - - - service: service - - binary: binary - - host: host - - status: service_status - -**Example Enable Scheduling For A Compute Service: JSON response** - -.. literalinclude:: ../../doc/api_samples/os-services/service-enable-put-resp.json +.. literalinclude:: ../../doc/api_samples/os-services/v2.11/services-list-get-resp.json :language: javascript Disable Scheduling For A Compute Service @@ -95,7 +50,7 @@ Disable Scheduling For A Compute Service .. rest_method:: PUT /os-services/disable -Disables scheduling for a Compute service. +Disables scheduling for a Compute service with optional logging. Specify the service by its host name and binary name. @@ -108,11 +63,10 @@ Request .. rest_parameters:: parameters.yaml - - - host: host + - host: host_name_body - binary: binary -**Example Disable Scheduling For A Compute Service: JSON request** +**Example Disable Scheduling For A Compute Service** .. literalinclude:: ../../doc/api_samples/os-services/service-disable-put-req.json :language: javascript @@ -124,10 +78,10 @@ Response - service: service - binary: binary - - host: host + - host: host_name_body - status: service_status -**Example Disable Scheduling For A Compute Service: JSON response** +**Example Disable Scheduling For A Compute Service** .. literalinclude:: ../../doc/api_samples/os-services/service-disable-put-resp.json :language: javascript @@ -150,12 +104,11 @@ Request .. rest_parameters:: parameters.yaml - - - host: host + - host: host_name_body - binary: binary - - disabled_reason: disabled_reason + - disabled_reason: disabled_reason_body -**Example Log Disabled Compute Service Information: JSON request** +**Example Log Disabled Compute Service Information** .. literalinclude:: ../../doc/api_samples/os-services/service-disable-log-put-req.json :language: javascript @@ -167,15 +120,102 @@ Response - service: service - binary: binary - - disabled_reason: disabled_reason - - host: host + - disabled_reason: disabled_reason_body + - host: host_name_body - status: service_status -**Example Log Disabled Compute Service Information: JSON response** +**Example Log Disabled Compute Service Information** .. literalinclude:: ../../doc/api_samples/os-services/service-disable-log-put-resp.json :language: javascript +Enable Scheduling For A Compute Service +======================================= + +.. rest_method:: PUT /os-services/enable + +Enables scheduling for a Compute service. + +Specify the service by its host name and binary name. + +Normal response codes: 200 + +Error response codes: badRequest(400), unauthorized(401), forbidden(403), itemNotFound(404) + +Request +------- + +.. rest_parameters:: parameters.yaml + + - host: host_name_body + - binary: binary + +**Example Enable Scheduling For A Compute Service** + +.. literalinclude:: ../../doc/api_samples/os-services/service-enable-put-req.json + :language: javascript + +Response +-------- + +.. rest_parameters:: parameters.yaml + + - service: service + - binary: binary + - host: host_name_body + - status: service_status + +**Example Enable Scheduling For A Compute Service** + +.. literalinclude:: ../../doc/api_samples/os-services/service-enable-put-resp.json + :language: javascript + +Update Forced Down +================== + +.. rest_method:: PUT /os-services/force-down + +Set or unset ``forced_down`` flag for the service. + +Action ``force-down`` available as of microversion 2.11. + +Specify the service by its host name and binary name. + +Normal response codes: 200 + +Error response codes: badRequest(400), unauthorized(401), forbidden(403), itemNotFound(404) + +Request +------- + +.. rest_parameters:: parameters.yaml + + - host: host_name_body + - binary: binary + - forced_down: forced_down + +**Example Update Forced Down** + +.. literalinclude:: ../../doc/api_samples/os-services/v2.11/service-force-down-put-req.json + :language: javascript + +Response +-------- + +.. rest_parameters:: parameters.yaml + + - service: service + - binary: binary + - forced_down: forced_down + - host: host_name_body + +| + +**Example Update Forced Down** + +.. literalinclude:: ../../doc/api_samples/os-services/v2.11/service-force-down-put-resp.json + :language: javascript + Delete Compute Service ====================== @@ -197,3 +237,5 @@ Request Response -------- + +No response returned in body upon successful DELETE. diff --git a/api-ref/source/parameters.yaml b/api-ref/source/parameters.yaml index 4b803db621c7..6c804673a43a 100644 --- a/api-ref/source/parameters.yaml +++ b/api-ref/source/parameters.yaml @@ -86,7 +86,7 @@ console_id: type: string disabled_reason: description: | - The reason for disable a service. + The reason for disabling a service. in: path required: false type: string @@ -241,11 +241,11 @@ server_id_path: required: true type: string service_id_path: + description: | + The id of the service. in: path required: true - type: int - description: | - The id of the service + type: integer snapshot_id_2: description: | The UUID of the snapshot. @@ -1188,6 +1188,12 @@ device_resp: in: body required: true type: string +disabled_reason_body: + description: | + The reason for disabling a service. + in: body + required: true + type: string disk_available_least: description: | The actual free disk on this hypervisor(in GB). @@ -1537,13 +1543,14 @@ force_live_migrate: type: boolean min_version: 2.30 forced_down: - in: body - required: true - type: boolean description: | Whether or not this service was forced down manually by an administrator. This value is useful to know that some 3rd party has verified the service should be marked down. + in: body + required: true + type: boolean + min_version: 2.11 forceDelete: description: | The action. @@ -3201,47 +3208,47 @@ server_uuid: type: string servers: description: | - List of ``server`` objects. + A list of ``server`` objects. in: body required: true type: array service: + description: | + Object representing a compute service. in: body required: true type: object - description: | - Object representing a compute service service_disable_reason: - in: body - required: true - type: string description: | The disable reason of the service, ``null`` if the service is enabled or disabled without reason provided. + in: body + required: true + type: string service_id_body: + description: | + The id of the service. in: body required: true type: integer - description: | - The id of the service service_state: - in: body - required: true - type: string description: | The state of the service. One of ``up`` or ``down``. -service_status: in: body required: true type: string +service_status: description: | The status of the service. One of ``enabled`` or ``disabled``. + in: body + required: true + type: string services: + description: | + A list of service objects. in: body required: true type: array - description: | - An array of service objects set_metadata: description: | The set_metadata object used to set metadata for host aggregate.