Merge "add api-ref for masakari vmoves"

api-ref/source/index.rst

@@ -13,3 +13,4 @@ Masakari project.
 .. include:: failover-segments.inc
 .. include:: hosts.inc
 .. include:: notifications.inc
+.. include:: vmoves.inc

api-ref/source/parameters.yaml

@@ -25,6 +25,12 @@ segment_id_path:
   in: path
   required: true
   type: string
+vmove_id_path:
+  description: |
+    The UUID of the vmove.
+  in: path
+  required: true
+  type: string
 
 # variables in query
 generated_since_query_notifications:
@@ -135,12 +141,34 @@ sort_key_segment:
   in: query
   required: false
   type: string
+sort_key_vmove:
+  description: |
+    Sorts by a vmove attribute. Default attribute is ``created_at``. You can specify
+    multiple pairs of sort key and sort direction query parameters. If you omit the
+    sort direction in a pair, the API uses the natural sorting direction of the vmove
+    ``sort_key`` attribute. The sort keys are limited to:
+
+    - ``created_at``
+    - ``updated_at``
+    - ``uuid``
+    - ``start_time``
+    - ``type``
+    - ``status``
+  in: query
+  required: false
+  type: string
 source_host_uuid_query_notifications:
   description: |
     Filter the notifications list result by source_host_uuid.
   in: query
   required: false
   type: string
+status_query_vmove:
+  description: |
+    Filter the vmoves list result by vmove status.
+  in: query
+  required: false
+  type: string
 type_query_host:
   description: |
     Filter the host list result by type of host.
@@ -153,7 +181,12 @@ type_query_notifications:
   in: query
   required: false
   type: string
-
+type_query_vmove:
+  description: |
+    Filter the vmoves list result by vmove type.
+  in: query
+  required: false
+  type: string
 # variables in body
 control_attributes:
   description: |
@@ -431,3 +464,69 @@ versions:
   required: true
   description: >
     A list of version objects that describe the API versions available.
+vmove:
+  description: |
+    A ``vmove`` object.
+  in: body
+  required: true
+  type: object
+vmove_end_time:
+  description: |
+    The date and time when the vmove ended.
+  in: body
+  required: true
+  type: string
+vmove_id:
+  description: |
+    ID of vmove.
+  in: body
+  required: true
+  type: string
+vmove_instance_name:
+  description: |
+    The name of the instance.
+  in: body
+  required: true
+  type: string
+vmove_instance_uuid:
+  description: |
+    The UUID of the instance.
+  in: body
+  required: true
+  type: string
+vmove_message:
+  description: |
+    The vmove message info.
+  in: body
+  required: true
+  type: string
+vmove_start_time:
+  description: |
+    The date and time when the vmove started.
+  in: body
+  required: true
+  type: string
+vmove_status:
+  description: |
+    The vmove status.
+  in: body
+  required: true
+  type: string
+vmove_type:
+  description: |
+    The vmove type.
+  in: body
+  required: true
+  type: string
+vmove_uuid:
+  description: |
+    The UUID of the vmove.
+  in: body
+  required: true
+  type: string
+vmoves:
+  description: |
+    A list of ``vmove`` objects.
+  in: body
+  required: true
+  type: array

api-ref/source/vmoves.inc

