-
Notifications
You must be signed in to change notification settings - Fork 433
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.
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
Generic Extensions (actions) #431
Changes from all commits
c590bd5
cf0ed7e
5a0820c
394d76e
7242bc5
f59f077
914dc83
f66a060
a400b53
12a1a22
99b2414
451a78f
2e15360
bcae8c0
73663f5
f601296
0ce6075
586a5cc
d236bf4
8360d16
5150a30
643e47c
1a64f74
4adddfe
a38ac79
ba5cf6c
eae12ed
750bdcf
ce8cab7
480c4ac
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
Original file line number | Diff line number | Diff line change |
---|---|---|
|
@@ -841,13 +841,93 @@ For success responses, the following fields are defined: | |
| --- | --- | --- | | ||
| dashboard_url | string | The URL of a web-based management user interface for the Service Instance; we refer to this as a service dashboard. The URL MUST contain enough information for the dashboard to identify the resource being accessed (`9189kdfsk0vfnku` in the example below). Note: a Service Broker that wishes to return `dashboard_url` for a Service Instance MUST return it with the initial response to the provision request, even if the service is provisioned asynchronously. If present, MUST be a non-empty string. | | ||
| operation | string | For asynchronous responses, Service Brokers MAY return an identifier representing the operation. The value of this field MUST be provided by the Platform with requests to the [Last Operation](#polling-last-operation) endpoint in a percent-encoded query parameter. If present, MUST be a non-empty string. | | ||
| extension_apis | array of [Extension API](#extension-api-object) objects | For extensions to the Service Broker API, Service Brokers MAY return one or more `extension_api` objects that describe additional API endpoints via an OpenAPI document. See [Extension API Object](#extension-api-object) for more information. | | ||
|
||
##### Extension API Object | ||
|
||
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, | ||
Restore, Stop, Start, Restart and Pause. | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Some of these example operations seem like they would be long-running. Is there any way for a broker to report status of a long running action back to the platform? There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Related to this, is there a way brokers can provide either success or failure messages for the platform to display when an operation is run? Ideally if the request fails, the UI can give a specific error about what went wrong instead of a generic failed error. There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Async ops, if enabled, would be defined via the swagger file. The platform could detect and subscribe to ops based on the returned swagger. There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more.
I'm not sure how a platform can detect it only from the swagger. A human looking at it might notice an endpoint called As an end user, I'd be worried if I couldn't check the status of an operation like "Restore" and know that it completed successfully. I could see it if the platform recognized the There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. I think the short answer is it's not going to be possible across the board for all APIs. My thought was that the platform could recognize a callback object in the openapi doc, (https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.1.md#callbackObject) and other openapi patterns to figure out what it needs, but we won't know until someone tries. It's the main issue with going the generic route on extensions. |
||
|
||
The `extension_api` MUST include a URI to an OpenAPI 3.0+ document that the | ||
Platform can use to determine the new endpoint(s), parameter(s) and | ||
authentication mechanism. The new 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. | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. One thing that occurred to me reading back through this is that it's not clear how the extensions are expected be invoked. Does the platform invoke them? Do users invoke them? This is probably entangled with @spadgett's question about long-running operations. There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. The answer to this from the googs perspective is yes. If the platform would like to invoke them then that should be ok, and if the platform provides all the information to a third-party that should work out as well. There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Can the PR clarify the concurrency aspects that the platform/users should comply with when invoking extensions ? For instance, should a broker exposing a This relates to #467 |
||
|
||
See [OpenAPI Server Object](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md#serverObject) for more information. | ||
|
||
| Response Field | Type | Description | | ||
| --- | --- | --- | | ||
| discovery_url* | string | A URI pointing to a valid OpenAPI 3.0+ document describing the API extension(s) to the Open Service Broker API including, endpoints, parameters, authentication mechanism 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. If local to the Service Broker the same authentication method for normal Serivce Broker calls MUST be used. If located on a remote server acccessing the OpenAPI document MUST NOT require authentication. MUST be a valid URI. If `discovery_url` is a path, the Platform can assume it is to be called relative to the basepath of the Service Broker. 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. | | ||
| server_url | string | A URI pointing to a remote server where API extensions will run. This URI will be used as the basepath for the [Paths Objects](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md#pathsObject) described by the `discovery_url` OpenAPI document. If no `server_url` is present, the Platform MUST assume the extension API endpoint(s) are to be invoked using the Service Broker host and port. If present, MUST be a valid URI. If `server_url` is a path, the Platform can assume it is to be called relative to the basepath of the Service Broker. | | ||
| 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, the same authentication mechanism used for the normal Open Service Broker APIs MUST work for the new endpoint(s). If the Service Broker wants to use alternate methods of authentication, (e.g. on remote servers) it MUST provide details to that mechanism in the OpenAPI document via one or more [Security Scheme Objects](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md#securitySchemeObject). Next, each extension endpoint in the OpenAPI document MUST have one or more [Security Requirement Objects](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md#securityRequirementObject) defined that matches a [Security Scheme Object](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md#securitySchemeObject). Lastly, the parameters needed by each [Security Scheme Object](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md#securitySchemeObject), (e.g. username and password for basic authentication), MUST be provided as part of the `extension_api` object within the `credentials` object. If credentials are present in an `extension_api` object, the Platform will need to verify the authentication method from the OpenAPI document. | | ||
| adheres_to | string | A URI refering to a specification detailing the implementation guidelines for the OpenAPI document hosted at the `discovery_url`. 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. If present, MUST be a valid URI. | | ||
|
||
\* Fields with an asterisk are REQUIRED. | ||
|
||
#### Provisioning response | ||
|
||
``` | ||
{ | ||
"dashboard_url": "http://example-dashboard.example.com/9189kdfsk0vfnku", | ||
"operation": "task_10" | ||
} | ||
``` | ||
#### Provisioning response with extentions | ||
|
||
``` | ||
{ | ||
"dashboard_url": "http://example-dashboard.example.com/9189kdfsk0vfnku", | ||
"operation": "task_10", | ||
"extension_apis":[{ | ||
"discovery_url": "http://example-openapi-doc.example.com/extensions", | ||
"server_url": "http://myremoteserver.example.com", | ||
"credentials": { | ||
"basic": { | ||
"username": "admin", | ||
"password": "changeme" | ||
}, | ||
"api_key": { | ||
"api_key": "some_key_value" | ||
}, | ||
"petstore_auth": { | ||
"token": "some_token_value" | ||
} | ||
}, | ||
"adheres_to": "http://example-specification.example.com" | ||
}] | ||
} | ||
``` | ||
|
||
#### OpenAPI Security Scheme Object example | ||
|
||
``` | ||
"securitySchemes": { | ||
"basic": { | ||
"type": "http", | ||
"scheme": "basic" | ||
}, | ||
"api_key": { | ||
"type": "apiKey", | ||
"name": "api_key", | ||
"in": "header" | ||
}, | ||
"petstore_auth": { | ||
"type": "oauth2", | ||
"flows": { | ||
"implicit": { | ||
"authorizationUrl": "http://example.org/api/oauth/dialog", | ||
"scopes": { | ||
"write:pets": "modify pets in your account", | ||
"read:pets": "read your pets" | ||
} | ||
} | ||
} | ||
} | ||
} | ||
``` | ||
|
||
## Updating a Service Instance | ||
|
||
|
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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 extensionsStop, Start, Restart and Pause
: service specific extensionsThere was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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'.
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.
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.I suspect this is out of scope for the current PR, at least until we see some real world emergent behavior for generic actions.