Pivotal Cloud Cache for PCF v1.0

Pivotal Cloud Cache Developer Guide

This document describes how a Pivotal Cloud Foundry (PCF) app developer can choose a service plan, create and delete Pivotal Cloud Cache (PCC) service instances, and bind an app.

You must install the Cloud Foundry Command Line Interface (cf CLI) to run the commands in this topic.

View All Plans Available for Pivotal Cloud Cache

Run cf marketplace -s p-cloudcache to view all plans available for Pivotal Cloud Cache. The plan names displayed are configured by the operator on tile installation.

$ cf marketplace -s p-cloudcache

Getting service plan information for service p-cloudcache as admin...

service plan   description      free or paid
extra-small    Caching Plan 1   free
small          Caching Plan 2   free
medium         Caching Plan 3   free
large          Caching Plan 4   free
extra-large    Caching Plan 5   free

Create a Pivotal Cloud Cache Service Instance

Run cf create-service p-cloudcache PLAN-NAME SERVICE-NAME to create a service instance. Replace PLAN-NAME with the name from the list of available plans. Replace SERVICE-NAME with a name of your choice. You use this name to refer to your service instance with other commands. Service instance names can include alpha-numeric characters, hyphens, and underscores.

$ cf create-service p-cloudcache extra-large my-cloudcache

Service instances are created asynchronously. Run the cf services command to view the current status of the service creation, and of other service instances in the current org and space:

$ cf services
Getting services in org my-org / space my-space as user...

name            service        plan    bound apps   last operation
my-cloudcache   p-cloudcache   small                create in progress

When completed, the status changes from create in progress to create succeeded.

Provide Optional Parameters

You can create a customized service instance by passing optional parameters to cf create-service using the -c flag. The -c flag accepts a valid JSON object containing service-specific configuration parameters, provided either in-line or in a file.

The PCC service broker supports the following parameters:

  • num_servers: An integer that specifies the number of server instances in the cluster. The minimum value is 4. The maximum and default values are configured by operator.
  • new_size_percentage: An integer that specifies the percentage of the heap to allocate to young generation. This value must be between 5 and 83. By default, the new size is 2 GB or 10% of heap, whichever is smaller.

The following example creates the service with five service instances in the cluster:

$ cf create-service p-cloudcache small my-cloudcache -c '{"num_servers": 5}'

Update a Pivotal Cloud Cache Service Instance

You can apply all optional parameters to an existing service instance using the cf update-service command. You can, for example, scale up a cluster by increasing the number of servers.

Previously specified optional parameters are persisted through subsequent updates. To return the service instance to default values, you must explicitly specify the defaults as optional parameters.

For example, if you create a service instance with five servers using a plan that has a default value of four servers:

$ cf create-service p-cloudcache small my-cloudcache -c '{"num_servers": 5}'

And you set the new_size_percentage to 50%:

$ cf update-service my-cloudcache -c '{"new_size_percentage": 50}'

Then the resulting service instance has 5 servers and new_size_percentage of 50% of heap.

Cluster Rebalancing

When updating a cluster to increase the number of servers, the available heap size is increased. When this happens, PCC automatically rebalances data in the cache to distribute data across the cluster.

This automatic rebalancing does not occur when a server leaves the cluster and later rejoins, for example when a VM is re-created, or network connectivity lost and restored. In this case, you must manually rebalance the cluster using the gfsh rebalance command while authenticated as a cluster operator.

Plan Updates

Your PCF operator may change the plan available on the Marketplace. If the operator changes the default value of one of the optional parameters, this change will not affect existing service instances. If the operator changes the allowed values of one of the optional parameters, for example decreasing the maximum value for num_servers, existing instances that exceed the new limits are not affected, but any subsequent service update that changes the optional parameter must adhere to the new limits.

You may see the following error message when attempting to update a service instance:

$ cf update-service  my-cloudcache -c '{"num_servers": 5}'
Updating service instance my-cloudcache as admin...
Server error, status code: 502, error code: 10001, message: Service broker error: Service cannot be updated at this time, please try again later or contact your operator for more information

This error message indicates that the operator has made an update to the plan used by this service instance. You must wait for the operator to apply plan changes to all service instances before you can make further service instance updates.

Access a Service Instance

Once you have created a service instance, you can start accessing it. Usually you should set up cache regions before using your service instance from a deployed CF app. You can do this with the gfsh command line tool. To connect, you must set up a service key.

Create Service Keys

Service keys provide a way to access your service instance outside the scope of a deployed CF app. Run cf create-service-key SERVICE-NAME KEY-NAME to create a service key. Replace SERVICE-NAME with the name you chose for your service instance. Replace KEY-NAME with a name of your choice. You use this name to refer to your service key with other commands.

