How On-Demand Services Process Commands

The sequence diagrams in this topic show how an on-demand service sets up and maintains service instances. The diagrams indicate which tasks are undertaken by the on-demand broker (ODB) and which require interaction with the Service Adapter.

Register the Service Broker with Cloud Foundry

The sequence diagram below shows the workflow for registering a service broker with Cloud Foundry.

sequenceDiagram User->>Cloud Controller:cf create-service-broker Cloud Controller->>On Demand Broker:GET catalog On Demand Broker->>Cloud Controller:catalog Cloud Controller->>User:OK

About Creating and Updating Service Instances

This section contains diagrams that present the workflow for the following actions:

Create a Service Instance

To create a service instance, users run the cf create-service command. For more information about this command, see Creating Service Instances.

The sequence diagram below shows the workflow for creating a service instance.

sequenceDiagram User->> Cloud Controller: cf create-service Cloud Controller->> On Demand Broker: POST instance (provision) On Demand Broker->>Service Adapter: generate-manifest Service Adapter->>On Demand Broker: manifest + secrets + BOSH configs opt Secure Manifests enabled On Demand Broker->>BOSH CredHub: store secrets On Demand Broker->>On Demand Broker: update manifest with CredHub names end opt BOSH configs enabled On Demand Broker->>BOSH: update configs end On Demand Broker->>BOSH: deploy BOSH->>On Demand Broker: accepted On Demand Broker->>Cloud Controller: accepted Cloud Controller->>User: create in progress loop until bosh task is complete Cloud Controller->>On Demand Broker: GET last operation On Demand Broker->>BOSH: GET deploy task BOSH->>On Demand Broker: task in progress On Demand Broker->>Cloud Controller: create in progress end Cloud Controller->>On Demand Broker: GET last operation On Demand Broker->>BOSH: GET task BOSH->>On Demand Broker: task done On Demand Broker->>Cloud Controller: create succeeded User->>Cloud Controller:cf service Cloud Controller->>User: create succeeded


There are two ways this process can fail:

  • Synchronously: The Cloud Controller deletes the service according to its orphan mitigation strategy. For more information, see Orphans.

  • Asynchronously: This happens while BOSH deploys the service instance. The Cloud Controller does not issue a delete request.

Update a Service Instance

To update a service instance, users run the cf update-service command. For more information about this command, see Update a Service Instance.

Updates can only proceed if the existing service instance is up-to-date. ODB calls generate-manifest on the service adapter to determine whether there are any pending changes for the instance.

Note: When determining whether there are pending changes for an instance during an update, ODB ignores any configuration supplied in the update block of the manifest returned by the service adapter’s generate-manifest subcommand. For more information, see Update Block in the Cloud Foundry BOSH documentation.

Update When There Are No Pending Changes

If there are no pending changes, the update proceeds. The manifest from the second call to generate-manifest is deployed.

The sequence diagram below shows the workflow for updating a service instance if there are no pending changes.

sequenceDiagram User->> Cloud Controller: cf update-service -c ’{“some”:“prop”}’ Cloud Controller->> On Demand Broker: PATCH instance (update) On Demand Broker->>BOSH:GET manifest BOSH->>On Demand Broker:previous manifest opt Secure Manifests enabled On Demand Broker->>BOSH CredHub: GET previous secrets BOSH CredHub->>On Demand Broker: secrets end opt BOSH configs enabled On Demand Broker->>BOSH:GET previous configs end On Demand Broker->>Service Adapter: generate-manifest (without PATCH options) Service Adapter->>On Demand Broker: manifest On Demand Broker->>On Demand Broker: check for pending changes On Demand Broker->>Service Adapter: generate-manifest (with PATCH options) Service Adapter->>On Demand Broker: manifest + secrets + BOSH configs opt Secure Manifests enabled On Demand Broker->>BOSH CredHub: store secrets On Demand Broker->>On Demand Broker: update manifest with CredHub names end opt BOSH configs enabled On Demand Broker->>BOSH: update configs end On Demand Broker->>BOSH: deploy BOSH->>On Demand Broker: accepted On Demand Broker->>Cloud Controller: accepted Cloud Controller->>User: update in progress loop until bosh task is complete Cloud Controller->>On Demand Broker:GET last operation On Demand Broker->>BOSH:GET task BOSH->>On Demand Broker:task in progress On Demand Broker->>Cloud Controller:update in progress end Cloud Controller->>On Demand Broker:GET last operation On Demand Broker->>BOSH:GET task BOSH->>On Demand Broker:task done On Demand Broker->>Cloud Controller:update succeeded User->>Cloud Controller: cf service Cloud Controller->>User: update succeeded

