Documentation for Glance tasks

Added some docs for:-
    - configuration
    - notifications
    - statuses

partially implements blueprint async-glance-workers

Change-Id: I4e33bc3be2278d6906968d1dac3aff6587eef6df

doc/source/configuring.rst

@@ -1295,3 +1295,20 @@ glance-registry service while the v2 API is not. This means that
 in order to use the v2 API, you must copy the necessary sql
 configuration from your glance-registry service to your
 glance-api configuration file.
+
+Configuring Glance Tasks
+------------------------
+
+Glance Tasks are implemented only for version 2 of the OpenStack Images API.
+
+``Please be aware that Glance tasks are currently a work in progress
+feature.`` Although, the API is available, the execution part of it
+is being worked on.
+
+The config value ``task_time_to_live`` is used to determine how long a task
+would be visible to the user after transitioning to either the ``success`` or
+the ``failure`` state.
+
+* ``task_time_to_live=<Time_in_hours>``
+
+Optional. Default: ``48``

doc/source/notifications.rst

@@ -76,6 +76,21 @@ Notification Types
 
   Emitted when an image deleted from Glance.
 
+* ``task.run``
+
+  Emitted when a task is picked up by the executor to be run.
+
+* ``task.processing``
+
+  Emitted when a task is sent over to the executor to begin processing.
+
+* ``task.success``
+
+  Emitted when a task is successfully completed.
+
+* ``task.failure``
+
+  Emitted when a task fails.
 
 Content
 -------
@@ -154,3 +169,50 @@ Payload
 
   For INFO events, it is the image id.
   WARN and ERROR events contain a text message in the payload.
+
+* task.run
+
+  The payload for INFO, WARN, and ERROR events contain the following:
+
+  task_id
+    ID of the task (UUID)
+  owner
+    Tenant or User ID that created this task (string)
+  task_type
+    Type of the task. Example, task_type is "import". (string)
+  status,
+    status of the task. Status can be "pending", "processing",
+    "success" or "failure". (string)
+  task_input
+    Input provided by the user when attempting to create a task. (dict)
+  result
+    Resulting output from a successful task. (dict)
+  message
+    Message shown in the task if it fails. None if task succeeds. (string)
+  expires_at
+    UTC time at which the task would not be visible to the user. (string)
+  created_at
+    UTC time at which the task was created. (string)
+  updated_at
+    UTC time at which the task was latest updated. (string)
+
+  The exceptions are:-
+    For INFO events, it is the task dict with result and message as None.
+    WARN and ERROR events contain a text message in the payload.
+
+* task.processing
+
+  For INFO events, it is the task dict with result and message as None.
+  WARN and ERROR events contain a text message in the payload.
+
+* task.success
+
+  For INFO events, it is the task dict with message as None and result is a
+  dict.
+  WARN and ERROR events contain a text message in the payload.
+
+* task.failure
+
+  For INFO events, it is the task dict with result as None and message is
+  text.
+  WARN and ERROR events contain a text message in the payload.

doc/source/statuses.rst

@@ -67,3 +67,29 @@ Images in Glance can be in one the following statuses:
 
    * Remove location from one or more to zero by PATCH method which is only
      supported in v2.
+
+Task Statuses
+==============
+
+Tasks in Glance can be in one the following statuses:
+
+* ``pending``
+
+  The task identifier has been reserved for a task in the Glance.
+  No processing has begun on it yet.
+
+* ``processing``
+
+  The task has been picked up by the underlying executor and is being run
+  using the backend Glance execution logic for that task type.
+
+* ``success``
+
+  Denotes that the task has had a successful run within Glance. The ``result``
+  field of the task shows more details about the outcome.
+
+* ``failure``
+
+  Denotes that an error occurred during the execution of the task and it
+  cannot continue processing. The ``message`` field of the task shows what the
+  error was.