Service Catalog Use Cases

Personas

Catalog Publishing/Curation/Discovery

Searching and Browsing Services:

1.  As a consumer, I'm able to search my catalog for services by attributes
    such as category
2.  As a consumer, I'm able to see metadata about a service prior to 
    creation which allows me to see if this service fits my need
3.  As a consumer, I'm able to see all the required and optional parameters
    the service takes in order to create it
4.  As a consumer, when listing services I see a union of the catalogs
    from all brokers that are registered. However, if I want to restrict the
    list to a specific broker I can pass that in as a flag.

Registering a Service Broker with the Service Catalog

A User must register each Service Broker with the Service Catalog to advertise the Services it offers in the Service Catalog. After the Service Broker has been registered with the Service Catalog, the Service Controller makes a call to the Service Broker’s /v2/catalog endpoint. The Service Broker returns a list of Services offered by that broker. Each Service has a set of plans that differentiate the tiers of that Service.

Updating a Service Broker

ServiceBroker operators make changes to the services their brokers offer. To refresh the services a broker offers, the Service Controller should re-list the /v2/catalog endpoint. The Service Controller should apply the result of re-listing the broker to its internal representation of that broker’s services:

  1. New services present in the re-list results are added
  2. Existing services are updated if a diff is present
  3. Existing services missing from the re-list are deleted

TODO: spell out various update scenarios and how they affect end-users

Delete a Service Broker

There must be a way to delete brokers from the catalog. We should evaluate whether deleting a broker should:

  1. Cascade down to the Service Instances for the broker
  2. Leave orphaned Service Instances in the Service Catalog
  3. Fail if Service Instances still exist for the broker

Search and Browsing Services

Searching Services

Consumers should be be able to search or filter their catalog by labels. For example, if I search for all services with ‘catalog=database’ the catalog will return the list of services that match that label. This assumes, of course, that producers are able to label their service offerings.

Service Metadata

Each service should have a list of metadata that it exposes in the catalog. If we’re following the Cloud Foundry model you can view the list of metadata fields here.

We should consider what metadata needs to be exposed for a strong CLI and UI experience. Here are some suggestions for metadata fields:

* name
* short description
* long desciption
* documentation/support urls
* icon URL
* image URLs - a list of images that could be displayed in a UI
* TOS (terms of service) link
* a list of plans
    * plan name
    * plan description
    * plan cost
* construction parameters
    * name
    * description
    * default value
* category label/tags
* version
* publisher name
* publisher contact url
* publisher website

Viewing Service Parameters

Each service offering may have a list of parameters (e.g., configuration) required to create that service. For example, if consuming a hosted database, I may need to specify the region, size, a link to a startup scripts, or other parameters.

For each service, I’m able to see the list of required and optional parameters that I can pass in during service creation. Service producers are able to specify default values for these parameters.

Listing Services

When listing all services available to be created, users will see a union of the catalog offerings from all brokers registered. However, users have the option of passing in a flag to limit results to just a specific registered broker.

TODO: How to deal with name conflicts for {broker, service}.

Requesting Services (Consumer)

Provisioning a Service Instance

ServiceBinding to a Service Instance

As an Application Operator, I should be able to accomplish the following sets of bindings:

Using/Consuming a Service Instance

Consuming applications that need specific handling of credentials or configuration should be able to use additional Kubernetes facilities to adapt/transform the contents of the the credentials/configuration. This includes, but is not limited to, side-car and init containers.

If the user were willing to change the application, then we could drop the credentials in some “standard” place by convention. This would be similar to how K8s service accounts work (service-account secrets are mounted at /var/run/secrets/kubernetes.io/serviceaccount), as well as VCAP_SERVICES in CF.

If the user were willing to change the configuration instead, they could specify how the credentials were surfaced to the application – which environment variables, volumes, etc.

Lifecycle of Service Instances

Unbinding from a Service Instance

Deprovisioning a Service Instance