Update When There Are Pending Changes

If there are pending changes, the update fails.

The sequence diagram below shows the workflow for updating a service instance if there are pending changes.

sequenceDiagram User->> Cloud Controller: cf update-service -c ’{“some”:“config”}’ Cloud Controller->> On Demand Broker: PATCH instance (update) On Demand Broker->>BOSH:GET manifest BOSH->>On Demand Broker:previous manifest On Demand Broker->>Service Adapter: generate-manifest (without request parameters) Service Adapter->>On Demand Broker: manifest On Demand Broker->>On Demand Broker: check for pending changes On Demand Broker->>Cloud Controller: update failed, pending changes detected Cloud Controller->>User: update failed, pending changes detected

Create or Update a Service Instance with Post-Deploy Errands

If a user runs the cf create-service command with post-deploy errands configured for the deployment, ODB does not report success to Cloud Foundry until the deployment is created, or updated, and all post-deploy errands complete. For more information about post-deploy errands, see Service Instance Lifecycle Errands.

The sequence diagram below shows the workflow for creating or updating a service instance when post-deploy errands are configured.

sequenceDiagram User->> Cloud Controller: cf create-service Cloud Controller->> On Demand Broker: POST instance (create) On Demand Broker->>Service Adapter: generate-manifest Service Adapter->>On Demand Broker: manifest + secrets + BOSH configs opt Secure Manifests enabled On Demand Broker->>BOSH CredHub: store secrets On Demand Broker->>On Demand Broker: update manifest with CredHub names end opt BOSH configs enabled On Demand Broker->>BOSH: update configs end On Demand Broker->>BOSH: deploy BOSH->>On Demand Broker: accepted On Demand Broker->>Cloud Controller: accepted Cloud Controller->>User: create in progress loop while bosh deployment is in progress Cloud Controller->>On Demand Broker: GET last operation On Demand Broker->>BOSH: GET deploy task BOSH->>On Demand Broker: task in progress On Demand Broker->>Cloud Controller: create in progress end loop until there are no more post-deploy errands to run Cloud Controller->>On Demand Broker: GET last operation On Demand Broker->>BOSH: run next post-deploy errand BOSH->>On Demand Broker: accepted On Demand Broker->>Cloud Controller:create in progress loop while bosh task errand is in progress Cloud Controller->>On Demand Broker:GET last operation On Demand Broker->>BOSH:GET errand task BOSH->>On Demand Broker:task in progress On Demand Broker->>Cloud Controller:create in progress end end Cloud Controller->>On Demand Broker:GET last operation On Demand Broker->>BOSH:GET final errand task BOSH->>On Demand Broker:task done On Demand Broker->>Cloud Controller:create succeeded User->>Cloud Controller:cf service Cloud Controller->>User: create succeeded

Recreate All Service Instances

ODB provides the BOSH errand recreate-all-service-instances. This errand executes a bosh -d DEPLOYMENT-NAME recreate --fix on each service instance (SI) managed by the broker. It is used for triggering low-level BOSH agent certificate re-installation, or for backup and restore purposes, for example in a migration between foundations.

The sequence diagram below shows the workflow for re-creating service instances.

