Tutorial Creating and Using a Cluster Configuration

A short walk-through that uses a single computer to demonstrate how to use gfsh to create a cluster configuration for a Geode cluster.

The gfsh command-line tool allows you to configure and start a Geode cluster. The cluster configuration service uses Apache Geode locators to store the configuration at the group and cluster levels and serves these configurations to new members as they are started. The locators store the configurations in a hidden region that is available to all locators and also write the configuration data to disk as XML files. Configuration data is updated as gfsh commands are executed.

This section provides a walk-through example of configuring a simple Apache Geode cluster and then re-using that configuration in a new context.

Create a working directory (For example:/home/username/my_geode) and switch to the new directory. This directory will contain the configurations for your cluster.

Start the gfsh command-line tool. For example:

$ gfsh

The gfsh command prompt displays.

    _________________________     __
   / _____/ ______/ ______/ /____/ /
  / /  __/ /___  /_____  / _____  /
 / /__/ / ____/  _____/ / /    / /
/______/_/      /______/_/    /_/    1.15

Monitor and Manage Apache Geode
gfsh>

Start a locator using the command in the following example:

gfsh>start locator --name=locator1
Starting a Geode Locator in /Users/username/my_geode/locator1...
.............................
Locator in /Users/username/my_geode/locator1 on 192.0.2.0[10334] as locator1
  is currently online.
Process ID: 70919
Uptime: 12 seconds
Geode Version: 1.15
Java Version: 8.0.121
Log File: /Users/username/my_geode/locator1/locator1.log
JVM Arguments: -Dgemfire.enable-cluster-configuration=true
-Dgemfire.load-cluster-configuration-from-dir=false
-Dgemfire.launcher.registerSignalHandlers=true -Djava.awt.headless=true
-Dsun.rmi.dgc.server.gcInterval=9223372036854775806
Class-Path: /Users/username/geode115/lib/geode-dependencies.jar

Successfully connected to: JMX Manager [host=192.0.2.0, port=1099]

Cluster configuration service is up and running.

Note that gfsh responds with a message indicating that the cluster configuration service is up and running. If you see a message indicating a problem, review the locator log file for possible errors. The path to the log file is displayed in the output from gfsh.

Start Apache Geode servers using the commands in the following example:

gfsh>start server --name=server1 --groups=group1
Starting a Geode Server in /Users/username/my_geode/server1...
.....
Server in /Users/username/my_geode/server1 on 192.0.2.0[40404] as server1
  is currently online.
Process ID: 5627
Uptime: 2 seconds
Geode Version: 1.15
Java Version: 8.0.121
Log File: /Users/username/my_geode/server1/server1.log

JVM Arguments: -Dgemfire.default.locators=192.0.2.0[10334] -Dgemfire.groups=group1
-Dgemfire.start-dev-rest-api=false -Dgemfire.use-cluster-configuration=true
-Dgemfire.launcher.registerSignalHandlers=true -Djava.awt.headless=true
Class-Path: /Users/username/geode115/lib/geode-dependencies.jar

gfsh>start server --name=server2 --groups=group1 --server-port=40405
Starting a Geode Server in /Users/username/my_geode/server2...
.....
Server in /Users/username/my_geode/server2 on 192.0.2.0[40405] as server2
  is currently online.
Process ID: 5634
Uptime: 2 seconds
Geode Version: 1.15
Java Version: 8.0.121
Log File: /Users/username/my_geode/server2/server2.log

JVM Arguments: -Dgemfire.default.locators=192.0.2.0[10334] -Dgemfire.groups=group1
-Dgemfire.start-dev-rest-api=false -Dgemfire.use-cluster-configuration=true
-Dgemfire.launcher.registerSignalHandlers=true -Djava.awt.headless=true
-Dsun.rmi.dgc.server.gcInterval=9223372036854775806
Class-Path: /Users/username/geode115/lib/geode-dependencies.jar

gfsh>start server --name=server3 --server-port=40406
Starting a Geode Server in /Users/username/my_geode/server3...
.....
Server in /Users/username/my_geode/server3 on 192.0.2.0[40406] as server3
  is currently online.
