Saikat

Notes on Open Service Broker

Open Service Broker (OSB)

What is it?

The Open Service Broker API allows independent software vendors, SaaS providers, and developers to easily provide backing services to workloads running on cloud-native platforms such as Cloud Foundry and Kubernetes.

The specification describes a simple set of API endpoints which can be used to provision, gain access to, and manage service offerings. It connects developers to a global ecosystem of services. Many platforms and thousands of service providers have adopted the specification.

Benefits

  • For Developers: A consistent way to connect applications to backing services, regardless of the service type or vendor. The operation is the same.

  • For Operators: This feature enables configuring a marketplace for developer self-service, reducing administrative overhead compared to manually provisioning and delegating access.

  • For Service Providers: A standard interface to offer services to a wide range of cloud native platforms.

Key Concepts & Participants

  • Platform: The software that will manage the cloud environment into which applications are provisioned and Service Brokers are registered. Users will not directly provision Services from Service Brokers, rather they will ask the Platform to manage Services and interact with the Service Brokers for them.

  • Service Broker: Service Brokers manage the lifecycle of Services. Platforms interact with Service Brokers to provision, get access to, and manage the services they offer.

  • Service: A managed software offering that can be used by an application.

  • Service Offering: The advertisement of a Service that a Service Broker supports.

  • Service Plan: The representation of the costs and benefits for a given variant of the Service Offering, potentially as a tier. Plans typically represent costs and benefits or ‘T-Shirt size’ the offering.

  • Service Instance: An instantiation of a Service Offering and Service Plan. Provisioning a new service instance reserves a resource on a service. Examples include a single database or an account on a web application.

  • Service Binding: Represents the request to use a Service Instance. Creation of a Service Binding either generates credentials necessary for accessing the resource or provides the Service Instance with information for a configuration change. Service Bindings will often contain the credentials that can then be used to communicate with the Service Instance.

Core Lifecycle Operations (API Endpoints)

Platforms interact with Service Brokers via HTTP(S) using a standard set of commands:

  • Fetching the catalog: Platforms fetch /v2/catalog to discover available Service Offerings and their Plans. Each Service Offering and Service Plan has an immutable id and a name. Platforms use the ID to identify resources across queries.

  • Provisioning: Creating a new Service Instance (PUT /v2/service_instances/:instance_id). The Broker takes action to create a new resource based on the requested Service Offering and Plan.

  • Updating: Modifying an existing Service Instance (PATCH /v2/service_instances/:instance_id). This can involve changing the Service Plan (if plan_updateable: true in the catalog) or modifying parameters.

  • Binding: Connecting an application to a Service Instance (PUT /v2/service_instances/:instance_id/service_bindings/:binding_id). This typically generates credentials or configuration needed for the application to connect. Supported if bindable: true in the catalog.

  • Unbinding: Disconnecting an application (DELETE /v2/service_instances/:instance_id/service_bindings/:binding_id). Deletes resources associated with the binding.

  • Deprovisioning: Deleting a Service Instance (DELETE /v2/service_instances/:instance_id). Deletes resources created during provisioning. Platforms MUST delete all Service Bindings for a Service Instance prior to attempting to deprovision it.

Synchronous vs. Asynchronous Operations

Service Brokers can execute operations either synchronously (complete by response) or asynchronously (in progress).

  • Synchronous: Operation completed when the Broker returns a successful response (200 OK, 201 Created).

  • Asynchronous: Operation is still in progress when the Broker responds (202 Accepted). Requires the Platform to include the query parameter ?accepts_incomplete=true. If asynchronous is required but the parameter is missing, the Broker MUST reject the request with 422 Unprocessable Entity and error code "AsyncRequired". A 202 Accepted response triggers the Platform to poll the last_operation endpoint for the Service Instance or Service Binding to check the status. Polling continues until the Broker indicates the operation is complete ("state": "succeeded" or "state": "failed").

Fundamental API Requirements

  • All requests from the Platform to the Service Broker MUST include the X-Broker-API-Version header.
  • Platforms SHOULD NOT reuse IDs for Service Instances and Service Bindings.
  • Communication between Platforms and Service Brokers is RECOMMENDED to be secured via TLS and authenticated. Unless otherwise agreed, HTTP basic authentication MUST be used.
  • Service Brokers MUST return appropriate HTTP status codes for success and failure. Specific error codes like "AsyncRequired" or "ConcurrencyError" are defined for certain failure scenarios.