Creating a Service Release using On-Demand Services SDK

This topic for service authors tells you about how you can create a service release for an on-demand service tile using On-Demand Services SDK.

Service Author deliverables

Service authors provide the following:

• The Service Release. For more information, see Overview below.

• The Service Adapter. For more information, see Creating a Service Adapter.

• Documentation for the operator to configure plan definitions for the Service Adapter.

• Documentation for the operator to backup and restore service instances.

Overview

A service release is a BOSH release of the service that you want to create on-demand instances of. The on-demand broker (ODB) deploys this release at instance creation time, once for each service instance.

To create a service release, VMware recommends that you do the following:

1. Package an Initial Service Release

2. Refine your release using the information in the following sections:

   • Use Job Links
   • Service Instance Lifecycle Errands

3. Package the Final Service Release

Package an Initial Service Release

Package an initial version of the BOSH release for your service to test whether it deploys successfully.

To do so, create and manually deploy a BOSH release for the service by following the instructions up to and including Step 6: Create a Dev Release in Creating a Release in the BOSH Documentation.

Note VMware recommends that you create sample manifests that deploy the service release(s). This helps you to write the generate-manifest component of the service adapter. For help writing a sample manifest, see Deployment Config in the BOSH documentation.

Example service releases:

• redis-example-service-release
• kafka-example-service-release

Use Job Links

When there are multiple jobs in the manifest that need to communicate over the network, VMware recommends that you use BOSH’s job link feature instead of using static IP addresses. IP addresses must be different for each service instance. When you use job links, BOSH inserts IP addresses or internal DNS names when templating the job configuration so you do not have to do it manually.

Job links are defined in the service release and configured in the manifest. For how to use job links, see Links in the BOSH documentation.

For an example, see the kafka-example-service-release on GitHub. The example uses implicit job links to get the IP addresses of the brokers and the zookeeper.

Service Instance Lifecycle Errands

Note This feature requires BOSH Director v261 or later.

Service instance lifecycle errands allow additional short-lived jobs to run as part of service instance deployment. ODB uses these errands to manage an instance lifecycle. A deployment is only considered successful if the deployment and all lifecycle errands complete successfully.

ODB supports the following service instance lifecycle errands:

• Post-deploy: These errands run after creating or updating a service instance. For example, running a health check to ensure the service instance is functioning. To see the workflow for post deploy errands, see Create or Update Service Instance with Post-Deploy Errands.
  
  
• Pre-delete: These errands run before the deletion of a service instance. For example, cleaning up data before a service shutdown. To see the workflow for pre-delete errands, see Delete a Service Instance with Pre-Delete Errand.

For information for operators about how to enable these errands in the manifest, see Enable Service Instance Lifecycle Errands.

Include Service Instance Lifecycle Errands

Lifecycle errands are defined in the service release. The service adapter or operator can configure these errands when generating a manifest.

To include lifecycle errands in your service release, do the following:

1. Decide what errands your on-demand service needs. For example, you could create a health check post-deploy errand using the criteria that you used to test the initial release.

2. Write code to run each lifecycle errand and define them as jobs in the service release. For how to do so, see the Using Errands in the BOSH documentation.

For an example implementation of a health check post-deploy errand, see the redis-example-service-release on GitHub.

Note When using the service adapter generate-manifest command, you must validate that any lifecycle errands configured in the plan parameter exist in the service release and are included in the service manifest as jobs. For more information about the generate manifest command, see generate-manifest.

Colocated Errands

Note This feature requires BOSH Director v263 or later.

Colocated errands run on an existing service instance group, avoiding additional resource allocation. Both post-deploy and pre-delete errands can be run as colocated errands.

To enable a new colocated errand, add the errand to the list of jobs of an instance group.

Package the Final Service Release

To package the final release, follow the instructions in Create a Final Release in the BOSH documentation.

The tile author packages this release into the tile. For direct BOSH deployments, an operator uploads this release to the BOSH Director.