Quickstart Using VMware GemFire

This topic explains how to create a VMware GemFire cluster or service instance with the VMware GemFire for Redis Apps extension enabled.

VMware GemFire 9.15
VMware GemFire 10.0
VMware GemFire for TAS
VMware GemFire for Kubernetes

VMware GemFire 9.15

Prerequisites

VMware GemFire 9.15 installed.
VMware GemFire for Redis Apps 1.1 downloaded and unzipped as described in Downloading the VMware GemFire for Redis Apps Extension.
Path to the folder containing the downloaded and unzipped VMware GemFire for Redis Apps files.

Start a VMware GemFire Cluster

Open a terminal window.
In the terminal window, confirm that you have installed VMware GemFire 9.15 or later by running:
```
gfsh version
```
The output text should read 9.15.0 or later. If it does not, download and install VMware GemFire 9.15 or later. For installation instructions, see Installing VMware GemFire in the VMware GemFire documentation.
Start the GemFire CLI, gfsh, by running:
```
gfsh
```
At the gfsh prompt, start a locator for managing the VMware GemFire cluster:
```
gfsh> start locator
```
After the locator has started, start a server. Use the --classpath configuration option to specify the filepath to the folder where you unzipped the VMware GemFire for Redis Apps extension files to enable the extension:
```
gfsh> start server --name=redisServer1 --locators=localhost[10334] --server-port=40404 --classpath=/path/to/gemfire-for-redis-apps/folder/lib/* --J=-Dgemfire-for-redis-enabled=true
```
Start an additional server with the extension enabled by running the same start server command with different values for the --name and --gemfire-for-redis-port parameters:
```
gfsh> start server --name=redisServer2 --locators=localhost[10334] --server-port=40405 --classpath=/path/to/gemfire-for-redis-apps/folder/lib/* --J=-Dgemfire-for-redis-port=6380 --J=-Dgemfire-for-redis-enabled=true
```
Your GemFire cluster should now be running with one locator and two servers, ready to connect with a Redis client.
To confirm that your GemFire cluster is ready to accept Redis commands, run the list regions command
```
gfsh list regions
```
The output should include the GEMFIRE_FOR_REDIS region in the list of regions:
```
List of regions
-----------------
GEMFIRE_FOR_REDIS
```

At this point, the cluster is up and running and able to have Redis client applications connect and send commands.

Shut Down the VMware GemFire Cluster

To shut down the VMware GemFire cluster that you started, run the command below in the terminal window with gfsh running.

Caution
This command shuts down the entire VMware GemFire cluster. All data in the cluster will be lost.

gfsh> shutdown --include-locators=true

VMware GemFire 10.0

Prerequisites

VMware GemFire 10.0 installed.
VMware GemFire for Redis Apps 1.1 .gfm file downloaded as described in Downloading the VMware GemFire for Redis Apps Extension.

Start a VMware GemFire Cluster

Move the VMware GemFire for Redis Apps .gfm file to the /path_to_gemfire/extensions/ directory in your VMware GemFire installation.
Open a terminal window.
In the terminal window, confirm that you have installed VMware GemFire 10.0 or later by running:
```
gfsh version
```
The output text should read 10.0.0 or later. If it does not, download and install VMware GemFire 10.0.0 or later. For installation instructions, see Installing VMware GemFire in the VMware GemFire documentation.
Start the GemFire CLI, gfsh, by running:
```
gfsh
```
At the gfsh prompt, start a locator for managing the VMware GemFire cluster:
```
gfsh> start locator
```

After the locator has started, start a server:

gfsh> start server --name=redisServer1 --locators=localhost[10334] --server-port=40404 --J=-Dgemfire-for-redis-enabled=true

Start an additional server with the extension enabled by running the same start server command with different values for the --name and --gemfire-for-redis-port parameters:
```
gfsh> start server --name=redisServer2 --locators=localhost[10334] --server-port=40405 --J=-Dgemfire-for-redis-port=6380 --J=-Dgemfire-for-redis-enabled=true
```

Your GemFire cluster should now be running with one locator and two servers, ready to connect with a Redis client.

To confirm that your GemFire cluster is ready to accept Redis commands, run the list regions command
```
gfsh list regions
```
The output should include the GEMFIRE_FOR_REDIS region in the list of regions:
```
List of regions
-----------------
GEMFIRE_FOR_REDIS
```

