Accessing a Service Instance
Warning: Pivotal Cloud Cache v1.7 is no longer supported because it has reached the End of General Support (EOGS) phase as defined by the Support Lifecycle Policy. To stay up to date with the latest software and security updates, upgrade to a supported version.
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:
- 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 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
, whereXXX
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
, whereXXX
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.
- 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 fileTRUSTSTORE-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 remember 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 Pivotal GemFire command line interface, gfsh
, to connect to the cluster over HTTPS.
- 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. - Unzip the Pivotal GemFire ZIP archive.
gfsh
is within thebin
directory in the expanded Pivotal GemFire. Usegfsh
with Unix orgfsh.bat
with Windows. Run
gfsh
, and then issue aconnect
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, andPASSWORD
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
andUSER-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
andUSER-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:
- 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. - Unzip the Pivotal GemFire ZIP archive.
gfsh
is within thebin
directory in the expanded Pivotal GemFire. Usegfsh
with Unix orgfsh.bat
with Windows. Run
gfsh
, and then issue aconnect
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
andUSER-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, hitEnter
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:
- Bring up the Ops Manager dashboard.
- Click on the PAS product tile.
- 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.