Using Session State Caching Powered by GemFire on Pivotal Cloud Foundry®

As you would expect with any data service on Pivotal Cloud Foundry® (PCF), the Session State Caching service simplifies the deployment and configuration of software that supports your applications. When you create a Session State Caching service instance, you are instantly provided with a dedicated instance of GemFire software without having to install and manage the underlying virtual machines or software manually.

About Session State Caching

Session State Caching Powered by GemFire can provide fast, scalable, and reliable session replication for your web applications without requiring application changes.

Using Session State Caching Powered by GemFire is useful in a Pivotal Cloud Foundry® environment because Pivotal Cloud Foundry® does not persist or replicate HTTP session data. This can be problematic when an instance of an application has crashed or stopped. The Session State Caching service makes session data available after an application crashes or stops and across all instances of an application.

Creating a Session State Caching Service Instance

The following procedure describes how to create a Session State Caching service instance in the Pivotal Cloud Foundry® Elastic Runtime environment.

PCF Developer Console Instructions

  1. Log in to the Pivotal Cloud Foundry® Developer Console.
  2. Select your Org from the drop-down list on the left.
  3. Select Marketplace from the left navigation menu under Spaces. The Services Marketplace displays the following:

    SSC Powered by GemFire Marketplace

  4. Select Session State Caching Powered by GemFire. The Session State Caching Powered by GemFire service page displays. The service page displays details on the plan, such as cost and active features. The service plan details are configured by your Cloud Foundry administrator when they install the service in Pivotal Cloud Foundry® Ops Manager.

    SSC Powered by GemFire Marketplace

  5. To create the service instance, click on the appropriate Select this plan button. The Configure Instance screen appears.

  6. In the Instance Name field, enter a name that will identify this specific Session State Caching service instance.

  7. From the Add to Space drop-down list, select the space where you or other users will deploy the applications that will bind to the service.

  8. (Optional) Select an application from the Bind to App drop-down list. The drop-down list displays available applications previously configured for this Org and Space. If you do not want to bind an application, select [do not bind]. You can bind your application later as described in Binding an Application to the GemFire Service.

  9. Click the Add button.

    Note: A GemFire instance (cluster) must be available for allocation. If all deployed GemFire instances have been allocated, you will receive an error. You will either need to delete existing service instances or ask the admin to deploy more instances in Ops Manager. See also Problem: Could not deploy a service instance in the Elastic Runtime.

CLI Instructions

  1. If you have not done so already, install the Pivotal Cloud Foundry® Command Line Interface. See Installing the cf CLI. (Installation binaries are available here).

  2. Log in to PCF using the cf CLI.

    $ cf login

  3. Run the following command to target the API endpoint, org, and space where you want to create the service:

    $ cf target -a API-ENDPOINT -o ORG-NAME -s SPACE-NAME

  4. Run the following command to view the available service plans:

    $ cf marketplace

    Getting services from marketplace in org staging / space staging as admin...
    OK
    service         plans                description
    p-ssc-gemfire   SessionReplication   Dedicated GemFire instance for storing HTTP session state.
    TIP:  Use 'cf marketplace -s SERVICE' to view descriptions of individual plans of a
    given service.
    
  5. Type the following command to create the service plan:

    $ cf create-service p-ssc-gemfire SERVICE-PLAN-NAME SERVICE-INSTANCE-NAME

    where SERVICE-PLAN-NAME is the name of the Service Plan you see in the marketplace, in this example, SessionReplication, and SERVICE-INSTANCE-NAME is a descriptive name that you want to use for the service.

    For example:

    $ cf create-service p-ssc-gemfire SessionReplication my-ssc-gemfire-test
    Creating service my-ssc-gemfire-test in org staging / space staging as admin...
    OK
    

Deploying Applications for Use with the Session State Caching Service

This section provides tips on pushing your application to the Pivotal Cloud Foundry® Elastic Runtime environment for use with the Session State Caching service. Some of the application deployment steps may differ depending on what kind of application you are deploying. Currently this service only supports the Java Buildpack.

