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 Tanzu Operations Manager and making them available to end users, see Services.
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.
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
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.
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",
...
}
]
}
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.
For details on consuming credentials specific to your development framework, refer to the Service Binding section in the documentation for your framework’s buildpack.
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.
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.
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
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.