From 36c688f694c7b3e27af804851b9072655946e8d9 Mon Sep 17 00:00:00 2001 From: Sean Dague Date: Wed, 11 May 2016 14:47:13 -0400 Subject: [PATCH] api-ref: finish validation for os-server-external-events.inc This completes the validation for the admin event interface, including detailing the codes we currently return in the parameter list. Because os-service was incorrectly using the 'status' key, when I renamed status => event_status I needed to also create a service_status to make things compile. It's accurate enough to move forward. Because this is really a Neutron only API, this is moved towards the bottom of the API list, to make it clear this isn't really designed to be used by end user apps. Part of bp:api-ref-in-rst Change-Id: I3ed46eec1c33a63b7a89d6d6b5eeda574effdc56 --- api-ref/source/index.rst | 2 +- api-ref/source/os-server-external-events.inc | 44 ++++++++++------ api-ref/source/os-services.inc | 8 +-- api-ref/source/parameters.yaml | 53 ++++++++++++-------- 4 files changed, 66 insertions(+), 41 deletions(-) diff --git a/api-ref/source/index.rst b/api-ref/source/index.rst index dd40dd5fcb7a..711dc0d32573 100644 --- a/api-ref/source/index.rst +++ b/api-ref/source/index.rst @@ -56,10 +56,10 @@ .. include:: os-security-groups.inc .. include:: os-security-group-default-rules.inc .. include:: os-security-group-rules.inc -.. include:: os-server-external-events.inc .. include:: os-server-groups.inc .. include:: os-services.inc .. include:: os-simple-tenant-usage.inc .. include:: os-tenant-network.inc .. include:: os-volumes.inc +.. include:: os-server-external-events.inc .. include:: extensions.inc diff --git a/api-ref/source/os-server-external-events.inc b/api-ref/source/os-server-external-events.inc index 990e1158e7fa..c652f3299bc6 100644 --- a/api-ref/source/os-server-external-events.inc +++ b/api-ref/source/os-server-external-events.inc @@ -1,12 +1,19 @@ .. -*- rst -*- -.. needs:parameter_verification -.. needs:example_verification -.. needs:body_verification ==================================================== Create external events (os-server-external-events) ==================================================== +.. warning:: + This is an ``admin`` level service API only designed to be used by + other OpenStack services. The point of this API is to coordinate + between Nova and Neutron (and potentially future services) on + activities they both need to be involved in, such as network + hotplugging. + + Unless you are writing Neutron code you **should not** be using + this API. + Creates one or more external events. The API dispatches each event to a server instance. @@ -15,14 +22,22 @@ Run Events .. rest_method:: POST /v2.1/{tenant_id}/os-server-external-events -Creates one or more external events, which the API dispatches to the instance. +Creates one or more external events, which the API dispatches to the +host a server is assigned to. If the server is not currently assigned +to a host the event will not be delivered. -You must assign this instance to a host. Otherwise, this call does not dispatch the event to the instance. +You will receive back the list of events that you submitted, with an +updated ``code`` and ``status`` indicating their level of success. -Normal response codes: 200 +Normal response codes: 200, 207 + +A 200 will be returned if all events succeeded, 207 will be returned +if some events could not be processed. The ``code`` attribute for the +event will explain further what went wrong. Error response codes: badRequest(400), unauthorized(401), forbidden(403), itemNotFound(404) + Request ------- @@ -30,12 +45,12 @@ Request - tenant_id: tenant_id - events: events - - name: name - - tag: tag + - name: event_name - server_uuid: server_uuid - - status: status + - status: event_status + - tag: event_tag -**Example Run Events: JSON request** +**Example Run Events** .. literalinclude:: ../../doc/api_samples/os-server-external-events/event-create-req.json :language: javascript @@ -47,13 +62,12 @@ Response - events: events - code: code - - name: name + - name: event_name - server_uuid: server_uuid - - status: status - - tag: tag + - status: event_status + - tag: event_tag -**Example Run Events: JSON response** +**Example Run Events** .. literalinclude:: ../../doc/api_samples/os-server-external-events/event-create-resp.json :language: javascript - diff --git a/api-ref/source/os-services.inc b/api-ref/source/os-services.inc index c18ae56bbc8d..4da3bb2c0440 100644 --- a/api-ref/source/os-services.inc +++ b/api-ref/source/os-services.inc @@ -45,7 +45,7 @@ Response - disabled_reason: disabled_reason - host: host - state: service_state - - status: status + - status: service_status - updated_at: updated - forced_down: forced_down - zone: OS-EXT-AZ:availability_zone @@ -90,7 +90,7 @@ Response - service: service - binary: binary - host: host - - status: status + - status: service_status **Example Enable Scheduling For A Compute Service: JSON response** @@ -132,7 +132,7 @@ Response - service: service - binary: binary - host: host - - status: status + - status: service_status **Example Disable Scheduling For A Compute Service: JSON response** @@ -176,7 +176,7 @@ Response - binary: binary - disabled_reason: disabled_reason - host: host - - status: status + - status: service_status **Example Log Disabled Compute Service Information: JSON response** diff --git a/api-ref/source/parameters.yaml b/api-ref/source/parameters.yaml index 08fd0df2658e..5ba09d5a7b98 100644 --- a/api-ref/source/parameters.yaml +++ b/api-ref/source/parameters.yaml @@ -859,7 +859,12 @@ cidr: type: string code: description: | - The HTTP response code for the event. + The HTTP response code for the event. The following codes are currently used: + + * 200 - successfully submitted event + * 404 - the instance specified by ``server_uuid`` was not found + * 422 - no host was found for the server specified by ``server_uuid``, + so there is no route to this server. in: body required: true type: string @@ -1011,6 +1016,26 @@ evacuate: in: body required: true type: string +event_name: + description: | + The event name. A valid value is ``network-changed``, ``network-vif-plugged``, + ``network-vif-unplugged``, or ``network-vif-deleted``. + in: body + required: true + type: string +event_status: + description: | + The event status. A valid value is ``failed``, ``completed``, or ``in-progress``. + Default is ``completed``. + in: body + required: false + type: string +event_tag: + description: | + A string value that identifies the event. + in: body + required: false + type: string events: description: | The action. @@ -1607,13 +1632,6 @@ name_10: in: body required: true type: string -name_2: - description: | - The event name. A valid value is ``network- changed``, ``network- vif-plugged``, - ``network-vif-unplugged``, or ``network-vif- deleted``. - in: body - required: true - type: string name_3: description: | The name to associate with the keypair. @@ -2152,6 +2170,12 @@ service_state: type: string description: | The state of the service. One of ``up`` or ``down``. +service_status: + in: body + required: true + type: string + description: | + The status of the service. One of ``enabled`` or ``disabled``. shelve: description: | The action. @@ -2195,13 +2219,6 @@ source_type: in: body required: true type: string -status: - description: | - The event status. A valid value is ``failed``, ``completed``, or ``in-progress``. - Default is ``completed``. - in: body - required: false - type: string server_status: description: | The server status. @@ -2214,12 +2231,6 @@ suspend: in: body required: true type: string -tag: - description: | - A string value that identifies the event. - in: body - required: false - type: string tenant_id_body: description: | The UUID of the tenant this server is owned by.