You will eventually want to scale your application to two or more instances for the purposes of achieving session replication.

Re-deploying your application does not affect data stored in any existing service instances bound to the application.

See Deploy an Application in the Pivotal Cloud Foundry® Documentation for detailed information on pushing CF applications.

Using the Java Buildpack

The Java Buildpack has been customized specifically for use with Session State Caching Powered by GemFire. When you use the Java Buildpack, your application automatically discovers the service environment variables and credentials, and no specific application configuration is required. See Example Walkthrough: Binding a Spring Java Application to a GemFire Service Instance for an example of this.

Important: Pivotal recommends that you use the latest Java Buildpack when pushing your applications. Specify the location of the buildpack using the -b parameter:

$ cf push YOUR-APP-NAME -p LOCATION-OF-YOUR-APP-FILE \
-b https://github.com/cloudfoundry/java-buildpack.git

To avoid having to restage your application after binding the service, you can push the application initially with the --no-start command:

$ cf push YOUR-APP-NAME -p LOCATION-OF-YOUR-APP-FILE \
 -b https://github.com/cloudfoundry/java-buildpack.git --no-start

Binding an Application to the Session State Caching Service

The following procedures describe how to bind a Session State Caching service instance to your Pivotal Cloud Foundry® application.

PCF Developer Console Instructions

  1. Log in to the Pivotal Cloud Foundry® Developer Console.

  2. Select your Org from the drop-down list on the left. This should be the same Org where you created the service instance.

  3. Select the space where your Session State Caching service instance and bound application have been deployed.

  4. Select the application that you wish to bind to the service. A page displays showing the already bound services and instances for this application.

  5. Click Bind. A list of available services displays.

    Service Binding

  6. Click the Bind button for the GemFire service you want to bind to this application.

  7. Using the Pivotal Cloud Foundry® CLI, start or restage your application. See Pushing or Restaging Applications After Changes.

CLI Instructions

Alternately via the CLI:

  1. Log in to your Pivotal Cloud Foundry® environment using the Pivotal Cloud Foundry® CLI.

    $ cf login

  2. Run the following command to target the specific org and space where you want to create the service plan.

    $ cf target -o ORG-NAME -s SPACE-NAME

  3. Run the following command to view running service instances:

    $ cf services

    Getting services in org staging / space staging as admin...
    OK
    name              service          plan                 bound apps
    my-ssc-gemfire-test   p-ssc-gemfire   SessionReplication
    
  4. Run the following command to bind the application to the service instance:

    $ cf bind-service APP-NAME SERVICE-INSTANCE-NAME

    For example:

    $ cf bind-service spring-petclinic my-ssc-gemfire-test
    Binding service my-ssc-gemfire-test to app spring-petclinic
    in org staging / space  staging as admin...
    OK
    TIP: Use 'cf restage' to ensure your env variable changes take effect
    
  5. Restage your application.

    $ cf restage APP-NAME

Pushing or Restaging Applications After Service Changes

To ensure that your application picks up the correct environment variables, you must restage or re-push your applications after binding them to the GemFire service. This can currently be done using the CLI. In addition, if you make any other changes to the GemFire Service while it is bound to your application (for example, add, modify or delete the service), you will need to re-push or restage your application afterwards.

Pushing or re-staging your application does not affect data stored in the existing service instance.

To restage or re-push your application using the Pivotal Cloud Foundry® CLI:

  1. Log in to your Pivotal Cloud Foundry® environment using the Pivotal Cloud Foundry® CLI.

    $ cf login

  2. Run the following command to target the API endpoint, org and space where you want to push or restage the application. For example:

    $ cf target -a API-ENDPOINT -o ORG-NAME -s SPACE-NAME

  3. Push or restage your existing application:

    $ cf push APP-NAME -p LOCATION-OF-YOUR-APP-FILE -b BUILDPACK-LOCATION

    or

    $ cf restage APP-NAME

    Alternately, if you pushed your application without starting it, you can start your application now to pick up the newly bound service.

    $ cf start APP-NAME

