Using Services in Pivotal Platform Dev

Page last updated:

This topic describes how to deploy, create, delete, update, and bind Marketplace services in Pivotal Platform Dev.

Overview

Pivotal Platform Dev provides access to three Marketplace services: Redis, RabbitMQ, and MySQL. You can create instances of these services and bind them to your apps to generate and deliver credentials to your apps.

Note: To manage and bind service instances, you must be running the Pivotal Platform Dev .iso or .tgz, and you must be logged in to your Pivotal Platform Dev instance. Complete the procedure in Using Pivotal Platform Dev before following the procedures below.

List Marketplace Services

To display information about the Marketplace services available in Pivotal Platform Dev:

  1. Start your Pivotal Platform Dev instance by running:

    cf dev start
    
  2. Run:

    cf marketplace
    

Services that are not started do not appear in Marketplace.

Deploy Services

Note: Ad hoc service deployment requires Pivotal Platform Dev v1.0.0 or later.

To deploy a service:

  1. Start your Pivotal Platform Dev instance by running:

    cf dev start
    
  2. Run:

    cf dev deploy-service SERVICE-NAME
    

    Where SERVICE-NAME is the name of the service you want to deploy: scs, redis, rabbitmq, or mysql.

Pivotal Platform Dev supports Marketplace services, giving developers access to Spring Cloud Services, Redis, RabbitMQ, and MySQL. The table below includes flags and descriptions for each service:

flag description
scs Server-side components for Spring Cloud projects.
redis Redis service provides a key-value store.
rabbitmq RabbitMQ is a robust and scalable high-performance multi-protocol messaging broker.
mysql MySQL databases on demand.

Create Service Instances

These sections describe how to create a service instance alone, with arbitrary parameters, or with instance tags.

Create a Service Instance

To create a service instance:

  1. Target your Pivotal Platform Dev instance’s API by running:

    cf login -a https://api.dev.cfdev.sh --skip-ssl-validation
    
  2. Run:

    cf create-service SERVICE PLAN SERVICE-INSTANCE
    

    Where:

    • SERVICE is the service for which you want to create service instances.
    • PLAN is the service plan you want to use. Service plans are a way for providers to offer varying levels of resources or features for the same service.
    • SERVICE-INSTANCE is the name you provide for your service instance. You can use any series of alpha-numeric characters, hyphens (-), and underscores (_). You can rename the instance at any time.

Note: For more information about how developers can bind apps with services that are not available in their Pivotal Marketplace, see User Provided Service Instances.

Arbitrary Parameters

Note: Arbitrary parameters require cf CLI v6.12.1 or later.

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 JSON file. For a list of supported configuration parameters, see the documentation for the particular service offering.

To provide parameters in-line:

  1. Target your Pivotal Platform Dev instance’s API by running:

    cf login -a https://api.dev.cfdev.sh --skip-ssl-validation
    
  2. Run:

    cf create-service SERVICE PLAN SERVICE-INSTANCE -c 'PARAMETERS-JSON-OBJECT'
    

    Where:

    • SERVICE is the service for which you want to create service instances.
    • PLAN is the service plan you want to use.
    • SERVICE-INSTANCE is the name you provide for your service instance.
    • PARAMETERS is the JSON object containing the parameters you want to configure.

To provide parameters in a JSON file:

  1. Target your Pivotal Platform Dev instance’s API by running:

    cf login -a https://api.dev.cfdev.sh --skip-ssl-validation
    
  2. Run:

    cf create-service SERVICE PLAN SERVICE-INSTANCE -c PARAMETERS-JSON-FILE-PATH
    

    Where:

    • SERVICE is the service for which you want to create service instances.
    • PLAN is the service plan you want to use.
    • SERVICE-INSTANCE is the name you provide for your service instance.
    • PARAMETERS-JSON-FILE-PATH is the file path of the JSON file containing the parameters you want to configure.

Instance Tags

Note: Instance tags require cf CLI v6.12.1 or later.

Some services provide a list of tags that Pivotal Platform delivers in the VCAP_SERVICES environment variable. These tags provide developers with a more generic way for apps to parse VCAP_SERVICES for credentials. Developers can provide their own tags when creating a service instance by including a comma-separated list of tags with the -t flag. For more information, see the VCAP_SERVICES section of the PAS Environment Variables topic.

