User-Provided Service Instances

Page last updated: December 11, 2015

This page assumes you are using cf CLI v6.

User-provided service instances allow you to represent external assets like databases, messaging services, and key-value stores in Cloud Foundry.

For example, suppose a developer obtains credentials, a URL, and a port number for communicating with an Oracle database that is managed outside of Cloud Foundry. Then the developer creates a user-provided service instance to represent this external resource and provisions the service instance with all the parameters required for communicating with the real Oracle database. Finally, she binds the user-provided service instance to her application.

The user-provided service instance allows the developer to:

  • Avoid hard-coding credentials for a service instance into her application.
  • Treat the user-provided service instance exactly like any other service instance.

Although the external asset in this example was a real Oracle database, it could have been a simple placeholder used for testing.

User provided services are outside of Cloud Foundry, so you never create or otherwise manage the service itself through Cloud Foundry; you only create and manage service instances.

The cf services command lists all the service instances (both user-provided and managed) in your target space.

In contrast to the user-provided kind, a managed service is one that a service broker advertises in a catalog.

cf CLI Commands for Working with User-Provided Service Instances

cf CLI commands for creating and updating user-provided service instances can be used in three ways: interactively, non-interactively, and in conjunction with third-party log management software as described in RFC 6587. When used with third-party logging, the cf CLI sends data formatted according to RFC 5424.

Once created, user-provided service instances can be bound to an application with cf bind-service, unbound with cf unbind-service, renamed with cf rename-service, and deleted with cf delete-service.

The cf create-user-provided-service Command

The alias for create-user-provided-service is cups.

To create a service instance in interactive mode, use the -p option with a comma-separated list of parameter names. The cf CLI then prompts you for each parameter in turn.

cf cups SERVICE_INSTANCE -p "host, port, dbname, username, password"

To create a service instance non-interactively, use the -p option with a JSON hash of parameter keys and values.

cf cups SERVICE_INSTANCE -p '{"username":"admin","password":"pa55woRD"}'

To create a service instance that drains information to third-party log management software, use the -l SYSLOG_DRAIN_URL option.

cf cups SERVICE_INSTANCE -l syslog://shared-domain.com:514

The cf update-user-provided-service Command

The alias for update-user-provided-service is uups. You can use cf update-user-provided-service to update one or more of the attributes for a user-provided service instance. Attributes that you do not supply are not updated.

To update a service instance non-interactively, use the -p option with a JSON hash of parameter keys and values.

cf uups SERVICE_INSTANCE -p '{"username":"USERNAME","password":"PASSWORD"}'

To update a service instance that drains information to third-party log management software, use the -l SYSLOG_DRAIN_URL option.

cf uups SERVICE_INSTANCE -l syslog://shared-domain.com:514

Note: 514 is the default syslog port. Ensure that this value is correct for your environment.

Binding User-Provided Service Instances to Applications

There are two ways to bind user-provided service instances to applications:

  • With a manifest, when you push the application.
  • With the cf bind-service command, after you push the application.

In either case, you must push your app to a space where the desired user-provided instances already exist.

For example, if you want to bind a service instance called test-mysql-01 to an app, the services block in the manifest should look like this:

services:
 - test-mysql-01

This excerpt from the cf push command and response demonstrates that Cloud Foundry reads the manifest and binds the service instance to the app, which is called msgapp.

$ cf push
Using manifest file /Users/a.user/test-apps/msgapp/manifest.yml

...

Binding service test-mysql-01 to msgapp in org my-org / space development as [email protected]
OK

Once the binding has taken effect, it is described in the VCAP_SERVICES environment variable.

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

For an example of the cf bind-service command, see the next section.

Example: Creating a User-Provided Service Instance and Binding it to an App

Suppose we want to create and bind an instance of a publish-subscribe messaging service to an app called msgapp. Our Cloud Foundry username is a.user, and we plan to call the instance pubsub. We know the URL and port for the service.

  1. We begin with the cf create-user-provided-service command in interactive mode, using its alias, cups.

    $ cf cups pubsub -p "host, port, binary, username, password"

host> pubsub01.shared-domain.com

port> 1234

url> pubsub-example.com

username> pubsubuser

password> p@$$w0rd
Creating user provided service pubsub in org my-org / space development as [email protected]...
OK

  2. When we list available services, we see that the new service is not yet bound to any apps.

    $ cf services
Getting services in org my-org / space development as [email protected]...
OK

name               service         plan    bound apps
pubsub     user-provided

  3. Now we bind the service to our app.

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

  4. For the binding to take effect, we must push our app a second time.

    Note: You can skip this step if you bind a syslog drain service instance to a deployed app. Syslog drain service instances bound to deployed apps automatically start after a short delay. 

    $ cf push msgapp
Updating app msgapp in org my-org / space development as [email protected]...
OK
...

  5. To verify that the service instance is now recorded in VCAP_SERVICES, examine the output of cf env:

    $ cf env msgapp
Getting env variables for app msgapp in org My-Org / space development as [email protected]...

System-Provided:
{
  "VCAP_SERVICES": {
    "user-provided": [
      {
        "name": "pubsub",
        "label": "user-provided",
        "tags": [],
        "credentials": {
          "binary": "pubsub.rb",
          "host": "pubsub01.shared-domain.com",
          "password": "p@29w0rd",
          "port": "1234",
          "username": "pubsubuser"
        },
      "syslog_drain_url": ""
    }
  ]
}