LATEST VERSION: 1.1 - CHANGELOG
Pivotal Cloud Cache for PCF v1.1

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 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...
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. This is available in Java buildpack v4 starting from v4.3, and in v3 starting from v3.19.

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.

Enable Session State Caching Using Spring Session

Session state caching for apps using Spring Session is a beta feature. It uses pre-release versions of Spring Session libraries.

To use spring-session with Cloud Cache, follow the steps below:

  1. Make the following changes to the app:

    • Replace existing Spring Session @EnableXXXHttpSession annotation with @EnableGemFireHttpSession(maxInactiveIntervalInSeconds = N) where N is seconds.
    • Add the spring-session-data-geode and spring-data-geode dependencies to the build.
    • Add beans to the Spring application config.

    For more information, see the spring-session-data-gemfire-example repository.

  2. Create a region named ClusteredSpringSessions in gfsh using the cluster_operator credentials: create region --name=ClusteredSpringSessions --type=PARTITION_HEAP_LRU

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 might 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

After you have created a service instance, you can start accessing it. Usually, you 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, see Create Service Keys below.

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 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": "gfsh-url",
    "pulse": "pulse-url"
  },
  "users": [
    {
      "password": "developer-password",
      "username": "developer"
    },
    {
      "password": "cluster_operator-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 v9.0.0 and later.

To install gfsh:

  1. Download the Pivotal GemFire ZIP archive from Pivotal Network.
  2. Unzip and locate the correct binary for your architecture. Use gfsh with Unix, or gfsh.bat with Windows.
  3. Add the gfsh binary to your path.
  4. Start the gfsh command-line tool. Then, from the gfsh> prompt, connect to your service instance as cluster_operator:
$ gfsh
    _________________________     __
   / _____/ ______/ ______/ /____/ /
  / /  __/ /___  /_____  / _____  /
 / /__/ / ____/  _____/ / /    / /
/______/_/      /______/_/    /_/    9.0.1

Monitor and Manage Pivotal GemFire

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

Connect with gfsh over HTTPS

Connecting over HTTPS involves a few more steps than connecting over HTTP, but it is required for some network setups. When connecting over HTTPS, you must use the same certificate you use to secure traffic into ERT; that is, the certificate you use where your TLS termination occurs. Before you can connect, you must create a truststore.

Create a Truststore

To create a truststore, use the same certificate you used to configure TLS termination. We suggest using the keytool command line utility to create a truststore file.

  1. Locate the certificate you use to configure TLS termination.
  2. Using your certificate, run the keytool command.

    For example:

    $ keytool -import -alias ENV -file CERTIFICATE.CER -keystore TRUSTSTORE-FILE-PATH"

    Where:

    • ENV is your system environment.
    • CERTIFICATE.CER is your certificate file.
    • TRUSTSTORE-FILE-PATH is the path to the location where you want to create the truststore file, including the name you want to give the file.
  3. When you run this command, you are prompted to enter a keystore password. Create a password and remember it!

  4. When prompted for the certificate details, enter yes to trust the certificate.

The following example shows how to run keytool and what the output looks like:

$ keytool -import -alias prod-ssl -file /tmp/loadbalancer.cer -keystore /tmp/truststore/prod.myTrustStore 
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

Establish the Connection with HTTPS

After you have created the truststore, you can connect using HTTPS.

  1. Download the Pivotal GemFire ZIP archive from Pivotal Network.
  2. Unzip and locate the correct binary for your architecture. Use gfsh with Unix or gfsh.bat with Windows.
  3. Add the gfsh binary to your path.
  4. Set the JAVA_ARGS environment variable with the following command:

    export JAVA_ARGS="-Djavax.net.ssl.trustStore=TRUSTSTORE-FILE-PATH"

    Where: TRUSTSTORE-FILE-PATH is the path to the TrustStore file you created in Create a Truststore.

    For example,

    $ export JAVA_ARGS="-Djavax.net.ssl.trustStore=/tmp/truststore/prod.myTrustStore"
    

  5. Using a URL starting with https, open the gfsh console and connect:

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

Monitor and Manage Pivotal GemFire

gfsh>connect --use-http --url=gfsh-url --user=cluster_operator --password=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:

  • 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   : NULL


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 PCC

A sample app written in pure Java has been put together 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.

Copy, update, and save the following sample manifest:

---
applications:
- name: sample_app
  path: build/libs/cloudcache-sample-app-1.0-SNAPSHOT-all.jar
  no-route: true
  health-check-type: none
  services:
  - service0  # replace this with the name of your service. Please refer
              # to docs above on how to create a cloud cache service instance.

Update the gradle.properties with your username and password used for https://commercial-repo.pivotal.io/

Run cf push -f PATH-TO-MANIFEST to deploy the app. Replace PATH-TO-MANIFEST with the path to the sample manifest you created.

After you push the app and it starts, you should see 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.

Connecting a Spring Boot App to PCC with SSC

This section describes the two ways in which you can connect a Spring Boot app to PCC:

  • Using a Tomcat app with a WAR file. This is the default method for Tomcat apps.
  • Using the spring-session-data-gemfire library. This method requires that you use the correct version of these libraries.

Use the Tomcat App

In PCC v1.1 and later, to get a Spring Boot app running with session state caching (SSC) on PCC, you must create a WAR file using the spring-boot-starter-tomcat plugin instead of the spring-boot-maven plugin to create a JAR file.

For example, if you want your app to use SSC, you cannot use spring-boot-maven to build a JAR file and push your app to PCF, because the Java buildpack does not pull in the necessary JAR files for SSC when it detects a Spring JAR file.

To build your WAR file, add this dependency to your pom.xml:

<dependency>
  <groupId>org.springframework.boot</groupId>
  <artifactId>spring-boot-starter-tomcat</artifactId>
  <scope>provided</scope>
</dependency>

For a full example of running a Spring Boot app that connects with SSC, run this app and use this following for your pom.xml:

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
  <modelVersion>4.0.0</modelVersion>

  <groupId>io.pivotal.gemfire.demo</groupId>
  <artifactId>HttpSessionCaching-Webapp</artifactId>
  <version>0.0.1-SNAPSHOT</version>
  <packaging>war</packaging>

  <name>HttpSessionCaching-Webapp</name>
  <description>Demo project for GemFire Http Session State caching</description>

  <parent>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-parent</artifactId>
    <version>1.5.3.RELEASE</version>
    <relativePath/> <!-- lookup parent from repository -->
  </parent>

  <properties>
    <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
    <project.reporting.outputEncoding>UTF-8</project.reporting.outputEncoding>
    <java.version>1.8</java.version>
  </properties>

  <dependencies>
    <dependency>
      <groupId>org.springframework.boot</groupId>
      <artifactId>spring-boot-starter-thymeleaf</artifactId>
    </dependency>

    <dependency>
      <groupId>org.springframework.boot</groupId>
      <artifactId>spring-boot-starter-tomcat</artifactId>
      <scope>provided</scope>
    </dependency>

    <dependency>
      <groupId>org.springframework.boot</groupId>
      <artifactId>spring-boot-starter-test</artifactId>
      <scope>test</scope>
    </dependency>
  </dependencies>

</project>

Use the Spring Session Data Gemfire App

You can connect your Spring app to PCC to do session state caching, but you must use the correct verion of the spring-session-data-gemfire library to do so. PCC v1.1.x only supports spring-session-data-gemfire version v2.0.0.M0.

PCC Version SSDG Verion
v1.1.x v2.0.0.M0

Example build.gradle file that works with PCC v1.1.x:

version = '0.0.1-SNAPSHOT'

buildscript {
    ext {
        springBootVersion = '2.0.0.M2'
    }
    repositories {
        mavenCentral()
        maven { url "https://repo.spring.io/snapshot" }
        maven { url "https://repo.spring.io/milestone" }
    }
    dependencies {
        classpath("org.springframework.boot:spring-boot-gradle-plugin:${springBootVersion}")
    }
}

apply plugin: 'java'
apply plugin: 'org.springframework.boot'
apply plugin: 'idea'

idea{
    module{
        downloadSources = true
        downloadJavadoc = true
    }
}

sourceCompatibility = 1.8
targetCompatibility = 1.8

repositories {
    mavenCentral()
    maven { url "https://repo.spring.io/libs-milestone" }
    maven { url "https://repo.spring.io/milestone" }
    maven { url "http://repo.springsource.org/simple/ext-release-local" }
    maven { url "http://repo.spring.io/libs-release/" }
    maven { url "https://repository.apache.org/content/repositories/snapshots" }
}


dependencies {
    compile("org.springframework.boot:spring-boot-starter-web:2.0.0.M3")
    compile("org.springframework.session:spring-session-data-gemfire:2.0.0.M0")
    compile("io.pivotal.spring.cloud:spring-cloud-gemfire-spring-connector:1.0.0.RELEASE")
    compile("io.pivotal.spring.cloud:spring-cloud-gemfire-cloudfoundry-connector:1.0.0.RELEASE")
    testCompile("org.springframework.boot:spring-boot-starter-test")
}
Create a pull request or raise an issue on the source for this page in GitHub