sequenceDiagram Operator->>Recreate Errand:bosh run errand recreate-all-service-instances Recreate Errand->>On Demand Broker:GET instances On Demand Broker->>CC / SI API:GET instances CC / SI API->>On Demand Broker:instances On Demand Broker->>Recreate Errand:instances loop for all instances Recreate Errand->>On Demand Broker: PATCH instance (recreate) On Demand Broker->>BOSH: recreate –fix BOSH->>On Demand Broker: accepted On Demand Broker->>Recreate Errand: accepted loop while bosh recreate task is in progress Recreate Errand->>On Demand Broker: GET last operation On Demand Broker->>BOSH: GET recreate task BOSH->>On Demand Broker: task in progress On Demand Broker->>Recreate Errand: recreate in progress end loop until there are no more post-deploy errands to run Recreate Errand->>On Demand Broker: GET last operation On Demand Broker->>BOSH: GET last task status BOSH->>On Demand Broker: task done On Demand Broker->>BOSH: run next post-deploy errand BOSH->>On Demand Broker: accepted On Demand Broker->>Recreate Errand:errand in progress end Recreate Errand->>On Demand Broker: GET last operation On Demand Broker->>BOSH: GET last task status BOSH->>On Demand Broker: task done On Demand Broker->>Recreate Errand: recreate succeeded end Recreate Errand->>Operator:completed successfully

About Upgrading Service Instances

This section contains diagrams that present the workflow for the following actions:

Upgrade All Service Instances

ODB provides the BOSH errand upgrade-all-service-instances. This errand upgrades all service instances managed by the broker. This is also used when a plan changes. The errand updates all instances that implement a plan with the new plan definition. For more information, see Upgrade All Service Instances.

The sequence diagram below shows the workflow for upgrading all service instances.

sequenceDiagram Operator->>Upgrade Errand:bosh run errand upgrade-all-service-instances Upgrade Errand->>On Demand Broker:GET instances On Demand Broker->>Cloud Controller:GET instances Cloud Controller->>On Demand Broker:instances On Demand Broker->>Upgrade Errand:instances loop for all instances Upgrade Errand->>On Demand Broker: PATCH instance (upgrade) On Demand Broker->>Service Adapter: generate-manifest Service Adapter->>On Demand Broker: manifest + secrets + BOSH configs opt Secure Manifests enabled On Demand Broker->>BOSH CredHub: store secrets On Demand Broker->>On Demand Broker: update manifest with CredHub names end opt BOSH configs enabled On Demand Broker->>BOSH: update configs end On Demand Broker->>BOSH: deploy BOSH->>On Demand Broker: accepted On Demand Broker->>Upgrade Errand: accepted Note over Upgrade Errand,BOSH: Upgrade Errand polls On Demand Broker for last operation until complete end Upgrade Errand->>Operator:completed successfully

Upgrade All Service Instances with External Service Instances API Configured

If the service instances API is configured, the upgrade-all-service-instances errand connects to a different endpoint to gather the list of instances to upgrade. For more information, see Service Instances API.

The sequence diagram below shows the workflow for upgrading all service instances with external service instances API configured.

sequenceDiagram Operator->>Upgrade Errand:bosh run errand upgrade-all-service-instances Upgrade Errand->>SI API:GET instances SI API->>Upgrade Errand:Service instances with Plan ID loop for all instances Upgrade Errand->>On Demand Broker: PATCH instance (upgrade) On Demand Broker->>Service Adapter: generate-manifest Service Adapter->>On Demand Broker: manifest On Demand Broker->>BOSH: deploy BOSH->>On Demand Broker: accepted On Demand Broker->>Upgrade Errand: accepted Note over Upgrade Errand,BOSH: Upgrade Errand polls On Demand Broker for last operation until complete end Upgrade Errand->>Operator:completed successfully

Upgrade All Service Instances with Maintenance Information Configured

If Cloud Foundry supports maintenance information and it is supplied in the ODB configuration, the upgrade-all-service-instances errand coordinates with Cloud Foundry to update only service instances that are outdated. If a service instance has already been upgraded successfully, then the errand has no effect on that service instance.

The sequence diagram below shows the workflow for upgrading all service instances when maintenance information is configured.

