Returning information about the provisioned instance in the response

[nilebox]

What's the recommended way of returning information about the provisioned instance? For example, the URL of provisioned S3 bucket or public IP address of the EC2 instance.

In the current spec the response body for provisioned Instance doesn't have such field suitable for returning arbitrary information.

The only generic way to return such information in the current spec I see is by using Binding's credentials response field. However, it seems hacky, as for examples I mentioned above there are no credentials to be generated, and there is nothing to bind/unbind. So in this case "binding" would just return Instance's static information, and "unbinding" would do nothing.

The more straightforward approach of returning such information would be extending Instance provisioning response with similar field.

[duglin]

Typically the credentials contain everything you need to talk to the service - not just passwords but host, port, etc... For example, here's a sample VCAP_SERVICES that I see in one of my test CF apps:

{"cloudantNoSQLDB":[{
  "credentials": {
    "username":"fd7d1b58-ffdb-428a-aad1-5f45848b8753-bluemix",
    "password":"c07750d55c6e8e3b0e2f4c6cf3a3d74937cf49e529ef84ad054a5811611",
    "host":"fd7d1b58-ffdb-428a-aad1-5f45848b8753-bluemix.cloudant.com",
    "port":443,
    "url":"https://fd7d1b58-ffdb-428a-aad1-5f45848b8753-bluemix:c07750d55c6e8e3b0e2f4c8ea3d74937cf49e529ef84ad054a5811611@fd7d1b58-ffdb-428a-aad1-5f45848b8753-bluemix.cloudant.com"
  },
  "syslog_drain_url":null,
  "label":"cloudantNoSQLDB",
  "provider":null,
  "plan":"Lite",
  "name":"Cloudant NoSQL DB-b1",
  "tags":["data_management","ibm_created","lite","ibm_dedicated_public"]
} ] } 

Notice the "host" and "port" fields.

[nilebox]

@duglin for your example it is fine, but what if there is nothing specific to "bind"? There is just an instance with static information about it. What I would like to see is bindable: false with provisioning response returning arbitrary JSON object, similar to Binding's credentials.

[duglin]

In the case of non-bindable instances I think its similar to dashboard_url, meaning I think you're supposed to extend the CreateInstanceResponse body to include any other stuff needed by the user to access the instance. Of course, w/o a well know place to put it there's no way for the platform to know which extra bits are meant for the end-user vs for the platform vs random stuff to ignore. Perhaps we need to add a well-defined property that's similar to "credentials" for CreateInstanceResponse.

[skaegi]

Returning "credentials" in your response as @duglin suggests is reasonable. We actually use the same approach to return input "parameters".

[duglin]

What do people think about adding a "metadata" field to CreateInstanceResponse to hold all info about the Instance? We could move dashboard_url into there too. That would allow properties that are intended for the platform (e.g. "operation") to remain outside of "metadata", while "metadata" could be blindly passed on to the user.

[nilebox]

Returning "credentials" in your response as @duglin suggests is reasonable.

that's what I am proposing as well, but since OSB doesn't require support for this in provisioning response, the platform (Cloud Foundry, Service Catalog) will whether ignore it or fail on validating response. So it's not about the way for broker to return arbitrary data, it's about the platform to recognize this data in unified way. So I am proposing to add the "credentials" section (or any other appropriate name) to the OSB spec.

We actually use the same approach to return input "parameters".

@skaegi Can you elaborate more? Where do you use this approach? Which OSB platform/marketplace are you using? Cloud Foundry?

[nilebox]

@duglin I am personally fine with having "metadata" field (in a similar manner to "context" added recently), but we'll have to leave dashboard_url and operation for backward compatibility anyway.

[duglin]

re: dashboard_url - agreed, what I meant to say was that we could deprecate it in its current location.

[skaegi]

sorry @nilebox just saw your comment now -- the system I'm using is called Open Toolchain which is used in Bluemix DevOps -- it predates OSB but is very similar to CF.

In our platform we check the return object for a matching json structure / json schema but otherwise will save all information returned from the provision call. When someone later asks to see the service instance we return this information.

We use this mechanism to allow a service instance to return a parameters object that we use in a form for "updating" the service instance. The parameters sent to the broker during a provision may be different from the parameters returned. For example, a broker might decide not to return secret credentials like apikeys or passwords.

I think it would be a reasonable change to add new defined properties like credentials and parameters on the provision response but that obviously needs some work.

[nilebox]

The question is whether we want to support non-sensitive data only (metadata is meant to be non-sensitive, I believe), or presume that any data can be potentially sensitive (aka credentials), or add support for both fields and keep them separate?

[nilebox]

Supporting this feature for asynchronous instance provisioning is tricky (currently there is no requirement for GET endpoints in the OSB spec), so we should probably postpone this until this issue is addressed in asynchronous bindings (see proposal https://github.com/openservicebrokerapi/servicebroker/pull/334 and issue https://github.com/openservicebrokerapi/servicebroker/issues/137)

[mattmcneeney]

This kind of information can now be fetched using the GET endpoints/async bindings. Closing.