For more details on deploying applications, see Deploy an Application in the Pivotal Cloud Foundry® documentation.

Viewing Binding Meta Data and Environment Variables

To view the binding variables, use the following procedures.

PCF Developer Console Instructions

  1. Log in to the Pivotal Cloud Foundry® Developer Console.
  2. Select your Org from the drop-down list on the left.
  3. Select the space where your Session State Caching service instance and bound application have been deployed.
  4. Select the application that you have bound to the Session State Caching service.
  5. Click on the Env Variables tab. The environment variables for the service binding display:

    GemFire Service Bindings

    Alternately, you can also view credentials used by the service when binding to the application by clicking on the Services tab and clicking Show credentials.

    Service credentials and locator address information displays:

    GemFire Credentials

CLI Instructions

To view the binding variables in the CLI, type the following command after you have bound your application to the GemFire service:

$ cf env APP-NAME

If successful, you should see content similar to the following in the returned output:

$ cf env spring-petclinic
Getting env variables for app spring-petclinic in org staging / space staging as admin...
OK
System-Provided:
{
 "VCAP_SERVICES": {
  "p-ssc-gemfire": [
   {
    "credentials": {
     "locators": [
      "10.0.0.49[55221]",
      "10.0.0.50[55221]"
     ],
     "password": "16586576749095366067",
     "username": "610e0259-a08d-4d10-7728-9b3c278f1e11"
    },
    "label": "p-ssc-gemfire",
    "name": "my-ssc-gemfire-test",
    "plan": "SessionReplication",
    "tags": [
     "gemfire",
     "session_replication"
    ]
   }
  ]
 }
}
No user-defined env variables have been set
No running env variables have been set
No staging env variables have been set

Unbinding an Application from the Session State Caching Service

When you create a Session State Caching service instance, the SSC GemFire Service Broker allocates a specific cluster of GemFire locators and servers. You can bind, unbind and the bind again to that particular service instance as often as you want. The service instance always uses the same cluster and the Service Broker does not do anything to the data in that service instance.

PCF Developer Console Instructions

To unbind the application from the GemFire service:

  1. Log in to the Pivotal Cloud Foundry® Developer Console.
  2. Select your Org from the drop-down list on the left.
  3. Select the space where your Session State Caching service instance and bound application have been deployed.
  4. Select the application that you have bound to the Session State Caching service. A page displays that show the bound services and instances for this application.
  5. Locate the bound service instance you want to unbind and click Unbind.

    Unbinding a GemFire Service

  6. A confirmation dialog box displays. Click Unbind again.

  7. If successful, the following message will appear at the top of the screen:

    Service successfully unbound from the application. TIP: Use ‘cf push’ to ensure your env variable changes take effect.
  8. Use the Pivotal Cloud Foundry® CLI to push or restage your application for the changes to take effect. See Pushing or Restaging Applications After Changes.

CLI Instructions

  1. Log in to your Pivotal Cloud Foundry® environment using the Pivotal Cloud Foundry® CLI.

    $ cf login

  2. Run the following command to target the org and space where you want to push or restage the application. For example:

    $ cf target -o ORG-NAME -s SPACE-NAME

  3. Run the following command:

    $ cf unbind-service APP-NAME SERVICE-INSTANCE-NAME

    where SERVICE-INSTANCE-NAME is the name of the GemFire instance you are unbinding from the specified APP-NAME.

    For example:

    $ cf unbind-service spring-petclinic my-ssc-gemfire-test
    Unbinding app spring-petclinic from service my-ssc-gemfire-test in org staging / space
    staging as admin...
    OK
    
  4. Restage or re-push your application for the application changes to take effect. See Pushing or Restaging Applications After Changes.

Deleting a Session State Caching Service Instance

