Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Allow Service Brokers to indicate the state of a Service Instance after a failed update or deprovisioning #637

Open
wants to merge 6 commits into
base: master
Choose a base branch
from
Open

Allow Service Brokers to indicate the state of a Service Instance after a failed update or deprovisioning #637

Changes from 4 commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
c6d21bf
Merge pull request #1 from openservicebrokerapi/master
fmui Aug 6, 2018
1385d2a
Allow Service Brokers to indicate the state of a Service Instance aft…
fmui Feb 18, 2019
edd1ab9
Merge branch 'master' into instance-state2
fmui Feb 18, 2019
59341ec
fixed keywords
fmui Mar 5, 2019
2bb9bec
Changed 'retry_delay' to 'retry_after'
fmui Mar 12, 2019
1a3c917
Removed duplicate description field.
fmui Mar 12, 2019
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
49 changes: 48 additions & 1 deletion spec.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -328,6 +328,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 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. |
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We already have a retry after concept in the last operation endpoint. Do you think it makes sense to use the same name for this as well, or do you think it needs to be distinct?


### Error Codes

Expand Down Expand Up @@ -772,15 +775,21 @@ 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. If present, MUST be a non-empty string. |
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The description field appears twice in this section. Conflict resolution artifact?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks. Fixed.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Great! Thank you!

| 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. |
| description | string | A user-facing message that can be used to tell the user details about the status of the operation. |
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Duplicate field here.


\* Fields with an asterisk are REQUIRED.

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
intended to prevent unnecessary, and premature, calls to the `last_operation`
endpoint. It is RECOMMENDED that the header include a duration rather than a
timestamp.

\* Fields with an asterisk are REQUIRED.


```
{
Expand Down Expand Up @@ -1179,6 +1188,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 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.

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:
Expand Down Expand Up @@ -1635,6 +1674,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 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:
Expand Down