Merge pull request #661 from fmui/instance-state3

Indicate if a Service Instance is still usable after a failed update or deprovisioning and if an update can be repeated

Author: fmui

openapi.yaml

@@ -779,6 +779,10 @@ components:
             - failed
         description:
           type: string
+        instance_usable:
+          type: boolean
+        update_repeatable:
+          type: boolean
 
     ServiceBindingResource:
       type: object
@@ -930,6 +934,10 @@ components:
           type: string
         description:
           type: string
+        instance_usable:
+          type: boolean
+        update_repeatable:
+          type: boolean 
 
   securitySchemes:
     basicAuth:

spec.md

@@ -329,6 +329,8 @@ For error responses, the following fields are defined:
 | --- | --- | --- |
 | error | string | A single word in camel case that uniquely identifies the error condition. If present, MUST be a non-empty string. |
 | description | string | A user-facing error message explaining why the request failed. If present, MUST be a non-empty string. |
+| instance_usable | boolean | If an update or deprovisioning operation failed, this flag indicates whether or not the Service Instance is still usable. If `true`, the Service Instance can still be used, `false` otherwise. This field MUST NOT be present for errors of other operations. Defaults to `true`. |
+| update_repeatable | boolean | If an update operation failed, this flag indicates whether this update can be repeated or not. If `true`, the same update operation MAY be repeated and MAY succeed; if `false`, repeating the same update operation will fail again. This field MUST NOT be present for errors of other operations. Defaults to `true`. |
 
 ### Error Codes
 
@@ -788,7 +790,9 @@ For success responses, the following fields are defined:
 | Response Field | Type | Description |
 | --- | --- | --- |
 | state* | string | Valid values are `in progress`, `succeeded`, and `failed`. While `"state": "in progress"`, the Platform SHOULD continue polling. A response with `"state": "succeeded"` or `"state": "failed"` MUST cause the Platform to cease polling. |
-| description | string | A user-facing message that can be used to tell the user details about the status of the operation. |
+| description | string | A user-facing message that can be used to tell the user details about the status of the operation. If present, MUST be a non-empty string. |
+| instance_usable | boolean | If an update or deprovisioning operation failed, this flag indicates whether or not the Service Instance is still usable. If `true`, the Service Instance can still be used, `false` otherwise. This field MUST NOT be present for errors of other operations. Defaults to `true`. |
+| update_repeatable | boolean | If an update operation failed, this flag indicates whether this update can be repeated or not. If `true`, the same update operation MAY be repeated and MAY succeed; if `false`, repeating the same update operation will fail again. This field MUST NOT be present for errors of other operations. Defaults to `true`. |
 
 The response MAY also include the `Retry-After` HTTP header. This header will
 indicate how long the Platform SHOULD wait before polling again and is
@@ -1232,6 +1236,28 @@ Responses with any other status code MUST be interpreted as a failure.
 When the response includes a 4xx or 5xx status code, the Service Broker MUST
 NOT apply any of the requested changes to the Service Instance.
 
+When an update fails, the Service Instance can still be usable or unusable
+or its state could be unknown to the Platform. If a Service Instance became
+unusable, another update MAY repair the Service Instance.
+The Platform SHOULD NOT allow the creation of new bindings of an unusable
+Service Instance until the instance has been deleted or repaired by a
+subsequent update.
+If the broker does not indicate in the
+[Error response](#service-broker-errors) or
+[Last Operation response](#polling-last-operation-for-service-instances)
+whether the Service Instance is usable or not, the Platform SHOULD assume
+it is still usable.
+
+A failed update might be repeatable. If the Service Broker
+indicates in the [Error response](#service-broker-errors) or
+[Last Operation response](#polling-last-operation-for-service-instances)
+that retrying this update does not make sense, the Platform SHOULD NOT
+repeat this update.
+For example, if a certain plan change is not supported by the
+Service Broker, all subsequent attempts will always fail, and the
+Platform SHOULD NOT retry this.
+Other updates MAY be possible.
+
 #### Body
 
 For success responses, the following fields are defined:
@@ -1743,6 +1769,14 @@ $ curl 'http://username:password@service-broker-url/v2/service_instances/:instan
 Responses with any other status code MUST be interpreted as a failure and the
 Platform MUST remember the Service Instance.
 
+When a deprovisioning fails, the Service Instance can still be usable or
+unusable or its state could be unknown. If a Service Instance becomes unusable,
+the Platform SHOULD NOT request new Service Bindings for that Service Instance.
+If the broker does not indicate in the [Error response](#service-broker-errors)
+or [Last Operation response](#polling-last-operation-for-service-instances)
+whether the Service Instance is usable or not, the Platform SHOULD assume it is
+still usable.
+
 #### Body
 
 For success responses, the following fields are defined:

swagger.yaml

@@ -686,6 +686,10 @@ definitions:
           - failed
       description:
         type: string
+      instance_usable:
+        type: boolean
+      update_repeatable:
+        type: boolean 
   ServiceBindingResource:
     type: object
     properties:
@@ -801,7 +805,10 @@ definitions:
         type: string
       description:
         type: string
-
+      instance_usable:
+        type: boolean
+      update_repeatable:
+        type: boolean
 securityDefinitions:
   basicAuth:
     type: basic