sequenceDiagram Operator->>Upgrade Errand:bosh run errand upgrade-all-service-instances Upgrade Errand->>On Demand Broker:GET instances On Demand Broker->>Cloud Controller:GET instances Cloud Controller->>On Demand Broker:instances On Demand Broker->>Upgrade Errand:instances loop for each instance to do CF upgrade Upgrade Errand->>Cloud Controller: PUT service_instance (upgrade) alt Cloud Controller version matches broker version for instance Cloud Controller->>Upgrade Errand: Success else Cloud Controller version differs from broker version for instance Cloud Controller->>On Demand Broker: PATCH instance (upgrade) On Demand Broker->>Service Adapter: generate-manifest Service Adapter->>On Demand Broker: manifest On Demand Broker->>BOSH: deploy BOSH->>On Demand Broker: accepted On Demand Broker->>Cloud Controller: accepted Cloud Controller->>Upgrade Errand: accepted Note over Upgrade Errand,BOSH: Upgrade Errand polls Cloud Controller until complete end end loop for each instance to do BOSH upgrade Upgrade Errand->>On Demand Broker: PATCH instance (upgrade) On Demand Broker->>Service Adapter: generate-manifest Service Adapter->>On Demand Broker: manifest On Demand Broker->>BOSH: deploy BOSH->>On Demand Broker: accepted On Demand Broker->>Upgrade Errand: accepted Note over Upgrade Errand,BOSH: Upgrade Errand polls On Demand Broker for last operation until complete end Upgrade Errand->>Operator:completed successfully

Upgrade One Service Instance with Maintenance Information Configured

If Cloud Foundry supports maintenance information and it is supplied in the ODB configuration, a user can trigger a single upgrade by running cf update-service SERVICE_NAME --upgrade.

The sequence diagram below shows the workflow for upgrading one service instance when maintenance information is configured.

sequenceDiagram User->>Cloud Controller:cf update-service –upgrade Cloud Controller->>On Demand Broker: PATCH instance (upgrade) On Demand Broker->>Service Adapter: generate-manifest Service Adapter->>On Demand Broker: manifest On Demand Broker->>BOSH: deploy BOSH->>On Demand Broker: accepted On Demand Broker->>Cloud Controller: accepted Cloud Controller->>User: accepted Note over User, Cloud Controller: user can poll Cloud Controller until complete

About Binding and Unbinding Service Instances

This section contains diagrams that present the workflow for the following actions:

Bind a Service Instance

To bind a service instance, users run the cf bind-service command. For more information about this command, see Bind a Service Instance.

The sequence diagram below shows the workflow for creating a binding.

sequenceDiagram User->>Cloud Controller:cf bind-service Cloud Controller->>On Demand Broker:PUT binding alt Secure Manifests enabled On Demand Broker->>BOSH CredHub:request secrets BOSH CredHub->>On Demand Broker:secrets On Demand Broker->>Service Adapter:create-binding with secrets else Secure Manifests disabled On Demand Broker->>Service Adapter:create-binding end Service Adapter->>On Demand Broker:binding credentials alt Secure Binding enabled On Demand Broker->>Runtime CredHub:Store credentials with ACLs for app On Demand Broker->>Cloud Controller:runtime CredHub reference else Secure Binding disabled On Demand Broker->>Cloud Controller:binding credentials end Cloud Controller->>User:OK

Unbind a Service Instance

To unbind a service instance, users run the cf unbind-service command. For more information about this command, see Unbind a Service Instance.

The sequence diagram below shows the workflow for unbinding a service instance.

sequenceDiagram User->>Cloud Controller:cf unbind-service Cloud Controller->>On Demand Broker:DELETE binding alt Secure Manifests enabled On Demand Broker->>BOSH CredHub:request secrets BOSH CredHub->>On Demand Broker:secrets On Demand Broker->>Service Adapter:delete-binding with secrets else Secure Manifests disabled On Demand Broker->>Service Adapter:delete-binding end Service Adapter->>On Demand Broker:exit 0 opt Secure Binding enabled On Demand Broker->>Runtime CredHub:Delete credentials Runtime CredHub->>On Demand Broker:OK end On Demand Broker->>Cloud Controller:OK Cloud Controller->>User:OK

About Deleting Service Instances

