LATEST VERSION: 1.2 - CHANGELOG
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.

Viewing All Plans Available for Pivotal Cloud Cache

Run cf marketplace -s p-cloudcache to view all plans available for PCC. 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...
OK

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

Creating a Pivotal Cloud Cache Service Instance

Run cf create-service p-cloudcache PLAN-NAME SERVICE-INSTANCE-NAME to create a service instance. Replace PLAN-NAME with the name from the list of available plans. Replace SERVICE-INSTANCE-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...
OK

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}'

Enable Session State Caching with the Java Buildpack

When the service instance name is followed by the session-replication tag, the Java buildpack will download all the required resources for session state caching.

To enable session state caching, do one of the following:

  • When creating your service instance name, append it with the session-replication tag. For example, for the p-cloudcache service:

     $ cf create-service p-cloudcache my-service-instance -t session-replication
  • When updating your service instance name (for example, if the updated name is new-service-instance), append it with the session-replication tag:

    $ cf update-service new-service-instance -t session-replication
  • End the service instance name with the text -session-replication: my-service-instance-session-replication.

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

About Changes to the Service Plan

Your PCF operator can change details of the service plan available on the Marketplace. If your operator changes the default value of one of the optional parameters, this does not affect existing service instances.

However, if your operator changes the allowed values of one of the optional parameters, existing instances that exceed the new limits are not affected, but any subsequent service updates that change the optional parameter must adhere to the new limits.

For example, if the PCF operator changes the plan by decreasing the maximum value for num_servers, any future service updates must adhere to the new num_servers value limit.

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

Accessing 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-INSTANCE-NAME KEY-NAME to create a service key. Replace SERVICE-INSTANCE-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-INSTANCE-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": [
    "10.244.0.66[55221]",
    "10.244.0.4[55221]",
    "10.244.0.3[55221]"
  ],
  "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.

Check the product snapshot of the PCC version you’re using to determine which version of gfsh you need in order to connect to your cluster. For example, if your tile package uses GemFire v9.0.4, you should be using a 9.0.4 version of the gfsh client.

To install gfsh:

  1. Download the 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
gfsh>

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

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

Workaround Connect with gfsh over HTTPS

Connecting over HTTPS is a bit more work than HTTP, but it is required for some network setups. The additional steps are:

  1. Creating a truststore.
  2. Setting an environment variable before you start gfsh.

Before you start this process, you’ll need to have your ERT environment certificate handy.

Create a truststore that contains the ERT certificate

We suggest using the keytool command line utility to create a truststore file. You’ll pass in your ERT certificate file with the -file flag, and the path for the output truststore file with the -keystore flag.

When you run this command, you will be prompted to enter a keystore password. Create a password and remember it! You will then be prompted with the certificate details. Type yes to trust the certificate.

Here is an example of how to run keytool and what the output looks like:

$ keytool -import -alias <env>-ssl -file <path-to-ERT-cert> -keystore <env>.truststore
Enter keystore password:
Re-enter new password:
Owner: CN=*.url.example.com, OU=Cloud Foundry, O=Pivotal, L=New York, ST=New York, C=US
Issuer: CN=*.url.example.com, OU=Cloud Foundry, O=Pivotal, L=New York, ST=New York, C=US
Serial number: bd84912917b5b665
Valid from: Sat Jul 29 09:18:43 EDT 2017 until: Mon Apr 07 09:18:43 EDT 2031
Certificate fingerprints:
     MD5:  A9:17:B1:C9:6C:0A:F7:A3:56:51:6D:67:F8:3E:94:35
     SHA1: BA:DA:23:09:17:C0:DF:37:D9:6F:47:05:05:00:44:6B:24:A1:3D:77
     SHA256: A6:F3:4E:B8:FF:8F:72:92:0A:6D:55:6E:59:54:83:30:76:49:80:92:52:3D:91:4D:61:1C:A1:29:D3:BD:56:57
     Signature algorithm name: SHA256withRSA
     Version: 3

Extensions:

#1: ObjectId: 2.5.29.10 Criticality=true
BasicConstraints:[
  CA:true
  PathLen:0
]

