Writing a v1 Cloud Foundry Service

Page last updated: December 4, 2015

There are two versions of the Cloud Foundry Services API. This page documents v1.

DEPRECATED: We recommend that all new service brokers be written against the version 2 API. Support for v1 service brokers will be removed at the end of 2015.

Writing a service involves writing a service broker that obeys the API contract between the Cloud Controller v2 (CC) and a v1 service broker. Service brokers were previously called Service Gateways (GW). The protocol is entirely RESTful HTTP, with bidirectional communication. In addition to authentication there are six basic operations that take place, described in this document. An oversimplified example of making a broker that supports the 3 most basic operations can be found here: https://github.com/geapi/cf-service-example.

Authentication

The Cloud Controller authenticates to a broker using a shared secret

The broker must reject all requests not including the shared secret with a 401 unauthorized response. The token is registered into the Cloud Controller by an admin user, usually using the cf CLI gem which adds commands like cf create-service-auth-token. Or one can directly make calls to the Cloud Controller v2 RESTful API to register a new shared secret (called auth token).

A broker authenticates to the Cloud Controller using a UAA token

Like all API endpoints in the Cloud Controller, the broker must first obtain and then include a valid Oauth2 token from UAA. This token must include the scope cloud_controller.admin, because only this scope has permission to modify the services catalog.

Catalog Management

With v2 of the Cloud Controller, a broker is responsible for maintaining its catalog of offerings and plans by issuing various RESTful API calls to the Cloud Controller. Normally the lifecycle is as follows:

1. On startup, the broker communicates with UAA to get an access token with sufficient permissions to access the Cloud Controller (currently admin access).
2. It then downloads the catalog of all available service offerings and plans from the Cloud Controller.
3. It issues POST requests to create missing offerings and plans. Offerings include a URL to access the broker responsible for future provision/bind requests.
4. It issues PUT requests to update existing offerings and plans that are not in sync.
5. It issues DELETE requests to remove offerings and plans it no longer wants to advertise.

All catalog management APIs are in the Cloud Controller. A service is identified by the combination of [label, provider, version], which must be unique. A plan is identified by [service_guid, name], which must also be unique.

We introduced the unique_id field in order to enable service brokers to change service labels, providers, and versions, and to change plan names. If a service broker sets a unique_id for its service in Cloud Controller, then the broker can use the unique_id to identify the service, even after it has changed the service name, etc. The same is true for plans.

To generate a unique_id, try this Online GUID Generator.

Creating a new service in the catalog

POST /v2/services

    {
      "metadata" = > {
        "guid" = > "9201fc22-ee74-42c8-9dcd-4425be183074",
        "url" = > "/v2/services/9201fc22-ee74-42c8-9dcd-4425be183074",
        "created_at" = > "2013-07-01 14:54:06 +0000",
        "updated_at" = > nil
      }, "entity" = > {
        "label" = > "push-gateway-1.0",
        "provider" = > "aws",
        "url" = > "http://where.your.gateway.lives.org",
        "description" = > "Your Gateway",
        "version" = > "1.0",
        "info_url" = > nil,
        "active" = > false,
        "unique_id" = > "pg-1.0",
        "extra" = > nil,
        "service_plans_url" = >
"/v2/services/9201fc22-ee74-42c8-9dcd-4425be183074/service_plans"
      }
    }
  

Updating a service in the catalog

PUT /v2/services

Listing the services catalog

GET /v2/services

Removing a service from the catalog

DELETE /v2/services/:guid

No body or query parameters. This request is expected to fail if there are plans, instances, or bindings attached to this service, as they must be deleted first.

Creating a new plan in the catalog

POST /v2/service_plans

Listing the plans

GET /v2/service_plans

Updating a plan in the catalog

PUT /v2/service_plans/:guid

Removing a plan from the catalog

DELETE /v2/service_plans/:guid

• No body
• No query parameters.

This request is expected to fail if there instances or bindings attached to this plan, as they must be deleted first.

Provisioning

