Using Services in PCF Dev

This topic describes how to create, delete, update, and bind marketplace services in PCF Dev.

PCF Dev provides access to three marketplace services: Redis, RabbitMQ, and MySQL. You can create instances of these services and bind them to your applications to generate and deliver credentials to the applications.

Note: To manage and bind service instances you must be running the PCF Dev VM and you must be logged in to your PCF Dev instance. Complete the steps in the Using PCF Dev topic before following the procedures below.

List Marketplace Services

Run the command cf marketplace to display information about the marketplace services provided by PCF Dev.

$ cf marketplace
Getting services from marketplace in org pcfdev-org / space pcfdev-space as admin...
OK

service      plans        description
p-mysql      512mb, 1gb   MySQL databases on demand
p-rabbitmq   standard     RabbitMQ is a robust and scalable high-performance multi-protocol messaging broker.
p-redis      shared-vm    Redis service to provide a key-value store

Create Service Instances

You can create a service instance with the command: cf create-service SERVICE PLAN SERVICE_INSTANCE

  • SERVICE The service you choose.
  • PLAN Service plans are a way for providers to offer varying levels of resources or features for the same service.
  • SERVICE_INSTANCE A name you provide for your service instance. This is an alias for the instance which is meaningful to you. Use any series of alpha-numeric characters, hyphens (-), and underscores (_). You can rename the instance at any time.

Example:

$ cf create-service p-mysql 512mb my_mysql
Creating service my_mysql in org pcfdev-org / space pcfdev-space as admin...
OK

Note: The User Provided Service Instances topic provides a way for developers to bind applications with services that are not available in their Cloud Foundry marketplace.

Arbitrary Parameters

Note: Arbitrary parameters require cf CLI v6.12.1+

Some services support additional configuration parameters with the provision 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 the documentation for the particular service offering.

Example providing parameters in-line:

$ cf create-service my-db-service small-plan my-db -c '{"storage_gb":4}'
Creating service my-db in org pcfdev-org / space pcfdev-space as admin...
OK

Example providing parameters in a file:

$ cf create-service my-db-service small-plan my-db -c /tmp/config.json
Creating service my-db in org pcfdev-org / space pcfdev-space as admin...
OK

Instance Tags

Note: Instance tags require cf CLI v6.12.1+

Some services provide a list of tags that Cloud Foundry delivers in the VCAP_SERVICES Environment Variable. These tags provide developers with a more generic way for applications to parse VCAP_SERVICES for credentials. Developers may provide their own tags when creating a service instance by including a comma-separated list of tags with the -t flag.

Example:

$ cf create-service my-db-service small-plan my-db -t "prod, workers"
Creating service my-db in org pcfdev-org / space pcfdev-space as admin...
OK

List Service Instances

You can list the service instances in your targeted space with the command cf services. The output includes any bound apps, along with the state of the last requested operation for the service instance.

Example:

$ cf services
Getting services in org pcfdev-org / space pcfdev-space as admin...
OK
name       service         plan        bound apps              last operation
my_mysql   p-mysql         512mb       myapp                   create succeeded

Get Details for a Particular Service Instance

Details include dashboard URLs, if applicable, and operation start and last updated timestamps.

Example:

$ cf service my_mysql
Service instance: my_mysql
Service: p-mysql
Plan: 512mb
Description: MySQL databases on demand
Documentation url:
Dashboard: https://mysql-broker.local.pcfdev.io/manage/instances/478d839c-dcfa-41cc-88ed-12f1b0b12a31
Last Operation
Status: create succeeded
Message:
Started: 2016-04-14T17:47:44Z
Updated:

Rename a Service Instance

You can change the name given to a service instance. When restarting any bound applications, the name of the instance will change in the VCAP_SERVICES environment variable. If your application depends on the instance name for discovering credentials, changing the name could break your application’s use of the service instance.

Example:

$ cf rename-service my_mysql my_mysql1
Renaming service my_mysql to my_mysql1 in org pcfdev-org / space pcfdev-space as admin...
OK

Update a Service Instance

Upgrade/Downgrade Service Plan

Note: Changing a plan requires cf CLI v6.7+ and cf-release v192+

By updating the service plan for an instance, users can effectively upgrade and downgrade their service instance to other service plans. Though the platform and CLI support this feature, services must expressly implement support for it, and not all services do. Furthermore, a service might support updating between some plans but not others. For example, a service might support updating a plan where only a logical change is required, but not where data migration is necessary. In either case, users can expect to see a meaningful error when plan update is not supported.

Example:

$ cf update-service my_mysql -p 1gb
Updating service instance my_mysql as admin...
OK

Arbitrary Parameters

Note: Arbitrary parameters require cf CLI v6.12.1+

Some services support additional configuration parameters with the update 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 the documentation for the particular service offering.

Example providing parameters in-line:

$ cf update-service mydb -c '{"storage_gb":4}'
Updating service instance mydb as admin...

Example providing parameters in a file:

$ cf update-service mydb -c /tmp/config.json
Updating service instance mydb as admin...

Instance Tags

Note: Instance tags require cf CLI v6.12.1+

Some services provide a list of tags that Cloud Foundry delivers in the VCAP_SERVICES Environment Variable. These tags provide developers with a more generic way for applications to parse VCAP_SERVICES for credentials. Developers may provide their own tags when creating a service instance by including a comma-separated list of tags with the -t flag.

Example:

$ cf update-service my-db -t "staging, web"
Updating service my-db in org org pcfdev-org / space pcfdev-space as admin...
OK

Delete a Service Instance

Deleting a service instance deprovisions the service instance and deletes all data associated with the service instance.

Example:

$ cf delete-service my_mysql
Really delete the service my_mysql?> y
Deleting service my_mysql in org pcfdev-org / space pcfdev-space as admin...
OK

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.

Example:

$ cf bind-service my-app my_mysql
Binding service my_mysql to app my_app in org pcfdev-org / space pcfdev-space as admin...
OK
TIP: Use 'cf restage my_app' to ensure your env variable changes take effect
$ cf restage 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

Note: 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 the documentation for the particular service offering.

Example providing parameters in-line:

$ cf bind-service rails-sample my-db -c '{"role":"read-only"}'
Binding service my-db to app rails-sample in org pcfdev-org / space pcfdev-space as admin...
OK

Example providing parameters in a file:

$ cf bind-service rails-sample my-db -c /tmp/config.json
Binding service my-db to app rails-sample in org pcfdev-org / space pcfdev-space as admin...
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/user/test-apps/test-msg-app/manifest.yml
...
Binding service test-mysql-01 to test-msg-app in org pcfdev-org / space pcfdev-space as admin...
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:

  1. Unbind the service instance using the credentials you are updating with the following command:

    $ cf unbind-service YOUR-APP YOUR-SERVICE-INSTANCE
    
  2. 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
    
  3. 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 my_mysql
Unbinding app my-app from service my_mysql in org pcfdev-org / space pcfdev-space as admin...
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.

Create a pull request or raise an issue on the source for this page in GitHub