Merge pull request #6 from duglin/modREADME

add some clarity on roles and goals

Author: pmorie

README.md

@@ -1,11 +1,63 @@
 ## `service-catalog`
 
-The service-catalog presents APIs for:
-
-1.  Determining which services and recipes for running instances of services
-    are available in a cluster
-2.  Making those services usable in namespaces and more granular subjects
-    (deployments, pods) within a Kubernetes cluster
+### Terminology
+
+Application: code that will access a Service. While in Kubernetes the code that
+is deployed is often called a "Service", to avoid confusion, this document will
+refer to the code that accesses a service as an "application".
+
+Recipe: the definition of an application or service in a form that can then be
+deployed into a cloud provider. For example, in Kubernetes terms, a recipe
+might be a [Deployment](http://kubernetes.io/docs/user-guide/deployments/)
+yaml file.
+
+Service: running code that is made available for use by an application.
+Traditionally, services are available via HTTP REST endpoints, but this is not
+a requirement.
+
+Service Broker: An endpoint that manages a set of services.
+
+Service Catalog: An endpoint that manages 1) a set of registered Service
+Brokers and 2) the list of services that are available for instantiation from
+those Service Brokers.
+
+Service Instance: Each request for a unique use of a Service will result in the
+Service Catalog requesting a new Service Instance from the owning Service
+Broker.
+
+### Purpose and Scope
+
+The service-catalog SIG will focus on a few key tasks:
+
+#### Service Catalog:
+1. Support a Service Catalog similar to what Cloud Foundry supports via
+   their Cloud Controller APIs. This Service Catalog will support the
+   notion of managing registered Service Brokers, which in turn dictates the
+   list of available services that can be used by applications running within
+   Kubernetes. The Service Catalog may be cluster-wide or scoped to something smaller, such
+   as a Namespace.
+2. Provide a mechanism by which applications deployed into Kubernetes can
+   signal their desire to connect to an instance of a Service Catalog managed
+   service. And, to have the information necessary for the application to
+   use the service instance provided to the application.
+
+#### Service Brokers
+1. Provide a framework to aide in the development of a Kubernetes-hosted 
+   Service Broker that can then be registered into a Service Catalog - 
+   either a Kubernetes Service Catalog or a Cloud Foundry one.
+2. Provide a mechanism by which a Kubernetes managed Service Broker can be
+   told which Namespace into which a new service instance should be created.
+   This is optional because not all services necessarily deploy new running
+   code for each service instance. For example, a DB service may simply
+   create a new set of DB tables per instance.
+
+#### Service Recipes
+1. Provide a Deployment Catalog that includes a list of pre-built deployable
+   resources that can then be instantiated into a Kubernetes environment.
+   Note that these may or may not be "Services" as defined above.
+2. These deployments, if they support the Service Broker APIs, can then be
+   registered into the Service Broker for use by applications on the
+   platform.
 
 This is the Kubernetes implementation of the service broker concept, which is
 joint effort amongst the different member organizations of the
@@ -17,18 +69,13 @@ Interested in contributing?  Check out the [documentation](./CONTRIBUTING.md)
 
 A very basic set of use cases to describe the problem space is:
 
-1.  Advertising and discovering services and recipes:
-    1.  As a service operator, I want to be able to publish service offerings
-        and recipes, so that users can search for my services and recipes they
-        can use
-2.  Recipes for running software systems in Kubernetes:
-    1.  As someone who created a recipe for running a software system in
-        Kubernetes, I want to share this recipe with others so that they can
-        easily stand up their own copy
+1.  Advertising and discovering of recipes:
+    1.  As a recipte provider, I want to be able to publish recipes
+        so that users can search and deploy them into their own environments.
     2.  As someone who wants to run a particular software system in Kubernetes,
         I want to be able to search for and use recipes that others may have
-        already created, so I can avoid spending time getting it to run myself
-3.  Sharing resources for a service:
+        already created, so I can avoid spending time getting it to run myself.
+2.  Sharing resources for a service:
     1.  As an operator of a software system, I want to share the resources that
         are required to use the system so that my users can easily consume
         them in their own namespaces
@@ -81,7 +128,7 @@ it lives off-cluster). All developers share the same credentials to access the
 database, but these credentials are managed by IT. Rather than having each
 developer create his or her own `Service` and `Secret` to connect to the
 database, IT creates a "db-app-xyz" `Service` and a "db-app-xyz" `Secret` in the
-"info-tech" namespace. 
+"info-tech" namespace.
 
 #### Consuming a set of shared resources for a service