When developers provision a service (using cf create-service), they issue an API request to the Cloud Controller including the offering, plan, and space. The Cloud Controller uses its database to determine which broker is responsible for this offering and issues an API request synchronously to the broker to provision the resources. This request includes less information than the user-initiated request, because brokers are supposed to not care about some CF concepts like users, spaces, and organizations.

The broker must then provision the resource, if possible, and respond with a “gateway identifier” (GWID) that can be used to identify the resource for future operations. In CF terms, what is created after provisioning is a “service instance”. No application should have access to the service instance until it has been bound by the user, so usually no service credentials exist at the time of provisioning.

To provision, the Cloud Controller sends a provision request to the broker. The full request URL is determined by concatenating the URL in the catalog + the path below.

POST :service_url/gateway/v1/configurations

Brokers should respond with 200 OK and a JSON response body containing fields from the table below. The Cloud Controller will interpret any non-2xx response codes as a failure to provision. Asterisks denote required fields.

Binding

Binding is a developer-initiated intention (using cf bind-service) to make a service instance available to a specific application, and it usually has side effects (such as creating new credentials for an application to access a database). Like provisioning, the developer makes an API call to the Cloud Controller including the instance ID and app ID to be bound, and the Cloud Controller makes an API call to the broker including just the service instance ID (brokers don’t know about apps).

The broker must then create a binding, if possible, and respond with both a GWID and credentials. For services where there is only 1 set of credentials to a logical resource, binding can simply return the same credentials to each application, though it will be impossible to properly revoke access to an application during unbind.

To bind, the Cloud Controller sends a bind request to the broker. The full request URL is determined by concatenating the URL in the catalog + the path below. For legacy reasons, a binding is known as a “handle” on the broker side.

POST /gateway/v1/configurations/:service_id/handles

Brokers should respond with 200 OK and a JSON response body containing fields from the table below. The Cloud Controller will interpret any non-2xx response codes as a failure to bind. Asterisks denote required fields.

Unbinding

Simply the opposite of bind, unbind is the developer-initiated intention to revoke a specific application’s access to a service instance. The developer makes an API call to the Cloud Controller, which makes an API call to the broker including the GWID of the binding that should be destroyed. If possible, the bound credentials should be destroyed so that application can no longer access the resource.

To delete a binding, the Cloud Controller sends an unbind request to the broker. The full request URL is determined by concatenating the URL in the catalog + the path below.

DELETE /gateway/v1/configurations/:service_id/handles/:handle_id

• Note: the service_id and handle_id exist in both the URL and BODY, see table:

Brokers should respond with 200 OK and a body that is null or {}. vcap-services-base returns {}. The Cloud Controller will interpret any non-2xx response codes as a failure and will not delete the binding from its database. The Cloud Controller ignores contents of JSON bodies.

Deprovisioning

Simply the opposite of provision, deprovision is the developer-initiated intention to remove a specific service instance. The developer makes an API call to the Cloud Controller, which makes an API call to the broker including the GWID of the instance that should be destroyed. The resources consumed by the service instance should be released, and hopefully made available to future requests.

To delete a service instance, the Cloud Controller sends a deprovision request to the broker. The full request URL is determined by concatenating the URL in the catalog + the path below.

DELETE /gateway/v1/configurations/:service_id

• No body
• No query parameters

The only argument, service_id, is the broker service_id that was returned from the provision response. The Cloud Controller deprovision request contains no body.

Brokers should respond with 200 OK and a body that is null or {}. vcap-services-base returns {}. The Cloud Controller interprets any non-2xx response codes as a failure and will not delete the instance from its database. The Cloud Controller ignores contents of JSON bodies.

Orphan Detection and Cleanup

The Cloud Controller is the source of truth, and the broker and the Cloud Controller can end up disagreeing about which services and binding exist. In this case, the broker is responsible for removing the bindings and instances that don’t exist anymore in the Cloud Controller. There are the Cloud Controller endpoints for getting a list of bindings and instances, and the broker should use these to find orphans and prune them.