Process ID: 5637
Uptime: 2 seconds
Geode Version: 1.15
Java Version: 8.0.121
Log File: /Users/username/my_geode/server3/server3.log
JVM Arguments: -Dgemfire.default.locators=192.0.2.0[10334]
-Dgemfire.start-dev-rest-api=false -Dgemfire.use-cluster-configuration=true
-Dgemfire.launcher.registerSignalHandlers=true -Djava.awt.headless=true
-Dsun.rmi.dgc.server.gcInterval=9223372036854775806
Class-Path: /Users/username/geode115/lib/geode-dependencies.jar

Note that the gfsh commands you used to start server1 and server2 specify a group named group1 while the command for server3 did not specify a group name.

Create some regions using the commands in the following example:

gfsh>create region --name=region1 --groups=group1 --type=REPLICATE
Member  | Status | Message
------- | ------ | --------------------------------------
server1 | OK     | Region "/region1" created on "server1"
server2 | OK     | Region "/region1" created on "server2"

Cluster configuration for group 'group1' is updated.


gfsh>create region --name=region2 --type=REPLICATE
Member  | Status | Message
------- | ------ | --------------------------------------
server1 | OK     | Region "/region2" created on "server1"
server2 | OK     | Region "/region2" created on "server2"
server3 | OK     | Region "/region2" created on "server3"

Cluster configuration for group 'cluster' is updated.

Note that region1 is created on all cache servers that specified the group named group1 when starting the cache server (server1 and server2, in this example). region2 is created on all members because no group was specified.

Deploy jar files. Use the gfsh deploy command to deploy application jar files to all members or to a specified group of members. The following example deploys the mx4j-3.0.2.jar and ra.jar files from the distribution. (Note: This is only an example, you do not need to deploy these files to use the Cluster Configuration Service. Alternately, you can use any two jar files for this demonstration.)

gfsh>deploy --groups=group1 --jars=/lib/mx4j-3.0.2.jar

Deploying files: mx4j-3.0.2.jar
Total file size is: 0.39MB

Continue?  (Y/n): y
Member  |  Deployed JAR  | Deployed JAR Location
------- | -------------- | ----------------------------------------------------------
server1 | mx4j-3.0.2.jar | /Users/username/my_geode/server1/mx4j-3.0.2.v1.jar
server2 | mx4j-3.0.2.jar | /Users/username/my_geode/server2/mx4j-3.0.2.v1.jar

gfsh>deploy --jars=/lib/ra.jar

Deploying files: ra.jar
Total file size is: 0.03MB

Continue?  (Y/n): y
Member  | Deployed JAR | Deployed JAR Location
------- | ------------ | --------------------------------------------------
server1 | ra.jar       | /Users/username/my_geode/server1/ra.v1.jar
server2 | ra.jar       | /Users/username/my_geode/server2/ra.v1.jar
server3 | ra.jar       | /Users/username/my_geode/server2/ra.v1.jar

Note that the mx4j-3.0.2.jar file was deployed only to the members of group1 and the ra.jar was deployed to all members.

Export the cluster configuration. You can use the gfsh export cluster-configuration command to create a zip file that contains the cluster's persisted configuration. The zip file contains a copy of the contents of the cluster_config directory. For example:
```
gfsh>export cluster-configuration --zip-file-name=/Users/username/myClConfig.zip
```
Apache Geode writes the cluster configuration to the specified zip file.
```
File saved to /Users/username/myClConfig.zip
```
The remaining steps demonstrate how to use the cluster configuration you just created.

Shut down the cluster using the following commands:

gfsh>shutdown --include-locators=true
As a lot of data in memory will be lost, including possibly events in queues, do you
really want to shutdown the entire distributed system? (Y/n): Y
Shutdown is triggered

gfsh>
No longer connected to 192.0.2.0[1099].
gfsh>

Exit the gfsh command shell:
```
gfsh>quit
Exiting...
```
Create a new working directory (for example: new_geode) and switch to the new directory.
Start the gfsh command shell:
```
$ gfsh
```

Start a new locator. For example:

gfsh>start locator --name=locator2 --port=10335
Starting a Geode Locator in /Users/username/new_geode/locator2...
.............................
Locator in /Users/username/new_geode/locator2 on 192.0.2.0[10335] as locator2
  is currently online.