At this point, the cluster is up and running and able to have Redis client applications connect and send commands.

Shut Down the VMware GemFire Cluster

To shut down the VMware GemFire cluster that you started, run the command below in the terminal window with gfsh running.

Warning: This command shuts down the entire VMware GemFire cluster. All data in the cluster will be lost.

gfsh> shutdown --include-locators=true

VMware GemFire for TAS

Prerequisites

Tanzu Application Service
The Cloud Foundry CLI (cf CLI)
VMware GemFire for TAS 1.14.8 or greater available in the marketplace.
Confirm that the port 6379 has been opened for the tile, according to the Networking for On-Demand Services.
VMware GemFire 9.15 installed.

Confirm GemFire Service Instance Availability in the Marketplace

The following instructions use the cf CLI; however, users can also confirm using the Apps Manager user interface if it is available to them.

Once logged in, run the cf marketplace command to see available services in the marketplace and confirm that a service with the description VMware GemFire appears in the list.

For example:

$ cf marketplace
Getting services from marketplace in org system / space system as admin...
OK
service       plans     description                                      broker
nfs           Existing  Existing NFSv3 and v4 volumes                    nfsbroker
p-cloudcache  dev-plan  VMware GemFire(version "9.15.5-build.1622")  cloudcache-broker

Start VMware GemFire Service Instance with GemFire for Redis Apps Add-on Enabled

Open a terminal window and log in to the space you would like to start the GemFire for TAS service instance.
Enable APIs for Redis and add the “redis” tag to your VMware GemFire for TAS service.
- When creating a new service, include -c '{"gemfire_for_redis_enabled":true} -t redis to the cf create-service command. Additional configuration of the VMware GemFire for TAS service instance with GemFire for Redis Apps enabled can be achieved using the parameters listed in the GemFire for TAS documentation.
  
  For example:
```
$ cf create-service p-cloudcache PLAN-NAME YOUR-SERVICE-INSTANCE-NAME -c '{"gemfire_for_redis_enabled":true}' -t redis
```
- When updating an existing service, add -c '{"gemfire_for_redis_enabled":true} -t "redis to the cf update-service command. Additional configuration of the VMware GemFire for TAS service instance with GemFire for Redis Apps enabled can be achieved using the parameters listed in the GemFire for TAS documentation.
  
  For example:
```
$ cf update-service YOUR-SERVICE-NAME -c '{"gemfire_for_redis_enabled":true}' -t "redis"
```
  Note: Updating the service causes all members of the cluster to restart.
(Optional) Transport Layer Security (TLS): VMware GemFire for TAS allows service instances to be created with Transport Layer Security (TLS) enabled. The behavior of TLS with GemFire for TAS and GemFire for Redis Apps differs from the Redis for TAS tile, which allows TLS and non-TLS ports to be active at the same time on a single service instance. GemFire for TAS only allows TLS to be on or off, not both/optional.

TLS can only be enabled during service instance creation. If you enable TLS, all connections must be made using a TLS-capable client. The non-TLS port will be unavailable.

To enable GemFire for Redis Apps and TLS on a VMware GemFire for TAS service instance, add tls:true to the parameters passed to the cf create-service command:

For example:
```
$ cf create-service p-cloudcache PLAN-NAME YOUR-SERVICE-INSTANCE-NAME -c '{"gemfire_for_redis_enabled":true,"tls":true}' -t redis
```
Note: This enables TLS for the entire cluster.

Confirm Add-on Enabled

To confirm that the GemFire for Redis Apps add-on is enabled, when the cluster is up and running, confirm that the GEMFIRE_FOR_REDIS region is present in the cluster.

Create a service key by running the following command:
```
cf create-service-key MY-SERVICE-INSTANCE MY-KEY
```

Inspect the service key:

cf service-key MY-SERVICE-INSTANCE MY-KEY

This returns a JSON response (VCAP_SERVICES) which includes a connection string to use with GemFire Shell (gfsh).

For example:

{...
  "gfsh_login_string": "connect
   --url=https://cloudcache-1.example.com/gemfire/v1
   --user=cluster_operator_XXX --password=cluster_operator-password --skip-ssl-validation"
}

