add doc to introduce Polling ability in webhook from PodTransisionRule

docs/operating/manuals/podtransitionrule.md

@@ -26,17 +26,22 @@ spec:
   - availablePolicy:
       maxUnavailableValue: 50%
     name: maxUnavailable
-  - stage: PreCheck  # stages are supported by PodOpsLifecycle
+  - stage: PreCheck  # stages are supported by PodOpsLifecycle. Defaults to PreCheck.
     labelCheck:
       requires:
         matchLabels:
           app.custom/ready: 'true' 
     name: labelCheck
-  - stage: PostCheck 
+  - stage: PostCheck
     webhook:
       clientConfig:
-        url: https://...
+        url: https://1.1.1.1:8089/post-stop
         caBundle: Cg==
+        poll:
+          url: http://1.1.1.1:8089/fetch-result
+          rawQueryKey: task-id   # URL parameter key to carry trace ID when fetching result. Defaults to task-id in form 'QueryUrl=URL?rawQueryKey=<task-id>'
+          intervalSeconds: 5
+          timeoutSeconds: 60
       failurePolicy: Fail
       parameters:
       - key: podIP
@@ -79,7 +84,7 @@ A `labelCheck` rule is used to check if labels are satisfied.
 You can define your own labels as change check conditions and modify the labels according to your needs.
 ```yaml
 labelCheck:
-  requirs:
+  requires:
     matchLabels:
       app.custom/ready: 'true' 
     matchExpressions:
@@ -88,38 +93,47 @@ labelCheck:
 ```
 
 ### Webhook
-A `webhook` is an HTTP callback: an HTTP POST that occurs when pods on configured stage.
-A web application can determine whether the pod can pass this check based on the request.
+A `webhook` is an HTTP callback, based on which a external web application can determine whether a pod can pass this check.
+
+* An HTTP POST occurs first when pods entries the configured stage which defaults PreCheck.
+* If `poll` is provided, this rule then keeps calling polling url to fetch a long running job result. This job can be located by `task-id` returned from the response of the first request.  
+
 
 ```yaml
 webhook:
   clientConfig: # custom server config
-    url: https://...
+    url: https://1.1.1.1:8089/post-stop
     caBundle: Cg==
-    intervalSeconds: 30
+    poll:
+      url: http://1.1.1.1:8089/fetch-result
+      rawQueryKey: task-id
+      intervalSeconds: 5
+      timeoutSeconds: 60
   failurePolicy: Fail
   parameters:
-  - key: podIP
-    valueFrom:
-      fieldRef: 
-        fieldPath: status.podIP
+    - key: podIP
+      valueFrom:
+        fieldRef:
+          fieldPath: status.podIP
 ```
-**Protocol**
+**Protocol without poll**
 
 Request:
 ```json
+// URL: https://1.1.1.1:8089/post-stop
+// Method: POST
+
 { 
-  "traceId": "<trace-id>",
-  "retryByTrace": false,
+  "traceId": "<trace-id>",    // <trace-id> is generated by Operating, which can be used to track request
   "stage": "PreTrafficOff",
   "ruleName": "webhookCheck",
-    "resources": [
+    "resources": [            // Information of Pods which are in this stage
   	{
       "apiVersion": "v1",
       "kind": "Pod",
       "name": "pod-a",
       "parameters": {
-      	"podIP": "1.0.0.1"
+      	"podIP": "1.0.0.1"    // Customized information users can indicate from rule paramter
       }
     },
     {
@@ -138,9 +152,69 @@ Response:
 {
   "success": false,
   "message": "msg",	
-  "passed": ["pod-a", "pod-b"], 
-  "retryByTrace": false
+  "finishedNames": ["pod-a", "pod-b"]
+}
+```
+Response `success` indicating all pods approved or not. If it's `false`, the `finishedNames` field can be used to approve partial pods.
+
+**Protocol with poll**
+
+Request:
+```json
+// URL: https://1.1.1.1:8089/post-stop
+// Method: POST
+
+{ 
+  "traceId": "<trace-id>",    // <trace-id> is generated by Operating, which can be used to track request
+  "stage": "PreTrafficOff",
+  "ruleName": "webhookCheck",
+    "resources": [            // Information of Pods which are in this stage
+  	{
+      "apiVersion": "v1",
+      "kind": "Pod",
+      "name": "pod-a",
+      "parameters": {
+      	"podIP": "1.0.0.1"    // Customized information users can indicate from rule paramter
+      }
+    },
+    {
+      "apiVersion": "v1",
+      "kind": "Pod",
+      "name": "pod-b",
+      "parameters": {
+      	"podIP": "1.0.0.2"
+      }
+    }
+  ]
+}
+```
+
+Response:
+
+```json
+{
+  "success": true,
+  "poll": true,         // required to indicate polling calls is necessary
+  "taskId": <task-id>,  // required to to fetch polling result
+  "message": "msg"
 }
 ```
-Response `success` indicate all pods approved or not. If it's `false`, the `passed` field can be used to allow partial pods.
-if response `retryByTrace=true`, the next retry request will reuse the previous `traceId`.
+Response `success` indicating whether the first request is success or not. If true and field `poll` in response is `true` (or field `async` in response is `true`), PodTransisionRule will then begin to keep calling poll URL to fetch process result.
+Field `taskId` is required for polling. 
+
+The request for polling is GET method and in form of `QueryUrl=URL?task-id=<task-id>`. The parameter key in this URL defaults `task-id`, if using `poll` in above response. It would be `trace-id` if using `async` in above response.
+Users can also indicate the key by field `poll.rawQueryKey`.
+
+The response from polling call is expected like following:
+
+```json
+{
+  "success": true,
+  "message": "msg",
+  "finished": false,
+  "finishedNames": ["pod-a", "pod-b"]
+}
+```
+
+`success` is supposed to be true, if there is no error. If all pods is approved, `finished` should be `true`.
+If `finished` is `false`, `finishedNames` can be used to allow partial pods to be approved.