On-Demand Services SDK v0.17

About the On-Demand Services SDK

Cloud Foundry Service Brokers and PCF Tiles

Service brokers let developers create service instances in their development spaces that they can call from their code. To do this, the brokers provide an interface between the Cloud Controller and the add-on software service that they represent. The service can run internal or external to a CF deployment, but the service broker always runs inside the cloud.

The service broker works by providing an API which the Cloud Controller calls to create service instances, bind them to apps, and perform other operations. Cloud Foundry service brokers are implemented as HTTP servers that conform to the service broker API.

In addition to providing an API, a service broker publishes a service catalog that may include multiple service plans, such as a free tier and a metered tier. Brokers register their service plans with the Cloud Controller to populate the services marketplace, which developers access with cf marketplace or through the Pivotal Cloud Foundry (PCF) Apps Manager.

On PCF, cloud operators make software services available to developers by finding them on Pivotal Network and then installing and configuring them through a tile interface in the Ops Manager Installation Dashboard. Installing a service tile creates a service broker, registers it with the Cloud Controller, and publishes the service plans that the broker offers. Developers can then create service instances in their spaces and bind them to their apps.

Your Service Tile in Ops Manager

The central element behind a service tile is the service broker, but the tile software includes other components that make the service easy for operators to install and maintain, and easy for developers to use. These components include configuration layouts, upgrade rules, lifecycle errands, and BOSH manifests for deploying the service instances.

BOSH 2.0 and Service Networks

Before BOSH 2.0, cloud operators pre-provisioned service instances from Ops Manager. In the Ops Manager Director Networking pane, they allocated a block of IP addresses for the service instance pool, and under Resource Config they provisioned pool VM resources, specifying the CPU, hard disk, and RAM they would use. All instances had to be provisioned at the same level. With each create-service request from a developer, Ops Manager handed out a static IP address from this block, and with each delete-service it cleaned up the VM and returned it to the available pool.

With BOSH 2.0 dynamic networking and Cloud Foundry asynchronous service provisioning, operators can now define a dynamically-provisioned service network that hosts instances more flexibly. The service network runs separate from the PCF default network. While the default network hosts VMs launched by Ops Manager, the VMs running in the service network are created and provisioned on-demand by BOSH, and BOSH lets the IaaS assign IP addresses to the service instance VMs. Each dynamic network attached to a job instance is typically represented as its own Network Interface Controller in the IaaS layer.

Operators enable on-demand services when they deploy PCF, by creating one or more service networks in the Ops Manager Director Create Networks pane and selecting the Service Network checkbox. Designating a network as a service network prevents Ops Manager from creating VMs in the network, leaving instance creation to the underlying BOSH.

Service Network checkbox

When they deploy an on-demand service, operators select the service network when configuring the tile for that on-demand service.

On-Demand Services

On-demand services use the dynamically-provisioned service network to host the single-tenant worker VMs that run as service instances within development spaces. This architecture lets developers provision IaaS resources for their service instances at creation time, rather than the operator pre-provisioning a fixed quantity of IaaS resources when they deploy the service broker.

By making services single-tenant, where each instance runs on a dedicated VM rather than sharing VMs with unrelated processes, on-demand services eliminate the “noisy neighbor” problem when one application hogs resources on a shared cluster. Single-tenant services can also support regulatory compliance where sensitive data must be compartmentalized across separate machines.

An on-demand service splits its operations between the default network and the service network. Shared components of the service, such as executive controllers and databases, run centrally on the default network along with the Cloud Controller, UAA, and other PCF components. The worker pool deployed to specific spaces runs on the service network.

Default Network and Service Network

On-Demand Services SDK and the On-Demand Broker

The on-demand services SDK is an SDK you can use to create on-demand brokers for single-tenant service offerings.

The on-demand services SDK simplifies broker and tile authoring, and is the standard approach for both Pivotal internal services teams and Pivotal partner independent software vendors (ISVs) to develop on-demand services for PCF.

The ODB SDK provides a generic on-demand broker (ODB) that answers API calls from the Cloud Controller. The service author plugs service-specific functionality into the ODB SDK via an executable called a Service Adapter. For more information about the responsibilities of service authors, please see Creating the Service Author Deliverables.

No additional or third-party components other than the service broker and the BOSH release for the service itself are required. This simplifies the setup. Everything is done through the single install process. This approach also simplifies support because there are fewer moving parts, and your customer’s network needs less customizing of DNS rules and additional firewall ports.

The on-demand services SDK imposes no constraints on the service authors’ ability to offer new functionality or expose configuration options in their service plans, such as rate limiting and external load balancers.

Service Adapters

A service adapter is a binary that is called out by the ODB when it wants to do service-specific tasks.


The above diagram shows where responsibility lies for each aspect of the ODB workflow.

The service author can focus on building the BOSH release of their service and provide a service adapter binary that manages manifest generation, binding, and unbinding. The ODB manages all interactions with Cloud Foundry and BOSH.

Thanks to BOSH v2, service authors can define resources globally (in Cloud Config). This makes manifests portable across BOSH CPIs and lets them be substantially smaller than old-style manifests. The ODB takes advantage of other BOSH v2 features as well, including dynamic IP management, availability zones, and links through which deployed BOSH instances can access IP addresses and other information from other instances.

Once an on-demand tile is authored and distributed, the operator installs and configures it the same way they do with any other Pivotal products. In the process, they select which of the tile’s available service plans to offer their developers.

Procedures for Using ODB

The following procedures outline how to set up, create and maintain a service tile based on the ODB SDK:

Create a pull request or raise an issue on the source for this page in GitHub