Generic Extensions (actions) #431

rhodie27 · 2018-01-26T00:04:53Z

See issue #114.

First draft of the generic actions (aka extensions) proposal on a per-service-instance basis.

A couple notes:

In addition to updating Provisioning, I added a separate section for Extensions at the bottom b/c I suspect we will add actions/extensions at the service (and broker) level next. A lot of this can likely be handled in the same way so it made sense to me to separate it out now.
The OpenAPI, Auth & adheres_to sections obviously need more content/wording, but I wanted to get some quick feedback on the direction.
I haven't really looked at any changes required outside of spec.md yet.
I'm an awful speller today, so good luck.

cfdreddbot · 2018-01-26T00:04:54Z

Hey rhodie27!

Thanks for submitting this pull request!

All pull request submitters and commit authors must have a Contributor License Agreement (CLA) on-file with us. Please sign the appropriate CLA (individual or corporate).

When sending signed CLA please provide your github username in case of individual CLA or the list of github usernames that can make pull requests on behalf of your organization.

If you are confident that you're covered under a Corporate CLA, please make sure you've publicized your membership in the appropriate Github Org, per these instructions.

Once you've publicized your membership, one of the owners of this repository can close and reopen this pull request, and dreddbot will take another look.

rhodie27 · 2018-01-26T00:20:15Z

Reopen please, my org was private for some reason. I fixed the CI issues.

cfdreddbot · 2018-01-26T00:44:22Z

Hey rhodie27!

Thanks for submitting this pull request! I'm here to inform the recipients of the pull request that you and the commit authors have already signed the CLA.

duglin · 2018-01-26T00:47:05Z

spec.md

