LATEST VERSION: 1.8 - RELEASE NOTES
Pivotal Cloud Cache v1.8

Set Up a Bidirectional System

This sequence of steps sets up a bidirectional transfer, as will be needed for an active-active pattern, as described in Bidirectional Replication Across a WAN.

  1. Create the cluster A service instance using the cluster A Cloud Foundry credentials. This example explicitly sets the distributed_system_id of cluster A using a -c option with a command of the form:

    cf create-service p-cloudcache PLAN-NAME SERVICE-INSTANCE-NAME -c '{
    "distributed_system_id" : ID-VALUE }'
    

    Here is a cluster A example of the create-service command:

    $ cf create-service p-cloudcache wan-cluster wan1 -c '{
    "distributed_system_id" : 1 }'
    

    Verify the completion of service creation prior to continuing to the next step. Output from the cf services command will show the last operation as create succeeded when service creation is completed.

  2. Create a service key for cluster A. The service key will contain generated credentials that this example will use in the creation of the cluster B service instance:

    $ cf create-service-key wan1 k1
    

    The contents of the service key will differ based upon the cluster configuration, and if an authentication and enterprise single sign-on (SSO) system such as LDAP has been configured. With the enterprise SSO, there will not be cluster operator and developer users in the service key. Without the enterprise SSO, the service key appears as in this example. Within the service key, each username is generated with a unique string appended so there will be unique user names for the different roles. The user names in this example have been modified to be easy to understand, and they are not representative of the user names that will be generated upon service key creation. Passwords generated for the service key are output in clear text. The passwords shown in this example have been modified to be easy to understand, and they are not representative of the passwords that will be generated upon service key creation. Here is sample output from cf service-key wan1 k1:

    Getting key k1 for service instance wan1 as admin...
    
    {
     "distributed_system_id": "1",
     "locators": [
      "10.0.16.21[55221]"
      "10.0.16.22[55221]"
      "10.0.16.23[55221]"
     ],
     "urls": {
      "gfsh": "https://cloudcache-1.example.com/gemfire/v1",
      "pulse": "https://cloudcache-1.example.com/pulse"
     },
     "users": [
      {
       "password": "cl-op-ABC-password",
       "roles": [
        "cluster_operator"
       ],
       "username": "cluster_operator_ABC"
      },
      {
       "password": "dev-DEF-password",
       "roles": [
        "developer"
       ],
       "username": "developer_DEF"
      }
     ],
     "wan": {
      "sender_credentials": {
       "active": {
        "password": "gws-GHI-password",
        "username": "gateway_sender_GHI"
       }
      }
     }
    }
    
  3. Communicate the cluster A locators’ IP and port addresses and sender_credentials to the cluster B Cloud Foundry administrator.

  4. Create the cluster B service instance using the cluster B Cloud Foundry credentials. This example explicitly sets the distributed_system_id. Use a -c option with the command to specify the distributed_system_id, the cluster A service instance’s locators, and the cluster A sender_credentials:

    $ cf create-service p-cloudcache wan-cluster wan2 -c '
    {
      "distributed_system_id":2,
      "remote_clusters":[
      {
        "remote_locators":[
          "10.0.16.21[55221]",
          "10.0.16.22[55221]",
          "10.0.16.23[55221]"],
        "trusted_sender_credentials":[
        {
          "username": "gateway_sender_GHI",
          "password":"gws-GHI-password"
        }]
      }]
    }'
    

    Verify the completion of service creation prior to continuing to the next step. Output from the cf services command will show the last operation as create succeeded when service creation is completed.

  5. Create the service key of cluster B:

    $ cf create-service-key wan2 k2
    

    The contents of the service key will differ based upon the cluster configuration, and if an authentication and enterprise single sign-on (SSO) system such as LDAP has been configured. With the enterprise SSO, there will not be cluster operator and developer users in the service key. Without the enterprise SSO, the service key appears as in this example.

    Here is sample output from cf service-key wan2 k2, which outputs details of the cluster B service key:

    Getting key k2 for service instance destination as admin...
    
    {
     "distributed_system_id": "2",
     "locators": [
      "10.0.24.21[55221]"
      "10.0.24.22[55221]"
      "10.0.24.23[55221]"
     ],
     "urls": {
      "gfsh": "https://cloudcache-2.example.com/gemfire/v1",
      "pulse": "https://cloudcache-2.example.com/pulse"
     },
     "users": [
      {
       "password": "cl-op-JKL-password",
       "roles": [
        "cluster_operator"
       ],
       "username": "cluster_operator_JKL"
      },
      {
       "password": "dev-MNO-password",
       "roles": [
        "developer"
       ],
       "username": "developer_MNO"
      }
     ],
     "wan": {
      "remote_clusters": [
      {
        "remote_locators": [
          "10.0.16.21[55221]",
          "10.0.16.21[55221]",
          "10.0.16.21[55221]"
        ],
        "trusted_sender_credentials": [
         "gateway_sender_GHI"
        ]
       }
      ],
      "sender_credentials": {
       "active": {
        "password": "gws-PQR-password",
        "username": "gateway_sender_PQR"
       }
      }
     }
    }
    
  6. Communicate the cluster B locators’ IP and port addresses and sender_credentials to the cluster A Cloud Foundry administrator.

  7. Update the cluster A service instance using the cluster A Cloud Foundry credentials to include the cluster B locators and the cluster B sender_credentials:

    $ cf update-service wan1 -c '
    {
      "remote_clusters":[
      {
        "remote_locators":[
          "10.0.24.21[55221]",
          "10.0.24.22[55221]",
          "10.0.24.23[55221]"],
        "trusted_sender_credentials":[
        {
          "username":"gateway_sender_PQR",
          "password":"gws-PQR-password"
        }]
      }]
    }'
    Updating service instance wan1 as admin
    
  8. To observe and verify that the cluster A service instance has been correctly updated, it is necessary to delete and recreate the cluster A service key. As designed, the recreated service key will have the same user identifiers and passwords; new unique strings and passwords are not generated. Use the cluster A Cloud Foundry credentials in these commands:

    $ cf delete-service-key wan1 k1
    
    $ cf create-service-key wan1 k1
    

    This example service key is shown assuming that an authentication and enterprise single sign-on (SSO) system such as LDAP has not been configured. The cluster A service key will now appear as:

    Getting key k1 for service instance wan1 as admin...
    
    {
     "distributed_system_id": "1",
     "locators": [
      "10.0.16.21[55221]",
      "10.0.16.22[55221]",
      "10.0.16.23[55221]"
     ],
     "urls": {
      "gfsh": "https://cloudcache-1.example.com/gemfire/v1",
      "pulse": "https://cloudcache-1.example.com/pulse"
     },
     "users": [
      {
       "password": "cl-op-ABC-password",
       "roles": [
        "cluster_operator"
       ],
       "username": "cluster_operator_ABC"
      },
      {
       "password": "dev-DEF-password",
       "roles": [
        "developer"
       ],
       "username": "developer_DEF"
      }
     ],
     "wan": {
      "remote_clusters": [
       {
        "remote_locators": [
         "10.0.24.21[55221]",
         "10.0.24.22[55221]",
         "10.0.24.23[55221]"
        ],
        "trusted_sender_credentials": [
         "gateway_sender_PQR"
        ]
       }
      ],
      "sender_credentials": {
       "active": {
        "password": "gws-GHI-password",
        "username": "gateway_sender_GHI"
       }
      }
     }
    }
    
  9. Use gfsh to create the cluster A gateway sender and the region. Any region operations that occur after the region is created on cluster A, but before the region is created on cluster B will be lost.

    • Connect using gfsh following the instructions in Connect with gfsh over HTTPS with a role that is able to manage both the cluster and the data.
    • Create the cluster A gateway sender. The required remote-distributed-system-id option identifies the distributed-system-id of the destination cluster. It is 2 for this example:

      gfsh>create gateway-sender --id=send_to_2 --remote-distributed-system-id=2 --enable-persistence=true
      
    • Create the cluster A region. The gateway-sender-id associates region operations with a specific gateway sender. The region must have an associated gateway sender in order to propagate region events across the WAN.

      gfsh>create region --name=regionX --gateway-sender-id=send_to_2 --type=PARTITION_REDUNDANT
      
  10. Use gfsh to create the cluster B gateway sender and region.

    • Connect using gfsh following the instructions in Connect with gfsh over HTTPS with a role that is able to manage both the cluster and the data.
    • Create the cluster B gateway sender:

      gfsh>create gateway-sender --id=send_to_1 --remote-distributed-system-id=1 --enable-persistence=true
      
    • Create the cluster B region:

      gfsh>create region --name=regionX --gateway-sender-id=send_to_1 --type=PARTITION_REDUNDANT
      