#2: ObjectId: 2.5.29.11 Criticality=false
SubjectAlternativeName [
  DNSName: *.sys.url.example.com
  DNSName: *.apps.url.example.com
  DNSName: *.uaa.sys.url.example.com
  DNSName: *.login.sys.url.example.com
  DNSName: *.url.example.com
  DNSName: *.ws.url.example.com
]

Trust this certificate? [no]:  yes
Certificate was added to keystore

Setting the Environment Variable

Now that you’ve created a truststore file, you’ll need to tell gfsh to use it. The way to do that is to set the JAVA_ARGS environment variable, before starting gfsh.

$ export JAVA_ARGS="-Djavax.net.ssl.trustStore=<path to generated truststore>"

Connect over HTTPS

This part is nearly the same as over HTTP; just make sure to use a url starting with https.

Open the gfsh console and connect via https:

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

Monitor and Manage Pivotal GemFire

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

Using Pivotal 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:

  • PARTITION_HEAP_LRU
  • REPLICATE_HEAP_LRU

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 enables the apps to connect to the service instance and read or write data to the region. Run cf bind-service APP-NAME SERVICE-INSTANCE-NAME to bind an app to your service instance. Replace APP-NAME with the name of the app. Replace SERVICE-INSTANCE-NAME with the name you chose for your service instance.

$ cf bind-service my-app my-cloudcache

Binding an app to the service instance provides connection information through the VCAP_SERVICES environment variable. Your app can use this information to configure components, such as the GemFire client cache, to use the service instance.

The following is a sample VCAP_SERVICES environment variable:

{
  "p-cloudcache": [
    {
      "credentials": {
    "locators": [
      "10.244.0.4[55221]",
      "10.244.1.2[55221]",
      "10.244.0.130[55221]"
    ],
    "urls": {
      "gfsh": "http://cloudcache-5574c540-1464-4f9e-b56b-74d8387cb50d.local.pcfdev.io/gemfire/v1",
      "pulse": "http://cloudcache-5574c540-1464-4f9e-b56b-74d8387cb50d.local.pcfdev.io/pulse"
    },
    "users": [
      {
        "password": "some_developer_password",
        "username": "developer"
      },
      {
        "password": "some_password",
        "username": "cluster_operator"
      }
    ]
      },
      "label": "p-cloudcache",
      "name": "test-service",
      "plan": "caching-small",
      "provider": null,
      "syslog_drain_url": null,
      "tags": [],
      "volume_mounts": []
    }
  ]
}

A Sample Java Client App for Pivotal Cloud Cache

A sample app in pure Java has been written to demonstrate how to connect an app to the service instance.

The code is available at https://github.com/cf-gemfire-org/cloudcache-sample-app.git

The code assumes that you have already created a region named test in your cluster using gfsh as described in the section above.

Apache Geode 1.0.0 is currently the only version that works to connect to our version of GemFire, which is listed in the build.gradle.

Follow these steps to deploy the sample app:

  1. Modify the sample manifest, replacing service0 with the name of your service.

    ---
    applications:
    - name: sample_app
    path: build/libs/cloudcache-sample-app-1.0-SNAPSHOT-all.jar
    no-route: true
    health-check-type: none
    services:
    - service0  
    
  2. To deploy the app, run the cf push command:

    $ cf push -f /path/to/manifest
    

After the app is pushed and started, there should be an entry in the test region where key=1 and value=one.

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.

Export gfsh Logs

You can get logs and .gfs stats files from your PCC service instances using the export logs command in gfsh.

  1. Use the Connect with gfsh procedure to connect to the service instance for which you want to see logs.
  2. Run export logs.
  3. Find the ZIP file in the directory where you started gfsh. This file contains a folder for each member of the cluster. The member folder contains the associated log files and stats files for that member.

For more information about the gfsh export command, see the gfsh export documentation.

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-INSTANCE-NAME KEY-NAME to delete the service key.
  2. Run cf unbind-service APP-NAME SERVICE-INSTANCE-NAME to unbind your app from the service instance.
  3. Run cf delete-service SERVICE-INSTANCE-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