+
+##### Extension APIs Object
+
+The `extension_apis` object MAY be used to describe any additional endpoint needed related to a Service Instance. An examples of this might include backup and restore endpoints for a database. If present, MUST return a `discovery_url`. See [Extensions](#extensions) for more information.


Can you wrap non-table lines at 80 columns to be consistent with the rest of the doc?

if present, each item in the extension_apis array MUST include a discovery_url property.

Although, I think this MUST is redundant with the REQUIRED aspect of the discovery_url you mention in the table below. So it might be best to remove here so we're not duplicating requirements.

I think I got these.

duglin · 2018-01-26T00:50:19Z

spec.md

+
+| Response field | Type | Description |
+| --- | --- | --- |
+| discovery_url | string | A URI pointing to a valid OpenAPI 3.0+ document describing the API extension(s) to the Service Instance including server location, endpoints, parameters and any other detail required for invocation. The location of the API extension endpoint(s) can be local to the Service Broker or on a remote server. The Platform MUST execute these API extensions on behalf of the client. MUST be a valid URI. See [OpenAPI](#openapi-document) for more information.|


s/required for invocation/needed for invocation/

Should probably use the '*' pattern to indicate that its a required field.

Rather than "The Platform MUST execute...", which sounds like the platform is required to invoke these even if it has no need to, I would suggest that we remove that sentence from here. Instead, since this is really more of a generic statement about the entire concept and not about this one field, let's add a sentence to the intro section at line 849 about this issue. And perhaps there say something like:

These APIs are extensions to the Open Service Broker API. As such they are intended to be invoked by the Platform on behalf of its clients.

I tried to think of a way to make it normative but it felt a bit odd. I don't think we ever say that the normal OSBAPIs MUST be invoked by the Platform, although its implied. So I think we can probably live with the same non-normative-ness in these too. WDYT?

I think it makes sense. I changed it.

duglin · 2018-01-26T01:01:48Z

spec.md

+| Response field | Type | Description |
+| --- | --- | --- |
+| discovery_url | string | A URI pointing to a valid OpenAPI 3.0+ document describing the API extension(s) to the Service Instance including server location, endpoints, parameters and any other detail required for invocation. The location of the API extension endpoint(s) can be local to the Service Broker or on a remote server. The Platform MUST execute these API extensions on behalf of the client. MUST be a valid URI. See [OpenAPI](#openapi-document) for more information.|
+| credentials | object | A Service Broker MAY return authentication details for running any of the extension API calls, especially for those running on remote servers. If not present, platforms can assume that standard broker authentication will work for the new endpoint(s). See [Extension Authentication](#extension-api-authentication) for more information.|


If not present, the same authentication mechanism used for the normal Open Service Broker APIs MUST work for the new endpoint(s).

duglin · 2018-01-26T01:09:02Z

spec.md

+| --- | --- | --- |
+| discovery_url | string | A URI pointing to a valid OpenAPI 3.0+ document describing the API extension(s) to the Service Instance including server location, endpoints, parameters and any other detail required for invocation. The location of the API extension endpoint(s) can be local to the Service Broker or on a remote server. The Platform MUST execute these API extensions on behalf of the client. MUST be a valid URI. See [OpenAPI](#openapi-document) for more information.|
+| credentials | object | A Service Broker MAY return authentication details for running any of the extension API calls, especially for those running on remote servers. If not present, platforms can assume that standard broker authentication will work for the new endpoint(s). See [Extension Authentication](#extension-api-authentication) for more information.|
+| adheres_to | string | A URI pointing to a specification detailing the implementation guidelines for the OpenAPI document hosted at the `discovery_url`. If present, must be a valid URI.|


I wonder if instead of "pointing" (which sort of implies there has to be a server listening at the endpoint), we should say "referring". Almost the same but perhaps wishy-washy enough to then allow us to add: While this property is a URI, there is no requirement for there to be an actual server listening at that endpoint. This value is meant to provide a unique identifier representing the set of extensions APIs supported.

Done. Wishy-washy it is!

duglin · 2018-01-26T01:09:27Z

spec.md

+      "discovery_url": "http://example-openapi-doc.example.com/extensions",
+      "credentials":[{
+        "tokenURL": "https://example.com/api/oauth/token"
+      }]


Yup. Got it.

duglin · 2018-01-26T01:17:35Z

spec.md

+
+### Extension API on Remote Servers
+
+Additional API endpoints MAY be executed on a remote server, however the OpenAPI document MUST include the servers `url` so that the Platform will know how to invoke the endpoint(s). If the server `context` parameter of the OpenAPI document is set to local host the Platform can assume the extension API endpoints are to be invoked using the Service Broker host and port.


s/can assume.../MUST use....

I assume that its just the host (localhost) that is swapped out in favor of the original host/port, right? meaning any path stuff in the OpenAPI doc should still be used right? We should probably say that if so. You may want to also say that any port number specified will be replace too if "localhost" is used - if that's your intent.

I'm talking specifically about the server object, https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md#serverObject, url. It can or cannot include a port. I'm think we want to say that if the doc just says http://localhost for url that signifies that it should run on the SB host/port. However, there is an issue if the OAPI doc provides more than one url. Perhaps we can say the doc should provide a url with a description "Service Broker host" to clearly identify the right one, whether it's localhost or other...

I need to think about this more, so I didn't modify it. Can get to it tomorrow.

duglin · 2018-01-26T01:20:53Z

spec.md

+
+### Extension API Authentication
+
+The Service Broker MAY use the the same broker authentication method for invocation of extension endpoints by not providing credentials as part of a `extensions_api` object. If no credentials are present in an `extensions_api` object, the Platform can assume that the default broker authentication is required.


This is a dup from what's above - I would suggest that we only say it once - and I think the one from above is good enough. You may be able to just move all of this section up above - not sure its worthy enough for just one para. Actually, would it read better to just move this entire "Extension" section into what we have above since it kind of feels like a repeat of the same material and anything new could just be sprinkled up there. Just a thought.

Yeah, I wasn't sure. Like I wrote in PR, while writing this I separated it out b/c a lot of it seemed like it would be redundant if we added extensions on other resources down the line. But, obviously, we could always abstract it out at that point in time.

I did it your way, for now. If others chime in and want it separated out I can always revert.

duglin · 2018-01-26T01:21:18Z

@rhodie27 overall I think it looks good! Just some editorial suggestions.

duglin · 2018-01-29T13:26:49Z

@rhodie27 any chance of addressing the comments before tomorrow's call?

This reverts commit 12a1a22.

duglin · 2018-01-30T01:14:17Z

spec.md

+Extension API endpoints MAY be executed on a remote server, however the OpenAPI
+document MUST include the servers `url` so that the Platform will know how to
+invoke the endpoint(s). If the server `context` parameter of the OpenAPI
+document is set to localhost the Platform can assume the extension API endpoints


may want to backtick localhost

should we s/can assume/MUST assume/ ?

Done. I think that makes sense. I can't think of a reason they wouldn't want to assume that.

duglin · 2018-01-30T01:36:59Z

spec.md

+
+| Response field | Type | Description |
+| --- | --- | --- |
+| discovery_url | string | A URI pointing to a valid OpenAPI 3.0+ document describing the API extension(s) to the Service Instance including server location, endpoints, parameters and any other detail the platform needs for invocation. The location of the API extension endpoint(s) can be local to the Service Broker or on a remote server. MUST be a valid URI. The returned OpenAPI document MUST be in json format. See the [OpenAPI Specification](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md) for more information. |


I think you need to add a * and the * Fields with an asterisk are REQUIRED. sentence after the description of the fields.

Yup, I thought I did. Must've reverted. There now.

gberche-orange · 2018-03-26T21:10:46Z

spec.md

+
+The `extension_api` object MAY be used to describe any additional endpoint
+to the Open Service Broker API. An example of this could be lifecycle
+management of a Service Instance, (e.g. "Day Two Operations"), like Backup,


I would suggest the specs to clarify when an extension_api should be defined and used by broker authors w.r.t. to asking 1st class support in the OSB API.

Are platforms expected to provide UI/CLI tooling for any declared extensions (i.e. dynamically generating UI from the openAPI document) ? Would generated UIs and user workflows be restricted to single API endpoint calls, or would instead spawn across multiple API calls (e.g. list backups, restore backup, delete backup) ?

Are platforms instead expected to additionally support specific curated extensions and bring optimized user experience for them? If so, where/how would such curated extensions be defined and published ?

Can the specs recommend use-cases for extensions such as:
1- operator specific extensions : a platform operators is adding custom features to a broker and brings custom UI on along it.
2- service specific extensions (say stop/resume operation) that only applies to a category of services
3- vendor specific extensions (say K8S/CF vendor X way of offering backup which differ from vendor Y)
4- platform specific extensions (e.g. CF AR service metrics ingestion which differs from K8S metrics ingestion) that can't be supported by platform-specific profiles

Would the mentioned day 2 operations seem be fitting some of the cases above?

Backup, Restore: vendor specific extensions

Stop, Start, Restart and Pause: service specific extensions

I would suggest the specs to clarify when an extension_api should be defined and used by broker authors w.r.t. to asking 1st class support in the OSB API.

The current thinking is it is entirely up to the broker author, and the platform can choose to provide, at minimum, the OpenAPI UI (or even just the OpenAPI url). Then platforms can extend the UI based on 'adheres_to'.

Are platforms expected to provide UI/CLI tooling for any declared extensions (i.e. dynamically generating UI from the openAPI document) ? Would generated UIs and user workflows be restricted to single API endpoint calls, or would instead spawn across multiple API calls (e.g. list backups, restore backup, delete backup) ?

We had talked about how to batch calls but it became clear that this could be designed forever and we decided to support just the single endpoint as a first step, but nothing stops a clever broker from providing batch/aggregation on their own.

Are platforms instead expected to additionally support specific curated extensions and bring optimized user experience for them? If so, where/how would such curated extensions be defined and published ?

adheres_to is the mechanism we think will do this. If it is proven that this is not enough we can always revisit the spec to add what is lacking.

Can the specs recommend use-cases for extensions such as:
1- operator specific extensions : a platform operators is adding custom features to a broker and brings custom UI on along it.
2- service specific extensions (say stop/resume operation) that only applies to a category of services
3- vendor specific extensions (say K8S/CF vendor X way of offering backup which differ from vendor Y)
4- platform specific extensions (e.g. CF AR service metrics ingestion which differs from K8S metrics ingestion) that can't be supported by platform-specific profiles

I suspect this is out of scope for the current PR, at least until we see some real world emergent behavior for generic actions.

duglin · 2018-08-17T15:05:00Z

I believe we were supposed to find out how much interest we each had on this one... from our side we are still interested in the idea in general but have no immediate need for it. I guess that means its a "nice to have" but not a "show stopper" or "must have" for us right now.

Samze · 2019-04-29T14:10:01Z

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

mattmcneeney · 2020-02-18T19:29:59Z

Closing this as we are planning on moving forward with #670

Michael Rhodes added 8 commits January 25, 2018 17:38

actions first draft

c590bd5

add to toc

cf0ed7e

fix broken link

5a0820c

spelling, links.

394d76e

Still can't spell.

7242bc5

Update spec.md

f59f077

Update spec.md

914dc83

Update spec.md

f66a060

Some minor changes to make ci happy.

a400b53

duglin closed this Jan 26, 2018

duglin reopened this Jan 26, 2018

duglin reviewed Jan 26, 2018

View reviewed changes

duglin mentioned this pull request Jan 29, 2018

Action Execution rohitkshetty/servicebroker#1

Open

Michael Rhodes added 4 commits January 29, 2018 18:42

addressing dougs comments

12a1a22

Revert "addressing dougs comments"

99b2414

This reverts commit 12a1a22.

Addressing Dougs comments.

451a78f

required/REQUIRED

2e15360

duglin reviewed Jan 30, 2018

View reviewed changes

zhongyi-zhang mentioned this pull request Feb 28, 2018

SQL DB - Add support for geo-replication Azure/open-service-broker-azure#313

Closed

duglin added 2 - validating through implementation do not merge labels Mar 1, 2018

Michael Rhodes added 4 commits March 7, 2018 16:48

changing name prior to removing

eae12ed

statement on local disc_url

750bdcf

+paths objects

ce8cab7

align with pr 459

480c4ac

This was referenced Mar 9, 2018

Implement alpha support for generic actions kubernetes-retired/go-open-service-broker-client#113

Closed

Add support for generic API extensions kubernetes-retired/go-open-service-broker-client#115

Merged

gberche-orange reviewed Mar 26, 2018

View reviewed changes

This was referenced May 21, 2018

Service metrics support via Generic Extensions #485

Open

There should be a health check end point for services that are provisioned #344

Closed

Service logs support via Generic Extensions #486

Open

mattmcneeney mentioned this pull request Jul 12, 2018

Generic Extensions (Actions) Proposal #114

Closed

mattmcneeney added this to the 2.15 milestone Dec 18, 2018

fmui mentioned this pull request Jan 17, 2019

How to extend more service binding operations? #631

Closed

mattmcneeney mentioned this pull request Mar 18, 2019

aws-service-operator vs aws-service-broker amazon-archives/aws-service-operator#137

Open

Samze mentioned this pull request May 28, 2019

Service Instance Generic Extensions/Actions (Take 2) #670

Open

mattmcneeney modified the milestones: 2.15, 2.12, 2.16 Jun 11, 2019

mattmcneeney closed this Feb 18, 2020

mattmcneeney removed this from the 2.16 milestone May 15, 2020

edwardecook mentioned this pull request May 26, 2020

ExtensionAPIs is not a currently proposed feature of OSBAPI kubernetes-retired/go-open-service-broker-client#153

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Generic Extensions (actions) #431

Generic Extensions (actions) #431

rhodie27 commented Jan 26, 2018

cfdreddbot commented Jan 26, 2018

rhodie27 commented Jan 26, 2018

cfdreddbot commented Jan 26, 2018

duglin Jan 26, 2018

duglin Jan 26, 2018

duglin Jan 26, 2018

rhodie27 Jan 30, 2018

duglin Jan 26, 2018

duglin Jan 26, 2018

duglin Jan 26, 2018

rhodie27 Jan 30, 2018

duglin Jan 26, 2018

rhodie27 Jan 30, 2018

duglin Jan 26, 2018

rhodie27 Jan 30, 2018

duglin Jan 26, 2018

rhodie27 Jan 30, 2018

duglin Jan 26, 2018

rhodie27 Jan 30, 2018 •

edited

Loading

duglin Jan 26, 2018

rhodie27 Jan 26, 2018

rhodie27 Jan 30, 2018

duglin commented Jan 26, 2018

duglin commented Jan 29, 2018

duglin Jan 30, 2018

duglin Jan 30, 2018

rhodie27 Jan 30, 2018

duglin Jan 30, 2018

rhodie27 Jan 30, 2018

gberche-orange Mar 26, 2018 •

edited

Loading

n3wscott Mar 28, 2018

duglin commented Aug 17, 2018

Samze commented Apr 29, 2019

mattmcneeney commented Feb 18, 2020


		##### Extension APIs Object

		The `extension_apis` object MAY be used to describe any additional endpoint needed related to a Service Instance. An examples of this might include backup and restore endpoints for a database. If present, MUST return a `discovery_url`. See [Extensions](#extensions) for more information.


		### Extension API on Remote Servers

		Additional API endpoints MAY be executed on a remote server, however the OpenAPI document MUST include the servers `url` so that the Platform will know how to invoke the endpoint(s). If the server `context` parameter of the OpenAPI document is set to local host the Platform can assume the extension API endpoints are to be invoked using the Service Broker host and port.


		### Extension API Authentication

		The Service Broker MAY use the the same broker authentication method for invocation of extension endpoints by not providing credentials as part of a `extensions_api` object. If no credentials are present in an `extensions_api` object, the Platform can assume that the default broker authentication is required.

Generic Extensions (actions) #431

Generic Extensions (actions) #431

Conversation

rhodie27 commented Jan 26, 2018

cfdreddbot commented Jan 26, 2018

rhodie27 commented Jan 26, 2018

cfdreddbot commented Jan 26, 2018

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

rhodie27 Jan 30, 2018 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

duglin commented Jan 26, 2018

duglin commented Jan 29, 2018

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

gberche-orange Mar 26, 2018 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

duglin commented Aug 17, 2018

Samze commented Apr 29, 2019

mattmcneeney commented Feb 18, 2020

rhodie27 Jan 30, 2018 •

edited

Loading

gberche-orange Mar 26, 2018 •

edited

Loading