Service Instances

Service brokers are responsible for provisioning the services advertised in their catalog and managing their lifecycle in the underlying cloud platform. The services created by the broker are referred to as service instances.

Service brokers must implement the {scosb-api-services}ServiceInstanceService.html[ServiceInstanceService] interface and provide implementations of the required methods of that interface. Each method receives a single Java object parameter containing all details of the request from the platform and returns a Java object value providing details of the operation to the platform.

The service instance create, update, and delete operations can be performed synchronously or asynchronously.

  • When a service broker creates, updates, or deletes a service instance synchronously, the appropriate interface method should block and only return a response to the platform when the operation completes successfully or when a failure occurs.

  • When performing an operation asynchronously, the service broker can return a response to the platform before the operation is complete and indicate in the response that the operation is in progress. The platform polls the service broker to get the status of the operation when an asynchronous operation is indicated.

Service Instance Creation

The service broker must provide an implementation of the {scosb-api-services}ServiceInstanceService.html#createServiceInstance-org.springframework.cloud.servicebroker.model.instance.CreateServiceInstanceRequest-[createServiceInstance()].

Service brokers typically provision a resource in the platform or in another system when creating a service instance. Service brokers are responsible for keeping track of any resources associated with a service instance for future retrieval, updating, or deletion.

Service Instance Updating

If the plan_updateable field is set to true in the services catalog, the service broker must provide an implementation of the {scosb-api-services}ServiceInstanceService.html#updateServiceInstance-org.springframework.cloud.servicebroker.model.instance.UpdateServiceInstanceRequest-[updateServiceInstance()]. Otherwise, this method is never called by the platform, and the default implementation in the interface can be used.

Services brokers can modify the configuration of an existing resource when updating a service instance or deploying a new resource.

Service Instance Deletion

An implementation of the {scosb-api-services}ServiceInstanceService.html#deleteServiceInstance-org.springframework.cloud.servicebroker.model.instance.DeleteServiceInstanceRequest-[deleteServiceInstance()] method must be provided by the service broker.

Any resources provisioned in the create operation should be deprovisioned by the delete operation.

Service Instance Operation Status Retrieval

If any create, update, or delete operation can return an asynchronous “operation in progress” response to the platform, the service broker must provide an implementation of the {scosb-api-services}ServiceInstanceService.html#getLastOperation-org.springframework.cloud.servicebroker.model.instance.GetLastServiceOperationRequest-[getLastOperation()]. Otherwise, this method is never called by the platform, and the default implementation in the interface can be used.

The platform polls this method of the service broker for a service instance that has an asynchronous operation in progress until the service broker indicates that the operation has completed successfully or a failure has occurred.

Service Instance Retrieval

If the instances_retrievable field is set to true in the services catalog, the service broker must provide an implementation of the {scosb-api-services}ServiceInstanceService.html#getServiceInstance-org.springframework.cloud.servicebroker.model.instance.GetServiceInstanceRequest-[getServiceInstance()]. Otherwise, this method is never called by the platform, and the default implementation in the interface can be used.

Service brokers are responsible for maintaining any service instance state necessary to support the retrieval operation.

Example Implementation

The following example shows a service instance implementation:

Unresolved directive in service-instances.adoc - include::{examples-dir}/ExampleServiceInstanceService.java[]