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

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

Open
wants to merge 1 commit into
base: master
Choose a base branch
from
Open

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

Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
86 changes: 85 additions & 1 deletion spec.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -25,6 +25,7 @@
- [Provisioning](#provisioning)
- [Fetching a Service Instance](#fetching-a-service-instance)
- [Updating a Service Instance](#updating-a-service-instance)
- [Service Instance Extensions](#service-instance-extensions)
- [Binding](#binding)
- [Types of Binding](#types-of-binding)
- [Fetching a Service Binding](#fetching-a-service-binding)
Expand Down Expand Up @@ -492,6 +493,7 @@ how Platforms might expose these values to their users.
| schemas | [Schemas](#schemas-object) | Schema definitions for Service Instances and Service Bindings for the Service Plan. |
| maximum_polling_duration | integer | A duration, in seconds, that the Platform SHOULD use as the Service's [maximum polling duration](#polling-interval-and-duration). |
| maintenance_info | [Maintenance Info](#maintenance-info-object) | Maintenance information for a Service Instance which is provisioned using the Service Plan. If provided, a version string MUST be provided and platforms MAY use this when [Provisioning](#provisioning) or [Updating](#updating-a-service-instance) a Service Instance. |
| extensions | array of [Extension](#extensions-object) objects | An array of extensions that the Service Broker MAY return. If specified, the extensions are available on created Service Instances of this Service Plan. |

\* Fields with an asterisk are REQUIRED.

Expand Down Expand Up @@ -539,6 +541,17 @@ schema being used.

\* Fields with an asterisk are REQUIRED.

##### Extensions Object

| Response Field | Type | Description |
| --- | --- | --- |
| id* | string | A Uniform Resource Name ([URN](https://tools.ietf.org/html/rfc2141)) that uniquely identifies the extension. It MUST include the namespace identifier(NID) `osbext` and a specific string(NSS) for the extension. For example `urn:osbext:/v1/backup`. |
Copy link
Contributor

@jberkhahn jberkhahn Jun 3, 2019 •
edited
Loading

Choose a reason for hiding this comment

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

shouldn't this be and a NAMESPACE specific string(NSS) (emphasis mine)? what namespace is this in reference to exactly?

Copy link
Contributor

Choose a reason for hiding this comment

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

Yes it could be if we think it will makes it more clear.
It's a reference to the URN syntax and the parts it consist of. https://tools.ietf.org/html/rfc2141#section-2

Copy link
Contributor

Choose a reason for hiding this comment

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

just writing down some concerns from the OSB meeting:

  • is this ID intended to be unique PER BROKER, or globally unique among ALL BROKERS when pointing to a specific extension? (i.e. all extensions that point http://example.com/extensions/backup_restore.yaml on ALL brokers are intended to be named the same thing on all brokers?)

Copy link
Contributor Author

@Samze Samze Jun 11, 2019 •
edited
Loading

Choose a reason for hiding this comment

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

We have two main reasons for an identifier:

The first is to support the use-case of the community coming up with a standard extensions and perhaps writing platform specific tooling for these extensions. Brokers may then want to opt-in to that already defined extension.

Then we have a separate requirement that a broker itself needs to be able to namespace extensions that it provides, say a broker wants to provide two backup and restore options and the openapi documents have colliding paths. We can use the urn as part of the broker provided path to trigger the extension.

We were hoping that having all extensions provide a globally unique urn would solve both of these problems, so I imagined that the ID (URN) was globally unique. I think perhaps our example here is misleading.

As for the structure of the URN this is something I'm not too sure about. I imagine the domain should be in there e.g. urn:osbext:pivotal.io/v1/mysqlbackups or urn:osbext:openservicebrokerapi.org/v1/community-back. Open to ideas around what this should look like and if URNs are the right thing here.

Copy link
Member

Choose a reason for hiding this comment

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

I also think the recommendation should be something like urn:osbext:<domain>/<some string> . But whatever we do, all the examples in the spec should follow the recommended pattern.

Copy link
Contributor Author

Choose a reason for hiding this comment

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

I've changed all examples to follow the pattern: urn:osbext:some-domain:some-version

| path* | string | A relative path on the Service Broker to trigger the extension's endpoint(s). This path will be relative to `/v2/service_instances/:instance_id/extensions`. This MUST be a relative URI. The Service Broker author can use this path to namespace an extension to avoid [Path Objects](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md#pathsObject) colliding with other extensions. |
| description | string | A short description of the Service Instance extension. If present, MUST be a non-empty string. |
| openapi_url* | string | A URI pointing to a valid [OpenAPI 3.0+](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md) document describing the API extension(s) available on each Service Instance of the Service Plan. If this is an absolute URI then it MUST have no authentication and be publicly available. If this is a relative URI then it is assumed to be hosted on the Service Broker and behind the [Service Broker Authentication](#platform-to-service-broker-authentication). All [Path Objects](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md#pathsObject) described in the document MUST be hosted by the Service Broker and MUST be relative to the URL `/v2/service_instances/:instance_id/extensions/:path`. The Service Broker MUST use the same authentication method used for other Open Service Broker API endpoints. |

\* Fields with an asterisk are REQUIRED.

```
{
"services": [{
Expand Down Expand Up @@ -635,7 +648,21 @@ schema being used.
"maintenance_info": {
"version": "2.1.1+abcdef",
"description": "OS image update.\nExpect downtime."
}
},
"extensions": [
{
"id": "urn:osbext:backup-and-restore:v1",
"path": "/instance-backup",
"description": "backup and restore Service Instance data.",
"openapi_url": "http://example.com/extensions/backup_restore.yaml"
},
{
"id": "urn:osbext:ping:v1",
"path": "/instance-ping",
"description": "check the health of a Service Instance.",
"openapi_url": "/extensions/ping.yaml"
}
]
}, {
"name": "fake-plan-2",
"id": "0f4008b5-XXXX-XXXX-XXXX-dace631cd648",
Expand Down Expand Up @@ -1282,6 +1309,63 @@ For success responses, the following fields are defined:
}
```

## Service Instance Extensions

Service Instance Extensions allow Service Broker authors to define new endpoints
that act on a Service Instance. This allows Service Broker authors to
extend the specification for Service specific operations. For example,
Backup, Restore, Start, Stop and Ping.

If the Service Broker has declared Service Instance extension(s) in the [Catalog](#catalog-management),
then the Service Broker MUST host a route that is used as the basepath to trigger
the extension(s). The Service Broker MUST host the path(s) relative to this route
that are defined in the [Extensions object](#extensions-object). The routes MUST
be a combination of the Service Broker author defined `path` field and the
[Path Objects](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md#pathsObject)
defined in the extension's OpenAPI 3.0 document.

#### Route
`/v2/service_instances/:instance_id/extensions/:extension_path`

`:instance_id` MUST be the ID of a previously provisioned Service Instance.

`:extension_path` MUST be the `path` field defined in the [Extensions object](#extensions-object).

For example if a Service Broker wanted to allow `POST` requests to trigger a
backup on the following path:

`/v2/service_instances/:instance_id/extensions/broker-extension-path/backup`.

They would define the following Service Instance Extension in the [Catalog](#catalog-management):

```json
{
"id": "urn:osbext:custom-extension:v1",
"path": "/broker-extension-path",
"description": "Allows backing up of Service Instance data.",
"openapi_url": "/extensions/custom-extension.yaml"
Copy link

Choose a reason for hiding this comment

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

I have couple of questions:

  1. The openapi_uri is this relative to something or absolute to the broker when hostname is not provided?
  2. For APIs that have relatively small OAS could there be an option to inline it in the Extension object, I recall that OAS supports JSON as well as YAML?

Thanks!

Copy link
Contributor Author

Choose a reason for hiding this comment

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

  1. In the description of openapi_url we state ...If this is an absolute URI then it MUST have no authentication and be publicly available. If this is a relative URI then it is MUST be hosted on the Service Broker and behind the [Service Broker Authentication](#platform-to-service-broker-authentication). Is this descriptive enough?

  2. We could do this. It adds some complication to the spec but may make Broker authors lives easier. Do you think most of your extensions would want to be embedded?

Copy link

Choose a reason for hiding this comment

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

Thanks @Samze for clarifying on the description 👍

I don't have strong feelings against either but do like the optionality. Though, the requirement of having created a service instance to get the extension specs makes me lean further away from the embedded part.

I'm 👍 to go as is. Thanks!

}
```

Where the `openapi_uri` field refers to the following OpenAPI document:

```yaml
openapi: "3.0.0"
info:
version: 1.0.0
title: My Service Extension
paths:
/backup:
post:
summary: Backup of a Service Instance
operationId: backup
tags:
- backup
responses:
'202':
description: Backup accepted
```


## Binding

Expand Down