This section contains diagrams that present the workflow for the following actions:

Delete a Service Instance

To delete a service instance, users run the cf delete-service command. For more information about this command, see Delete a Service Instance.

The service adapter is not invoked in the delete service workflow.

The sequence diagram below shows the workflow for deleting service instances.

sequenceDiagram User->>Cloud Controller:cf delete-service Cloud Controller->>On Demand Broker:DELETE instance On Demand Broker->>BOSH:delete deployment BOSH->>On Demand Broker:accepted On Demand Broker->>Cloud Controller:accepted Cloud Controller->>User: delete in progress loop until bosh task is complete Cloud Controller->>On Demand Broker: GET last operation On Demand Broker->>BOSH: GET task BOSH->>On Demand Broker: task in progress On Demand Broker->>Cloud Controller: delete in progress end Cloud Controller->>On Demand Broker: GET last operation On Demand Broker->>BOSH: GET task BOSH->>On Demand Broker: task done opt Secure Manifests enabled On Demand Broker->>BOSH CredHub: DELETE ODB-managed secrets BOSH CredHub->>On Demand Broker: delete secrets succeeded end opt BOSH configs enabled On Demand Broker->>BOSH: delete configs end On Demand Broker->>Cloud Controller: delete succeeded User->>Cloud Controller:cf service Cloud Controller->>User: not found

Delete a Service Instance with Pre-Delete Errands

If a user runs the cf delete-service command with pre-delete errands configured for the deployment, ODB does not report success to Cloud Foundry until all pre-delete errands complete and the deployment is deleted. For more information about pre-delete errands, see Service Instance Lifecycle Errands.

The sequence diagram below shows the workflow for deleting service instances with pre-delete errands configured.

sequenceDiagram User->>Cloud Controller:cf delete-service Cloud Controller->>On Demand Broker:DELETE instance On Demand Broker->>BOSH:run first pre-delete errand BOSH->>On Demand Broker:accepted On Demand Broker->>Cloud Controller:accepted Cloud Controller->>User: delete in progress loop while the errand is in progress Cloud Controller->>On Demand Broker:GET last operation On Demand Broker->>BOSH:GET first errand task BOSH->>On Demand Broker:task in progress On Demand Broker->>Cloud Controller:delete in progress end loop until there are no more pre-delete errands to run Cloud Controller->>On Demand Broker:GET last operation On Demand Broker->>BOSH: run next pre-delete errand BOSH->>On Demand Broker:accepted On Demand Broker->>Cloud Controller:delete in progress loop while the errand is in progress Cloud Controller->>On Demand Broker: GET last operation On Demand Broker->>BOSH: GET errand task BOSH->>On Demand Broker: task in progress On Demand Broker->>Cloud Controller: delete in progress end end Cloud Controller->>On Demand Broker: GET last operation On Demand Broker->>BOSH: run delete-deployment BOSH->>On Demand Broker: task in progress On Demand Broker->>Cloud Controller: delete in progress loop while delete deployment bosh task is in progress Cloud Controller->>On Demand Broker: GET last operation On Demand Broker->>BOSH: GET delete deployment task BOSH->>On Demand Broker: task in progress On Demand Broker->>Cloud Controller: delete in progress end Cloud Controller->>On Demand Broker: GET last operation On Demand Broker->>BOSH: GET delete deployment task BOSH->>On Demand Broker: task done opt Secure Manifests enabled On Demand Broker->>BOSH CredHub: DELETE ODB-managed secrets BOSH CredHub->>On Demand Broker: delete secrets succeeded end opt BOSH configs enabled On Demand Broker->>BOSH: delete configs end On Demand Broker->>Cloud Controller: delete succeeded User->>Cloud Controller:cf service Cloud Controller->>User: not found

Delete All Service Instances

ODB provides the BOSH errand delete-all-service-instances. This errand deletes all service instances managed by the broker. For how to use this errand, see Delete All Service Instances.

The sequence diagram below shows the workflow for deleting all service instances.

