Delivering service credentials to an app

You will learn how to bind your apps to service instances for the purpose of generating credentials and delivering them to apps. For an overview of services, and documentation on other service management operations, see Using Services. If you are interested in building services for Ops Manager and making them available to end users, see Services.

Bind a Service Instance

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

Not all services support binding, as some services deliver value to users directly without integration with an app. In many cases binding credentials are unique to an app, 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

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

Arbitrary Parameters

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.

See the following examples:

$ 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 App Manifest

As an alternative to binding a service instance after pushing an app, you can use the app manifest to bind the service instance during cf push.

The following excerpt from an app manifest binds a service instance called test-mysql-01 to the app on push.

services:
 - test-mysql-01

The following excerpt from an app manifest binds a service instance called db-test with arbitrary parameters to the app on push.

Note Arbitrary parameters are supported in app manifests in cf CLI v7.0 and later.

services:
  - name: db-test
    parameters:
      schema: customschema

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 app manifests, see Deploying with App Manifests.

Named Service Bindings

Service offering and service instance names vary across environments. App authors can discover the service instances their apps require, without having to know environment-specific service names. Developers can specify a service binding name to be included in VCAP_SERVICES.

To specify the service binding name, provide the --binding-name flag when binding an app to a service instance:

$ cf bind-service my-app my-service --binding-name postgres-database
OK

The provided name will be available in the name and binding_name properties in the VCAP_SERVICES environment variable:

"VCAP_SERVICES": {
  "service-name": [
    {
      "name": "postgres-database",
      "binding_name": "postgres-database",
      ...
    }
  ]
}

Using Bound Service Instances

Once you have a service instance created and bound to your app, you need to configure the app 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 apps 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

This section describes how to update service instance credentials. When updating the credentials, you can restage the app immediately and experience app downtime. If your app uses blue-green deployment, you can update service instance credentials with no downtime.

For more information about user-provided services, see Update a User-provided Service Instance in User-Provided Service Instances.

With Downtime

To update your service credentials:

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 app bound to the service instance so that the app recognizes your environment variable updates.

Without Downtime

To update your service credentials without experiencing app downtime:

Start a blue-green update of the app. For more information, see Using Blue-Green Deployment to Reduce Downtime and Risk. Push the “Green” version of the app with the --no-start parameter to prevent the app from starting right away:
```
$ cf push YOUR-APP --no-start
```
Bind the service instances to the newly-deployed “Green” app with the following command:
```
$ cf bind-service YOUR-APP YOUR-SERVICE-INSTANCE
```
Start the “Green” app with cf start:
```
$ cf start YOUR-APP
```

Unbind the service instances from the Blue app:

$ cf unbind-service YOUR-APP YOUR-SERVICE-INSTANCE

Unbind a Service Instance

Unbinding a service removes the credentials created for your app 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

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