When you delete a Session State Caching service instance, all applications that are bound to that service are automatically unbound and any data in the service instance is cleared. In addition, the allocated service instance (GemFire cluster) is returned to the pool of available clusters and those locators and cache servers are now available to future applications.

PCF Developer Console Instructions

To delete a service instance using the Pivotal Cloud Foundry® Developer Console:

  1. Log in to the Pivotal Cloud Foundry® Developer Console.
  2. Select your Org from the drop-down list on the left.
  3. Locate the row under Services that contains the service instance you want to delete and click Delete.
  4. If you had applications that were bound to this service, you may need to restage or re-push your application for the application changes to take effect. See Pushing or Restaging Applications After Changes.

CLI Instructions

  1. Log in to your Pivotal Cloud Foundry® environment using the Pivotal Cloud Foundry® CLI.

    $ cf login

  2. Run the following command to target the org and space where you want to push or restage the application. For example:

    $ cf target -o ORG-NAME -s SPACE-NAME

  3. Run the following command:

    $ cf delete-service SERVICE-INSTANCE-NAME

    where SERVICE-INSTANCE-NAME is the name of the Session State Caching service you are deleting. Enter ‘y’ when prompted.

    For example:

    $ cf delete-service my-ssc-gemfire-test
    Really delete the service my-ssc-gemfire-test?> y
    Deleting service my-gemfire-test in org staging / space staging as admin...
    OK

  4. If you had applications that were bound to this service, you may need to restage or re-push your application for the application changes to take effect. See Pushing or Restaging Applications After Changes.

Example Walkthrough: Deploying a Spring Java Application with Session State Caching Powered by GemFire

This section provides a step-by-step example of deploying and binding a Spring Java sample application to the Session State Caching service on Pivotal Cloud Foundry®. After deploying the application, we’ll look at how GemFire manages session replication by querying session data in GemFire’s Pulse monitoring tool.

For demonstration purposes, we’ll use the Spring PetClinic application and the session replication-enabled GemFire service. To follow the steps in this walkthrough, you will need:

  • git command line tool
  • Maven 3
  • Pivotal Cloud Foundry® installation
  • Pivotal Session State Caching service plan installation in your Elastic Runtime environment
  • access to a Pivotal Cloud Foundry® Developer Console
  • cf Command Line Interface (cf CLI) tool

Step 1: Download and package the sample application

  1. Open a terminal. In a working directory, download the Spring Petclinic application from GitHub:

    $ git clone https://github.com/SpringSource/spring-petclinic.git

  2. Change directories to the spring-petclinic directory.

    $ cd spring-petclinic

  3. Build the application WAR file with Maven.

    $ mvn package

    As defined by the project’s pom.xml file, this command will build the following file in the following location within the spring-petclinic directory:

    target/petclinic.war

Step 2: Push the PetClinic application to Pivotal Cloud Foundry®

  1. Log in to your Pivotal Cloud Foundry® environment using the Pivotal Cloud Foundry® CLI.

    $ cf login

  2. This step requires that you have a running Pivotal Cloud Foundry® environment where you can push your applications. Run the following command to target the API endpoint, org and space where you will run the application. For example:

    $ cf target -a API-ENDPOINT -o ORG-NAME -s SPACE-NAME

  3. Push the petclinic application to your Pivotal Cloud Foundry® installation:

    $ cf push spring-petclinic -p target/petclinic.war -i 2 \ -b https://github.com/cloudfoundry/java-buildpack.git --no-start

    This command specifies that the Pivotal Cloud Foundry® specifies the location of the application file and the Java buildpack to use. Since we are using Session State Caching for session state replication, we will run two instances of the application. In addition, we will specify the --no-start option so that we can pick up the bound service before starting the application. After running the command, you should see output similar to the following:

    $ cf push spring-petclinic -p target/petclinic.war -i 2
    -b https://github.com/cloudfoundry/java-buildpack.git --no-start
    Creating app spring-petclinic in org staging / space staging as admin...
    OK
    
    Using route spring-petclinic.pandora.boxes.cf-app.com
    Binding spring-petclinic.pandora.boxes.cf-app.com to spring-petclinic...
    OK
    
    Uploading spring-petclinic...
    Uploading app files from: target/petclinic.war
    Uploading 730.4K, 140 files
    Done uploading
    OK
    
  4. Keep this terminal open for step 5.