Open a separate terminal window.
In the terminal window, confirm that you have installed VMware GemFire 9.15 or later by running:
```
gfsh version
```
The output text should read 9.15.0 or later. If it does not, download and install VMware GemFire 9.15 or later. For installation instructions, see Installing VMware GemFire in the VMware GemFire documentation.
Start the GemFire CLI, gfsh, by running:
```
gfsh
```

Copy the content following the gfsh_login_string in the service instance key (step 2, above) and paste it into the gfsh terminal.

gfsh connect --url=https://cloudcache-1.example.com/gemfire/v1 --user=cluster_operator_XXX --password=cluster_operator-password --skip-ssl-validation

Once connected to the service instance run the list regions command
```
gfsh list regions
```
The output should include the following:
```
List of regions
-----------------
GEMFIRE_FOR_REDIS
```
At this point, the service instance is up and running and able to have Redis client applications bind to the GemFire service instance.
For information about how to bind a Spring Boot and Redis client application to the GemFire service instance, see Application Development
For more information about connecting to a GemFire service instance, see Accessing a Service Instance in the VMware GemFire for TAS documentation.

VMware GemFire for Kubernetes

Start a VMware GemFire Kubernetes Cluster

Follow the steps in this section to create a VMware GemFire for Kubernetes cluster with the VMware GemFire for Redis Apps extension enabled.

Prerequisites

A Kubernetes Cluster
A VMware Tanzu Network account or the ability to access the VMware GemFire for Redis Apps image.

Start a VMware GemFire Kubernetes Cluster With GemFire 9.15

Follow the instructions in the GemFire for Kubernetes documentation to install the VMware GemFire Operator.

Once the operator is installed create a yaml file that will be used to start your VMware GemFire cluster, note the name of the file as this will be used in the next step.

For example, a simple yaml file may look like the following:

apiVersion: gemfire.vmware.com/v1
kind: GemFireCluster
metadata:
  name: gemfirecluster-with-redis-sample
spec:
  # Avoid using the "latest" tag in production as it is harder to track which
  # version of the image is running and may cause members to upgrade
  # unexpectedly.
  image: registry.tanzu.vmware.com/pivotal-gemfire/vmware-gemfire:9.15.4
  # Set antiAffinityPolicy to "Cluster" or "Full" in production to limit the
  # chance of data loss.
  antiAffinityPolicy: None
  security:
    tls: {}
  metrics:
    emission: Default
  locators:
    replicas: 2
    resources:
      requests:
        memory: 1Gi
  servers:
    replicas: 2
    resources:
      requests:
        memory: 1Gi
    libraries:
      - name: gemfire-for-redis-apps
        container:
          image: registry.tanzu.vmware.com/tanzu-gemfire-for-redis-apps/gemfire-for-redis-apps:1.1.0
          path: "/gemfire-for-redis-apps/*"
          imagePullSecretRef:
            name: image-pull-secret
    overrides:
      jvmOptions: ["-Dgemfire-for-redis-enabled=true"]

Create a VMware GemFire cluster with VMware GemFire for Redis Apps by applying the file created above to your Kubernetes cluster.
```
kubectl apply -f GEMFIRE-CLUSTER-YAML-FILE.yaml -n NAMESPACE-NAME
```

Once the cluster has started running confirm that VMware GemFire for Redis Apps has been deployed correctly. This can be accomplished by first connecting to the VMware GemFire cluster’s server pod, and checking the version.

Start the GemFire CLI (gfsh) on a server pod by running the following command:
```
kubectl -n NAMESPACE-NAME exec -it NAME-OF-GEMFIRE-SERVER-POD-0 -- gfsh
```
Once gfsh is running, run the version command
```
gfsh> version --full
```

The output should look similar to the following:

...
----------------------------------------
VMware GemFire for Redis Apps
----------------------------------------
GemFire-For-Redis-Apps-Source-Repository: support/1.1
GemFire-For-Redis-Apps-Source-Revision: 2b44cab354cfcec854c5c42205d84841dec037f9
GemFire-For-Redis-Apps-Version: 1.1.0
GemFire-For-Redis-Apps-Source-Date: 2023-03-01 15:03:50 -0800
...

Exit the current gfsh connection
```
gfsh> exit
```