Verify Bidirectional WAN Setup

This verification uses gfsh to put a region entry into each of cluster A and cluster B, in order to observe that the entry appears in the other cluster.

  1. Run gfsh and connect following the instructions in Connect with gfsh over HTTPS with a role that is able to manage both the cluster and the data.

  2. Verify that cluster A has a complete set of gateway senders and gateway receivers:

    gfsh>list gateways
    

    Also verify that there are no queued events in the gateway senders.

  3. In a separate terminal window, run gfsh and connect following the instructions in Connect with gfsh over HTTPS with a role that is able to manage both the cluster and the data.

  4. Verify that cluster B has a complete set of gateway senders and gateway receivers:

    gfsh>list gateways
    

    Also verify that there are no queued events in the gateway senders.

  5. Use gfsh to do a put operation from the cluster A gfsh connection. This example assumes that both the key and the value for the entry are strings. The gfsh help put command shows the put command’s options. Here is an example:

    gfsh>put --region=regionX --key=mykey1 --value=stringvalue1
    Result      : true
    Key Class   : java.lang.String
    Key         : mykey1
    Value Class : java.lang.String
    Old Value   : null
    
  6. Wait approximately 30 seconds before using the cluster B gfsh connection to do a get of the same key that was put into the region on cluster A.

    gfsh>get --region=regionX --key=mykey1
    Result      : true
    Key Class   : java.lang.String
    Key         : mykey1
    Value Class : java.lang.String
    Value       : "stringvalue1"
    

    You should see that cluster B has the value.

  7. Repeat steps 5 and 6 to do a put operation operation on cluster B and verify that the entry is sent to cluster A.

  8. Remove both test entries from both clusters with two gfsh commands, issuing the commands on one of the clusters. The WAN replication will cause the removal of the test entries on the other cluster.

    gfsh>remove --region=regionX --key=mykey1
    Result    : true
    Key Class : java.lang.String
    Key       : mykey1
    
    gfsh>remove --region=regionX --key=mykey2
    Result    : true
    Key Class : java.lang.String
    Key       : mykey2
    
Create a pull request or raise an issue on the source for this page in GitHub