To provide tags when creating a service instance:

  1. Target your Pivotal Platform Dev instance’s API by running:

    cf login -a https://api.dev.cfdev.sh --skip-ssl-validation
    
  2. Run:

    cf create-service SERVICE PLAN SERVICE-INSTANCE -t "TAG-1, TAG-2"
    

    Where:

    • SERVICE is the service for which you want to create service instances.
    • PLAN is the service plan you want to use.
    • SERVICE-INSTANCE is the name you provide for your service instance.
    • TAG-1 and TAG-2 are the tags you want to provide the service instance.

Examine Service Instances

These sections describe how to list the service instances in your targeted space and get details for a particular service instance.

List Service Instances

To list the service instances in your targeted space:

  1. Target your Pivotal Platform Dev instance’s API by running:

    cf login -a https://api.dev.cfdev.sh --skip-ssl-validation
    
  2. Run:

    cf services
    

The output includes any bound apps, along with the state of the last requested operation for the service instance.

Get Details for a Particular Service Instance

To get details about a particular service instance:

  1. Target your Pivotal Platform Dev instance’s API by running:

    cf login -a https://api.dev.cfdev.sh --skip-ssl-validation
    
  2. Run:

    cf service SERVICE-INSTANCE
    

    Where SERVICE-INSTANCE is the name of the service instance you want to examine.

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

Rename a Service Instance

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

To rename a service instance:

  1. Target your Pivotal Platform Dev instance’s API by running:

    cf login -a https://api.dev.cfdev.sh --skip-ssl-validation
    
  2. Run:

    cf rename-service OLD-SERVICE-INSTANCE-NAME NEW-SERVICE-INSTANCE-NAME
    

    Where:

    • OLD-SERVICE-INSTANCE-NAME is the current name of the service instance.
    • NEW-SERVICE-INSTANCE-NAME is the new name you want to give the service instance.

Update a Service Instance

These sections describe how to update a service instance’s service plan, arbitrary parameters, or instance tags.

Upgrade or Downgrade Service Plan

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

By updating the service plan for a service 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.

To update the service plan for a service instance:

  1. Target your Pivotal Platform Dev instance’s API by running:

    cf login -a https://api.dev.cfdev.sh --skip-ssl-validation
    
  2. Run:

    cf update-service SERVICE-INSTANCE -p SERVICE-PLAN
    

    Where:

    • SERVICE-INSTANCE is the name of the service instance.
    • SERVICE-PLAN is the name of the service plan you want to update.

Arbitrary Parameters

Note: Arbitrary parameters require cf CLI v6.12.1 or later.

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 JSON file. For a list of supported configuration parameters, see the documentation for the particular service offering.

To update the parameters of a service instance in-line:

  1. Target your Pivotal Platform Dev instance’s API by running:

    cf login -a https://api.dev.cfdev.sh --skip-ssl-validation
    
  2. Run:

    cf update-service SERVICE-INSTANCE -c 'PARAMETERS-JSON-OBJECT'
    

    Where:

    • SERVICE-INSTANCE is the name of your service instance.
    • PARAMETERS is the JSON object containing the parameters you want to update.

To update the parameters of a service instance with a JSON file:

  1. Target your Pivotal Platform Dev instance’s API by running:

    cf login -a https://api.dev.cfdev.sh --skip-ssl-validation
    
  2. Run:

    cf update-service SERVICE-INSTANCE -c PARAMETERS-JSON-FILE-PATH
    

    Where:

    • SERVICE-INSTANCE is the name of your service instance.
    • PARAMETERS-JSON-FILE-PATH is the file path of the JSON file containing the parameters you want to update.

Instance Tags

Note: Instance tags require cf CLI v6.12.1 or later.

Some services provide a list of tags that Pivotal Platform delivers in the VCAP_SERVICES environment variable. These tags provide developers with a more generic way for apps to parse VCAP_SERVICES for credentials. Developers can provide their own tags when creating a service instance by including a comma-separated list of tags with the -t flag.

To update the tags of a service instance:

  1. Target your Pivotal Platform Dev instance’s API by running:

    cf login -a https://api.dev.cfdev.sh --skip-ssl-validation
    
  2. Run:

    cf update-service SERVICE-INSTANCE -t "TAG-1, TAG-2"
    

    Where:

    • SERVICE-INSTANCE is the name of your service instance.
    • TAG-1 and TAG-2 are the tags you want to update.

