Accessing a Service Instance

This topic explains how to access a service instance of VMware Tanzu GemFire for Tanzu Application Service (GemFire for Tanzu Application Service).

After you have created a service instance, you can access it. The gfsh command line tool provides cluster maintenance and data access functionality. Many gfsh commands require an authenticated connection that can be set up with the gfsh connect command.

Connecting requires these one-time, setup steps:

Create a service key.
Create a truststore.
Acquire the correct version of gfsh.
Set a JAVA_ARGS environment variable.

Create a Service Key

A service key provides a way to access your service instance outside the scope of a deployed 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 can use this name to refer to your service key with other commands.

$ cf create-service-key my-cloudcache my-service-key

View a Service Key

To view a service key, run cf service-key SERVICE-INSTANCE-NAME KEY-NAME.

$ cf service-key my-cloudcache my-service-key

The service key reveals the configuration of your service instance. It shows addresses and ports of its locators, and contains an element called remote_cluster-info that provides fields by which the service instance can be reached from other service instances. The service key specifies two URLs, one URL used to connect the gfsh client to the service instance, and another URL used to view the Pulse dashboard in a web browser, which allows monitoring of the service instance status.

View a Service Key with External Authentication

If external authentication such as LDAP through User Account and Authentication (UAA) is in place, the external authentication system handles user credentials, and they will not appear in the service key.

If an external authentication system has been configured, then the cf service-key command returns output in the following format, without role-based login credentials:

{
  "distributed_system_id": "0",
  "gfsh_login_string": "connect
    --url=https://cloudcache-1.example.com/gemfire/v1
    --user=\u003cusername\u003e --password=\u003cpassword\u003e",
  "locators": [
    "id1.locator.services-subnet.service-instance-id.bosh[55221]",
    "id2.locator.services-subnet.service-instance-id.bosh[55221]",
    "id3.locator.services-subnet.service-instance-id.bosh[55221]"
  ],
  "remote_cluster_info": {
    "recursors": {
      "services-subnet.service-instance-id.bosh": [
        "10.0.8.6:1053",
        "10.0.8.7:1053",
        "10.0.8.5:1053"
      ]
    },
    "remote_locators": [
      "id1.locator.services-subnet.service-instance-id.bosh[55221]",
      "id2.locator.services-subnet.service-instance-id.bosh[55221]",
      "id3.locator.services-subnet.service-instance-id.bosh[55221]"
    ],
    "trusted_sender_credentials": [
      {
        "password": "gws-GHI-password",
        "username": "gateway_sender_GHI"
      }
    ]
  },
  "urls": {
    "gfsh": "https://cloudcache-1.example.com/gemfire/v1",
    "management": "https://cloudcache-1.example.com/management/docs",
    "pulse": "https://cloudcache-1.example.com/pulse"
  },
  "wan": {
    "remote_clusters": [
      {
        "recursors": {
          "services-subnet-2.service-instance-id-2.bosh": [
            "10.1.16.7:1053",
            "10.1.16.6:1053",
            "10.1.16.8:1053"
          ]
        },
        "remote_locators": [
          "id1.locator.services-subnet-2.service-instance-id-2.bosh[55221]",
          "id2.locator.services-subnet-2.service-instance-id-2.bosh[55221]",
          "id3.locator.services-subnet-2.service-instance-id-2.bosh[55221]"
        ],
        "trusted_sender_credentials": [
          {
            "password": "gws-PQR-password",
            "username": "gateway_sender_PQR"
          }
        ]
      }
    ]
  }
}

View a Service Key without External Authentication

If external authentication such as LDAP through User Account and Authentication (UAA) has not been configured, the service key shows role-based login credentials as username/password pairs.

The cf service-key command returns output in the following format and includes role-based login credentials:

{
  "distributed_system_id": "0",
  "gfsh_login_string": "connect
    --url=https://cloudcache-1.example.com/gemfire/v1
    --user=cluster_operator_XXX --password=cluster_operator-password --skip-ssl-validation",
    "locators": [
      "id1.locator.services-subnet.service-instance-id.bosh[55221]",
      "id2.locator.services-subnet.service-instance-id.bosh[55221]",
      "id3.locator.services-subnet.service-instance-id.bosh[55221]"
    ],
    "remote_cluster_info": {
      "recursors": {
        "services-subnet.service-instance-id.bosh": [
          "10.0.8.6:1053",
          "10.0.8.7:1053",
          "10.0.8.5:1053"
         ]
       },
       "remote_locators": [
         "id1.locator.services-subnet.service-instance-id.bosh[55221]",
         "id2.locator.services-subnet.service-instance-id.bosh[55221]",
         "id3.locator.services-subnet.service-instance-id.bosh[55221]"
       ],
       "trusted_sender_credentials": [
         {
           "password": "gws-GHI-password",
           "username": "gateway_sender_GHI"
         }
       ]
     },
     "urls": {
       "gfsh": "https://cloudcache-1.example.com/gemfire/v1",
       "management": "https://cloudcache-1.example.com/management/docs",
       "pulse": "https://cloudcache-1.example.com/pulse"
     },
     "users": [
       {
         "password": "developer-password",
         "roles": [
           "developer"
         ],
         "username": "developer_XXX"
       },
       {
         "password": "cluster_operator-password",
         "roles": [
           "cluster_operator"
         ],
         "username": "cluster_operator_XXX"
       }
     ],
     "wan": {
       "remote_clusters": [
         {
         "recursors": {
           "services-subnet-2.service-instance-id-2.bosh": [
             "10.1.16.7:1053",
            "10.1.16.6:1053",
            "10.1.16.8:1053"
          ]
        },
        "remote_locators": [
          "id1.locator.services-subnet-2.service-instance-id-2.bosh[55221]",
          "id2.locator.services-subnet-2.service-instance-id-2.bosh[55221]",
          "id3.locator.services-subnet-2.service-instance-id-2.bosh[55221]"
        ],
        "trusted_sender_credentials": [
          {
            "password": "gws-PQR-password",
            "username": "gateway_sender_PQR"
          }
        ]
      }
    ]
  }
}