$ cf create-service-key my-cloudcache my-service-key

Run cf create-service-key SERVICE-NAME KEY-NAME to view the newly created service key.

$ cf service-key my-cloudcache my-service-key

The cf service-key returns output in the following format:

  "locators": [
  "urls": {
    "gfsh": "",
    "pulse": ""
  "users": [
      "password": "",
      "username": "developer"
      "password": "",
      "username": "cluster_operator"

This returned structure contains the following information:

  • cluster_operator and developer credentials
  • gfsh-url: A URL usable to connect the gfsh client to the service instance
  • pulse-url: A URL usable to view the Pulse dashboard in a web browser, which allows monitoring of the service-instance status. You can use the developer credentials to authenticate.

The cluster_operator and developer roles provide access to different functions on the service instance.

You can use the cluster_operator credentials to administer the service instance. For example, you can use the cluster_operator credentials to define or delete cache regions.

You can use the developer credentials to perform create, retrieve, update, and delete (CRUD) data operations. You can also use the cluster_operator credentials to perform the same functions the developer credentials. As a best practice, you should use the role with the least amount of permissions necessary.

Connect with gfsh

You can manage your cluster and data with the gfsh command-line interface. PCC works with gfsh version 9.0.0 and above.

To install gfsh:

  1. Download “Pivotal Gemfire” zip archive from Pivotal Network
  2. Unzip and locate the correct binary for your architecture (gfsh for unix or gfsh.bats for windows)
  3. Add the gfsh binary to your path

Start the gfsh command-line tool:

$ gfsh
    _________________________     __
   / _____/ ______/ ______/ /____/ /
  / /  __/ /___  /_____  / _____  /
 / /__/ / ____/  _____/ / /    / /
/______/_/      /______/_/    /_/    9.0.1

Monitor and Manage Pivotal GemFire

From the gfsh> prompt, connect to your service instance as cluster_operator:

gfsh>connect --use-http --url= --user=cluster_operator --password=

Using Cloud Cache

Create Regions with gfsh

After connecting with gfsh as a cluster_operator, you can define a new cache region.

The following command creates a partitioned region with a single redundant copy:

gfsh>create region --name=my-cache-region --type=PARTITION_HEAP_LRU --redundant-copies=1
     Member      | Status
---------------- | -------------------------------------------------------
cacheserver-z2-1 | Region "/my-cache-region" created on "cacheserver-z2-1"
cacheserver-z3-2 | Region "/my-cache-region" created on "cacheserver-z3-2"
cacheserver-z1-0 | Region "/my-cache-region" created on "cacheserver-z1-0"
cacheserver-z1-3 | Region "/my-cache-region" created on "cacheserver-z1-3"

The following region types are recommended for PCC:


To achieve optimal performance, you should understand the type of region that is relevant to your situation. For more information, see the Pivotal GemFire Region Types documentation.

You can test the newly created region by writing and reading values with gfsh:

gfsh>put --region=/my-cache-region --key=test --value=thevalue
Result      : true
Key Class   : java.lang.String
Key         : test
Value Class : java.lang.String
Old Value   : 

gfsh>get --region=/my-cache-region --key=test
Result      : true
Key Class   : java.lang.String
Key         : test
Value Class : java.lang.String
Value       : thevalue

In practice, you should perform these get/put operations from a deployed PCF app. To do this, you must bind the service instance to these apps.

Bind an App to a Service Instance

Binding your apps to a service instance allows the apps to connect to the service instance, and read or write data to the region. Run cf bind-service APP-NAME SERVICE-NAME to bind an app to your service instance. Replace APP-NAME with the name of the app. Replace SERVICE-NAME with the name you chose for your service instance.

$ cf bind-service my-app my-cloudcache

Binding an app to the service instance provide connection information through the VCAP_SERVICES environment variable, which your app can use to configure components like a GemFire client cache to use the service instance.

Use the Pulse Dashboard

You can access the Pulse dashboard for a service instance by accessing the pulse-url you obtained from a service key in a web browser.

Use either the cluster_operator or developer credentials to authenticate.

Deleting a Service Instance

You can delete service instances using the cf CLI. Before doing so, you must remove any existing service keys and app bindings.

  1. Run cf delete-service-key SERVICE-NAME KEY-NAME to delete the service key.
  2. Run cf unbind-service APP-NAME SERVICE-NAME to unbind your app from the service instance.
  3. Run cf delete-service SERVICE-NAME to delete the service instance.
$ cf delete-service-key my-cloudcache my-service-key
$ cf unbind-service my-app my-cloudcache
$ cf delete-service my-cloudcache

Deletions are asynchronous. Run cf services to view the current status of the service instance deletion.

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