Process ID: 5749
Uptime: 15 seconds
Geode Version: 1.15
Java Version: 8.0.121
Log File: /Users/username/new_geode/locator2/locator2.log

JVM Arguments: -Dgemfire.enable-cluster-configuration=true
-Dgemfire.load-cluster-configuration-from-dir=false
-Dgemfire.launcher.registerSignalHandlers=true -Djava.awt.headless=true
-Dsun.rmi.dgc.server.gcInterval=9223372036854775806
Class-Path: /Users/username/geode115/lib/geode-dependencies.jar

Successfully connected to: JMX Manager [host=192.0.2.0, port=1099]

Cluster configuration service is up and running.

Import the cluster configuration using the import cluster-configuration command. For example:

gfsh>import cluster-configuration --zip-file-name=/Users/username/myClConfig.zip
This command will replace the existing cluster configuration, if any, The old configuration will be backed up in the working directory.

Continue?  (Y/n): y
Cluster configuration successfully imported

Note that the locator2 directory now contains a cluster_config subdirectory.

Start a server that does not reference a group:

gfsh>start server --name=server4 --server-port=40414
Starting a Geode Server in /Users/username/new_geode/server4...
........
Server in /Users/username/new_geode/server4 on 192.0.2.0[40414] as server4
is currently online.
Process ID: 5813
Uptime: 4 seconds
Geode Version: 1.15
Java Version: 8.0.121
Log File: /Users/username/new_geode/server4/server4.log

JVM Arguments: -Dgemfire.default.locators=192.0.2.0[10335]
-Dgemfire.start-dev-rest-api=false -Dgemfire.use-cluster-configuration=true
-Dgemfire.launcher.registerSignalHandlers=true -Djava.awt.headless=true
-Dsun.rmi.dgc.server.gcInterval=9223372036854775806
Class-Path: /Users/username/geode115/lib/geode-dependencies.jar

Start another server that references group1:

gfsh>start server --name=server5 --groups=group1 --server-port=40415
Starting a Geode Server in /Users/username/new_geode/server5...
.....
Server in /Users/username/new_geode/server2 on 192.0.2.0[40415] as server5
is currently online.
Process ID: 5954
Uptime: 2 seconds
Geode Version: 1.15
Java Version: 8.0.121
Log File: /Users/username/new_geode/server5/server5.log
JVM Arguments: -Dgemfire.default.locators=192.0.2.0[10335] -Dgemfire.groups=group1
-Dgemfire.start-dev-rest-api=false -Dgemfire.use-cluster-configuration=true
-Dgemfire.launcher.registerSignalHandlers=true -Djava.awt.headless=true
-Dsun.rmi.dgc.server.gcInterval=9223372036854775806
Class-Path: /Users/username/geode115/lib/geode-dependencies.jar

Use the list regions command to display the configured regions. Note that region1 and region2, which were configured in the original cluster level are available.
```
gfsh>list regions
List of regions
---------------
region1
region2
```

Use the describe region command to see which members host each region. Note that region1 is hosted only by server5 because server5 was started using the group1 configuration. region2 is hosted on both server4 and server5 because region2 was created without a group specified.

gfsh>describe region --name=region1
Name            : region1
Data Policy     : replicate
Hosting Members : server5

Non-Default Attributes Shared By Hosting Members

 Type  |    Name     | Value
------ | ----------- | ---------------
Region | data-policy | REPLICATE
       | size        | 0
       | scope       | distributed-ack

gfsh>describe region --name=region2
..........................................................
Name            : region2
Data Policy     : replicate
Hosting Members : server5
                  server4

Non-Default Attributes Shared By Hosting Members

 Type  |    Name     | Value
------ | ----------- | ---------------
Region | data-policy | REPLICATE
       | size        | 0
       | scope       | distributed-ack

This new cluster uses the same configuration as the original system. You can start any number of servers using this cluster configuration. All servers will receive the cluster-level configuration. Servers that specify group1 also receive the group1 configuration.

Shut down your cluster using the following commands:

gfsh>shutdown --include-locators=true
As a lot of data in memory will be lost, including possibly events in queues,
  do you really want to shutdown the entire distributed system? (Y/n): Y
Shutdown is triggered

gfsh>
No longer connected to 192.0.2.0[1099].