From 0ce0e677ed65d92ec580bb324f05a3e243e9c852 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Florian=20Mu=CC=88ller?= Date: Tue, 7 Aug 2018 11:15:09 +0200 Subject: [PATCH 1/5] Added clarification of the state of an instance after a failed update or deletion operation --- spec.md | 16 +++++++++++++--- 1 file changed, 13 insertions(+), 3 deletions(-) diff --git a/spec.md b/spec.md index ebdaed37..65a70d20 100644 --- a/spec.md +++ b/spec.md @@ -782,6 +782,7 @@ For success responses, the following fields are defined: | --- | --- | --- | | 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. If present, MUST be a non-empty string. | +| instance_corrupt | boolean | For failed update and deprovisioning operations, this field indicates whether the instance is still usable or not. If the value is `true`, the Service Instance MUST be considered corrupt and the Platform SHOULD NOT allow the creation of new bindings. If the value is `false`, the Service Instance is in an unmodified and usable state. The default is true. | \* Fields with an asterisk are REQUIRED. @@ -1190,9 +1191,13 @@ $ curl http://username:password@service-broker-url/v2/service_instances/:instanc | 400 Bad Request | MUST be returned if the request is malformed or missing mandatory data. | | 422 Unprocessable entity | MUST be returned if the requested change is not supported or if the request cannot currently be fulfilled due to the state of the Service Instance (e.g. Service Instance utilization is over the quota of the requested plan). Additionally, a `422 Unprocessable Entity` MUST be returned if the Service Broker only supports asynchronous update for the requested plan and the request did not include `?accepts_incomplete=true`; in this case the response body MUST contain a error code `"AsyncRequired"` (see [Service Broker Errors](#service-broker-errors)). The error response MAY include a helpful error message in the `description` field such as `"This Service Plan requires client support for asynchronous service operations."`. | -Responses with any other status code MUST be interpreted as a failure. When the response includes a 4xx status code, the Service Broker MUST NOT -apply any of the requested changes to the Service Instance. +apply any of the requested changes to the Service Instance and the +Service Instance MUST be in an unmodified and usable state. + +Responses with any other status code MUST be interpreted as a failure. +The Service Instance MUST be considered corrupt and the Platform SHOULD NOT +allow the creation of new bindings. #### Body @@ -1672,8 +1677,13 @@ $ curl 'http://username:password@service-broker-url/v2/service_instances/:instan | 410 Gone | MUST be returned if the Service Instance does not exist. | | 422 Unprocessable Entity | MUST be returned if the Service Broker only supports asynchronous deprovisioning for the requested plan and the request did not include `?accepts_incomplete=true`. The response body MUST contain error code `"AsyncRequired"` (see [Service Broker Errors](#service-broker-errors)). The error response MAY include a helpful error message in the `description` field such as `"This Service Plan requires client support for asynchronous service operations."`. | +When the response includes a 4xx status code other than 410 Gone, the +Service Instance MUST be in an unmodified and usable state. + Responses with any other status code MUST be interpreted as a failure and the -Platform MUST remember the Service Instance. +Platform MUST remember the Service Instance. The Service Instance MUST be +considered corrupt and the Platform SHOULD NOT allow the creation of +new bindings. #### Body From 0c1308a56cc8469886d2339891220a2e18857277 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Florian=20Mu=CC=88ller?= Date: Fri, 17 Aug 2018 13:24:27 +0200 Subject: [PATCH 2/5] Clarified default of the instance_corrupt field. --- spec.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/spec.md b/spec.md index 65a70d20..79f22e46 100644 --- a/spec.md +++ b/spec.md @@ -782,7 +782,7 @@ For success responses, the following fields are defined: | --- | --- | --- | | 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. If present, MUST be a non-empty string. | -| instance_corrupt | boolean | For failed update and deprovisioning operations, this field indicates whether the instance is still usable or not. If the value is `true`, the Service Instance MUST be considered corrupt and the Platform SHOULD NOT allow the creation of new bindings. If the value is `false`, the Service Instance is in an unmodified and usable state. The default is true. | +| instance_corrupt | boolean | For failed update and deprovisioning operations, this field indicates whether the instance is still usable or not. If the value is `true`, the Service Instance MUST be considered corrupt and the Platform SHOULD NOT allow the creation of new bindings. If the value is `false`, the Service Instance is in an unmodified and usable state. If not specified, the state of the resource is unspecified by this specification. | \* Fields with an asterisk are REQUIRED. From a8bc00f6bd4d5d5384d9edcb3f3e6e8ee22a68bc Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Florian=20Mu=CC=88ller?= Date: Fri, 31 Aug 2018 14:16:38 +0200 Subject: [PATCH 3/5] Added section about corrupt instances --- spec.md | 13 +++++++++++++ 1 file changed, 13 insertions(+) diff --git a/spec.md b/spec.md index 79f22e46..ac5d43c5 100644 --- a/spec.md +++ b/spec.md @@ -29,6 +29,7 @@ - [Fetching a Service Binding](#fetching-a-service-binding) - [Unbinding](#unbinding) - [Deprovisioning](#deprovisioning) + - [Corrupt Service Instances](#corrupt-service-instances) - [Orphans](#orphans) ## API Overview @@ -1699,6 +1700,18 @@ For success responses, the following fields are defined: } ``` +## Corrupt Service Instances + +When an update or delete operation fails, the Service Instance MAY be corrupt. +A corrupt instance MAY be misconfigured, in an invalid state, not reachable, or +not working at all. +Platforms SHOULD not try to create bindings for this instance anymore. +Whether or not a corrupt instance can be repaired by, for example, updating it +again, is undefined. +Deprovisioning a corrupt instance SHOULD still be possible. A Platform MUST +remember the Service Instance until it is successfully deprovisioned or it has +been cleaned up as an orphan. + ## Orphans The Platform is the source of truth for Service Instances and Service Bindings. From 550c6e51233387c6738a73b48dcfaab621ed7a59 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Florian=20Mu=CC=88ller?= Date: Tue, 18 Sep 2018 10:32:35 +0200 Subject: [PATCH 4/5] Fixed CI failure --- spec.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/spec.md b/spec.md index ac5d43c5..e8b9bbce 100644 --- a/spec.md +++ b/spec.md @@ -1705,7 +1705,7 @@ For success responses, the following fields are defined: When an update or delete operation fails, the Service Instance MAY be corrupt. A corrupt instance MAY be misconfigured, in an invalid state, not reachable, or not working at all. -Platforms SHOULD not try to create bindings for this instance anymore. +Platforms SHOULD NOT try to create bindings for this instance anymore. Whether or not a corrupt instance can be repaired by, for example, updating it again, is undefined. Deprovisioning a corrupt instance SHOULD still be possible. A Platform MUST From 549b8559387d0e345795deff402a065fc2454351 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Florian=20Mu=CC=88ller?= Date: Fri, 5 Oct 2018 17:28:14 +0200 Subject: [PATCH 5/5] Replaced instance_corrupt with status_code --- spec.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/spec.md b/spec.md index e8b9bbce..efc64a58 100644 --- a/spec.md +++ b/spec.md @@ -783,7 +783,8 @@ For success responses, the following fields are defined: | --- | --- | --- | | 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. If present, MUST be a non-empty string. | -| instance_corrupt | boolean | For failed update and deprovisioning operations, this field indicates whether the instance is still usable or not. If the value is `true`, the Service Instance MUST be considered corrupt and the Platform SHOULD NOT allow the creation of new bindings. If the value is `false`, the Service Instance is in an unmodified and usable state. If not specified, the state of the resource is unspecified by this specification. | +| status_code | number | The HTTP status code that would have been returned if the operation would have been executed synchronously. If the state is `failed` this field SHOULD be present and the value MUST be an integer in the range of 400 to 599. This field MUST NOT be present for any other state. | +| error | string | An error code as described in the [Service Broker Errors](#service-broker-errors) section. If present, MUST be a non-empty string. If the state is `failed` and there is an error code this field SHOULD be present. This field MUST NOT be present for any other state. | \* Fields with an asterisk are REQUIRED.