This service key for a GemFire for Tanzu Application Service installation in which an external authentication such as LDAP via UAA has not been configured specifies these user roles that are predefined, for interacting with and within the cluster:

The cluster operator administers the pool, performing operations such as creating and destroying regions, and creating gateway senders. The identifier assigned for this role is of the form cluster_operator_XXX, where XXX is a unique string generated upon service instance creation and incorporated in this user role’s name.
The developer does limited cluster administration such as region creation, and the developer role is expected to be used by applications that are interacting with region entries. The developer does CRUD operations on regions. The identifier assigned for this role is of the form developer_XXX, where XXX is a unique string generated upon service instance creation and incorporated in this user role’s name.

Connect with gfsh over HTTPS

When connecting over HTTPS, you must use the same certificate you use to secure traffic into VMware Tanzu Application Service for VMs (Tanzu Application Service for VMs); that is, the certificate you use where your TLS termination occurs. See Determine Your TLS Termination.

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.

Locate the certificate you use to configure TLS termination. See Determine Your TLS Termination.
Using your certificate, run the keytool command:

keytool -import -file CERTIFICATE.CER -keystore TRUSTSTORE-FILE-PATH -storetype JKS

where + 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
When you run this command, you are prompted to enter a keystore password. Create a password and record it.
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 -file /tmp/loadbalancer.cer -keystore /tmp/truststore/prod.myTrustStore -storetype JKS
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 use the cluster’s command line interface, gfsh, to connect to the cluster over HTTPS.

Acquire the compressed TAR file of Apache Geode from VMware Tanzu Network. Find the correct version to download by referencing the table in Product Snapshot and Version Compatibility. Note that a JDK or JRE will also be required.
Expand the VMware Tanzu GemFire compressed TAR file. gfsh is within the bin directory in the expanded Tanzu GemFire folder.
Run gfsh on Unix with a command of the form:
```
/PATH-TO-VMWARE-GEMFIRE/bin/gfsh
```
Or, on Windows, with a command of the form:
```
\PATH-TO-VMWARE-GEMFIRE\bin\gfsh.bat
```
At the gfsh prompt, issue a connect command of the form:
```
connect --use-http=true --url=HTTPS-gfsh-URL
  --trust-store=TRUSTSTORE-FILE-PATH --trust-store-password=PASSWORD
  --user=USER-NAME --password=USER-PASSWORD
```
The HTTPS-gfsh-URL is the gfsh URL from the service key. See Create Service Keys for instructions on how to view the service key. TRUSTSTORE-FILE-PATH is the path to the trustStore file you created in Create a Truststore, and PASSWORD is the associated password you created. If you omit the --trust-store-password option from the command line, you will be prompted to enter the password.

For an installation configured without an external authentication such as LDAP via UAA, the USER-NAME and USER-PASSWORD are taken from the service key, and they will either be for the developer role or for the cluster operator role, depending on the gfsh operations to be performed.

For an installation configured with an external authentication such as LDAP via UAA, the USER-NAME and USER-PASSWORD are your credentials as issued and set up by your organization within your SSO system.

Establish the Connection in a Development Environment

When working in a non-production, development environment, a developer may choose to work in a less secure manner by eliminating the truststore and SSL mutual authentication.

The steps to establish the gfsh connection become:

Acquire the connect command (the gfsh_login_string) from the service key. This command will connect using the cluster_operator role. This connect command assumes that the installation is configured without an external authentication such as LDAP via UAA.
Acquire the compressed TAR file of Apache Geode from the VMware Tanzu Network. Find the correct version to download by referencing the table in Product Snapshot and Version Compatibility. Note that a JDK or JRE will also be required.
Expand the Tanzu GemFirecompressed TAR file. gfsh is within the bin directory in the expanded Tanzu GemFire folder.
Run gfsh on Unix with a command of the form:
```
/PATH-TO-VMWARE-GEMFIRE/bin/gfsh
```
Or, on Windows, with a command of the form:
```
\PATH-TO-VMWARE-GEMFIRE\bin\gfsh.bat
```
Then issue the acquired connect command:
```
gfsh>connect --url=https://cloudcache-1.example.com/gemfire/v1
  --user=cluster_operator_XXX --password=cluster_operator-password
  --skip-ssl-validation
```
At each of the nine gfsh prompts that ask for keystore, truststore, and SSL details, hit Enter to step through the prompts and connect.

Determine Your TLS Termination

To connect your GemFire for Tanzu Application Service service instance using gfsh, you will need the certificate from where your TLS termination occurs. The TLS termination may be at the Gorouter, at the HAProxy, or at your load balancer. Request the needed certificate from your VMware Tanzu Application Service for VMs (Tanzu Application Service for VMs) operator.

The Tanzu Application Service for VMs operator determines the location of your TLS termination:

Open the Ops Manager dashboard.
Click on the Tanzu Application Service for VMs product tile.
Click on the Networking section under the Settings tab.

The choice of TLS termination is labeled with TLS termination point.

If the choice names the Gorouter or HAProxy, the certificate is in the same section, labeled with Certificates and private keys for the Gorouter and HAProxy.

If the choice names the Infrastructure load balancer, then the Tanzu Application Service for VMs operator can retrieve the certificate from the load balancer.