Binding Applications to Service Instances

Page last updated: October 15, 2015

This page assumes you are using cf CLI v6.

This topic describes binding applications to service instances for the purpose of generating credentials and delivering them to applications. For an overview of services, and documentation on other service management operations, see Using Services. If you are interested in building Services for Cloud Foundry and making them available to end users, see the Custom Services documentation.

Bind a Service Instance

Binding a service instance to your application triggers credentials to be provisioned for the service instance and delivered to the application runtime in the VCAP_SERVICES environment variable. For details on consuming these credentials with your application, see Using Bound Service Instances.

Not all services support binding, as some services deliver value to users directly without integration with an application. In many cases binding credentials are unique to an application, and another app bound to the same service instance would receive different credentials; however this depends on the service.

$ cf bind-service my-app mydb
Binding service mydb to my-app in org my-org / space test as [email protected]...
OK
TIP: Use 'cf push' to ensure your env variable changes take effect

$ cf restart my-app

Note: You must restart or in some cases re-push your application for changes to be applied to the VCAP_SERVICES environment variable and for the application to recognize these changes.

Arbitrary Parameters

Arbitrary parameters require cf CLI v6.12.1+

Some services support additional configuration parameters with the bind request. These parameters are passed in a valid JSON object containing service-specific configuration parameters, provided either in-line or in a file. For a list of supported configuration parameters, see documentation for the particular service offering.

$ cf bind-service rails-sample my-db -c '{"role":"read-only"}'

Binding service my-db to app rails-sample in org console / space development as [email protected]...
OK

$ cf bind-service rails-sample my-db -c /tmp/config.json

Binding service my-db to app rails-sample in org console / space development as [email protected]... OK

Binding with Application Manifest

As an alternative to binding a service instance after pushing an application, you can use the application manifest to bind the service instance during push. As of cf CLI v6.12.1, Arbitrary Parameters are not supported in application manifests.

The following excerpt from an application manifest would bind a service instance called test-mysql-01 to the application on push.

services:
 - test-mysql-01

The following excerpt from the cf push command and response demonstrates that the cf CLI reads the manifest and binds the service instance to an app called test-msg-app.

$ cf push
Using manifest file /Users/Bob/test-apps/test-msg-app/manifest.yml

...

Binding service test-mysql-01 to test-msg-app in org My-Org / space development as [email protected]
OK

For more information about application manifests, see Deploying with Application Manifests.

Using Bound Service Instances

Once you have a service instance created and bound to your application, you need to configure the application to dynamically fetch the credentials for your service instance. The VCAP_SERVICES environment variable contains credentials and additional metadata for all bound service instances. There are two methods developers can leverage to have their applications consume binding credentials.

Parse the JSON yourself: See the documentation for VCAP_SERVICES. Helper libraries are available for some frameworks.
Auto-configuration: Some buildpacks create a service connection for you by creating additional environment variables, updating config files, or passing system parameters to the JVM.

For details on consuming credentials specific to your development framework, refer to the Service Binding section in the documentation for your framework’s buildpack.

Update Service Credentials

To update your service credentials, perform the following steps:

Unbind the service instance using the credentials you are updating with the following command:
```
$ cf unbind-service YOUR-APP YOUR-SERVICE-INSTANCE
```
Bind the service instance with the following command. This adds your credentials to the VCAP_SERVICES environment variable.
```
$ cf bind-service YOUR-APP YOUR-SERVICE-INSTANCE
```
Restart or re-push the application bound to the service instance so that the application recognizes your environment variable updates.

Unbind a Service Instance

Unbinding a service removes the credentials created for your application from the VCAP_SERVICES environment variable.

$ cf unbind-service my-app mydb
Unbinding app my-app from service mydb in org my-org / space test as [email protected]...
OK

Note: You must restart or in some cases re-push your application for changes to be applied to the VCAP_SERVICES environment variable and for the application to recognize these changes.