Services Overview

Page last updated:

Architecture and Terminology

Services are integrated with Pivotal Platform by implementing a documented API for which the Cloud Controller is the client, called the Service Broker API. This should not be confused with the Cloud Controller API, often used to refer to the version of Pivotal Platform itself. When one refers to “Pivotal Platform v2”, they are referring to the version of the Cloud Controller API. The Service Broker API is versioned independently of the Cloud Controller API.

“Service broker” is the term that refers 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 apps and services does not flow through the service broker, the term “gateway” caused confusion. Although “gateway” still appears in old code, the term “broker” is used in conversation, in new code, and in documentation.

Service brokers advertise a catalog of service offerings and service plans, as well as interpreting calls for 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 app necessary for accessing the resource. The reserved resource is called 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 app.

View a larger version of this image.

Implementation and Deployment

How a service is implemented is up to the service provider or developer. Pivotal Platform only requires that the service provider implement the Service Broker API. A broker can be implemented as a separate app, or by adding the required HTTP endpoints to an existing service.

Because Pivotal Platform only requires that a service implements the Service Broker API in order to be available to Pivotal Platform end users, many deployment models are possible. The following are examples of valid deployment models:

  • Entire service packaged and deployed by BOSH alongside Pivotal Platform
  • Service broker packaged and deployed by BOSH alongside Pivotal Platform, rest of the service deployed and maintained by other means
  • Broker (and optionally service) pushed as an app to Pivotal Platform user space
  • Entire service, including broker, deployed and maintained outside of Pivotal Platform by other means