There are two ways in which Cloud Foundry enables developers to add services to their applications, Managed Services and User-provided Service Instances. Managed Services have been integrated with Cloud Foundry via APIs and enable end-users to provision new service instances and credentials on demand. User-provided Service Instances are a mechanism to deliver credentials to applications for service instances which have been pre-provisioned outside of Cloud Foundry.
The documentation in this section pertains to building and integrating Managed Services with Cloud Foundry.
Services are integrated with Cloud Foundry by implementing a documented API for which the cloud controller is the client; we call this the Service Broker API. This should not be confused with the cloud controller API, often used to refer to the version of Cloud Foundry itself; when one refers to “Cloud Foundry v2” they are referring to the version of the cloud controller API. The services API is versioned independently of the cloud controller API.
Service Broker is the term we use to refer to a component of the service which implements the service broker API. This component was formerly referred to as a Service Gateway, however as traffic between applications and services does not flow through the broker we found the term gateway caused confusion. Although gateway still appears in old code, we use the term broker in conversation, in new code, and are updating documentation to reflect the change.
In general, service brokers advertise a catalog of service offerings and service plans to Cloud Foundry, and receive calls from Cloud Foundry for five functions: fetch catalog, provision (create), bind, unbind, and deprovision (delete). What a broker does with each call can vary between services; in general, 'provision' reserves resources on a service and 'bind' delivers information to an application necessary for accessing the resource. We call the reserved resource a Service Instance. What a service instance represents can vary by service; it could be a single database on a multi-tenant server, a dedicated cluster, or even just an account on a web application.
How a service is implemented is up to the service provider/developer. Cloud Foundry only requires that the service provider implement the service broker API. A broker can be implemented as a separate application, or by adding the required http endpoints to an existing service.
Because Cloud Foundry only requires that a service implements the broker API in order to be available to Cloud Foundry end users, many deployment models are possible. The following are examples of valid deployment models.
- Entire service packaged and deployed by BOSH alongside Cloud Foundry
- Broker packaged and deployed by BOSH alongside Cloud Foundry, rest of the service deployed and maintained by other means
- Broker (and optionally service) pushed as an application to Cloud Foundry user space
- Entire service, including broker, deployed and maintained outside of Cloud Foundry by other means
You'll need a Cloud Foundry instance to deploy and test your service broker as you are developing it. You must have admin access to your CF instance. You may use any existing install of CF as long you have admin access to it. Otherwise, we recommend deploying a new CF development instance using Bosh Lite.
- v2 Service Broker API
- Managing Service Brokers
- Access Control
- Catalog Metadata
- Binding Credentials
- Using Services
The following example service broker applications have been developed - these are a great starting point if you are developing your own service broker.
- GitHub repo service - this is designed to be an easy-to-read example of a service broker, with complete documentation, and comes with a demo app that uses the service. The broker can be deployed as an application to any Cloud Foundry instance or hosted elsewhere. The service broker uses GitHub as the service back end.
- MySQL database service - this broker and its accompanying MySQL server are designed to be deployed together as a BOSH release. BOSH is used to deploy or upgrade the release, monitors the health of running components, and restarts or recreates unhealthy VMs. The broker code alone can be found here.