@@ -0,0 +1,161 @@
+.. -*- rst -*-
+
+================
+ VMoves (vmoves)
+================
+
+**VMoves**
+
+A vmove belongs to one host failure notification.
+
+Lists, shows details for vmoves.
+
+List VMoves
+============
+
+.. rest_method:: GET /notification/{notification_id}/vmoves
+
+Lists IDs, notification_id, instance_id, source_host, dest_host,
+start_time, end_time, status and type for all VM moves.
+
+Vmoves contain a `type` attribute that indicates the current
+vmove type. The possible vmove `type` values are:
+
+- ``evacuation``. The vmove is one evacuation.
+- ``migration``. The vmove is one migration.
+- ``live_migration``. The vmove is one live_migration.
+
+Vmoves contain a `status` attribute that indicates the current
+vmove state. The possible vmove `status` values are:
+
+- ``pending``. The vmove is in pending state and yet to be processed.
+- ``ongoing``. The vmove is in progress.
+- ``succeeded``. The vmove is processed successfully.
+- ``failed``. The vmove is processed failed.
+- ``ignored``. The vmove is ignored for some reason.
+
+You can filter on the `type` and `status` when you complete a list
+vmoves request.
+
+**Preconditions**
+
+The notification must exist.
+
+Response Codes
+--------------
+
+.. rest_status_code:: success status.yaml
+
+   - 200
+
+.. rest_status_code:: error status.yaml
+
+   - 400
+   - 401
+   - 403
+   - 404
+
+..
+
+  BadRequest (400) is returned if the notification type is not `COMPUTE_NODE`.
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+  - notification_id: notification_id_path
+  - limit: limit
+  - marker: marker
+  - sort_dir: sort_dir
+  - sort_key: sort_key_vmove
+  - status: status_query_vmove
+  - type: type_query_vmove
+
+Response
+--------
+
+.. rest_parameters:: parameters.yaml
+
+  - vmoves: vmoves
+  - created_at: created
+  - updated_at: updated
+  - deleted: deleted
+  - id: vmove_id
+  - uuid: vmove_uuid
+  - notification_uuid: notification_uuid
+  - instance_uuid: vmove_instance_uuid
+  - instance_name: vmove_instance_name
+  - source_host: host_name
+  - dest_host: host_name
+  - start_time: vmove_start_time
+  - end_time: vmove_end_time
+  - status: vmove_status
+  - type: vmove_type
+  - message: vmove_message
+
+**Example List vmoves**
+
+.. literalinclude:: ../../doc/api_samples/vmoves/vmoves-list-resp.json
+   :language: javascript
+
+
+Show VMove Details
+===================
+
+.. rest_method:: GET /notifications/{notification_id}/vmoves/{vmove_id}
+
+Shows details for a vmove.
+
+**Preconditions**
+
+The notification must exist.
+The vmove must exist.
+
+Response Codes
+--------------
+
+.. rest_status_code:: success status.yaml
+
+   - 200
+
+.. rest_status_code:: error status.yaml
+
+   - 401
+   - 403
+   - 404
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+  - notification_id: notification_id_path
+  - vmove_id: vmove_id_path
+
+Response
+--------
+
+.. rest_parameters:: parameters.yaml
+
+  - vmove: vmove
+  - created_at: created
+  - updated_at: updated
+  - deleted: deleted
+  - id: vmove_id
+  - uuid: vmove_uuid
+  - notification_uuid: notification_uuid
+  - instance_uuid: vmove_instance_uuid
+  - instance_name: vmove_instance_name
+  - source_host: host_name
+  - dest_host: host_name
+  - start_time: vmove_start_time
+  - end_time: vmove_end_time
+  - status: vmove_status
+  - type: vmove_type
+  - message: vmove_message
+
+**Example Show VMove Details**
+
+.. literalinclude:: ../../doc/api_samples/vmoves/vmove-get-resp.json
+   :language: javascript

doc/api_samples/vmoves/vmove-get-resp.json

@@ -0,0 +1,19 @@
+{
+    "vmove": {
+        "created_at": "2023-01-28T14:55:27.000000",
+        "updated_at": null,
+        "deleted_at": null,
+        "deleted": false,
+        "id": 1,
+        "notification_uuid": "a0e70d3a-b3a2-4616-b65d-a7c03a2c85fc",
+        "instance_uuid": "1c2f1795-ce78-4d4c-afd0-ce141fdb3952",
+        "instance_name": "vm1",
+        "source_host": "host1",
+        "dest_host": "host2",
+        "start_time": "2023-01-28T14:55:27.000000",
+        "end_time": "2023-01-28T14:55:31.000000",
+        "status": "succeeded",
+        "type": "evacuation",
+        "message": null
+    }
+}

doc/api_samples/vmoves/vmoves-list-resp.json

@@ -0,0 +1,21 @@
+{
+    "vmoves": [
+        {
+            "created_at": "2023-01-28T14:55:27.000000",
+            "updated_at": null,
+            "deleted_at": null,
+            "deleted": false,
+            "id": 1,
+            "notification_uuid": "a0e70d3a-b3a2-4616-b65d-a7c03a2c85fc",
+            "instance_uuid": "1c2f1795-ce78-4d4c-afd0-ce141fdb3952",
+            "instance_name": "vm1",
+            "source_host": "host1",
+            "dest_host": "host2",
+            "start_time": "2023-01-28T14:55:27.000000",
+            "end_time": "2023-01-28T14:55:31.000000",
+            "status": "succeeded",
+            "type": "evacuation",
+            "message": null
+        }
+    ]
+}