From 1385d2ab6b27c13cd594f0d01735fd9edfa58f8c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Florian=20Mu=CC=88ller?= Date: Mon, 18 Feb 2019 14:13:03 +0100 Subject: [PATCH 1/4] Allow Service Brokers to indicate the state of a Service Instance after a failed update or deprovisioning --- spec.md | 44 ++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 44 insertions(+) diff --git a/spec.md b/spec.md index ebdaed37..80840a49 100644 --- a/spec.md +++ b/spec.md @@ -314,6 +314,9 @@ 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 can 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. | +| retry_delay | integer | This field suggests how long (in seconds) the Platform SHOULD wait until it repeats the operation. If this a negative number, the Platform SHOULD NOT automatically repeat the operation. Defaults to 0 seconds. | ### Error Codes @@ -782,6 +785,9 @@ 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_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 can 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. | +| retry_delay | integer | If an operation failed, this field suggests how long (in seconds) the Platform SHOULD wait until it repeats the operation. If this a negative number, the Platform SHOULD NOT automatically repeat the operation. Defaults to 0 seconds. | \* Fields with an asterisk are REQUIRED. @@ -1194,6 +1200,36 @@ 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. +When an update fails, the Service Instance may be still usable or unusable +or its state may 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 be may or may not 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. + +If an update is repeatable, the Service Broker MAY indicate whether +the update is repeatable immediately, after a certain period of time, +or after some manual intervention. If the Service Broker does not provide +this information, the Platform SHOULD assume that the update can be +repeated immediately. +Whether the Platform automatically repeats the update or not, is Platform +specific. + #### Body For success responses, the following fields are defined: @@ -1675,6 +1711,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 may be still usable or +unusable or its state may be unknown. If a Service Instance became unusable, +the Platform SHOULD NOT allow the creation of new bindings. +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: From 59341ec0751c16c4d370f49325b0b994ffa97b3d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Florian=20Mu=CC=88ller?= Date: Tue, 5 Mar 2019 12:54:11 +0100 Subject: [PATCH 2/4] fixed keywords --- spec.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/spec.md b/spec.md index dcdce5f9..767c216a 100644 --- a/spec.md +++ b/spec.md @@ -329,7 +329,7 @@ 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 can 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. | +| 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. | | retry_delay | integer | This field suggests how long (in seconds) the Platform SHOULD wait until it repeats the operation. If this a negative number, the Platform SHOULD NOT automatically repeat the operation. Defaults to 0 seconds. | ### Error Codes @@ -777,7 +777,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_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 can 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. | +| 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. | | retry_delay | integer | If an operation failed, this field suggests how long (in seconds) the Platform SHOULD wait until it repeats the operation. If this a negative number, the Platform SHOULD NOT automatically repeat the operation. Defaults to 0 seconds. | | description | string | A user-facing message that can be used to tell the user details about the status of the operation. | @@ -1188,8 +1188,8 @@ 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. -When an update fails, the Service Instance may be still usable or unusable -or its state may be unknown to the Platform. If a Service Instance became +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 @@ -1200,14 +1200,14 @@ If the broker does not indicate in the whether the Service Instance is usable or not, the Platform SHOULD assume it is still usable. -A failed update be may or may not be repeatable. If the Service Broker +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. +Platform SHOULD NOT retry this. Other updates MAY be possible. If an update is repeatable, the Service Broker MAY indicate whether @@ -1674,8 +1674,8 @@ $ 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 may be still usable or -unusable or its state may be unknown. If a Service Instance became unusable, +When a deprovisioning fails, the Service Instance can still be usable or +unusable or its state could be unknown. If a Service Instance became unusable, the Platform SHOULD NOT allow the creation of new bindings. If the broker does not indicate in the [Error response](#service-broker-errors) or [Last Operation response](#polling-last-operation-for-service-instances) From 2bb9becf4c0d1c7b448fccb488b93543acc6d59a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Florian=20Mu=CC=88ller?= Date: Tue, 12 Mar 2019 09:42:45 +0100 Subject: [PATCH 3/4] Changed 'retry_delay' to 'retry_after' --- spec.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/spec.md b/spec.md index 767c216a..84d60059 100644 --- a/spec.md +++ b/spec.md @@ -330,7 +330,7 @@ For error responses, the following fields are defined: | 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. | -| retry_delay | integer | This field suggests how long (in seconds) the Platform SHOULD wait until it repeats the operation. If this a negative number, the Platform SHOULD NOT automatically repeat the operation. Defaults to 0 seconds. | +| retry_after | integer | This field suggests how long (in seconds) the Platform SHOULD wait until it repeats the operation. If this a negative number, the Platform SHOULD NOT automatically repeat the operation. Defaults to 0 seconds. | ### Error Codes @@ -778,7 +778,7 @@ For success responses, the following fields are defined: | 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. | -| retry_delay | integer | If an operation failed, this field suggests how long (in seconds) the Platform SHOULD wait until it repeats the operation. If this a negative number, the Platform SHOULD NOT automatically repeat the operation. Defaults to 0 seconds. | +| retry_after | integer | If an operation failed, this field suggests how long (in seconds) the Platform SHOULD wait until it repeats the operation. If this a negative number, the Platform SHOULD NOT automatically repeat the operation. Defaults to 0 seconds. | | description | string | A user-facing message that can be used to tell the user details about the status of the operation. | \* Fields with an asterisk are REQUIRED. From 1a3c917b7be8df3037b246119ce20d7a78475e44 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Florian=20Mu=CC=88ller?= Date: Tue, 12 Mar 2019 09:49:30 +0100 Subject: [PATCH 4/4] Removed duplicate description field. --- spec.md | 1 - 1 file changed, 1 deletion(-) diff --git a/spec.md b/spec.md index 84d60059..a8892bff 100644 --- a/spec.md +++ b/spec.md @@ -779,7 +779,6 @@ For success responses, the following fields are defined: | 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. | | retry_after | integer | If an operation failed, this field suggests how long (in seconds) the Platform SHOULD wait until it repeats the operation. If this a negative number, the Platform SHOULD NOT automatically repeat the operation. Defaults to 0 seconds. | -| description | string | A user-facing message that can be used to tell the user details about the status of the operation. | \* Fields with an asterisk are REQUIRED.