Delete a Service Instance

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

To delete a service instance:

  1. Target your Pivotal Platform Dev instance’s API by running:

    cf login -a https://api.dev.cfdev.sh --skip-ssl-validation
    
  2. Run:

    cf delete-service SERVICE-INSTANCE
    

    Where SERVICE-INSTANCE is the name of the service instance you want to delete.

  3. When you are prompted to confirm that you want to delete the service instance, enter y.

Bind Service Instances

These sections describe how to bind a service instance to your app alone, bind a service instance to your app with arbitrary parameters, use an app manifest to bind the service instance during a push, and configure apps with bound service instances to consume binding credentials.

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.

To bind a service instance to your app:

  1. Run:

    cf bind-service APP-NAME SERVICE-INSTANCE
    

    Where:

    • APP-NAME is the name of your app.
    • SERVICE-INSTANCE is the name of the service instance you want to bind to your app.
  2. Restage your app by running:

    cf restage APP-NAME
    

    Where APP-NAME is the name of your app.

  3. Restart or re-push the app bound to the service instance so the app recognizes your environment variable updates.

Arbitrary Parameters

Note: Arbitrary parameters require cf CLI v6.12.1 or later.

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 JSON file. For a list of supported configuration parameters, see the documentation for the particular service offering.

To bind a service instance to your app with parameters in-line:

  1. Run:

    cf APP-NAME SERVICE-INSTANCE -c 'PARAMETERS-JSON-OBJECT'
    

    Where:

    • APP-NAME is the name of your app.
    • SERVICE-INSTANCE is the name of the service instance you want to bind to your app.
    • PARAMETERS-JSON-OBJECT is the JSON object containing the parameters you want to configure.
  2. Restage your app by running:

    cf restage APP-NAME
    

    Where APP-NAME is the name of your app.

To bind a service instance to your app with in a JSON file:

  1. Run:

    cf bind-service APP-NAME SERVICE-INSTANCE -c PARAMETERS-JSON-FILE-PATH
    

    Where:

    • APP-NAME is the name of your app.
    • SERVICE-INSTANCE is the name of the service instance you want to bind to your app.
    • PARAMETERS-JSON-FILE-PATH is the file path of the JSON file containing the parameters you want to configure.
  2. Restage your app by running:

    cf restage APP-NAME
    

    Where APP-NAME is the name of your app.

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 a push. As of cf CLI v6.12.1, arbitrary parameters are not supported in app manifests.

To bind a service instance to your app on push:

  1. Add the following to your app manifest:

    services:
     - SERVICE-INSTANCE
    

    Where SERVICE-INSTANCE is the name of the service instance you want to bind to your app.

  2. Run:

    cf push APP-NAME
    

    Where APP-NAME is the name of your app.

For more information about app manifests, see Deploying with App Manifests.

Using Bound Service Instances

Once you have a service instance created and bound to your app, you must 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 you can use to configure your apps to consume binding credentials:

  • Parse the JSON yourself: For more information, see the VCAP_SERVICES section of the PAS Environment Variables topic. 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, see the Service Binding section in the documentation for your framework’s buildpack.

Update Service Credentials

To update your service credentials:

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

    cf unbind-service APP-NAME SERVICE-INSTANCE
    

    Where:

    • APP-NAME is the name of your app.
    • SERVICE-INSTANCE is the name of the service instance for which you want to update credentials.
  2. Re-bind the service instance by running:

    cf bind-service APP-NAME SERVICE-INSTANCE
    

    Where:

    • APP-NAME is the name of your app.
    • SERVICE-INSTANCE is the name of the service instance for which you want to update credentials. This adds your credentials to the VCAP_SERVICES environment variable.
  3. Restart or re-push the app bound to the service instance so the app recognizes your environment variable updates.

Unbind a Service Instance

Unbinding a service instance removes the credentials created for your app from the VCAP_SERVICES environment variable.

To unbind a service instance from your app:

  1. Run:

    cf unbind-service APP-NAME SERVICE-INSTANCE
    

    Where:

    • APP-NAME is the name of your app.
    • SERVICE-INSTANCE is the name of the service instance you want to unbind from your app.
  2. Restart or re-push the app bound to the service instance so the app recognizes your environment variable updates.