Delivering service credentials to an app

Page last updated:

You can bind your apps to service instances for the purpose of generating credentials and delivering them to apps. For an overview of services, and documentation about 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 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. CloudFoundry offers 3 different methods to deliver those credentials to the app.

For details about the different delivery methods and consumption of these credentials with your app, see Credential Delivery Methods.

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 receives different credentials, but this depends on the service.

$ cf bind-service my-app mydb
Binding service mydb to my-app in org my-org / space test as me@example.com...
OK
TIP: Use 'cf push' to ensure your env variable changes take effect

$ cf restart my-app

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.

Credential Delivery Methods

After your service instance is created and bound to your app, the credentials, along with some metadata, are available in the app container and can be consumed by your app. There are three delivery methods, which are mutually exclusive. The developer can choose which one to use and then must adjust the consumption in the app accordingly. For details about consuming credentials specific to your development framework, see the Service Binding section in the documentation for your framework’s buildpack.

Default VCAP_SERVICES environment variable

By default, credentials and additional metadata for all bound service instances are stored in the VCAP_SERVICES environment variable.

There are two methods developers can use 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 checking the binding data manually app developers can use cf env. See View Env.

The maximum size of content of the VCAP_SERVICES environment variable is 130 KB. If you want to bind more services to the app or the services you want to bind provide lots of data, you can use one of the other methods.

File-based VCAP services (experimental)

This delivery method is used when the app feature file-based-vcap-services is enabled. The environment variable VCAPSERVICESFILE_PATH will be made available in the app container and contains the path to a file containing the same content as the VCAP_SERVICES environment variable above.

The binding data can be viewed like this:

cf ssh <app_name> -c 'cat $VCAP_SERVICES_FILE_PATH'

The vcap_services file content cannot exceed 1 MB, otherwise an IncompatibleBindings error is raised.

Service Binding K8s (experimental)

This delivery method is used when the app feature service-binding-k8s is enabled. The environment variable SERVICEBINDINGROOT is made available in the app container. It contains the path to the root folder of a file structure containing binding information. This method is fully compatible with the specification on servicebinding.io, which is used by Kubernetes as well.

The binding data can be viewed like this:

cf ssh <app_name> -c 'find $SERVICE_BINDING_ROOT -type f -exec bash -c "echo {}: \$(cat {})" \;'

The bytesize of all files and their content combined cannot exceed 1 MB, otherwise an IncompatibleBindings error is raised.

Here are some examples outlining the transformation of VCAP_SERVICES to the file structure:

Nested structures inside their value will be serialized as JSON objects. The same applies if the value is a list.

VCAP_SERVICES= {
  "foo": [
    {
      "name": "foo",
      "credentials": {
        "simple": "value",
        "deeply": {
          "nested": "value"
        },
        "list": ["v", "a", "l", "u", "e"]
      }
    }
  ]
}

Service Binding Files:
  foo/name: foo
  foo/simple: value
  foo/deeply: {"nested":"value"}
  foo/list: ["v","a","l","u","e"]

Existing credential keys can be overwritten by other attributes – VCAP_SERVICES attributes plus type and provider. The full list of reserved file names is: binding-guid, binding-name, instance-guid, instance-name, name, label, tags, plan, syslog-drain-url, volume-mounts, type, and provider. Overwriting an existing key does not result in an error.

VCAP_SERVICES= {
  "foo": [
    {
      "name": "foo",
      "credentials": {
        "name": "user",
        "secret": "password"
      }
    }
  ]
}

Service Binding Files:
  foo/name: foo
  foo/secret: password

Empty lists or null values are omitted; that is, no file will be created.

VCAP_SERVICES= {
  "foo": [
    {
      "name": "foo",
      "binding_guid": "45436ca8-0a7c-45e3-9439-ca1b44db7a2b",
      "syslog_drain_url": null,
      "volume_mounts": []
    }
  ]
}

Service Binding Files:
  foo/name: foo
  foo/binding-guid: 45436ca8-0a7c-45e3-9439-ca1b44db7a2b

Binding names and keys resulting in filenames must match [a-z0-9-.]{1,253}. Invalid binding names and keys result in IncompatibleBindings error. VCAPSERVICES attributes are transformed to comply with this schema; that is, underscores are replaced by hyphens, so that, for example, `VCAPSERVICES attribute binding_guidbecomes file namebinding-guid`.

VCAP_SERVICES= {
  "foo": [
    {
      "name": "foo",
      "binding_guid": "45436ca8-0a7c-45e3-9439-ca1b44db7a2b",
      "instance_guid": "83745ca8-0a7c-45e3-9439-ca1b44db7a2b"
    }
  ]
}

Service Binding Files:
  foo/name: foo
  foo/binding-guid: 45436ca8-0a7c-45e3-9439-ca1b44db7a2b
  foo/instance-guid: 83745ca8-0a7c-45e3-9439-ca1b44db7a2b

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 user@example.com...
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 user@example.com... 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. Arbitrary parameters used in this example are available in cf CLI 7.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 Bob@scapp.io
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 include 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 is 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",
      ...
    }
  ]
}

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:

  1. Unbind the service instance using the credentials you are updating by running:

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

  2. Bind the service instance. This command adds your credentials to the VCAP_SERVICES environment variable.

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

  3. 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:

  1. 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

  2. Bind the service instances to the newly-deployed “Green” app by running:

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

  3. Start the “Green” app with cf start:

    $ cf start YOUR-APP

  4. 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 me@example.com...
OK

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.

View the source for this page in GitHub