sequenceDiagram Operator->>Delete Errand:bosh run errand delete-all-service-instances Delete Errand->>Cloud Controller:GET instances Cloud Controller->>Delete Errand:instances loop for all instances Delete Errand->>Cloud Controller:GET bindings Cloud Controller->>Delete Errand:bindings loop for all bindings Delete Errand->>Cloud Controller:cf unbind-service Cloud Controller->>On Demand Broker: DELETE binding On Demand Broker->>Service Adapter:delete-binding Service Adapter->>On Demand Broker:exit code 0 On Demand Broker->>Cloud Controller:OK Cloud Controller->>Delete Errand:OK end Delete Errand->>Cloud Controller:GET service keys Cloud Controller->>Delete Errand:service keys loop for all service keys Delete Errand->>Cloud Controller:cf delete-service-key Cloud Controller->>On Demand Broker: DELETE binding On Demand Broker->>Service Adapter:delete-binding Service Adapter->>On Demand Broker:exit code 0 On Demand Broker->>Cloud Controller:OK Cloud Controller->>Delete Errand:OK end Delete Errand->>Cloud Controller:cf delete-service Cloud Controller->>On Demand Broker:DELETE instance On Demand Broker->>BOSH:delete deployment BOSH->>On Demand Broker:accepted On Demand Broker->>Cloud Controller:accepted Cloud Controller->>Delete Errand:accepted loop until DELETE completes Delete Errand->>Cloud Controller:GET instance Cloud Controller->>Delete Errand:delete instance in progress Note over Cloud Controller,BOSH: The Cloud Controller asynchronously polls ODB, which in turn polls BOSH for last operation status end Delete Errand->>Cloud Controller:GET instance Cloud Controller->>Delete Errand:instance not found end Delete Errand->>Operator:completed successfully

Delete All Service Instances and Deregister Broker

ODB provides the BOSH errand delete-all-service-instances-and-deregister-broker. This errand deletes all service instances managed by the broker and deregisters the broker from Cloud Foundry. For how to use this errand, see Delete All Service Instances and Deregister Broker.

The sequence diagram below shows the workflow for deleting all service instances and deregistering the broker.

sequenceDiagram Operator->>Delete Errand:bosh run errand delete-all-service-instances-and-deregister-broker Delete Errand->>Cloud Controller:POST disable-service-access Cloud Controller->>Delete Errand:completed successfully Delete Errand->>Cloud Controller:GET instances Cloud Controller->>Delete Errand:instances loop for all instances Delete Errand->>Cloud Controller:GET bindings Cloud Controller->>Delete Errand:bindings loop for all bindings Delete Errand->>Cloud Controller:cf unbind-service Cloud Controller->>On Demand Broker: DELETE binding On Demand Broker->>Service Adapter:delete-binding Service Adapter->>On Demand Broker:exit code 0 On Demand Broker->>Cloud Controller:OK Cloud Controller->>Delete Errand:OK end Delete Errand->>Cloud Controller:GET service keys Cloud Controller->>Delete Errand:service keys loop for all service keys Delete Errand->>Cloud Controller:cf delete-service-key Cloud Controller->>On Demand Broker: DELETE binding On Demand Broker->>Service Adapter:delete-binding Service Adapter->>On Demand Broker:exit code 0 On Demand Broker->>Cloud Controller:OK Cloud Controller->>Delete Errand:OK end Delete Errand->>Cloud Controller:cf delete-service Cloud Controller->>On Demand Broker:DELETE instance On Demand Broker->>BOSH:delete deployment BOSH->>On Demand Broker:accepted On Demand Broker->>Cloud Controller:accepted Cloud Controller->>Delete Errand:accepted loop until DELETE completes Delete Errand->>Cloud Controller:GET instance Cloud Controller->>Delete Errand:delete instance in progress Note over Cloud Controller,BOSH: The Cloud Controller asynchronously polls ODB, which in turn polls BOSH for last operation status end Delete Errand->>Cloud Controller:GET instance Cloud Controller->>Delete Errand:instance not found end Delete Errand->>Cloud Controller:DELETE service-broker Cloud Controller->>Delete Errand:completed successfully Delete Errand->>Operator:completed successfully