Step 3: Create a Pivotal GemFire Service Instance

Note: This step assumes that your Pivotal Cloud Foundry® Administrator has already deployed Session State Caching Powered by GemFire to your Elastic Runtime environment and that it is available from the Marketplace. See Installing the Pivotal GemFire Service for Pivotal Cloud Foundry® for instructions.

Next, we will create a service instance in your environment.

  1. Log in to the Pivotal Cloud Foundry® Developer Console.
  2. Select your Org from the drop-down list on the left.
  3. Select Marketplace from the left navigation menu under Spaces. The Services Marketplace displays.
  4. Select Session State Caching Powered by GemFire. The Session State Caching service page displays.

    Creating a GemFire Service

  5. To create the service instance, click on the appropriate Select this plan button. The Configure Instance screen appears.

  6. In the Instance Name field, enter a descriptive name for this Session State Caching service instance– for example, “my-ssc-gemfire-test”.

  7. Select a space from the Add to Space drop-down list.

  8. From the Bind to App drop-down list, select [do not bind]. We will bind the application in the next step. Click the Add button.

Step 4: Bind the Pivotal GemFire service to your application

  1. Select the space where your Pivotal GemFire service instance and spring-petclinic have been deployed.
  2. Select the spring-petclinic application. A page displays showing recent logs and application activity.

    Application Page At this point, the application is not yet running.

  3. Click on the Services tab.

  4. Click on the Bind a service button. A list of available services displays. Application Page - Bind a Service

  5. Click the Bind button for the GemFire service you created in Step 3.

  6. Click the Play button on the application to start the bound application instances.

    Application Page - Bind a Service Success

  7. Alternatively, return to your open terminal. Using the Pivotal Cloud Foundry® CLI, start your application.

    $ cf start spring-petclinic

    You should see output similar to the following:

    Starting app spring-petclinic in org staging / space staging as admin...
    -----> Downloaded app package (26M)
    Cloning into '/tmp/buildpacks/java-buildpack'...
    -----> Java Buildpack Version: 623c428 | https://github.com/cloudfoundry/java-buildpack.git#623c428
    -----> Downloading Open Jdk JRE 1.8.0\_40 from https://download.run.pivotal.io/openjdk/lucid/x86_64/openjdk-1.8.0_40.tar.gz (2.3s)
       Expanding Open Jdk JRE to .java-buildpack/open\_jdk\_jre (3.1s)
    -----> Downloading Spring Auto Reconfiguration 1.7.0\_RELEASE from https://download.run.pivotal.io/auto-reconfiguration/auto-reconfiguration-1.7.0\_RELEASE.jar (0.1s)
       Modifying /WEB-INF/web.xml for Auto Reconfiguration
    -----> Downloading Tomcat Instance 8.0.20 from https://download.run.pivotal.io/tomcat/tomcat-8.0.20.tar.gz (0.4s)
       Expanding Tomcat to .java-buildpack/tomcat (0.3s)
    -----> Downloading Tomcat Lifecycle Support 2.4.0\_RELEASE from https://download.run.pivotal.io/tomcat-lifecycle-support/tomcat-lifecycle-support-2.4.0\_RELEASE.jar (0.0s)
    -----> Downloading Tomcat Logging Support 2.4.0\_RELEASE from https://download.run.pivotal.io/tomcat-logging-support/tomcat-logging-support-2.4.0\_RELEASE.jar (0.0s)
    -----> Downloading Tomcat Access Logging Support 2.4.0\_RELEASE from https://download.run.pivotal.io/tomcat-access-logging-support/tomcat-access-logging-support-2.4.0\_RELEASE.jar (0.0s)
    -----> Downloading GemFire 8.0.0 from https://download.run.pivotal.io/gem-fire/gem-fire-8.0.0.jar (3.4s)
    -----> Downloading GemFire Logging API 1.5.8 from https://download.run.pivotal.io/slf4j-api/slf4j-api-1.5.8.jar (0.5s)
    -----> Downloading GemFire Logging 1.5.8 from https://download.run.pivotal.io/slf4j-jdk14/slf4j-jdk14-1.5.8.jar (0.4s)
    -----> Downloading GemFire Modules 8.0.0\_1 from https://download.run.pivotal.io/gem-fire-modules/gem-fire-modules-8.0.0\_1.jar (1.2s)
    -----> Downloading GemFire Modules Tomcat7 8.0.0\_1 from https://download.run.pivotal.io/gem-fire-modules-tomcat7/gem-fire-modules-tomcat7-8.0.0_1.jar (0.5s)
    -----> Downloading GemFire Security 8.0.0 from https://download.run.pivotal.io/gem-fire-security/gem-fire-security-8.0.0.jar (0.5s)
    -----> Uploading droplet (89M)
    0 of 2 instances running, 2 starting
    0 of 2 instances running, 2 starting
    0 of 2 instances running, 2 starting
    0 of 2 instances running, 2 starting
    2 of 2 instances running
    App started
    OK
    App spring-petclinic was started using this command ``
    Showing health and status for app spring-petclinic in org staging / space staging as admin...
    OK
    requested state: started
    instances: 2/2
    usage: 1G x 2 instances
    urls: spring-petclinic.pandora.boxes.cf-app.com
    last uploaded: Mon Mar 16 20:16:03 +0000 2015
          state     since                    cpu    memory         disk
    \#0   running   2015-03-16 01:25:23 PM   0.0%   697.5M of 1G   168.4M of 1G
    \#1   running   2015-03-16 01:25:23 PM   0.0%   691.2M of 1G   168.4M of 1G
    

