Accessing a Service Instance

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 will be set up with the gfsh connect command.

Connecting will require these one-time, setup steps:

  1. Create a service key.
  2. Create a truststore.
  3. Acquire the correct version of gfsh.
  4. 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 CF 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

Run cf service-key SERVICE-INSTANCE-NAME KEY-NAME to view the newly created service key.

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

The service key will differ based on whether an authentication and enterprise single sign-on (SSO) system such as LDAP has been configured for the PCC service instance. In both cases the service key will contain both a URL used to connect the gfsh client to the service instance, and a URL used to view the Pulse dashboard in a web browser, which allows monitoring of the service instance status.

If an authentication and enterprise single sign-on (SSO) system such as LDAP has been configured, then the cf service-key returns output in the following format:

{
 "distributed_system_id": "0",
 "locators": [
  "10.244.0.66[55221]",
  "10.244.0.4[55221]",
  "10.244.0.3[55221]"
 ],
 "urls": {
  "gfsh": "https://cloudcache-1.example.com/gemfire/v1",
  "pulse": "https://cloudcache-1.example.com/pulse"
 },
 "wan": {
  "sender_credentials": {
   "active": {
    "password": "gws-XXX-password",
    "username": "gateway_sender_XXX"
   }
  }
 }
}

If an authentication and enterprise single sign-on (SSO) system such as LDAP has not been configured, then the cf service-key returns output in the following format:

{
 "distributed_system_id": "0",
 "locators": [
  "10.244.0.66[55221]",
  "10.244.0.4[55221]",
  "10.244.0.3[55221]"
 ],
 "urls": {
  "gfsh": "https://cloudcache-1.example.com/gemfire/v1",
  "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": {
  "sender_credentials": {
   "active": {
    "password": "gws-XXX-password",
    "username": "gateway_sender_XXX"
   }
  }
 }
}

This service key for a PCC installation in which an authentication and enterprise single sign-on (SSO) system such as LDAP 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 Pivotal Application Service (PAS); 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.

  1. Locate the certificate you use to configure TLS termination. See Determine Your TLS Termination.

  2. 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

  3. When you run this command, you are prompted to enter a keystore password. Create a password and remember it!

  4. 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 Pivotal GemFire command line interface, gfsh, to connect to the cluster over HTTPS.

  1. Acquire the correct gfsh by downloading the correct Pivotal GemFire ZIP archive from Pivotal Network. The correct version of Pivotal GemFire to download is any patch version of the Pivotal GemFire version listed in the PCC release notes. A link to the PCC release notes is on Pivotal Network in the Release Details for your PCC version. Note that a JDK or JRE will also be required, as specified in the release notes.

    Note: An attempt to use the wrong gfsh version will result in an error message indicating that there is a version mismatch.

  2. Unzip the Pivotal GemFire ZIP archive. gfsh is within the bin directory in the expanded Pivotal GemFire. Use gfsh with Unix or gfsh.bat with Windows.

  3. Run gfsh, and then 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 authentication and enterprise single sign-on (SSO) system such as LDAP, 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 authentication and enterprise single sign-on (SSO) system such as LDAP, the USER-NAME and USER-PASSWORD are your credentials as issued and set up by your organization within your SSO system.

Establish the Connection with HTTPS 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:

  1. Acquire gfsh by downloading the correct Pivotal GemFire ZIP archive from Pivotal Network. The correct version of Pivotal GemFire to download is any patch version of the Pivotal GemFire version listed in the PCC release notes. A link to the PCC release notes is on Pivotal Network in the Release Details for your PCC version. Note that a JDK or JRE will also be required, as specified in the release notes.
  2. Unzip the Pivotal GemFire ZIP archive. gfsh is within the bin directory in the expanded Pivotal GemFire. Use gfsh with Unix or gfsh.bat with Windows.

  3. Run gfsh, and then issue a connect command that specifies an HTTPS URL of the form:

    connect --use-http=true --use-ssl --skip-ssl-validation=true
 --url=HTTPS-gfsh-URL --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.

    For an installation configured without an authentication and enterprise single sign-on (SSO) system such as LDAP, 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.

    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 PCC 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 Pivotal Cloud Foundry (PCF) operator.

The PCF operator determines the location of your TLS termination:

  1. Bring up the Ops Manager dashboard.
  2. Click on the PAS product tile.
  3. Click on the Networking section under the Settings tab.

The choice of TLS termination is labeled with Configure support for the X-Forwarded-Client-Cert.

If the choice names the Router or HAProxy, the certificate is in the same section, labeled with Certificate and Private Key for HAProxy and Router.

If the choice names the infrastructure load balancer, then the PCF operator can retrieve the certificate from the load balancer.