Generic Extensions (Actions) Proposal

[avade]

Following the discussion in #107 this issue aims to create a proposal for "Service Broker Actions".

---

Problem

As a service broker author, I want to be able to optionally offer operations beyond "provision, update, bind, unbind, delete" so that I can provide new features to users of my service via the service broker API

Examples

• Backup and restore functionality (previous discussion Add support for backup & restore to the service broker api #107)
• Schedule things via the service broker

Workflows

Service clients can:

• Discover the actions available from a service broker
• Trigger a specific action synchronously
• Trigger a specific action asynchronously
• Pass input parameters to the action
• Discover and validate input parameters (input parameter schema)

Service authors can:

• Optionally define actions at service broker registration time

History

#107
https://docs.google.com/document/d/1Y5vwWjvaUIwHI76XU63cAS8xEOJvN69-cNoCQRqLPqU/edit#heading=h.kzfeyua6md59

Next steps

1. Proposal document
2. Review on OSBAPI WG call

[gberche-orange]

Here is a google docs placeholder. I'll try fleshing some ideas there in the coming days. Anyone feel free to start earlier if they have some bandwidth.

@avade do you have pointers to the WG calendar and dialin/minutes details ?

[avade]

@gberche-orange Perfect thanks! - @shalako can add you to the invite.

[shalako]

Sent. Guillaume, consider that dial-in info will change for next week's call. I'll be sending an update to the invite shortly.

[gberche-orange]

thanks @shalako

I've proposed a first draft into https://docs.google.com/document/d/1Dhs4RrvXxyDcmK8LdxbkHcEb_HrpiA4XqVwaIy2sTXg/edit

I've moved the sharing mode to comment so that we can systematically get notifications from suggestions. Let me know the list of people to share with edit role as to accept/reject suggestions collaboratively.

[gberche-orange]

@avade @paulcwarren any feedback on the proposal prior to the WG call today ?

[avade]

I will be taking a look this morning.

…

On 13 Dec 2016 8:08 a.m., "Guillaume Berche" ***@***.***> wrote: @avade <https://github.com/avade> any feedback on the proposal prior to the WG call today ? — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#114 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AAeB1yCPnl5BHANSc5_b10wihkeTSqn6ks5rHlJ1gaJpZM4LGvV5> .

[bmelville]

Is there any update on this proposal? It's something we're interested in seeing as well, so would love to see it gain traction.

B.

[avade]

Right now I am focusing on the schema / removing CFisms. I should get a chance to get stuck into this later next week, but I this feature seems to unlock lots of interesting broker uses cases for Pivotal.

…

On Tue, Jan 10, 2017 at 6:30 PM, Brendan Melville ***@***.***> wrote: Is there any update on this proposal? It's something we're interested in seeing as well, so would love to see it gain traction. B. — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#114 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AAeB14J9D1R97ZNgJd-EYWt7Fk1kPhwHks5rQ85JgaJpZM4LGvV5> .

[jmcarp]

I just filed #148 to ask about this more generally, but I was wondering whether this proposal might allow broker-defined actions to be executed on pending service instances.

[gberche-orange]

@jmcarp the proposal doc mentions currency control for broker actions with different approaches. Broker actions are certainly a subresource of a service instance, but we had not yet detailed how/whether consistency would be required between the two.

For instance, if a backup action is on going, can the parent service instance be updated or deleted, or similarly to service bindings should all broker actions complete before the parent service instance can be deleted.

Having more details on your use cases for broker actions would help refine the proposal, including during long-lasting service instance create/update operations.

[metayd]

LGTM
Any Update?
Thanks

[duglin]

general direction looks good. Couple of things

• I'd like to discuss this at the f2f in a few weeks
• in prep for that, could we get a version of the spec with the proposed edits?
• we'll probably want to include the ability to describe the parameters to the actions via schema
• we may want to consider defining an "Actions Profile" to define some common action names so that we don't get "backup" vs "back-up" - if that's a problem, not 100% sure yet.

[petereberlein]

The proposal document actually contains two options: actions as parameters in a PATCH request and actions modelled as resources. I would strongly prefer the latter one as it is more transparent and also better extensible for long running actions (delete them, get a status update, etc.)

[avade]

I would like to revisit the conversation about supporting B&R as a first class API concept. It is still Pivotals main use case for actions.

We can still progress with actions as a concept, but I would prioritise solving the B&R case first.

[petereberlein]

Addressing a concrete use case (like B&R) will help detailing the concept, but it should be generic enough to add further actions later on without the need of extending/changing this concept.

So maybe we can just use B&R as a concrete example for actions in general?

[avade]

The approach I was thinking was to put both solutions (actions and making B&R first class in the API) then we can compare and contrast.

[duglin]

We'd prefer to not overload the current APIs so the 2nd approach (dedicated resources) feels cleaner. One other bit of feedback I got was that the actions should not be linked to the plans - we'd prefer if there wasn't a tight coupling between plans and actions. Also, since the list of available actions may vary based on the state of the instance it would be nicer to support GET /v2/service_instances/:instance_id/actions instead.

Are people comfortable with making a statement about the type of actions that should be included here? Meaning, they should be limited to admin type of actions that act upon the service instance. I don't think we want people to take actions that should be invoked by the end-user via the connection info in the binding and move them to be actions performed by the platform on their behalf. I view this as the diff between action "on" the service vs actions "with" service service.

[mattmcneeney]

In the CF world, many of these actions are likely to be long-running, so we would like to support asynchronous calls, with the ability to fetch the current status of any actions and cancelling a pending action. I'd also like to see a branch (or multiple) with the proposed changes so we can discuss the proposed implementation.

[gberche-orange]

I started detailing how a backup use-case could like with the 2nd approach. I called them "snapshots" to reflect that they are triggered by application developers at the given point in time (as to avoid confusion with service operators scheduled backups intended for data loss/durability)

In terms of UX, the end users would see the following list of actions for a given data service instance (say a RDBMS service) inferred from the broker catalog response, along with associated input parameters and response format (ommited here)

• create-snapshot
• restore-snapshot
• list-snapshots
• delete-snaphot

A possible REST calls flow would then be:

Requesting a snapshot (async)
curl -X PUT /v2/service_instances/:instance_id/actions_instances/1 -d "actions=create-snapshot&parameters={name=snapshot_A}"
202 ACCEPTED

Checking snapshot completion: in progress
curl -X GET /v2/service_instances/:instance_id/actions_instances/1
200 OK
state="in progress"
description="creating snapshot  10%"

Checking snaphot completion: completed
curl -X GET /v2/service_instances/:instance_id/actions_instances/1
200 OK
state="suceeded"
description="snapshot  id 1 created successfully."
resource={name=snapshot_A, size=100MB, download-url=...}

Requesting a new snapshot:

curl -X PUT /v2/service_instances/:instance_id/actions_instances/2 -d "actions=create-snapshot&parameters={name=snapshot_B}"
202 ACCEPTED

Checking snaphot completion: in progress (stalled)
curl -X GET /v2/service_instances/:instance_id/actions_instances/2
200 OK
state="in progress"
description="creating snapshot  10%"

Cancelling a pending snaphot operation:
curl -X DELETE /v2/service_instances/:instance_id/actions_instances/2
200 OK

Requesting lists of snapshots (synchronous)

curl -X PUT /v2/service_instances/:instance_id/actions_instances/3 -d "action=list-snapshots"
201 CREATED

curl -X GET /v2/service_instances/:instance_id/actions_instances/3
state="suceeded"
description="list of snapshots successfully completed."
resource=[{name=snapshot_A, size=100MB, download-url=...} , ]

Restore a given snapshot in time:

curl -X PUT /v2/service_instances/:instance_id/actions_instances/4 -d "action=restore-snapshot&parameters={name=snapshot_A}"
202 ACCEPTED

Checking restore completion: in progress
curl -X GET /v2/service_instances/:instance_id/actions_instances/4
200 OK
state="in progress"
description="restoring snapshot  10%"

Checking restore completion: completed
curl -X GET /v2/service_instances/:instance_id/actions_instances/4
200 OK
state="suceeded"
description="snapshot  id 1 created successfully."
resource={size=100MB,download-url=...}

Delete a given snapshot
curl -X PUT /v2/service_instances/:instance_id/actions_instances/4 -d "action=delete-snapshot&parameters={name=snapshot_A}"
200 OK

I started a draft branch detailing the schema part enabling discovery of the actions: https://github.com/avade/servicebroker/compare/method-attached-schemas...orange-cloudfoundry:issue114-from-165?expand=1 including the input parameters and the response This is based on avade:method-attached-schemas in #165. I did not start the work on detailing the REST endpoints in the specs.

Pending issues:

• how long should completed action resources available for query ? should the spec describe this ? Brokers could need to implement a kind of garbage collection on completed actions.
• is there a need/use-cases for update/delete of an action resource ?

[petereberlein]

The semantics of deleting an action resource would be something like a cancel - this is already useful for the backup/restore use case.
Updating is less obvious as a typical implementation would not allow updating action parameters during action execution. But who knows what people will use actions for in the future? So we might not specify update for now but reserve it for when a good use case comes up.

[mattmcneeney]

There is an ongoing conversation in the OSBAPI Slack about the state that brokers do/should keep (this has implications on the async bindings and fetching input parameters features). There is support for stateless brokers; it keeps them simple and easy to implement. If brokers were required to keep the results of many actions, perform garbage collection, etc, then this could make them much more complex to develop.

However, with async create, update and delete (optional), brokers do already have to maintain some state (remembering the last operation result).

Regarding @gberche-orange's proposal (thanks Guillaume!);

• I like the extensibility of actions and the ability to define schemas
• Is there some inconsistency with existing endpoints if the platform is specifying the action_instances ID? With the existing async calls, the broker returns an operation string to the platform which is used to check the status of the operation via the last_operation endpoint.
• To me it makes sense for PUT to create a new action, GET to fetch the status and DELETE to cancel it. I'm not sure we should handle other HTTP verbs for now until we have a strong use case.

Before we dive too deep into the implementation, please could everyone share their current use cases for actions? For CF, the key ones we want to solve asap are backup and restore. What other actions are people finding a need for brokers to support?

[gberche-orange]

Before we dive too deep into the implementation, please could everyone share their current use cases for actions?

The proposal document "problem" section details some use-cases such as:

• stop/start a service instance as to reduce resource consumption without losing data hold by the service. For data services, a stop may trigger an archival of the data to cold storage (such as AWS glacier) and a release of hot/warm computing resources associated to the service instance (storage, RAM, …), a start may fetch data from cold storage and provision computing resources.
• configure the service, such as enable/disable verbose logging.

I refined the problem section with additional details, benefits of actions and non-goals section. Feel free to make suggestions to the google doc or ask for edit permissions.

I would like to revisit the conversation about supporting B&R as a first class API concept. It is still Pivotals main use case for actions.
We can still progress with actions as a concept, but I would prioritise solving the B&R case first.

It would be useful to alternative see 1st class support for snapshot/restore in OSB to compare both approaches.

Potential pros for 1st class support for snapshot/restore in OSB w.r.t. broker actions:

• could allow for more friendly user experience (e.g. display a list of available snapshots available to restore from and prompt user to select one) than what simple generic broker actions are likely to enable while keeping complexity in OSB API low.

Potential cons for 1st class support for snapshot/restore in OSB w.r.t. broker actions:

• common B&R denominator among data services is too small, and that a normative B&R be too simplistic to be effective for some services. Would need extensibility to be built-in.

[nilebox]

Any updates on this issue?

I'd like to discuss this at the f2f in a few weeks

I see the following action in the F2F notes: Define a generic “actions” mechanism - Alex L, Doug
@avade @duglin do you have any updates or further details on this?

Before we dive too deep into the implementation, please could everyone share their current use cases for actions?

Our use cases are very similar to the ones already listed: we need a support of extensible set of Operations actions supported by service brokers (backup/restore or anything else service broker specific). So generic mechanism of defining actions would be useful for us.

[vaikas]

As discussed on the weekly call, here's a draft proposal for making actions be more generic.
https://docs.google.com/document/d/1fVBzqi6OK-lyfjDKADSk35hZD4YUqM2AMtoLOgrDDCE/edit

[rhodie27]

Based on the F2F feedback I put together a list of action use cases and how they would be implemented using @vaikas-google's proposal. That can be found @ https://docs.google.com/document/d/1o-JuW0kVH6TIk8i-1nXas6767xyfuUti4p7St-BC-aM/edit?usp=sharing

I think the next steps are:

1. Bring everyone interested up to speed on the use cases, (hopefully including UI people)
2. Agree on terminology, (adheres_to, discovery_url, management_api)
3. Determine if adheres_to is necessary in the first iteration of this.
4. Look at bulk operations, (maybe move mgmt_api to plan).
5. Can this be used for service actions? (Let's talk about Generic Broker Actions #376)
6. Compile a full list of potential actions, (if desired)
7. Start working on the spec language.

What I would like to do is host meetings outside of the weekly call, (with anyone interested), to start driving this to completion. Let's discuss who & the frequency on today's call.

[rhodie27]

Notes from the sync up on actions on 12/14/17:

1. Bring everyone interested up to speed on the use cases, (hopefully including UI people)

• @nilebox is going to add his use case of a generic api for many actions into the use case format.
  • He thinks it'll fit fine and is happy with the general direction.
• Jessica gave some insight into the UI flow. She will get more time after the holidays to review.
• We all agreed we need more UI folks to verify the flow.

2. Agree on terminology, (adheres_to, discovery_url, management_api)

• Current consensus:
  • extention_api instead of management_api
  • discovery_url stays as is
  • adheres_to stays as is
  • @vaikas-google ESL is solid

3. Determine if adheres_to is necessary in the first iteration of this.

• We agreed that adheres_to should be necessary in the first iteration of actions.
• Agreed that adheres_to should also be mandatory; if you don't follow a spec you can use a junk URI.
• Do not want to leave it out and then add it in later.

4. Look at bulk operations, (maybe move mgmt_api to plan).

• Started the conversation, but we went back to the UI flow and if it worked in general.

Other Stuff

• @duglin started an outline of the intended schema:

  • https://docs.google.com/document/d/1o-JuW0kVH6TIk8i-1nXas6767xyfuUti4p7St-BC-aM/edit?ts=5a319720#heading=h.1ql3y8ouad77

• @rhodie27 to schedule another call for next week, (at a proper time for the London folks).

[ash2k]

👍
And thanks for the notes!

[vaikas]

For #3, middle point: - Agreed that *adheres_to* should also be mandatory; if you don't follow a spec you can use a junk URI. You could also probably just point it to discovery_url :)

…

On Thu, Dec 14, 2017 at 2:39 PM, Michael Rhodes ***@***.***> wrote: Notes from the sync up on actions on 12/14/17: *1. Bring everyone interested up to speed on the use cases, (hopefully including UI people)* - @nilebox <https://github.com/nilebox> is going to add his use case of a generic api for many actions into the use case format. - He thinks it'll fit fine and is happy with the general direction. - Jessica gave some insight into the UI flow. She will get more time after the holidays to review. - We all agreed we need more UI folks to verify the flow. *2. Agree on terminology, (adheres_to, discovery_url, management_api)* - Current consensus: - *extention_api* instead of management_api - *discovery_url* stays as is - *adheres_to* stays as is - @vaikas-google <https://github.com/vaikas-google> ESL is solid *3. Determine if adheres_to is necessary in the first iteration of this.* - We agreed that *adheres_to* should be necessary in the first iteration of actions. - Agreed that *adheres_to* should also be mandatory; if you don't follow a spec you can use a junk URI. - Do not want to leave it out and then add it in later. *4. Look at bulk operations, (maybe move mgmt_api to plan).* - Started the conversation, but we went back to the UI flow and if it worked in general. **Other Stuff - @duglin <https://github.com/duglin> started an outline of the intended schema: - https://docs.google.com/document/d/1o-JuW0kVH6TIk8i- 1nXas6767xyfuUti4p7St-BC-aM/edit?ts=5a319720#heading=h.1ql3y8ouad77 <https://docs.google.com/document/d/1o-JuW0kVH6TIk8i-1nXas6767xyfuUti4p7St-BC-aM/edit?ts=5a319720#heading=h.1ql3y8ouad77> - @rhodie27 <https://github.com/rhodie27> to schedule another call for next week, (at a proper time for the London folks). — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#114 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AKwedNDMJkstTQqFsab1tmNU6VbRnxGxks5tAaOzgaJpZM4LGvV5> .

[nilebox]

Just published an example of our use case with OpenAPI spec for generic operations with semi-strict contract and async execution support: https://docs.google.com/document/d/1o-JuW0kVH6TIk8i-1nXas6767xyfuUti4p7St-BC-aM/edit?ts=5a31a014#heading=h.kss2koahby2k

Seems to work for us 👍

[fmui]

Could we allow the discovery_url also to be relative to the broker URL? It should be easy for the cloud controller to compile the URL, but it may be difficult/cumbersome for the broker (for example if it resides behind a reverse proxy).

[duglin]

If we make it a URI-reference per the URI spec then I think that should cover it.

[fmui]

Can we then rename discovery_url to discovery_uri?

[n3wscott]

Do you want URI because you want to allow data: encoded document or other such thing? It looks like swagger / Open API only allow for URL: https://swagger.io/docs/specification/api-host-and-base-path/

…

On Mon, Dec 18, 2017 at 6:25 AM Florian Müller ***@***.***> wrote: Can we then rename discovery_url to discovery_uri? — You are receiving this because you are subscribed to this thread. Reply to this email directly, view it on GitHub <#114 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/Aezx8H8gwUyVFlpZdchFG_4qbPI98V-5ks5tBnXJgaJpZM4LGvV5> .

[fmui]

Do you want URI because you want to allow data: encoded document or other
such thing? It looks like swagger / Open API only allow for URL:
https://swagger.io/docs/specification/api-host-and-base-path/

The strange thing is that Open API talks about URLs but refers to the URI spec (RFC 3986).
Open API allows relative paths, which are not covered in the URL spec.

[duglin]

yup I noticed the same thing for some other work recently, so I'd opt for URI too

[rhodie27]

Notes from the 1/8 sync up on Actions, (apologies for the delay):

1. Continued the debate on adheres_to:

• should it be mandatory and point to discovery_url or just be optional.
• will people use it to push standardized extentions to the api.
• should we just leave it out of the first release of actions.

2. We should probably start calling this feature extensions instead of actions

• this mechanism is a way to build in actions, but also will support general extensions to api.

3. UI developer feedback

• Jessica from Pivotal really wants a list of the action names prior to getting the swagger doc.
• Building a pregenerated UI from adheres_to is not something she is interested in.

4. General feedback

• We should just move this to validating by implementation; we won't know the major issues until we get some feedback

5. Did not get to the bulk operation conversation.

6. Need to have a conversation on where the actions should be returned

• plan vs service instance
• E.g. do we really want to say that actions can differ from service instance to service instance?

7. Decided we would do one more call to discuss bulk operations and plan vs service instance and then get this into the spec behind a feature gate.

• Mike is going to set this up for Wed 1/17 at 12:30pm EST
• We are going to start getting a PR together for this regardless of the outcome of that meeting.

Recording (104 MB):
https://zoom.us/recording/play/Ogc_DAXBOiBt1bce7Djyv65ZTw2KVRDU-aNSz-AjFx2QcYOsad3zzwKt7OmcH6hy

Audio Only-1 (28 MB):
https://zoom.us/recording/play/NTQFO3-JdpXKqU4xs7R7JX8q2XcLcedUrY3WJsGpLHlL8DSMyHtIJDE2sDDnzAX9

[cforce]

6. Need to have a conversation on where the actions should be returned
   E.g. do we really want to say that actions can differ from service instance to service instance?

If the actions supported by the implementing service party are first queried with instantiation, you can't make it part of the "static" plan, ca you? I mean if the cloud services offers additional functions over the time. If an intance is created, it's based on a version of the instance at creation time e.g. v1. A second instance one week later might be instantiated on v2, while first instance is still not upgraded. If instance of v2 has more actions than instance of v1 the still have the same plan, doesn't they? Plan's does not represent the version of functional service actions which is available with a instantiated service plan, does it? If yes, that would imply to create new service plans with every change of a service regarding its upgraded action spec.
That would even make it necesarry to change the plan of all these instantiated services with an update of that service. For SAS updates which must happen without service consumer action - but a "plan" with assigned costs/contract that changes that is no good fit, is it?

[rhodie27]

You wouldn't need to add a new plan to add new actions. You simply add/update the discovery_url or the openapi spec that it points to.

Your "functions over time" use case is valid and interesting.

Regardless, we're going to move forward with actions at the service instance for now.

[rhodie27]

Notes from the 1/17 sync up on Extensions, :

1. Bulk Operations

• this might be supported today, but the work is on the platform side to support.
• we won't know if there is a use case for this until we move to validation
• harder to take things away (from the spec) than to add them, e.g. let's not do too much at the start.

2. Service Plan vs Service Instance

• state of a service instance might change the instance, e.g. you shouldn't be able to pause a paused service instance.
• using plan make it harder & more unreliable to handle service instance parameters

3. Ville & Mike sync up on PR under the following terms

• Include adheres_to
• Use term 'extentions'
• discovery_url returned via service instance
• need to clearly state what credentials should be used to initiate the actions, e.g. platform or other

4. General feedback

• We should just move this to validating by implementation; we won't know the major issues until we get some feedback

5. Jeremy @ MSFT

• first usecase would be Backup Operations
• SQL DB - provide a pass through to the native Backup/Restore api
• next would be others around Day 2 Operations
• would probably use this proposal right away

6. John @ Redhat / Ansible

• Using actions to execute an ansible task
• Backup / day 2 / is a priority
• Would be able to use in March / contingent on service catalog.

7. Retrospective

• Good use of outside sessions and a way to engage community
• Got good feedback / participation from people that don't attend the weekly status call
• We should use this is a vehicle going forward

Recording:
Mike forgot to hit record.

[avade]

Thanks for the detailed notes @rhodie27. Looking forward to reading the PR.

discovery_url returned via service instance

Glad to hear this was the outcome, I also believe this is the right level for actions to be exposed functionally.

I wonder if a plan could advertise the actions in a way that could be consumed programmatically in a catalog. To start with the description/metadata field could work, at least some kind of community standard.

[mattmcneeney]

Renaming this to match PR #431

[Samze]

After a period of inactivity we are now revisiting generic instance extensions. There is a new proposal doc here.

[mattmcneeney]

I can't assign @Samze to this, but this is assigned to him :)

[Samze]

Replaced by #670