Suggest mechanism to notice and trigger maintenance of a Service Instance

[williammartin]

Given some disagreement on https://github.com/openservicebrokerapi/servicebroker/pull/628 about the need for arbitrary data to describe the changes in some particular maintenance, I'd like to propose we tackle this problem in two steps.

What are the problem statements?

1. As an application developer, I want to be able to update my own service instances when convenient to me, so that I can schedule downtime.
2. As a platform operator, I want to be able to update out of date service instances, so I can manage offerings reasonably.

What is required to support this?

1. There MUST be some indication that an update is available for a service instance
2. There MUST be some way to trigger an update of a service instance
3. There SHOULD be some indication of the impact of an update

What changes are proposed to the spec?

Since there is already a way to update a service instance via a PATCH:

1. There MUST be some indication that the service broker now provides an updated version of a service
2. There SHOULD be some indication of the impact of an update

I feel like the first point is uncontroversial, and the second is where there is some disagreement about whether an arbitrary data structure is required, or whether a string could suffice. In either case, we should have a structure we can extend to capture this:

maintenance_info: {
  version: "1.2.3+abcedf",
}

This should provide sufficient information for the Platform to determine (and provide this information to an Application Developer/Platform Operator), and trigger (as instructed by an Application Developer/Platform Operator) maintenance.

I can open a separate PR to deal with point 2, but the summary can be found below.

---

Why should there be an indication of what is available in an update?

One of our customers strongly desires the ability to show details of specific changes in a service, for example, changes in middleware. One way we could solve this is to have a details string as an absolute representation about what is contained in this version:

maintenance_info: {
  version: "1.2.3+abcedf",
  details: "stemcell: 224.6, os: 12.4",
}

Which, if the platform compared to a previously stored version might produce an experience like:

$ cf service s1

name:            s1
service:         example-service
tags:
plan:            example-plan
description:     ...

Showing status of last operation from service s1...

status:    create succeeded
message:
started:   2019-01-02T14:10:47Z
updated:   2019-01-02T14:10:47Z

An update is available for this service instance:
  Current: stemcell: 220.1, os: 12.4
  Update:  stemcell: 224.6, os: 12.4

So why might this not be sufficient or unpleasant?

1. Unstructured data in string format is not easily machine consumable
2. It is hard to computationally determine what has changed in an update
3. It could be a confusing field for brokers. Since we cannot guarantee that all versions of a service are moved through incrementally, the details field cannot be written as a description of changes, only as an absolute statement of what is contained in a version.

What could we do instead?

We could add a details object (for arbitrary keys to values) to the maintenance_info:

maintenance_info: {
  version: "abcedf",
  details: {
   "stemcell": "224.6",
   "os": "12.4",
  },
}

The platform could then compare changes between stored details and those in the catalog if a version change has happened:

$ cf service s1

name:            s1
service:         example-service
tags:
plan:            example-plan
description:     ...

Showing status of last operation from service s1...

status:    create succeeded
message:
started:   2019-01-02T14:10:47Z
updated:   2019-01-02T14:10:47Z

An update is available for this service instance:
   stemcell: 224.6

---

If we provide details as a structure, isn't that hash sufficient to determine that an update is available, why provide a version string?

Yes, it is sufficient. A version string may be beneficial or a hinderance to authors, or it may simply allow us to progress.

[Lafunamor]

I think this proposal makes more sense than #628 as it is more generic. But if we only include a version field, why don't we make it at the root of the plan? This information is also helpful outside the maintenance use case. I don't see any additional value of adding the maintenance_info field without also adding the JSON object details.

[williammartin]

Thanks for your thoughts. I think this is captured in:

I feel like the first point is uncontroversial, and the second is where there is some disagreement about whether an arbitrary data structure is required, or whether a string could suffice. In either case, we should have a structure we can extend to capture this.

We believe there will be something there, we just need to figure out what that will look like. Is there some way for me to make this clearer? What other use case are you thinking for the version field other than maintenance?

[Lafunamor]

I think it's helpful to provide the current version of a certain service. This could also be saved to be able to compare it with new versions (as per your description above). If I'm not missing anything there is currently no way to provide that except adding it into the description or as metadata.

[williammartin]

The expectation is that the platform stores the maintenance_info for comparison, so in that way I think it already satisfies your request.

[fmui]

If maintenance can be triggered through the dashboard, the mainenance_info held by the platform can go out of sync. It might make sense to provide the current version of a service instance also through the fetch endpoint.

[williammartin]

Is this a use case we actually want to support? Since maintenance_info is a new concept, I guess we could also include a updates to a service instance that change themaintenance_infoMUST only be triggered via the platform.

I can't say I have enough experience or knowledge of breadth of brokers to understand if this is something service providers want.

With your suggestion, I'm guessing you think that if a user triggers maintenance via a platform, the platform should fetch first to see that maintenance really should happen, and then report back to a user that maintenance wasn't actually required after all?

[mattmcneeney]

Closing this as #642 has been merged