Step 5: Run the sample application in different web browsers

  1. Return to the Pivotal Cloud Foundry® Developer Console and the spring-petclinic application page.
  2. Locate the route of the web app. Application Page with Route Link

  3. Click on this link to launch the web application in your browser. You should see the following web page appear: Pet Clinic Site

  4. Open this web application in multiple browsers. Click around the Spring PetClinic application. Using different browser clients, try adding data and searching for data.

Step 6: Query session replication data in the Pulse Monitoring tool

  1. Return to the Pivotal Cloud Foundry® Developer Console.
  2. On the spring-petclinic application page, click on the Services tab.
  3. Under the list of Services, locate the Manage link for the Session State Caching service that you created in step Manage Link

    This link launches the Pivotal GemFire Pulse Monitoring tool.

  4. If you haven’t done so already, select Authorize on the Application Authorization page for Pulse.

    Authorization

  5. After authorizing single sign-on authorization, the Pulse Monitoring the tool launches in Cluster View mode.

    Pulse Cluster View

    Notice that the cluster has five members– three GemFire servers and two GemFire locators as defined for a Session State Caching service instance. The number of clients reflects the two instances of the spring-petclinic application bound to the service. If you scale the application in Cloud Foundry by increasing the number of application instances, the number of clients will increase accordingly. In addition, there is one region called /sessions which is created by default.

  6. Click on Data to view the default /sessions region. Mouse over the region space. A popup displays the entry count and size of the region.

    Pulse Data View

  7. Next, click on the Data Browser tab to query the region. Enter the following queries into the Query Editor box.

    select count(*) from /sessions

    This query returns the number of session records in the region. In this case, 2.

    Pulse Data Browser - select count

    Delete the existing query and enter in the following query:

    select id from /sessions

    This query returns a list of session ids found in the region.

    Pulse Data Browser - select id

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