Now we will confirm that VMware GemFire for Redis Apps has created the default region that will hold our Redis data.
- Start gfsh on a locator pod:
```
kubectl -n NAMESPACE-NAME exec -it NAME-OF-GEMFIRE-LOCATOR-POD-0 -- gfsh
```
- Connect to the locator using the connect command:
```
gfsh> connect --locator=NAME-OF-GEMFIRE-LOCATOR-POD-0[10334]
```
- List the cluster regions
```
gfsh> list regions
```
- The output should be similar to the following:
```
List of regions
-----------------
GEMFIRE_FOR_REDIS
```
- Exit the current gfsh connection
```
gfsh> exit
```

At this point the cluster is up and running and able to have Redis client applications connect and send commands.

Start a VMware GemFire Kubernetes Cluster With GemFire 10.0

Follow the instructions in the GemFire for Kubernetes documentation to install the VMware GemFire Operator version 2.2.

Once the operator is installed create a yaml file that will be used to start your VMware GemFire cluster, note the name of the file as this will be used in the next step.

For example, a simple yaml file may look like the following:

apiVersion: gemfire.vmware.com/v1
kind: GemFireCluster
metadata:
  name: gemfirecluster-with-redis-sample
spec:
  # Avoid using the "latest" tag in production as it is harder to track which
  # version of the image is running and may cause members to upgrade
  # unexpectedly.
  image: registry.tanzu.vmware.com/pivotal-gemfire/vmware-gemfire:10.0.0
  # Set antiAffinityPolicy to "Cluster" or "Full" in production to limit the
  # chance of data loss.
  antiAffinityPolicy: None
  security:
    tls: {}
  metrics:
    emission: Default
  locators:
    replicas: 2
    resources:
      requests:
        memory: 1Gi
  servers:
    replicas: 2
    resources:
      requests:
        memory: 1Gi
    libraries:
      - name: gemfire-for-redis-apps
        container:
          image: registry.tanzu.vmware.com/tanzu-gemfire-for-redis-apps/gemfire-for-redis-apps:1.1.0
          path: "/gemfire-for-redis-apps-gfm/*"
          imagePullSecretRef:
            name: image-pull-secret
    overrides:
      jvmOptions: ["-Dgemfire-for-redis-enabled=true"]

Create a VMware GemFire cluster with VMware GemFire for Redis Apps by applying the file created above to your Kubernetes cluster.
```
kubectl apply -f GEMFIRE-CLUSTER-YAML-FILE.yaml -n NAMESPACE-NAME
```

Start the GemFire CLI (gfsh) on a server pod by running the following command:
```
kubectl -n NAMESPACE-NAME exec -it NAME-OF-GEMFIRE-SERVER-POD-0 -- gfsh
```
Once gfsh is running, run the version command
```
gfsh> version --full
```

The output should look similar to the following:

...
----------------------------------------
VMware GemFire for Redis Apps
----------------------------------------
GemFire-For-Redis-Apps-Source-Repository: support/1.1
GemFire-For-Redis-Apps-Source-Revision: 496078ba99319578aa235d084f46745d89cf2d5f
GemFire-For-Redis-Apps-Version: 1.1.0
GemFire-For-Redis-Apps-Source-Date: 2022-07-28 10:04:01 -0700
...

Exit the current gfsh connection
```
gfsh> exit
```

Now we will confirm that VMware GemFire for Redis Apps has created the default region that will hold our Redis data.
- Start gfsh on a locator pod:
```
kubectl -n NAMESPACE-NAME exec -it NAME-OF-GEMFIRE-LOCATOR-POD-0 -- gfsh
```
- Connect to the locator using the connect command:
```
gfsh> connect --locator=NAME-OF-GEMFIRE-LOCATOR-POD-0[10334]
```
- List the cluster regions
```
gfsh> list regions
```
- The output should be similar to the following:
```
List of regions
-----------------
GEMFIRE_FOR_REDIS
```
- Exit the current gfsh connection
```
gfsh> exit
```

At this point the cluster is up and running and able to have Redis client applications connect and send commands.

Shut Down the VMware GemFire for Kubernetes Cluster

To shut down the VMware GemFire for Kubernetes cluster, follow the steps in Create or Delete a VMware GemFire Cluster in the VMware GemFire for Kubernetes documentation.