Pivotal Cloud Cache 1 · Redis for PCF Redis Yes Yes (shared-VM plan). Only recommended for test...

PivotalCloudCache1.5

Note:ThesupportperiodforPivotalCloudCache(PCC)1.5hasexpired,andthisversionisnolongersupported.Tostayuptodatewiththelatestsoftwareandsecurityupdates,upgradetoasupportedversion.

©CopyrightPivotalSoftwareInc,2013-2019

23

13454748515258646974818284869299

102107109110119126127129130

TableofContents

TableofContentsPivotalCloudCachePivotalCloudCacheOperatorGuidePivotalCloudCacheDeveloperGuideViewingAllPlansAvailableforPivotalCloudCacheCreatingaPivotalCloudCacheServiceInstanceSetUpWAN-SeparatedServiceInstancesSetUpaBidirectionalSystemSetUpaUnidirectionalSystemSetUpanAdditionalBidirectionalInteractionSetUpanAdditionalUnidirectionalInteractionSettingUpServersforanInlineCacheDeletingaServiceInstanceUpdatingaPivotalCloudCacheServiceInstancegfshCommandRestrictionsAccessingaServiceInstanceUsingPivotalCloudCacheDevelopinganAppUnderTLSConnectingaSpringBootApptoPivotalCloudCachewithSessionStateCachingCreatingContinuousQueriesUsingSpringDataGemFireApplicationDevelopmentDesignPatternsRegionDesignExampleApplicationsASimpleJavaAppTroubleshootingPivotalCloudCacheReleaseNotes

©CopyrightPivotalSoftwareInc,2013-present 2 1.5

PivotalCloudCacheInthistopic

Overview

ProductSnapshot

PCCandOtherPCFServices

PCCArchitectureGemFireBasics

ThePCCCluster

MemberCommunication

WorkflowtoSetUpaPCCService

NetworkingforOn-DemandServices

ServiceNetworkRequirementDefaultNetworkandServiceNetwork

RequiredNetworkingRulesforOn-DemandServices

PCCInstancesAcrossWAN

RecommendedUsageandLimitations

Security

Feedback

OverviewPivotalCloudCache(PCC)isahigh-performance,high-availabilitycachinglayerforPivotalCloudFoundry(PCF).PCCoffersanin-memorykey-valuestore.Itdeliverslow-latencyresponsestoalargenumberofconcurrentdataaccessrequests.

PCCprovidesaservicebrokertocreatein-memorydataclustersondemand.TheseclustersarededicatedtothePCFspaceandtunedforspecificusecasesdefinedbyyourserviceplan.Serviceoperatorscancreatemultipleplanstosupportdifferentusecases.

PCCusesPivotalGemFire.ThePivotalGemFireAPIDocumentation detailstheAPIforclientaccesstodataobjectswithinPivotalGemFire.

Thisdocumentationperformsthefollowingfunctions:

DescribesthefeaturesandarchitectureofPCC


http://gemfire-apis.docs.pivotal.io/

ProvidesthePCFoperatorwithinstructionsforinstalling,configuring,andmaintainingPCC

Providesappdevelopersinstructionsforchoosingaserviceplan,creating,anddeletingPCCserviceinstances

Providesappdevelopersinstructionsforbindingapps

ProductSnapshotThefollowingtableprovidesversionandversion-supportinformationaboutPCC:

Element Details

Version v1.5.4

Releasedate May8,2019

Softwarecomponentversion GemFirev9.6.2

CompatibleOpsManagerversion(s) v2.3.xandv2.2.x

CompatiblePivotalApplicationService(PAS)*version(s) v2.3.xandv2.2.x

IaaSsupport AWS,Azure,GCP,OpenStack,andvSphere

IPsecsupport Yes

RequiredBOSHstemcellversion Xenial250.9oramorerecentversion

MinimumJavabuildpackversionrequiredforapps v3.13

*AsofPCFv2.0,ElasticRuntimeisrenamedPivotalApplicationService(PAS).

PCCandOtherPCFServicesAswellasPivotalCloudCache,otherPCFservicesofferon-demandserviceplans.Theseplansletdevelopersprovisionserviceinstanceswhentheywant.

Thesecontrastwiththeolderpre-provisionedserviceplans,whichrequireoperatorstoprovisiontheserviceinstancesduringinstallationandconfigurationthroughtheservicetileUI.

ThefollowingtablelistswhichPCFservicesofferon-demandandpre-provisionedserviceplans:

PCFservicetileStandaloneproductrelatedtotheservice

Supportson-demand Supportspre-provisioned

Yes.Onlyrecommendedfortest


RabbitMQforPCF PivotalRabbitMQ Yes environments.

RedisforPCF Redis YesYes(shared-VMplan).Onlyrecommendedfortestenvironments.

MySQLforPCF MySQL Yes No

PivotalCloudCache(PCC)

PivotalGemFire Yes No

Forservicesthatofferbothon-demandandpre-provisionedplans,youcanchoosetheplanyouwanttousewhenconfiguringthetile.

PCCArchitecture

GemFireBasics

PivotalGemFireisthedatastorewithinPivotalCloudCache(PCC).AsmallamountofadministrativeGemFiresetupisrequiredforaPCCserviceinstance,andanyappwillusealimitedportionoftheGemFireAPI.

ThePCCarchitecturalmodelisaclient-servermodel.Theclientsareappsormicroservices,andtheserversareasetofGemFireserversmaintainedbyaPCCserviceinstance.TheGemFireserversprovidealow-latency,consistent,fault-tolerantdatastorewithinPCC.

GemFireholdsdatainkey/valuepairs.Eachpairiscalledanentry.Entriesarelogicallygroupedintosetscalledregions.Aregionisamap(ordictionary)datastructure.

Theapp(client)usesPCCasacache.Acachelookup(read)isagetoperationonaGemFireregion.ThecacheoperationofacachewriteisaputoperationonaGemFireregion.TheGemFirecommand-line


interface,called gfsh ,facilitatesregionadministration.Use gfsh tocreateanddestroyregionswithinthePCCserviceinstance.

ThePCCCluster

PCCdeployscacheclustersthatusePivotalGemFiretoprovidehighavailability,replicationguarantees,andeventualconsistency.

Whenyoufirstspinupacluster,youhavethreelocatorsandatleastfourservers.

graphTD;ClientsubgraphP-CloudCacheClustersubgraphlocatorsLocator1Locator2Locator3endsubgraphserversServer1Server2Server3Server4endendClient==>Locator1Client-->Server1Client-->Server2Client-->Server3Client-->Server4

Whenyouscaletheclusterup,youhavemoreservers,increasingthecapacityofthecache.Therearealwaysthreelocators.

graphTD;ClientsubgraphP-CloudCacheClustersubgraphlocatorsLocator1Locator2Locator3endsubgraphserversServer1Server2Server3Server4Server5Server6Server7endendClient==>Locator1Client-->Server1Client-->Server2Client-->Server3Client-->Server4Client-->Server5Client-->Server6Client-->Server7

MemberCommunication

Whenaclientconnectstothecluster,itfirstconnectstoalocator.ThelocatorreplieswiththeIPaddressofaserverforittotalkto.Theclientthenconnectstothatserver.

sequenceDiagramparticipantClientparticipantLocatorparticipantServer1Client->>+Locator:WhatserverscanItalkto?Locator->>-Client:Server1Client->>Server1:Hello!

Whentheclientwantstoreadorwritedata,itsendsarequestdirectlytotheserver.

sequenceDiagramparticipantClientparticipantServer1Client->>+Server1:What’sthevalueforKEY?Server1->>-Client:VALUE

Iftheserverdoesn’thavethedatalocally,itfetchesitfromanotherserver.

sequenceDiagramparticipantClientparticipantServer1participantServer2Client->>+Server1:What’sthevalueforKEY?Server1->>+Server2:What’sthevalueforKEY?Server2->>-Server1:VALUEServer1->>-Client:VALUE


WorkflowtoSetUpaPCCServiceTheworkflowforthePCFadminsettingupaPCCserviceplan:

graphTD;subgraphPCFAdminActionss1s2endsubgraphDeveloperActionss4ends1[1.UploadP-CloudCache.pivotaltoOpsManager]s2[2.ConfigureCloudCacheServicePlans,i.e.caching-small]s1-->s2s3[3.OpsManagerdeploysCloudCacheServiceBroker]s2-->s3s4[4.Developercalls`cfcreate-servicep-cloudcachecaching-smalltest`]s3-->s4s5[5.OpsManagercreatesaCloudCacheclusterfollowingthecaching-smallspecifications]s4-->s5

NetworkingforOn-DemandServicesThissectiondescribesnetworkingconsiderationsforPivotalCloudCache.

ServiceNetworkRequirementWhenyoudeployPCF,youmustcreateastaticallydefinednetworktohostthecomponentvirtualmachinesthatconstitutethePCFinfrastructure.

PCFcomponents,liketheCloudControllerandUAA,runonthisinfrastructurenetwork.On-demandPCFservicesmayrequirethatyouhostthemonanetworkthatrunsseparatelyfromthePCFdefaultnetwork.Youcanalsodeploytilesonseparateservicenetworkstomeetyourownsecurityrequirement.

PCFv2.1andlaterincludedynamicnetworking.Operatorscanusethisdynamicnetworkingwithasynchronousserviceprovisioningtodefinedynamically-provisionedservicenetworks.Formoreinformation,seeDefaultNetworkandServiceNetwork.

InPCFv2.1andlater,on-demandservicesareenabledbydefaultonallnetworks.OperatorscancreateseparatenetworkstohostservicesinBOSHDirector,butdoingsoisoptional.Operatorsselectwhichnetworkhostson-demandserviceinstanceswhentheyconfigurethetileforthatservice.

DefaultNetworkandServiceNetwork

On-demandPCFservicesrelyontheBOSH2.0abilitytodynamicallydeployVMsinadedicatednetwork.Theon-demandservicebrokerusesthiscapabilitytocreatesingle-tenantserviceinstancesinadedicatedservicenetwork.

On-demandservicesusethedynamically-provisionedservicenetworktohostthesingle-tenantworkerVMsthatrunasserviceinstanceswithindevelopmentspaces.ThisarchitectureletsdevelopersprovisionIaaSresourcesfortheirserviceinstancesatcreationtime,ratherthantheoperatorpre-provisioninga


fixedquantityofIaaSresourceswhentheydeploytheservicebroker.

Bymakingservicessingle-tenant,whereeachinstancerunsonadedicatedVMratherthansharingVMswithunrelatedprocesses,on-demandserviceseliminatethe“noisyneighbor”problemwhenoneapphogsresourcesonasharedcluster.Single-tenantservicescanalsosupportregulatorycompliancewheresensitivedatamustbecompartmentalizedacrossseparatemachines.

Anon-demandservicesplitsitsoperationsbetweenthedefaultnetworkandtheservicenetwork.Sharedcomponentsoftheservice,suchasexecutivecontrollersanddatabases,runcentrallyonthedefaultnetworkalongwiththeCloudController,UAA,andotherPCFcomponents.Theworkerpooldeployedtospecificspacesrunsontheservicenetwork.

ThediagrambelowshowsworkerVMsinanon-demandserviceinstancerunningonaseparateservicesnetwork,whileothercomponentsrunonthedefaultnetwork.

RequiredNetworkingRulesforOn-DemandServices


Beforedeployingaservicetilethatusestheon-demandservicebroker(ODB),requesttheneedednetworkconnectionstoallowcomponentsofPCFtocommunicatewithODB.

ThespecificsofhowtoopenthoseconnectionsvariesforeachIaaS.

Seethefollowingtableforkeycomponentsandtheirresponsibilitiesinanon-demandarchitecture.

KeyComponents TheirResponsibilities

BOSHDirector

CreatesandupdatesserviceinstancesasinstructedbyODB.

BOSHAgentIncludesanagentoneveryVMthatitdeploys.TheagentlistensforinstructionsfromtheBOSHDirectorandcarriesoutthoseinstructions.TheagentreceivesjobspecificationsfromtheBOSHDirectorandusesthemtoassignarole,orjob,totheVM.

BOSHUAA IssuesOAuth2tokensforclientstousewhentheyactonbehalfofBOSHusers.

PAS Containstheappsthatareconsumingservices

ODBInstructsBOSHtocreateandupdateservices,andconnectstoservicestocreatebindings.

Deployedserviceinstance

Runsthegivendataservice.Forexample,thedeployedRedisforPCFserviceinstancerunstheRedisforPCFdataservice.

Regardlessofthespecificnetworklayout,theoperatormustensurenetworkrulesaresetupsothatconnectionsareopenasdescribedinthetablebelow.

Thiscomponent…

Mustcommunicatewith…

DefaultTCPPort Communicationdirection(s) Notes

ODB

BOSHDirector

BOSHUAA

25555(BOSHDirector)

8443(UAA)

8844(CredHub)

One-way

TheBOSHDirectorandBOSHUAAdefaultportsarenotconfigurable.TheCredHubdefaultportisconfigurable.

ODBDeployedserviceinstances

Specifictotheservice(suchasRabbitMQforPCF).Maybeoneormoreports.

One-way

Thisconnectionisforadministrativetasks.Avoidopeninggeneraluse,app-specificportsforthisconnection.


ODBPAS(orElasticRuntime)

8443 One-wayThedefaultportisnotconfigurable.

ErrandVMs

PAS(orElasticRuntime)

ODB

DeployedServiceInstances

8443

8080

Specifictotheservice.Maybeoneormoreports.

One-wayThedefaultportisnotconfigurable.

BOSHAgentBOSHDirector

4222 Two-way

TheBOSHAgentrunsoneveryVMinthesystem,includingtheBOSHDirectorVM.TheBOSHAgentinitiatestheconnectionwiththeBOSHDirector.Thedefaultportisnotconfigurable.

DeployedappsonPAS(orElasticRuntime)

Deployedserviceinstances

Specifictotheservice.Maybeoneormoreports.

One-way

Thisconnectionisforgeneraluse,app-specifictasks.Avoidopeningadministrativeportsforthisconnection.

PAS(orElasticRuntime)

ODB 8080 One-way

Thisportmaybedifferentforindividualservices.Thisportmayalsobeconfigurablebytheoperatorifallowedbythetiledeveloper.

PCCInstancesAcrossWAN

PCCserviceinstancesrunningwithindistinctPCFfoundationsmaycommunicatewitheachotheracrossaWAN.Inatopologysuchasthis,thememberswithinoneserviceinstanceusetheirownprivateaddressspace,asdefinedinRFC1918 .

AVPNmaybeusedtoconnecttheprivatenetworkspacesthatlayacrosstheWAN.Thestepsrequiredto


https://tools.ietf.org/html/rfc1918

enabletheconnectivitybyVPNaredependentontheIaaSprovider(s).

Theprivateaddressspaceforeachserviceinstance’snetworkmustbeconfiguredwithnon-overlappingCIDRblocks.Configurethenetworkpriortocreatingserviceinstances.LocatedirectionsforcreatinganetworkontheappropriateIAASproviderwithinthesectiontitledArchitectureandInstallationOverview .

RecommendedUsageandLimitationsSeeDesignPatternsfordescriptionsofthevarietyofdesignpatternsthatPCCsupports.

PCCstoresobjectsinkey/valueformat,wherevaluecanbeanyobject.

SeegfshCommandRestrictionsforlimitationsontheuseofgfshcommands.

Limitations

Scaledownoftheclusterisnotsupported.

Planmigrations,forexample, -p flagwiththe cf update-service command,arenotsupported.

SecurityPivotalrecommendsthatyoudothefollowing:

RunPCCinitsownnetwork

Usealoadbalancertoblockdirect,outsideaccesstotheGorouter

ToallowPCCnetworkaccessfromapps,youmustcreateapplicationsecuritygroupsthatallowaccessonthefollowingports:

1099

8080

40404

55221

Formoreinformation,seethePCFApplicationSecurityGroups topic.

PCCworkswiththeIPsecAdd-onforPCF.ForinformationabouttheIPsecAdd-onforPCF,seeSecuringDatainTransitwiththeIPsecAdd-on .


https://docs.pivotal.io/pivotalcf/installing/index.html

https://docs.pivotal.io/pivotalcf/adminguide/app-sec-groups.html#creating-groups

https://docs.pivotal.io/addon-ipsec/index.html

Authentication

PCCserviceinstancesarecreatedwiththreedefaultGemFireuserrolesforinteractingwithclusters:

AclusteroperatormanagestheGemFireclusterandcanaccessregiondata.

Adevelopercanaccessregiondata.

AgatewaysenderpropagatesregiondatatoanotherPCCserviceinstance.

Allclientapps,gfsh,andJMXclientsmustauthenticateasoneoftheseuserrolestoaccessthecluster.

TheidentifiersassignedfortheserolesaredetailedinCreateServiceKeys.

Authorization

Eachuserroleisgivenpredefinedpermissionsforclusteroperations.Toaccomplishaclusteroperation,theuserauthenticatesusingoneoftheroles.Priortoinitiatingtherequestedoperation,thereisaverificationthattheauthenticateduserrolehasthepermissionauthorizedtodotheoperation.Herearethepermissionsthateachuserrolehas:

Theclusteroperatorrolehas CLUSTER:MANAGE , CLUSTER:WRITE , CLUSTER:READ , DATA:MANAGE ,DATA:WRITE ,and DATA:READ permissions.

Thedeveloperrolehas CLUSTER:READ , DATA:WRITE ,and DATA:READ permissions.

Thegatewaysenderrolehas DATA:WRITE permission.

MoredetailsaboutthesepermissionsareinthePivotalGemFiremanualunderImplementingAuthorization .

FeedbackPleaseprovideanybugs,featurerequests,orquestionstothePivotalCloudFoundryFeedbacklist.


http://gemfire.docs.pivotal.io/geode/managing/security/implementing_authorization.html

mailto:[email protected]

PivotalCloudCacheOperatorGuideInthistopic

RequirementsforPivotalCloudCache

PreparingforTLSOverview

ProvideorGenerateaCACertificate

InstallingandConfiguringPivotalCloudCacheConfigureTileProperties

SettingServiceInstanceQuotas

CreateGlobal-levelQuotas

CreatePlan-levelQuotas

CreateandSetOrg-levelQuotas

CreateandSetSpace-levelQuotas

ViewCurrentOrgandSpace-levelQuotas

MonitorQuotaUseandServiceInstanceCount

CalculateResourceCostsforOn-DemandPlans

MonitoringPivotalCloudCacheServiceInstancesServiceInstanceMetrics

PerMemberMetrics

GatewaySenderandGatewayReceiverMetrics

DiskMetrics

TotalMemoryConsumption

MonitoringPCCServiceInstanceswithPrometheus

UpgradingPivotalCloudCache

MigratingtoaTLS-EnabledCluster

UpdatingPivotalCloudCachePlans

UninstallingPivotalCloudCache

TroubleshootingViewStatisticsFiles

SmokeTestFailures

GeneralConnectivity

ThisdocumentdescribeshowaPivotalCloudFoundry(PCF)operatorcaninstall,configure,andmaintainPivotalCloudCache(PCC).

RequirementsforPivotalCloudCacheTheNetworkingforOn-DemandServices sectiondescribesnetworkingrequirementsforPCC.

AsofPCCv1.5.3,PCCincreasessecuritybyrequiringTLSencryptionforgfshandPulse.FollowtheinstructionsinPreparingforTLSpriortoinstallingthetile.

PreparingforTLS

ThistopicdescribeshowtoprovideanexistingCertificateAuthority(CA)certificatetoBOSHCredHub andhowtogenerateanewCAcertificatewithBOSHCredHub,ifyoudonotalreadyhaveone.

warning:AsofPCCv1.5.3,PCCincreasessecuritybyrequiringTLSencryptionforgfshandPulse.CompletetheproceduresinthistopicbeforeinstallingthePCCtileaspartofanupgrade.

warning:ThisprocedureinvolvesrestartingalloftheVMsinyourPCFdeploymentinordertopropagateaCAcertificate.Theoperationcantakealongtimetocomplete.


https://docs.pivotal.io/p-cloud-cache/1-5/#service-network

https://docs.pivotal.io/tiledev/credhub.html

Overview

EnablingTLSprovisionsPCCserviceinstanceswithacertificatesothatapps,gfsh,andPulsecanestablishanencryptedconnectionwiththePCCserviceinstance.

ThecertificatedeployedonthePCCserviceinstanceisaservercertificate.TheservercertificateisgeneratedbyCredHub,acomponentdesignedforcentralizedcredentialmanagementinPCF.CredHubisdeployedonthesameVMastheBOSHDirector.

CredHubgeneratestheservercertificateusingaCertificateAuthority(CA)certificate.TheCAcertificatemustbeprovidedtoCredHubbytheoperatororgeneratedbyCredHub.

AppsusetheCAcertificatetoauthenticatecomponentsofPCCserviceinstances.AppsthatcommunicatewithPCCmusthaveaccesstotheCAcertificateinordertovalidatethattheservercertificatecanbetrusted.

ProvideorGenerateaCACertificate

PerformthefollowingprocedurestocreateaUserAccountandAuthentication(UAA)clientforCredHub,logintoCredHub,andprovideorgenerateaCAcertificate.

CreateaUAAClient

PerformthefollowingstepstocreateaUAAclientforCredHubonyourUAAserver:

1. RetrievetheIPaddressoftheBOSHDirectorVMandtheDirectorcredentialsbyperformingthestepsinGatherCredentialandIPAddressInformation .

BoththeUAAandCredHubserversarecolocatedontheBOSHDirectorVM.

2. SSHintotheOpsManagerVMbyperformingthestepsinSSHintoOpsManagerVM .

3. FromtheOpsManagerVM,usetheUAACommandLineInterface(UAAC)totargettheUAAserverontheBOSHDirectorVM.IntheUAACcommand,specifytheIPaddressfortheBOSHDirectorVMandport8443.

Runthefollowingcommand:

uaactargetBOSH-DIRECTOR:8443

where BOSH-DIRECTOR istheIPaddressoftheBOSHDirectorVM.YouretrievedthisaddressfromtheStatustaboftheOpsManagerDirectortileinstep1.

Forexample:

$uaactarget10.0.0.5:8443

4. IntheCredentialstaboftheOpsManagerDirectortile,retrievetheUAALoginClientCredentialsandrecordthe identity and password values.

5. RetrievetheUAAAdminUserCredentialsandrecordthe identity and password values.

warning:AnoperatormustrotatetheCAcertificateifitexpiresorifitbecomescompromised.TorotateyourCAcertificate,seeRotatingCACertificatesforPivotalCloudFoundryServices inthePivotalKnowledgeBase.DonotattempttorotateaCAcertificateonyourown.ContactPivotalSupport andperformtheprocedureinthePivotalKnowledgeBasearticlewiththeirassistance.

Note:ThesearethecredentialsfortheUAAservercolocatedontheBOSHDirector,nottheUAAservercolocatedonPivotalApplicationService.


https://discuss.pivotal.io/hc/en-us/articles/360002542194-Rotating-CA-Certificates-for-Pivotal-Cloud-Foundry-Services

https://support.pivotal.io

https://docs.pivotal.io/pivotalcf/customizing/trouble-advanced.html#gather

https://docs.pivotal.io/pivotalcf/customizing/trouble-advanced.html#ssh

6. FromtheOpsManagerVM,usetheUAACtogetatoken.


uaactokenownergetlogin--secret=UAA-LOGIN-CLIENT-CRED

where UAA-LOGIN-CLIENT-CRED isthe password valueoftheUAALoginClientCredentialsthatyouretrievedinstep4.

Forexample:

$uaactokenownerget\login--secret=abcdefghijklm123456789

7. Whenpromptedforausernameandpassword,enterthevaluesfor identity and password oftheUAAAdminUserCredentialsthatyouretrievedinstep5.Forexample:

Username:adminPassword:********************************

8. AddaUAAclientforCredHubwiththecorrectgrants.

Enterthefollowingcommand:

$uaacclientadd\--authorized_grant_typesclient_credentials\--authoritiescredhub.read,credhub.write

9. WhenpromptedforClientID,enter credhub .Whenpromptedfor Newclientsecret ,enterasecurepasswordofyourchoice.Forexample:

ClientID:credhubNewclientsecret:*******Verifynewclientsecret:*******scope:uaa.noneclient_id:credhubresource_ids:noneauthorized_grant_types:client_credentialsautoapprove:authorities:credhub.writecredhub.readname:credhubrequired_user_groups:lastmodified:1518198701452id:credhubcreated_by:f609e861-39ec-4a16-8aee-cba9e9b079e3

AddtheCACertificate

PerformthefollowingstepstologintoCredHub,provideorgenerateaCAcertificate,andaddthecertificatetoOpsManager:

1. FromtheOpsManagerVM,settheAPItargetoftheCredHubCLItoyourCredHubserver.


credhubapihttps://BOSH-DIRECTOR:8844--ca-cert=/var/tempest/workspaces/default/root_ca_certificate

where BOSH-DIRECTOR istheIPaddressoftheBOSHDirectorVM.

Forexample:


$credhubapihttps://10.0.0.5:8844--ca-cert=/var/tempest/workspaces/default/root_ca_certificate

2. LogintoCredHub.


credhublogin--client-name=credhub--client-secret=CLIENT-SECRET

where CLIENT-SECRET istheclientsecretyousetinstep9above.

Forexample:

$credhublogin\--client-name=credhub\--client-secret=abcdefghijklm123456789

3. UsetheCredHubCLItocheckwhetheraservicesCAcertificatealreadyispresent.

Enterthefollowingcommand:

$credhubget\--name="/services/tls_ca"

Ifyoualreadyhaveacertificateatthe services/tls_ca path,skiptostep5.

4. UsetheCredHubCLItogenerateaCAcertificateorprovideanexistingone.

IfyoudonothaveaCAcertificate,usetheCredHubCLItogenerateone.Enterthefollowingcommand:

$credhubgenerate\--name="/services/tls_ca"\--type="certificate"\--no-overwrite\--is-ca\--common-name="rootCA"

IfyouhaveanexistingCAcertificatethatyouwanttouse,createanewfilecalled root.pem withthecontentsofthecertificate.Thenenterthefollowingcommand,specifyingthepathto root.pem andtheprivatekeyforthecertificate:

$credhubset\--name="/services/tls_ca"\--type="certificate"\--certificate=./root.pem\--private=ERKSOSMFF...

5. UsetheBOSHCLIv2toextractthe certificate portionfromtheCAcertificateandprintit.Enterthefollowingcommand:

$bosh2interpolate<(credhubget--name=/services/tls_ca)\--path/value/certificate

6. Recordtheoutputofthe bosh2interpolate commandfromstep4.

7. NavigatetotheOpsManagerInstallationDashboardandselecttheOpsManagerDirectortile.ClickSecurity.

8. PastethecontentsoftheCAcertificateintoTrustedCertificatesandclickSave.

Note:YourPCFdeploymentmayhavemultipleCAcertificates.PivotalrecommendsadedicatedCAcertificateforservices.


9. TheCAcertificatemustalsobeaddedfortheGorouter.NavigatetothePASSettingstab.ClickonNetworking.AddtheCAcertificatetotheboxlabeledCertificateAuthoritiesTrustedbyRouterandHAProxyandclickSave.

10. Optionally,ifyouareusingOpsManagerv2.3orlater,clickReviewPendingChanges(seeReviewingPendingProductChanges ).

11. ClickApplyChanges.

InstallingandConfiguringPivotalCloudCacheWithanOpsManagerrole(detailedinUnderstandRolesinOpsManager )thathastheproperpermissionstoinstallandconfigure,followthesestepstoinstallPCConPCF:

1. DownloadthetilefromthePivotalNetwork .

2. ClickImportaProducttoimportthetileintoOpsManager.

3. Clickthe+symbolnexttotheuploadedproductdescription.

4. ClickontheCloudCachetile.

5. CompletealltheconfigurationstepsintheConfigureTilePropertiessectionbelow.

6. ReturntotheOpsManagerInstallationDashboard.Optionally,ifyouareusingOpsManagerv2.3orlater,clickReviewPendingChanges(seeReviewingPendingProductChanges ).

7. ClickApplyChangestocompletetheinstallationofthePCCtile.

ConfigureTileProperties

Configurethesectionslistedontheleftsideofthepage.


https://docs.pivotal.io/pivotalcf/customizing/review-pending-changes.html

https://docs.pivotal.io/pivotalcf/opsguide/config-rbac.html#about

https://network.pivotal.io/products/cloud-cache


Asyoucompleteasection,saveit.Agreencheckmarkappearsnexttothesectionname.Eachsectionnamemustshowthisgreencheckmarkbeforeyoucancompleteyourinstallation.

AssignAZsandNetworks

Settings

ServicePlans,includingtheDevPlan

Syslog

ServiceInstanceUpgrades

Security

Errands

AssignAvailabilityZonesandNetworks

ToselectAZsandnetworksforVMsusedbyPCC,dothefollowing:

1. ClickAssignAZsandNetworks.

2. ConfigurethefieldsontheAssignAZsandNetworkspaneasfollows:

Field Instructions

Placesingletonjobsin SelecttheregionthatyouwantforsingletonVMs.

Balanceotherjobsin SelecttheAZ(s)youwanttousefordistributingotherGemFireVMs.Pivotalrecommendsselectingallofthem.

Network SelectyourPAS(orElasticRuntime)network.

ServiceNetwork SelectthenetworktobeusedforGemFireVMs.

3. ClickSave.

Settings

SmokeTestSettings

Thesmoke-testserrandthatrunsaftertileinstallation.Theerrandverifiesthatyourinstallationwassuccessful.Bydefault,the smoke-test errandrunsonthe system organdthe p-cloudcache-smoke-test space.

Toselectwhichplanyouwanttouseforsmoketests,dothefollowing:

Selectaplantousewhenthe smoke-tests errandruns.

Ensuretheselectedplanisenabledandconfigured.Forinformationaboutconfiguringplans,seeConfigureServicePlansbelow.Iftheselectedplanisnotenabled,the smoke-tests errandfails.

Pivotalrecommendsthatyouusethesmallestfour-serverplanforsmoketests.Becausesmoketestscreateandlaterdestroythisplan,usingaverysmallplanreducesinstallationtime.

Note:Smoketestswillfailunlessyouenableglobaldefaultapplicationsecuritygroups(ASGs).YoucanenableglobaldefaultASGsbybindingtheASGtothe system orgwithoutspecifyingaspace.ToenableglobaldefaultASGs,use cfbind-running-security-

group.


Settings:AllowOutboundInternetAccessSettings

Bydefault,outboundinternetaccessisnotallowedfromserviceinstances.

IfBOSHisconfiguredtouseanexternalblobstore,youneedallowoutboundinternetaccessfromserviceinstances.Logforwardingandbackups,whichrequireexternalendpoints,mightalsorequireinternetaccess.

Toallowoutboundinternetaccessfromserviceinstance,dothefollowing:

SelectAllowoutboundinternetaccessfromserviceinstances(IaaS-dependent).

DefaultDistributedSystemIDSetting

EveryserviceinstancehasanintegeridentifiercalledadistributedsystemID.TheIDdefaultstothevalue0.ServiceinstancesthatformadistributedsystemthatcommunicatesacrossaWANwillneeddistinctIDs.ThosedistinctIDvaluesaresetwhencreatingtheserviceinstance.

TochangethedefaultdistributedsystemIDvalue,replacethedefaultvalueof0withyournewdefaultvalue.Acceptablevaluesareintegersgreaterthanorequalto0andlessthanorequalto255.

ConfigureServicePlans

Youcanconfigurefiveindividualplansforyourdevelopers.SelectthePlan1throughPlan5tabstoconfigureeachofthem.

Note:OutboundnetworktrafficrulesalsodependonyourIaaSsettings.ConsultyournetworkorIaaSadministratortoensurethatyourIaaSallowsoutboundtraffictotheexternalnetworksyouneed.


ThePlanEnabledoptionisselectedbydefault.IfyoudonotwanttoaddthisplantotheCFservicecatalog,selectPlanDisabled.Youmustenableat


leastoneplan.

ThePlanNametextfieldallowsyoutocustomizethenameoftheplan.ThisplannameisdisplayedtodeveloperswhentheyviewtheserviceintheMarketplace.

ThePlanDescriptiontextfieldallowsyoutosupplyaplandescription.ThedescriptionisdisplayedtodeveloperswhentheyviewtheserviceintheMarketplace.

TheEnablemetricsforserviceinstancescheckboxenablesmetricsforserviceinstancescreatedusingtheplan.Onceenabled,themetricsaresenttotheLoggregatorFirehose.

TheCFServiceAccessdrop-downmenugivesyoutheoptiontodisplayornotdisplaytheserviceplanintheMarketplace.EnableServiceAccessdisplaystheserviceplantheMarketplace.DisableServiceAccessmakestheplanunavailableintheMarketplace.Ifyouchoosethisoption,youcannotmaketheplanavailableatalatertime.LeaveServiceAccessUnchangedmakestheplanunavailableintheMarketplacebydefault,butallowsyoutomakeitavailableatalatertime.

TheServiceInstanceQuotasetsthemaximumnumberofPCCclustersthatcanexistsimultaneously.

Whendeveloperscreateorupdateaserviceinstance,theycanspecifythenumberofserversinthecluster.TheMaximumserversperclusterfieldallowsoperatorstosetanupperboundonthenumberofserversdeveloperscanrequest.Ifdevelopersdonotexplicitlyspecifythenumberofserversinaserviceinstance,anewclusterhasthenumberofserversspecifiedintheDefaultNumberofServersfield.

TheAvailabilityzonesforserviceinstancessettingdetermineswhichAZsareusedforaparticularcluster.ThemembersofaclusteraredistributedevenlyacrossAZs.

TheremainingfieldscontroltheVMtypeandpersistentdisktypeforserversandlocators.ThetotalsizeofthecacheisdirectlyrelatedtothenumberofserversandtheamountofmemoryoftheselectedserverVMtype.Werecommendthefollowingconfiguration:

FortheVMtypefortheLocatorVMsfield,selectaVMthathasatleast2CPUs,1GBofRAMand4GBofdiskspace.

ForthePersistentdisktypefortheLocatorVMsfield,select10GBorhigher.

FortheVMtypefortheServerVMsfield,selectaVMthathasatleast2CPUs,4GBofRAMand8GBofdiskspace.

ForthePersistentdisktypefortheserverVMsfield,select10GBorhigher.

Whenyoufinishconfiguringtheplan,clickSavetosaveyourconfigurationoptions.

ConfigureaDevPlan

ADevPlanisatypeofserviceplan.UseaDevPlanfordevelopmentandtesting.Theplanprovidesasinglelocatorandserver,whicharecolocatedwithinasingleVM.

ThepageforconfiguringaDevPlanissimilartothepageforconfiguringotherserviceplans.ToconfiguretheDevPlan,inputinformationinthefieldsandmakeselectionsfromtheoptionsonthePlanfortestdevelopmentpage.

warning!Afteryou’veselectedAZsforyourservicenetwork,youcannotaddadditionalAZs;doingsocausesexistingserviceinstancestolosedataonupdate.


Ifyouhaveenabledpost-deployscriptsinyourBOSHDirector,aregionisautomaticallycreated.Toconfirmthatpost-deployscriptsareenabled,navigatetotheDirectorConfigpaneofOpsMangerDirectorandverifythatEnablePostDeployScriptsisselected.


Syslog

Bydefault,syslogforwardingisnotenabledinPCC.However,PCCsupportsforwardingsyslogtoanexternallogmanagementservice(forexample,Papertrail,Splunk,oryourcustomenterpriselogsink).Thebrokerlogsareusefulfordebuggingproblemscreating,updating,andbindingserviceinstances.

Toenableremotesyslogfortheservicebroker,dothefollowing:

1. ClickSyslog.

2. ConfigurethefieldsontheSyslogpaneasfollows:

Field Instructions

EnableRemoteSyslog Selecttoenable.

ExternalSyslogAddress Entertheaddressorhostofthesyslogserverforsendinglogs,forexample, logs.example.com .

ExternalSyslogPort Entertheportofthesyslogserverforsendinglogs,forexample, 29279 .

EnableTLSforSyslogSelecttoenablesecurelogtransmissionthroughTLS.Withoutthis,remotesyslogsendsunencryptedlogs.WerecommendenablingTLS,asmostsyslogendpointssuchasPapertrailandLogsearchrequireTLS.


PermittedPeerforTLSCommunication.ThisisrequiredifTLSisenabled.

Ifthereareseveralpeerserversthatcanrespondtoremotesyslogconnections,thenprovidearegex,suchas*.example.com .

CACertificateforTLSCommunication

Iftheservercertificateisnotsignedbyaknownauthority,forexample,aninternalsyslogserver,providetheCAcertificateofthelogmanagementserviceendpoint.

Sendserviceinstancelogstoexternal

Bydefault,onlythebrokerlogsareforwardedtoyourconfiguredlogmanagementservice.Ifyouwanttoforwardserverandlocatorlogsfromallserviceinstances,selectthis.Thisletsyoumonitorthehealthoftheclusters,althoughitgeneratesalargevolumeoflogs.

Ifyoudon’tenablethis,yougetonlythebrokerlogswhichincludeinformationaboutserviceinstancecreation,butnotabouton-goingclusterhealth.

3. ClickSave.

ServiceInstanceUpgrades

AconfigurablenumberofserviceinstancesmaybeupgradedconcurrentlybyenteringanewvaluethatisgreaterthanoneandlessthantheBOSHworkercountfortheNumberofsimultaneousupgrades.

SpecifyasetofserviceinstancestoactascanariesfortheupgradeprocessbychangingtheNumberofupgradecanaryinstancestoavaluegreaterthan0.Ifallcanaryinstancessuccessfullyupgrade,theremaininginstancesareupgraded.Ifanycanaryinstancefailstoupgrade,theupgradefailsandnofurtherinstancesareupgraded.

ClickSaveafterchangingvalues.

Security

TheenvironmentmaybeconfiguredtomoresecurelystoreservicekeyswithinCredHub,insteadofwithinthecloudcontroller’sdatastore.Toenablethisfunctionality:

1. ClickSecurity.

2. ClickontheboxlabeledEnableSecureServiceInstanceCredentialstoenableuseofCredHub.

3. An‘X’isrequiredinthetextboxtopromotetheunderstandingthataTLS-enabledserviceinstancecannotbecreatedifthePCFenvironmentisnotsetuptohandleTLS.SeePreparingforTLSforhowtopreparethePCFenvironment.

4. ClickSave.


Errands

Bydefault,post-deployandpre-deleteerrandsalwaysrun.Pivotalrecommendskeepingthesedefaults.However,ifnecessary,youcanchangethesedefaultsasfollows.

ForgeneralinformationabouterrandsinPCF,seeManagingErrandsinOpsManager

1. ClickErrands.

2. Changethesettingfortheerrands.

3. ClickSave.

SettingServiceInstanceQuotasOn-demandprovisioningisintendedtoaccelerateappdevelopmentbyeliminatingtheneedfordevelopmentteamstorequestandwaitforoperatorstocreateaserviceinstance.However,tocontrolcosts,operationsteamsandadministratorsmustensureresponsibleuseofresources.

Thereareseveralwaystocontroltheprovisioningofon-demandserviceinstancesbysettingvariousquotasattheselevels:

Global

Plan

Org

Space

Afteryousetquotas,youcan:

ViewCurrentOrgandSpace-levelQuotas

MonitorQuotaUseandServiceInstanceCount

CalculateResourceCostsforOn-DemandPlans

CreateGlobal-levelQuotasEachPivotalCloudFoundry(PCF)servicehasaseparateservicebroker.Aglobalquotaattheservicelevelsetsthemaximumnumberofserviceinstancesthatcanbecreatedbyagivenservicebroker.Ifaservicehasmorethanoneplan,thenthenumberofserviceinstancesforallplanscombinedcannotexceedtheglobalquotafortheservice.

TheoperatorsetsaglobalquotaforeachPCFserviceindependently.Forexample,ifyouhaveRedisforPCFandRabbitMQforPCF,youmustsetaseparateglobalservicequotaforeachofthem.

Whentheglobalquotaisreachedforaservice,nomoreinstancesofthatservicecanbecreatedunlessthequotaisincreased,orsomeinstancesofthatservicearedeleted.

TheglobalquotaissetintheservicetileinOpsManager,shownforanexampleservicebelow.


https://docs.pivotal.io/pivotalcf/customizing/managing_errands.html

CreatePlan-levelQuotasAservicemayofferoneormoreplans.Youcansetaseparatequotaperplansothatinstancesofthatplancannotexceedtheplanquota.Foraservicewithmultipleplans,thetotalnumberofinstancescreatedforallplanscombinedcannotexceedtheglobalquotafortheservice.

Whentheplanquotaisreached,nomoreinstancesofthatplancanbecreatedunlesstheplanquotaisincreasedorsomeinstancesofthatplanaredeleted.

TheplanquotaissetintheservicetileinOpsManager,shownforanexampleserviceplanbelow.

Note:Thisisanexampleimageonly.Thefollowingscreenmaylookslightlydifferentforyourserviceorreleaseversion.

Note:Thisisanexampleimageonly.Thefollowingscreenmaylookslightlydifferentforyourserviceorreleaseversion.



CreateandSetOrg-levelQuotasAnorg-levelquotaappliestoallPCFservicesandsetsthemaximumnumberofserviceinstancesanorganizationcancreatewithinPCF.Forexample,ifyousetyourorg-levelquotato100,developerscancreateupto100serviceinstancesinthatorgusinganycombinationofPCFservices.

Whenthisquotaismet,nomoreserviceinstancesofanykindcanbecreatedintheorgunlessthequotaisincreasedorsomeserviceinstancesaredeleted.

Tocreateandsetanorg-levelquota,dothefollowing:

1. Runthiscommandtocreateaquotaforserviceinstancesattheorglevel:

cf create-quota QUOTA-NAME -m TOTAL-MEMORY -i INSTANCE-MEMORY -r ROUTES -s SERVICE-INSTANCES --allow-paid-service-plans

wherethesevariablesare:

QUOTA-NAME —AnameforthisquotaTOTAL-MEMORY —MaximummemoryusedbyallserviceinstancescombinedINSTANCE-MEMORY —MaximummemoryusedbyanysingleserviceinstanceROUTES —MaximumnumberofroutesallowedforallserviceinstancescombinedSERVICE-INSTANCES —Maximumnumberofserviceinstancesallowedfortheorg

Forexample:cfcreate-quotamyquota-m1024mb-i16gb-r30-s50--allow-paid-service-plans

2. Associatethequotayoucreatedabovewithaspecificorgbyrunningthefollowingcommand:

cf set-quota ORG-NAME QUOTA-NAME

Forexample: cfset-quotadev_orgmyquota

Formoreinformationonmanagingorg-levelquotas,seeCreatingandModifyingQuotaPlans .

CreateandSetSpace-levelQuotasAspace-levelservicequotaappliestoallPCFservicesandsetsthemaximumnumberofserviceinstancesthatcanbecreatedwithinagivenspaceinPCF.Forexample,ifyousetyourspace-levelquotato100,developerscancreateupto100serviceinstancesinthatspaceusinganycombinationofPCFservices.

Whenthisquotaismet,nomoreserviceinstancesofanykindcanbecreatedinthespaceunlessthequotaisupdatedorsomeserviceinstancesaredeleted.

Tocreateandsetaspace-levelquota,dothefollowing:

1. Runthefollowingcommandtocreatethequota:

cf create-space-quota QUOTA -m TOTAL-MEMORY -i INSTANCE-MEMORY -r ROUTES -s SERVICE-INSTANCES --allow-paid-service-plans

wherethesevariablesare:


https://docs.pivotal.io/pivotalcf/1-12/adminguide/quota-plans.html

QUOTA-NAME —AnameforthisquotaTOTAL-MEMORY —MaximummemoryusedbyallserviceinstancescombinedINSTANCE-MEMORY —MaximummemoryusedbyanysingleserviceinstanceROUTES —MaximumnumberofroutesallowedforallserviceinstancescombinedSERVICE-INSTANCES —Maximumnumberofserviceinstancesallowedfortheorg

Forexample: cfcreate-space-quotamyspacequota-m1024mb-i16gb-r30-s50--allow-paid-service-plans

2. Associatethequotayoucreatedabovewithaspecificspacebyrunningthefollowingcommand:

cf set-space-quota SPACE-NAME QUOTA-NAME

Forexample:cfset-space-quotamyspacemyspacequota

Formoreinformationonmanagingspace-levelquotas,seeCreatingandModifyingQuotaPlans .

ViewCurrentOrgandSpace-levelQuotasTovieworgquotas,runthefollowingcommand.

cforgORG-NAME

Toviewspacequotas,runthefollowingcommand:

cfspaceSPACE-NAME

Formoreinformationonmanagingorgandspace-levelquotas,seetheCreatingandModifyingQuotaPlans .

MonitorQuotaUseandServiceInstanceCountService-levelandplan-levelquotause,andtotalnumberofserviceinstances,areavailablethroughtheon-demandbrokermetricsemittedtoLoggregator.Thesemetricsarelistedbelow:

MetricName Description

on-demand-broker/SERVICE-NAME/quota_remaining Quotaremainingforallinstancesacrossallplans

on-demand-broker/SERVICE-NAME/PLAN-NAME/quota_remaining Quotaremainingforaspecificplan

on-demand-broker/SERVICE-NAME/total_instances Totalinstancescreatedacrossallplans

on-demand-broker/SERVICE-NAME/PLAN-NAME/total_instances Totalinstancescreatedforaspecificplan

CalculateResourceCostsforOn-DemandPlansOn-demandplansusededicatedVMs,disks,andvariousotherresourcesfromanIaaS,suchasAWS.Tocalculatemaximumresourcecostforplansindividuallyorcombined,youmultiplythequotabythecostofVMandPersistentDisktypesselectedintheplanconfiguration(s).ThespecificcostsdependonyourIaaS.

TheimagebelowshowsanexampleoftheVMtypeandpersistentdiskselected,aswellasthequotaforthisplan.

Note:Quotametricsarenotemittedifnoquotahasbeenset.




CalculateMaximumResourceCostPerOn-DemandPlan

TocalculatethemaximumcostofVMsandpersistentdiskforeachplan,dothefollowingcalculation:

planquotaxcostofselectedresources

Forexample,ifyouselectedtheoptionsintheaboveimage,youhaveselectedaVMtypemicro.cpuandapersistentdisktype20GB,andtheplanquotais15.TheVMandpersistentdisktypeshaveanassociatedcostfortheIaaSyouareusing.Therefore,tocalculatethemaximumcostofresourcesforthisplan,multiplythecostoftheresourcesselectedbytheplanquota:

(15xcostofmicro.cpuVMtype)+(15xcostof20GBpersistentdisk)

CalculateMaximumResourceCostforAllOn-DemandPlans

Tocalculatethemaximumcostforallplanscombined,addtogetherthemaximumcostsforeachplan.Thisassumesthatthesumofyourindividualplanquotasislessthantheglobalquota.

Hereisanexample:

(plan1quotaxplan1resourcecost)+(plan2quotaxplan2resourcecost)=maxcostforallplans

CalculateActualResourceCostofallOn-DemandPlans

Tocalculatethecurrentactualresourcecostacrossallyouron-demandplans:

1. Findthenumberofinstancescurrentlyprovisionedforeachactiveplanbylookingatthe total_instance metricforthatplan.

2. Multiplythe total_instance countforeachplanbythatplan’sresourcecosts.Recordthecostsforeachplan.

3. AddupthecostsnotedinStep2togetyourtotalcurrentresourcecosts.

Forexample:

(plan1total_instancesxplan1resourcecost)+(plan2total_instancesxplan2resourcecost)=currentcostforallplans

MonitoringPivotalCloudCacheServiceInstances

Important:Althoughoperatorscanlimiton-demandinstanceswithplanquotasandaglobalquota,asdescribedintheabovetopics,IaaSresourceusagestillvariesbasedonthenumberofon-demandinstancesprovisioned.


PCCclustersandbrokersemitservicemetrics.YoucanuseanytoolthathasacorrespondingCloudFoundrynozzletoreadandmonitorthesemetricsinrealtime.

Asanappdeveloper,whenyouopttouseadataservice,youshouldbepreparedto:

monitorthestateofthatservice

triageissuesthatoccurwiththatservice

benotifiedofanyconcerns

Ifyoubelieveanissuerelatestotheunderlyinginfrastructure(network,CPU,memory,ordisk),youwillneedtocaptureevidenceandnotifyyourplatformteam.Themetricsdescribedinthissectioncanhelpincharacterizingtheperformanceandresourceconsumptionofyourserviceinstance.

ServiceInstanceMetrics

Inthedescriptionsofthemetrics,KPIstandsforKeyPerformanceIndicator.

MemberCount

serviceinstance.MemberCount

Description Returnsthenumberofmembersinthedistributedsystem.

MetricType number

Suggestedmeasurement Everysecond

MeasurementType count

WarningThreshold lessthanthemanifestmembercount

SuggestedActionsThisdependsontheexpectedmembercount,whichisavailableintheBOSHmanifest.Ifthenumberexpectedisdifferentfromthenumberemitted,thisisacriticalsituationthatmayleadtodataloss,andthereasonsfornodefailureshouldbeinvestigatedbyexaminingtheservicelogs.

WhyaKPI? Memberlossduetoanyreasoncanpotentiallycausedataloss.

TotalAvailableHeapSize

serviceinstance.TotalHeapSize

Description Returnsthetotalavailableheap,inmegabytes,acrossallinstancemembers.

MetricType number


MeasurementType pulse

WhyaKPI?Ifthetotalheapsizeandusedheapsizearetooclose,thesystemmightseethrashingduetoGCactivity.Thisincreaseslatency.

TotalUsedHeapSize

serviceinstance.UsedHeapSize

Description Returnsthetotalheapusedacrossallinstancemembers,inmegabytes.

MetricType number





TotalAvailableHeapSizeasaPercentage

serviceinstance.UnusedHeapSizePercentage

Description Returnstheproportionoftotalavailableheapacrossallinstancemembers,expressedasapercentage.

MetricType percent


MeasurementType compoundmetric

WarningThreshold 40%

CriticalThreshold 10%

SuggestedActionsIfthisisaspikeduetoevictioncatchingupwithinsertfrequency,thencustomersneedtokeepaclosewatchthatitshouldnothittheREDmarker.Ifthereisnoeviction,thenhorizontalscalingissuggested.


PerMemberMetrics

MemoryUsedasaPercentage

member.UsedMemoryPercentage

Description RAMbeingconsumed.

MetricType percent

Suggestedmeasurement Averageoverlast10minutes

MeasurementType average



CountofJavaGarbageCollections

member.GarbageCollectionCount

Description Thenumberoftimesthatgarbagehasbeencollected.

MetricType number

Suggestedmeasurement Sumoverlast10minutes


WarningThreshold DependentontheIaaSandappusecase.

CriticalThreshold DependentontheIaaSandappusecase.

SuggestedActionsCheckthenumberofqueriesrunagainstthesystem,whichincreasesthedeserializationofobjectsandincreasesgarbage.

WhyaKPI?Ifthefrequencyofgarbagecollectionishigh,thesystemmightseehighCPUusage,whichcausesdelaysinthecluster.


CPUUtilizationPercentage

member.HostCpuUsage

Description Thismember’sprocessCPUutilization,expressedasapercentage.

MetricType percent





SuggestedActions IfthisisnothappeningwithhighGCactivity,thesystemisreachingitslimits.Horizontalscalingmighthelp.

WhyaKPI?HighCPUusagecausesdelayedresponsesandcanalsomakethemembernon-responsive.Thiscancausethemembertobekickedoutofthecluster,potentiallyleadingtodataloss.

AverageLatencyofGetOperations

member.GetsAvgLatency

Description Theaveragelatencyofcachegetoperations,innanoseconds.

MetricType number





SuggestedActions IfthisisnothappeningwithhighGCactivity,thesystemisreachingitslimit.Horizontalscalingmighthelp.

WhyaKPI?Itisagoodindicatoroftheoverallresponsivenessofthesystem.Ifthisnumberishigh,theserviceadministratorshoulddiagnosetherootcause.

AverageLatencyofPutOperations

member.PutsAvgLatency

Description Theaveragelatencyofcacheputoperations,innanoseconds.

MetricType number





SuggestedActions IfthisisnothappeningwithhighGCactivity,thesystemisreachingitslimit.Horizontalscalingmighthelp.

WhyaKPI?Itisagoodindicatoroftheoverallresponsivenessofthesystem.Ifthisnumberishigh,theserviceadministratorshoulddiagnosetherootcause.

JVMpauses

member.JVMPauses


Description ThequantityofJVMpauses.

MetricType number

Suggestedmeasurement Sumover2seconds




SuggestedActionsCheckthecachedobjectsize;ifitisgreaterthan1MB,youmaybehittingthelimitationonJVMtogarbagecollectthisobject.Otherwise,youmaybehittingtheutilizationlimitonthecluster,andwillneedtoscaleuptoaddmorememorytothecluster.

WhyaKPI?DuetoaJVMpause,thememberstopsrespondingto“are-you-alive”messages,whichmaycausethismembertobekickedoutofthecluster.

FileDescriptorLimit

member.FileDescriptorLimit

Description Themaximumnumberofopenfiledescriptorsallowedforthemember’shostoperatingsystem.

MetricType number



WhyaKPI?Ifthenumberofopenfiledescriptorsexceedsnumberavailable,itcausesthemembertostoprespondingandcrash.

OpenFileDescriptors

member.TotalFileDescriptorOpen

Description Thecurrentnumberofopenfiledescriptors.

MetricType number



WhyaKPI?Ifthenumberofopenfiledescriptorsexceedsnumberavailable,itcausesthemembertostoprespondingandcrash.

QuantityofRemainingFileDescriptors

member.FileDescriptorRemaining

Description Thenumberofavailablefiledescriptors.

MetricType number


MeasurementType compoundmetric

WarningThreshold 1000

CriticalThreshold 100

SuggestedActions Scalehorizontallytoincreasecapacity.

Ifthenumberofopenfiledescriptorsexceedsnumberavailable,itcausesthemembertostoprespondingand


WhyaKPI? crash.

GatewaySenderandGatewayReceiverMetrics

ThesearemetricsemittedthroughtheCFNozzleforgatewaysendersandgatewayreceivers.

QueueSizefortheGatewaySender

gatewaySender.<sender-id>.EventQueueSize

Description Thecurrentsizeofthegatewaysenderqueue.

MetricType number


EventsReceivedattheGatewaySender

gatewaySender.<sender-id>.EventsReceivedRate

DescriptionAcountoftheeventscomingfromtheregiontowhichthegatewaysenderisattached.Itisthecountsincethelasttimethemetricwaschecked.Thefirsttimeitischecked,thecountisofthenumberofeventssincethegatewaysenderwascreated.

MetricType number


EventsQueuedbytheGatewaySender

gatewaySender.<sender-id>.EventsQueuedRate

Description

Acountoftheeventsqueuedonthegatewaysenderfromtheregion.Thisquantityofeventsmightbelowerthanthequantityofeventsreceived,asnotallreceivedeventsarequeued.Itisacountsincethelasttimethemetricwaschecked.Thefirsttimeitischecked,thecountisofthenumberofeventssincethegatewaysenderwascreated.

MetricType number


EventsReceivedbytheGatewayReceiver

gatewayReceiver.EventsReceivedRate

DescriptionAcountoftheeventsreceivedfromthegatewaysenderwhichwillbeappliedtotheregiononthegatewayreceiver’ssite.Itisthecountsincethelasttimethemetricwaschecked.Thefirsttimeitischecked,thecountisofthenumberofeventssincethegatewayreceiverwascreated.

MetricType number


DiskMetrics

ThesearemetricsemittedthroughtheCFNozzlefordisks.

AverageLatencyofDiskWrites

diskstore.DiskWritesAvgLatency

Description Theaveragelatencyofdiskwritesinnanoseconds.


MetricType number

MeasurementType timeinnanoseconds

QuantityofBytesonDisk

diskstore.TotalSpace

Description Thetotalnumberofbytesontheattacheddisk.

MetricType number


QuantityofAvailableBytesonDisk

diskstore.UseableSpace

Description Thetotalnumberofbytesofavailablespaceontheattacheddisk.

MetricType number


TotalMemoryConsumption

TheBOSH mem-check errandcalculatesandoutputsthequantityofmemoryusedacrossallPCCserviceinstances.ThiserrandhelpsPCFoperatorsmonitorresourcecosts,whicharebasedonmemoryusage.

Fromthedirector,runaBOSHcommandoftheform:

bosh-d<servicebrokername>run-errandmem-check

Withthiscommand:

bosh-dcloudcache-service-brokerrun-errandmem-check

Hereisananonymizedportionofexampleoutputfromthe mem-check errandforatwoclusterdeployment:

Analyzingdeploymentxxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxx1...JVMheapusageforserviceinstancexxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxx1UsedTotal=1204MBMaxTotal=3201MB

Analyzingdeploymentxxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxx2...JVMheapusageforserviceinstancexxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxx2UsedTotal=986MBMaxTotal=3201MB

JVMheapusageforallclusterseverywhere:UsedGlobalTotal=2390MBMaxGlobalTotal=6402MB

MonitoringPCCServiceInstanceswithPrometheus

Prometheusisoneofvarioustoolsyoucanusetomonitorservicesinstances.Itisamonitoringandalertingtoolkitthatallowsformetricscraping.YoucanusetheFirehoseexporter toexportallthemetricsfromtheFirehose,whichyoucanthengraphwithGrafana tomonitoryourPCCcluster.

Followtheinstructionshere todeployPrometheusalongsideyourPCFcluster.

PrometheuscanbedeployedonanyIaaS.YouneedtoverifythattheFirehoseexporterjobcantalktoyourUAAVM.ThismightinvolveopeningupfirewallrulesorenablingyourVMtoallowoutgoingtraffic.


https://github.com/cloudfoundry-community/firehose_exporter

https://github.com/grafana/grafana

https://github.com/pivotal-cf/prometheus-on-PCF

Youcanrunquerieson,andbuildacustomdashboardof,specificmetricsthatareimportanttoyou.

UpgradingPivotalCloudCacheUpgrademinorreleaseversionsfromyourcurrentlydeployedversiontothetargetversioninsequentialorder.Forexample,PCCv1.2mustbeupgradedtoPCCv1.3priortoupgradingtoPCCv1.4.NotethateachPCCreleaseiscompatiblewithtwoPivotalApplicationService(PAS)andOpsManagerversions,asspecifiedintheProductSnapshot .IncorporatethoseupgradestoPASandOpsManagerinyourupgradeprocessasrequiredtomaintaincompatibility,asdescribedinUpgradingPivotalCloudFoundry .

FollowthestepsbelowtoupgradePCC:

1. DownloadthenewversionofthetilefromthePivotalNetwork.

2. UploadtheproducttoOpsManager.


https://docs.pivotal.io/p-cloud-cache/1-5/#snapshot

https://docs.pivotal.io/pivotalcf/customizing/upgrading-pcf.html

3. ClickAddnexttotheuploadedproduct.

4. ClickontheCloudCachetileandconfiguretheupgradeoptions.

Totrytheupgradeonasmallnumberofserviceinstancesfirst,setthequantityofcanaryserviceinstancesasdescribedinServiceInstanceUpgrades.SetthenumberofinstancesthataretobeupgradedinparallelasdescribedinServiceInstanceUpgrades.MakesurethatundertheErrandssection,theUpgradeAllServiceInstancesPost-DeployErrandisDefault(On).Savethechange.



MigratingtoaTLS-EnabledClusterAnexistingPCCserviceinstancethatdoesnotuseTLSencryptionmaybemigratedtobecomeaPCCserviceinstancewithTLSencryptionenabled.

Followtheproceduregivenhereaftertheseprerequisiteshavebeenmet:

AllstepswithinPreparingforTLShavebeencompleted.

TheserviceinstancehasbeenupgradedtoPCCv1.5.2oramorerecentPCCversion.TherewillbenoPCCversionchangeduringthemigration.

FollowthisproceduretomigratetheexistingPCCserviceinstance:

1. AsaPCFoperator,stopallapps.First,listallappstoidentifythe APP_NAME .

$ cf apps

Then,stopeachappwith:

$ cf stop APP_NAME

2. Forallnon-persistentregions,usethe gfsh commandlinetooltoexportthedata.

CompletethestepswithinAccessingaServiceInstancetoacquirethecorrectversionof gfsh ,runit,andconnecttotheclusterusingtheclusteroperatorrole/credentialsfromtheservicekey.Listtheregions.

gfsh>list regions

Foreachregion,use gfsh describe todetermineiftheregionispersistentornotandtoacquireaservername.

gfsh>describe region --name=REGION_NAME

Foreachnon-persistentregion,usethissingle gfsh commandtoexportallthedatawithintheregion.The SERVER_NAME identifieswhichGemFireserverreceivesthe export commandandpropagatesthecommandtoallotherGemFireserverswithinthecluster.

gfsh>export data --parallel --region=REGION_NAME --member=SERVER_NAME --dir=/var/vcap/store/gemfire-server

3. YourPCFoperatorneedstotargettheBOSHDirectorinordertoacquirethe DEPLOYMENT_NAME .

Run

warning!Thisprocedurewillrequiredowntimefortheserviceinstanceduringthemigration.

warning!Withoutanexport,allnon-persistentregionentrieswillbeirretrievablylost.



$ cf service SERVICE_INSTANCE_NAME

toacquirethedigitsthatuniquelyidentifytheserviceinstance.Thedigits( XXX-XXX inthefollowinginstructions)arethosebetweencloudcache- andtheperiod . .

LogintotheBOSHDirector.

$ bosh log-in

The DEPLOYMENT_NAME willappearintheoutputof

$ bosh deployments | grep XXX-XXX

4. UsingPCFoperatorcredentials,stoptheBOSHdeployment:

$ bosh -d DEPLOYMENT_NAME stop

andtype“y”whenprompted.

5. AcquiretheBOSHmanifestwith:

$ bosh -d DEPLOYMENT_NAME manifest > DEPLOYMENT_NAME-manifest.yml

6. EdittheacquiredBOSHmanifest.Therearethreelocationswithinthemanifestfilethatwillrequireadditions.Thesethreelocationsareidentifiedwithinthisanonymizedportionofthemanifestfilewiththesymbols①,②,and③.Thefirstpartofthemanifestfileisomitted,asitslistedvalueschangebasedonthePCCversion.Realpasswordshavebeenreplacedwiththeplaceholder password ,andusernameshavebeenreplacedwiththeplaceholder userX withinthisexample.

instance_groups:- name: locator instances: 3 jobs: - name: gemfire-locator release: gemfire properties: gemfire: ① distributed-system-id: 0 locator: bpm_enabled: true port: '55221' properties: enable-time-statistics: true persist-pdx: true security: internal_cluster_password: password internal_cluster_username: userX roles: cluster_operator: - CLUSTER:WRITE - CLUSTER:READ - DATA:MANAGE - DATA:WRITE - DATA:READ - CLUSTER:MANAGE:DEPLOY - CLUSTER:MANAGE - CLUSTER:MANAGE:GATEWAY developer: - CLUSTER:READ - DATA:WRITE - DATA:READ gateway: - DATA:WRITE users: cluster_operator_userX: password: password roles: - cluster_operator


developer_userX: password: password roles: - developer - name: route_registrar release: routing consumes: nats: deployment: cf-NNNNNNNNNNN from: nats properties: route_registrar: routes: - name: cloudcache port: 8080 ② registration_interval: 20s uris: - cloudcache-XXX-XXX.example.com - name: bpm release: bpm vm_type: micro.cpu stemcell: stemcell persistent_disk_type: '10240' azs: - us-central1-f networks: - name: example-services-subnet- name: server instances: 4 jobs: - name: gemfire-server release: gemfire properties: gemfire: server: bpm_enabled: true create-gateway-receiver: true development-mode: false properties: enable-time-statistics: true jmx-manager-start: true security: gateway_password: password gateway_username: gateway_sender_userX - name: prime-cluster-for-pcc release: gemfire - name: bpm release: bpm vm_type: medium.cpu stemcell: stemcell persistent_disk_type: '10240' azs: - us-central1-f networks: - name: example-services-subnetupdate: canaries: 1 canary_watch_time: 1000-600000 update_watch_time: 1000-600000 max_in_flight: 32 serial: truefeatures: converge_variables: true ③

AddlinestotheBOSHmanifest,usingthelinesasshowninredinthefollowingmodifiedversionofthemanifest.Substituteyourdigitsthatuniquelyidentifyyourserviceinstancefor XXX-XXX withintheaddedlines.

instance_groups:- name: locator instances: 3 jobs: - name: gemfire-locator release: gemfire properties:


gemfire: ① tls: true truststore_password: ((trust-store-password)) keystore_password: ((key-store-password)) certificate: ((gemfire-certificate)) trusted_certs: - ((/cf/diego-instance-identity-root-ca)) - ((/services/tls_ca)) distributed-system-id: 0 locator: bpm_enabled: true port: '55221' properties: enable-time-statistics: true persist-pdx: true security: internal_cluster_password: password internal_cluster_username: userX roles: cluster_operator: - CLUSTER:WRITE - CLUSTER:READ - DATA:MANAGE - DATA:WRITE - DATA:READ - CLUSTER:MANAGE:DEPLOY - CLUSTER:MANAGE - CLUSTER:MANAGE:GATEWAY developer: - CLUSTER:READ - DATA:WRITE - DATA:READ gateway: - DATA:WRITE users: cluster_operator_userX: password: password roles: - cluster_operator developer_userX: password: password roles: - developer - name: route_registrar release: routing consumes: nats: deployment: cf-NNNNNNNNNNN from: nats properties: route_registrar: routes: - name: cloudcache port: 8080 ② tls_port: 8080 server_cert_domain_san: cloudcache-XXX-XXX.example.com registration_interval: 20s uris: - cloudcache-XXX-XXX.example.com - name: bpm release: bpm vm_type: micro.cpu stemcell: stemcell persistent_disk_type: '10240' azs: - us-central1-f networks: - name: example-services-subnet- name: server instances: 4 jobs: - name: gemfire-server release: gemfire properties: gemfire: server:


bpm_enabled: true create-gateway-receiver: true development-mode: false properties: enable-time-statistics: true jmx-manager-start: true security: gateway_password: password gateway_username: gateway_sender_userX - name: prime-cluster-for-pcc release: gemfire - name: bpm release: bpm vm_type: medium.cpu stemcell: stemcell persistent_disk_type: '10240' azs: - us-central1-f networks: - name: example-services-subnetupdate: canaries: 1 canary_watch_time: 1000-600000 update_watch_time: 1000-600000 max_in_flight: 32 serial: truefeatures: converge_variables: true ③ variables:- name: trust-store-password type: password- name: key-store-password type: password- name: gemfire-certificate type: certificate options: ca: /services/tls_ca common_name: gemfire-ssl alternative_names: - gemfire-ssl - cloudcache-XXX-XXX.example.com

7. RedeploytheBOSHmanifest.DoaBOSHdeployusingtheeditedBOSHmanifest:

$ bosh -d SERVICE-INSTANCE-NAME deploy SERVICE-INSTANCE-NAME-manifest.yml


8. RestarttheclusterwithasequentialBOSHstart:

$ bosh start -d SERVICE-INSTANCE-NAME --max-in-flight=1


9. Run gfsh andfollowthedirectionsinConnectwithgfshoverHTTPStoconnecttotheTLS-enabledcluster.

10. Use gfsh toimportallregiondatathatwasexportedearlierinthisprocedure.Foreachearlier-exportedregion,do:

gfsh>import data --parallel --region=REGION_NAME --member=SERVER_NAME --dir=/var/vcap/store/gemfire-server

11. RevisetheappsuchthatitworkswithaTLS-enabledPCCserviceinstancebyfollowingtheinstructionswithinDevelopinganAppUnderTLS.Re-build,re-deploy,andstarttheapp.

UpdatingPivotalCloudCachePlansFollowthestepsbelowtoupdateplansinOpsManager.


1. ClickontheCloudCachetile.

2. ClickontheplanyouwanttoupdateundertheInformationsection.

3. Editthefieldswiththechangesyouwanttomaketotheplan.

4. ClickSavebuttononthebottomofthepage.

5. ClickonthePCFOpsManagertonavigatetotheInstallationDashboard.



Planchangesarenotappliedtoexistingservicesinstancesuntilyourunthe upgrade-all-service-instances BOSHerrand.YoumustusetheBOSHCLItorunthiserrand.Untilyourunthiserrand,developerscannotupdateserviceinstances.

Changestofieldsthatcanbeoverriddenbyoptionalparameters,forexample num_servers or new_size_percentage ,changethedefaultvalueoftheseinstanceproperties,butdonotaffectexistingserviceinstances.

Ifyouchangetheallowedlimitsofanoptionalparameter,forexamplethemaximumnumberofserverspercluster,existingserviceinstancesinviolationofthenewlimitsarenotmodified.

Whenexistinginstancesareupgraded,allplanchangesareappliedtothem.UpgradesandupdatestoserviceinstancescancausearollingrestartofGemFireservers.Beawarethattherebalancingofdatatomaintainredundancymayimpacttheperformanceoftheremainderoftheserverswithintheserviceinstance.

UninstallingPivotalCloudCacheTouninstallPCC,followthestepsfrombelowfromtheInstallationDashboard:

1. Clickthetrashcaniconinthebottom-right-handcornerofthetile.



Troubleshooting

ViewStatisticsFiles

Youcanvisualizetheperformanceofyourclusterbydownloadingthestatisticsfilesfromyourservers.ThesefilesarelocatedinthepersistentstoreoneachVM.Tocopythesefilestoyourworkstation,runthefollowingcommand:

`bosh2-eBOSH-ENVIRONMENT-dDEPLOYMENT-NAMEscpserver/0:/var/vcap/store/gemfire-server/statistics.gfs/tmp`

SeethePivotalGemFireInstallingandRunningVSD topicforinformationaboutloadingthestatisticsfilesintoPivotalGemFireVSD.

SmokeTestFailures

Error:“Creatingp-cloudcacheSERVICE-NAMEfailed”

ThesmoketestscouldnotcreateaninstanceofGemFire.Totroubleshootwhythedeploymentfailed,usethecfCLItocreateanewserviceinstanceusingthesameplananddownloadthelogsoftheservicedeploymentfromBOSH.

warning:Datalossmayresultfromtherestartofacluster.SeeRestartingaClusterfortheconditionsunderwhichdatalossoccurs.




http://gemfire.docs.pivotal.io/gemfire/tools_modules/vsd/running_vsd.html

Error:“DeletingSERVICE-NAMEfailed”

Thesmoketestattemptedtocleanupaserviceinstanceitcreatedandfailedtodeletetheserviceusingthe cfdelete-service

command.Totroubleshoot

thisissue,runBOSH logs toviewthelogsonthebrokerortheserviceinstancetoseewhythedeletionmayhavefailed.

Error:CannotconnecttotheclusterSERVICE-NAME

Thesmoketestwasunabletoconnecttothecluster.

Totroubleshoottheissue,reviewthelogsofyourloadbalancer,andreviewthelogsofyourCFRoutertoensuretheroutetoyourPCCclusterisproperlyregistered.

YoualsocancreateaserviceinstanceandtrytoconnecttoitusingthegfshCLI.Thisrequirescreatingaservicekey.

Error:“Couldnotperformcreate/putonCloudCachecluster”

Thesmoketestwasunabletowritedatatothecluster.Theusermaynothavepermissionstocreatearegionorwritedata.

Error:“CouldnotretrievevaluefromCloudCachecluster”

Thesmoketestwasunabletoreadbackthedataitwrote.DatalosscanhappenifaclustermemberimproperlystopsandstartsagainorifthemembermachinecrashesandisresurrectedbyBOSH.RunBOSH logs toviewthelogsonthebrokertoseeiftherewereanyinterruptionstotheclusterbyaserviceupdate.

GeneralConnectivity

Client-to-ServerCommunication

PCCClientscommunicatetoPCCserversonport40404andwithlocatorsonport55221.BothoftheseportsmustbereachablefromthePAS(orElasticRuntime)networktoservicethenetwork.

MembershipPortRange

PCCserversandlocatorscommunicatewitheachotherusingUDPandTCP.Thecurrentportrangeforthiscommunicationis 49152-65535 .

IfyouhaveafirewallbetweenVMs,ensurethisportrangeisopen.

PortRangeUsageAcrossaWAN

GatewayreceiversandgatewaysenderscommunicateacrossWAN-separatedserviceinstances.EachPCCserviceinstanceusesGemFiredefaultsforthegatewayreceiverports.Thedefaultistheinclusiverangeofportnumbers5000to5499.

EnsurethisportrangeisopenwhenWAN-separatedserviceinstanceswillcommunicate.


PivotalCloudCacheDeveloperGuideThisdocumentdescribeshowaPivotalCloudFoundry(PCF)appdevelopercanchooseaserviceplan,createanddeletePivotalCloudCache(PCC)serviceinstances,andbindanapp.

YoumustinstalltheCloudFoundryCommandLineInterface (cfCLI)torunthecommandsinthistopic.

Inthistopic:

ViewingAllPlansAvailableforPivotalCloudCache

CreatingaPivotalCloudCacheServiceInstance

ProvideOptionalParametersEnableSessionStateCachingwiththeJavaBuildpackEnableSessionStateCachingUsingSpringSessionDevPlans

SetUpWAN-SeparatedServiceInstances

SetUpaBidirectionalSystemSetUpaUnidirectionalSystem

SettingUpServersforanInlineCache

ImplementaCacheLoaderforReadMissesImplementanAsynchronousEventQueueandCacheListenerforWriteBehindImplementaCacheWriterforWriteThroughConfigureUsinggfshWriteBehindConfigureUsinggfshWriteThrough

DeletingaServiceInstance

UpdatingaPivotalCloudCacheServiceInstance

RebalancingaClusterRestartingaClusterAboutChangestotheServicePlan

gfshCommandRestrictions

AccessingaServiceInstance

CreateServiceKeys


http://docs.pivotal.io/pivotalcf/cf-cli/install-go-cli.html

ConnectwithgfshoverHTTPS

CreateaTruststoreEstablishtheConnectionwithHTTPSEstablishtheConnectionwithHTTPSinaDevelopmentEnvironment

UsingPivotalCloudCache

CreateRegionswithgfshWorkingwithDiskStoresJavaBuildPackRequirementsBindanApptoaServiceInstanceUsethePulseDashboardAccessServiceMetricsAccessServiceBrokerMetricsExportgfshlogsDeployanAppJARFiletotheServersUsetheGemFire-GreenplumConnector

DevelopinganAppUnderTLS

ConnectingaSpringBootApptoPivotalCloudCachewithSessionStateCaching

UsetheTomcatAppUseaSpringSessionDataGemFireApp

CreatingContinuousQueriesUsingSpringDataGemFire


ViewingAllPlansAvailableforPivotalCloudCacheRun cfmarketplace-sp-

cloudcachetoviewallplansavailableforPCC.Theplannamesdisplayedare

configuredbytheoperatorontileinstallation.

$cfmarketplace-sp-cloudcache

Gettingserviceplaninformationforservicep-cloudcacheasadmin...OK

serviceplandescriptionfreeorpaidextra-smallCachingPlan1freesmallCachingPlan2freemediumCachingPlan3freelargeCachingPlan4freeextra-largeCachingPlan5free


CreatingaPivotalCloudCacheServiceInstanceInthistopic

ProvideOptionalParameters

EnableSessionStateCachingwiththeJavaBuildpack

EnableSessionStateCachingUsingSpringSession

DevPlans

Run cfcreate-servicep-cloudcachePLAN-NAMESERVICE-INSTANCE-NAME

tocreateaserviceinstance.Replace

PLAN-NAME withthenamefromthelistofavailableplans.Replace SERVICE-INSTANCE-NAME withanameofyourchoice.Usethisnametorefertoyourserviceinstancewithothercommands.Serviceinstancenamescanincludealpha-numericcharacters,hyphens,andunderscores.

$cfcreate-servicep-cloudcacheextra-largemy-cloudcache

Serviceinstancesarecreatedasynchronously.Runthe cfservices commandtoviewthecurrentstatusoftheservicecreation,andofotherserviceinstancesinthecurrentorgandspace:

$cfservicesGettingservicesinorgmy-org/spacemy-spaceasuser...OK

nameserviceplanboundappslastoperationmy-cloudcachep-cloudcachesmallcreateinprogress

Whencompleted,thestatuschangesfrom createinprogress to createsucceeded

.

ProvideOptionalParametersYoucancreateacustomizedserviceinstancebypassingoptionalparametersto cfcreate-

serviceusingthe

-c flag.The -c flagacceptsavalidJSONobjectcontainingservice-specificconfigurationparameters,providedeitherin-lineorinafile.

ThePCCservicebrokersupportsthefollowingparameters:


tls :Aboolean,thatwhentrue,enablesTLSforallcommunicationwithinthecluster.

num_servers :Anintegerthatspecifiesthenumberofserverinstancesinthecluster.Theminimumvalueis 4 .Themaximumanddefaultvaluesareconfiguredbytheoperator.

new_size_percentage :Anintegerthatspecifiesthepercentageoftheheaptoallocatetoyounggeneration.Thisvaluemustbebetween 5 and 83 .Bydefault,thenewsizeis2GBor10%ofheap,whicheverissmaller.

ThisexampleenablesTLSwithinthecluster:

$cfcreate-servicep-cloudcachesmallTLS-cluster-c'{"tls":true}'

Thisexamplecreatestheservicewithfiveserviceinstancesinthecluster:

$cfcreate-servicep-cloudcachesmallmy-cloudcache-c'{"num_servers":5}'

EnableSessionStateCachingwiththeJavaBuildpackWhenthe session-replication tagisspecified,theJavabuildpackdownloadsalltherequiredresourcesforsessionstatecaching.ThisfeatureisavailableinJavabuildpackversion3.19andhigher,uptobutnotincludingversion4.Itisthenavailableagaininversion4.3.

Toenablesessionstatecaching,dooneofthefollowingitems:

Option1:Whencreatingyourserviceinstancename,specifythe session-replication tag.Forexample:

$cfcreate-servicep-cloudcachesmall-planmy-service-instance-tsession-replication

Option2:Updateyourserviceinstance,specifyingthe session-replication tag:

$cfupdate-servicenew-service-instance-tsession-replication

Option3:Whencreatingtheservice,nametheserviceinstancenamebyappendingitwiththestring -

session-replication ,forexample my-service-instance-session-replication .

EnableSessionStateCachingUsingSpringSessionTouseSpringSession forsessionstatecachingforappswithPCC,followthestepsbelow:


http://projects.spring.io/spring-session/

1. Makethefollowingchangestotheapp:

ReplaceexistingSpringSession @EnableXXXHttpSession annotationwith@EnableGemFireHttpSession(maxInactiveIntervalInSeconds = N) where N isseconds.

Addthe spring-session-data-geode and spring-data-geode dependenciestothebuild.AddbeanstotheSpringappconfig.

Formoreinformation,seethespring-session-data-gemfire-example repository.

2. Createaregionnamed ClusteredSpringSessions ingfshusingthe cluster_operator_XXX credentials:createregion--name=ClusteredSpringSessions--type=PARTITION_HEAP_LRU

DevPlansTheDevPlanisatypeofserviceplanthatisusefulfordevelopmentandtesting.ThisexamplecreatesaDevPlanserviceinstance:

$cfcreate-servicep-cloudcachedev-planmy-dev-cloudcache

TheplanprovidesasinglelocatorandasingleservercolocatedwithinasingleVM.BecausetheVMisrecycledwhentheserviceinstanceisupdatedorupgraded,alldatawithintheregionislostuponupdateorupgrade.

Whenpost-deployscriptsareenabledforOpsManager,theserviceinstanceiscreatedwithasinglesampleregioncalled example_partition_region .Theregionisoftype PARTITION_REDUNDANT_HEAP_LRU ,asdescribedinPartitionedRegionTypesforCreatingRegionsontheServer.

If example_partition_region hasnotbeencreated,itisprobablybecausepost-deployscriptsarenotenabledforOpsManager,asdescribedinConfigureaDevPlan.


https://github.com/jxblum/spring-session-data-gemfire-example

SetUpWAN-SeparatedServiceInstancesTwoserviceinstancesmayformasingledistributedsystemacrossaWAN.TheinteractionofthetwoserviceinstancesmayfollowoneofthepatternsdescribedwithinthesectiononDesignPatterns.

CallthetwoserviceinstancesAandB.TheGemFireclusterwithineachserviceinstanceusesanidentifiercalleda distributed_system_id .Thisexampleassigns distributed_system_id=

1toclusterAand

distributed_system_id=2

toclusterB.GemFiregatewaysendersprovidethecommunicationpathand

constructthatpropagatesregionoperationsfromoneclustertoanother.OnthereceivingendareGemFiregatewayreceivers.Creatingaserviceinstancealsocreatesgatewayreceivers.

Note:TosetupmorethantwoserviceinstancesacrossaWAN,setuptheinteractionbetweenthefirsttwoserviceinstancesAandBfollowingthedirectionsineitherSetUpaBidirectionalSystemorSetUpaUnidirectionalSystem,asappropriate.Afterthat,setuptheinteractionbetweenserviceinstanceAandanotherserviceinstance(calledC)followingthedirectionsineitherSetUpanAdditionalBidirectionalInteractionorSetUpanAdditionalUnidirectionalInteraction,asappropriate.


SetUpaBidirectionalSystemThissequenceofstepssetsupabidirectionaltransfer,aswillbeneededforanactive-activepattern,asdescribedinBidirectionalReplicationAcrossaWAN.

1. CreatetheclusterAserviceinstanceusingtheclusterACloudFoundrycredentials.Thisexampleexplicitlysetsthedistributed_system_id ofclusterAusinga -c optionwithacommandoftheform:

cfcreate-servicep-cloudcachePLAN-NAMESERVICE-INSTANCE-NAME-c'{"distributed_system_id":ID-VALUE}'

HereisaclusterAexampleofthe create-service command:

$cfcreate-servicep-cloudcachewan-clusterwan1-c'{"distributed_system_id":1}'

Verifythecompletionofservicecreationpriortocontinuingtothenextstep.Outputfromthe cfservices commandwillshowthe lastoperation as createsucceeded whenservicecreationiscompleted.

2. CreateaservicekeyforclusterA.TheservicekeywillcontaingeneratedcredentialsthatthisexamplewilluseinthecreationoftheclusterBserviceinstance:

$cfcreate-service-keywan1k1

Withintheservicekey,each username isgeneratedwithauniquestringappendedsotherewillbeuniqueusernamesforthedifferentroles.Theusernamesinthisexamplehavebeenmodifiedtobeeasytounderstand,andtheyarenotrepresentativeoftheusernamesthatwillbegenerateduponservicekeycreation.Passwordsgeneratedfortheservicekeyareoutputincleartext.Thepasswordsshowninthisexamplehavebeenmodifiedtobeeasytounderstand,andtheyarenotrepresentativeofthepasswordsthatwillbegenerateduponservicekeycreation.Hereissampleoutputfrom cfservice-keywan1k1 :

Gettingkeyk1forserviceinstancewan1asadmin...

{"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. CommunicatetheclusterAlocators’IPandportaddressesand sender_credentials totheclusterBCloudFoundryadministrator.

4. CreatetheclusterBserviceinstanceusingtheclusterBCloudFoundrycredentials.Thisexampleexplicitlysetsthedistributed_system_id .Usea -c optionwiththecommandtospecifythe distributed_system_id ,theclusterAservice

instance’slocators,andtheclusterA sender_credentials :

$cfcreate-servicep-cloudcachewan-clusterwan2-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"}]}]}'



showthe lastoperation as createsucceeded whenservicecreationiscompleted.

5. CreatetheservicekeyofclusterB:


Hereissampleoutputfrom cfservice-keywan2k2 ,whichoutputsdetailsoftheclusterBservicekey:

Gettingkeyk2forserviceinstancedestinationasadmin...

{"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. CommunicatetheclusterBlocators’IPandportaddressesand sender_credentials totheclusterACloudFoundryadministrator.

7. UpdatetheclusterAserviceinstanceusingtheclusterACloudFoundrycredentialstoincludetheclusterBlocatorsandtheclusterB sender_credentials :

$cfupdate-servicewan1-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"}]}]}'Updatingserviceinstancewan1asadmin

8. ToobserveandverifythattheclusterAserviceinstancehasbeencorrectlyupdated,itisnecessarytodeleteandrecreatetheclusterAservicekey.Asdesigned,therecreatedservicekeywillhavethesameuseridentifiersandpasswords;newuniquestringsandpasswordsarenotgenerated.UsetheclusterACloudFoundrycredentialsinthesecommands:

$cfdelete-service-keywan1k1


TheclusterAservicekeywillnowappearas:



{"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. UsegfshtocreatetheclusterAgatewaysenderandtheregion.AnyregionoperationsthatoccuraftertheregioniscreatedonclusterA,butbeforetheregioniscreatedonclusterBwillbelost.

ConnectusinggfshandtheclusterA cluster_operator credentials,whichareneededtobeauthorizedforthegatewaysendercreationoperation:

gfsh>connect--url=https://cloudcache-1.example.com/gemfire/v1--use-http--user=cluster_operator_ABC--password=cl-op-ABC-password

CreatetheclusterAgatewaysender.Therequired remote-distributed-system-id optionidentifiesthe distributed-system-

id ofthedestinationcluster.Itis2forthisexample:

gfsh>creategateway-sender--id=send_to_2--remote-distributed-system-id=2--enable-persistence=true

CreatetheclusterAregion.The gateway-sender-id associatesregionoperationswithaspecificgatewaysender.TheregionmusthaveanassociatedgatewaysenderinordertopropagateregioneventsacrosstheWAN.

gfsh>createregion--name=regionX--gateway-sender-id=send_to_2--type=PARTITION_REDUNDANT

10. UsegfshtocreatetheclusterBgatewaysenderandregion.

ConnectusinggfshandtheclusterB cluster_operator credentials,whichareneededtobeauthorizedforthegatewaysendercreationoperation:

gfsh>connect--url=https://cloudcache-2.example.com/gemfire/v1--use-http--user=cluster_operator_JKL--password=cl-op-JKL-password

CreatetheclusterBgatewaysender:


CreatetheclusterBregion:



SetUpaUnidirectionalSystemThissequenceofstepssetsupaunidirectionaltransfer,suchthatalloperationsinclusterAarereplicatedinclusterB.TwodesignpatternsthatuseunidirectionalreplicationaredescribedinBlue-GreenDisasterRecoveryandCQRSPatternAcrossaWAN.

1. CreatetheclusterAserviceinstanceusingtheclusterACloudFoundrycredentials.Thisexampleexplicitlysetsthedistributed_system_id ofclusterAusinga -c optionwithacommandoftheform:

cfcreate-servicep-cloudcachePLAN-NAMESERVICE-INSTANCE-NAME-c'{"distributed_system_id":ID-VALUE}'

HereisaclusterAexampleofthe create-service command:

$cfcreate-servicep-cloudcachewan-clusterwan1-c'{"distributed_system_id":1}'

Verifythecompletionofservicecreationpriortocontinuingtothenextstep.Outputfromthe cfservices commandwillshowthe lastoperation as createsucceeded whenservicecreationcompletes.

2. CreateaservicekeyforclusterA.TheservicekeywillcontaingeneratedcredentialsthatthisexamplewilluseinthecreationoftheclusterBserviceinstance:


Withintheservicekey,each username isgeneratedwithauniquestringappendedsotherewillbeuniqueusernamesforthedifferentroles.Theusernamesinthisexamplehavebeenmodifiedtobeeasytounderstand,andtheyarenotrepresentativeoftheusernamesthatwillbegenerateduponservicekeycreation.Passwordsgeneratedfortheservicekeyareoutputincleartext.Thepasswordsshowninthisexamplehavebeenmodifiedtobeeasytounderstand,andtheyarenotrepresentativeofthepasswordsthatwillbegenerateduponservicekeycreation.Hereissampleoutputfrom cfservice-keywan1k1 :


{"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. CommunicatetheclusterAlocators’IPandportaddressesand sender_credentials totheclusterBCloudFoundryadministrator.

4. CreatetheclusterBserviceinstanceusingtheclusterBCloudFoundrycredentials.Thisexampleexplicitlysetsthedistributed_system_id .Usea -c optionwiththecommandtospecifythe distributed_system_id ,theclusterAservice





showthe lastoperation as createsucceeded whenservicecreationiscompleted.

5. CreatetheservicekeyofclusterB:


NotethattheclusterBservicekeywillcontainunneeded(fortheunidirectionalsetup)butautomaticallycreatedsender_credentials .Hereissampleoutputfrom cfservice-keywan2k2 ,whichoutputsdetailsoftheclusterBservicekey:


{"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. CommunicatetheclusterBlocators’IPandportaddressestotheclusterACloudFoundryadministrator.

7. UpdatetheclusterAserviceinstanceusingtheclusterACloudFoundrycredentialstoincludetheclusterBlocators:

$cfupdate-servicewan1-c'{"remote_clusters":[{"remote_locators":["10.0.24.21[55221]","10.0.24.22[55221]","10.0.24.23[55221]"]}]}'Updatingserviceinstancewan1asadmin







{"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]"]]}],"sender_credentials":{"active":{"password":"gws-GHI-password","username":"gateway_sender_GHI"}}}}


9. UsegfshtocreatetheclusterAgatewaysenderandtheregion.AnyregionoperationsthatoccuraftertheregioniscreatedonclusterA,butbeforetheregioniscreatedonclusterBwillbelost.






CreatetheclusterAregion.The gateway-sender-id associatesregionoperationswithaspecificgatewaysender.TheregionmusthaveanassociatedgatewaysenderinordertopropagateregioneventsacrosstheWAN.


10. UsegfshtocreatetheclusterBregion.

ConnectusinggfshandtheclusterB cluster_operator credentials,whichareneededtobeauthorizedforthecreateoperation:

gfsh>connect--url=https://cloudcache-2.example.com/gemfire/v1--use-http--user=cluster_operator_JKL--password=cl-op-JKL-password


gfsh>createregion--name=regionX--type=PARTITION_REDUNDANT


SetUpanAdditionalBidirectionalInteractionFollowthissequenceofstepstosetupabidirectionaltransferoverWANbetweentwoPCCserviceinstances,onceaninitialsetupisinplaceforafirstpairofPCCserviceinstances.

CallthefirstpairofPCCserviceinstancesAandB.ThissetofdirectionssetsupaninteractionbetweenserviceinstanceAandserviceinstanceC.ServiceinstanceAisalreadycreatedandhasaservicekey.

TheGemFireclusterwithineachserviceinstanceusesanidentifiercalleda distributed_system_id .Thisexampleassumestheassignmentof distributed_system_id=

1forclusterA, distributed_system_id=

2forclusterB,and distributed_system_id=

3forcluster

C.

1. CommunicatetheclusterAlocators’IPandportaddressesand sender_credentials totheclusterCCloudFoundryadministrator.

2. CreatetheclusterCserviceinstanceusingtheclusterCCloudFoundrycredentials.Thisexampleexplicitlysetsthedistributed_system_id .Usea -c optionwiththecommandtospecifythe distributed_system_id ,theclusterAservice




3. CreatetheservicekeyofclusterC:


Hereissampleoutputfrom cfservice-keywan3k3 ,whichoutputsdetailsoftheclusterCservicekey:



{"distributed_system_id":"3","locators":["10.0.32.21[55221]""10.0.32.22[55221]""10.0.32.23[55221]"],"urls":{"gfsh":"https://cloudcache-3.example.com/gemfire/v1","pulse":"https://cloudcache-3.example.com/pulse"},"users":[{"password":"cl-op-STU-password","roles":["cluster_operator"],


],"username":"cluster_operator_STU"},{"password":"dev-VWX-password","roles":["developer"],"username":"developer_VWX"}],"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-YZA-password","username":"gateway_sender_YZA"}}}}

4. CommunicatetheclusterClocators’IPandportaddressesand sender_credentials totheclusterACloudFoundryadministrator.

5. UpdatetheclusterAserviceinstanceusingtheclusterACloudFoundrycredentialstoincludetheclusterClocatorsandtheclusterC sender_credentials .TheclusterAserviceinstancemustspecifyas remote_locators and trusted_sender_credentials

thedetailsforallclustersitinteractswith.Forthisexample,thatisbothclustersBandC:

$cfupdate-servicewan1-c'{"remote_clusters":[{"remote_locators":["10.0.24.21[55221]","10.0.24.22[55221]","10.0.24.23[55221]","10.0.32.21[55221]","10.0.32.22[55221]","10.0.32.23[55221]"],"trusted_sender_credentials":[{"username":"gateway_sender_PQR","password":"gws-PQR-password"},{"username":"gateway_sender_YZA","password":"gws-YZA-password"}]}]


}]}'Updatingserviceinstancewan1asadmin






{"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]","10.0.32.21[55221]","10.0.32.22[55221]","10.0.32.23[55221]"],"trusted_sender_credentials":["gateway_sender_PQR","gateway_sender_YZA"]


]}],"sender_credentials":{"active":{"password":"gws-GHI-password","username":"gateway_sender_GHI"}}}}

7. UsegfshtocreatetheclusterAgatewaysenderandaltertheexistingregion.






AltertheexistingclusterAregionsothatitspecifiesallgatewaysendersassociatedwiththeregion.Therearetwogatewaysendersinthisexample,onethatgoestoclusterBandasecondthatgoestoclusterC.

gfsh>alterregion--name=regionX--gateway-sender-id=send_to_2,send_to_3

8. UsegfshtocreatetheclusterCgatewaysenderandregion.

ConnectusinggfshandtheclusterC cluster_operator credentials,whichareneededtobeauthorizedforthegatewaysendercreationoperation:

gfsh>connect--url=https://cloudcache-3.example.com/gemfire/v1--use-http--user=cluster_operator_STU--password=cl-op-STU-password

CreatetheclusterCgatewaysender:


CreatetheclusterCregion:



SetUpanAdditionalUnidirectionalInteractionFollowthissequenceofstepstosetupanadditionalunidirectionaltransferoverWANbetweentwoPCCserviceinstances,onceaninitialsetupisinplaceforafirstpairofPCCserviceinstances.

CallthefirstpairofPCCserviceinstancesAandB.ThissetofdirectionssetsupaunidirectionalinteractionfromserviceinstanceAtoserviceinstanceC.ServiceinstanceAisalreadycreatedandhasaservicekey.

TheGemFireclusterwithineachserviceinstanceusesanidentifiercalleda distributed_system_id .Thisexampleassumestheassignmentof distributed_system_id=

1forclusterA, distributed_system_id=

2forclusterB,and distributed_system_id=

3forcluster

C.

1. CommunicatetheclusterAlocators’IPandportaddressesand sender_credentials totheclusterCCloudFoundryadministrator.

2. CreatetheclusterCserviceinstanceusingtheclusterCCloudFoundrycredentials.Thisexampleexplicitlysetsthedistributed_system_id .Usea -c optionwiththecommandtospecifythe distributed_system_id ,theclusterAservice




3. CreatetheservicekeyofclusterC:


NotethattheclusterCservicekeywillcontainunneeded(fortheunidirectionalsetup)butautomaticallycreatedsender_credentials .Hereissampleoutputfrom cfservice-keywan3k3 ,whichoutputsdetailsoftheclusterCservicekey:



{"distributed_system_id":"3","locators":["10.0.32.21[55221]""10.0.32.22[55221]""10.0.32.23[55221]"],"urls":{"gfsh":"https://cloudcache-3.example.com/gemfire/v1","pulse":"https://cloudcache-3.example.com/pulse"},"users":[{"password":"cl-op-STU-password","roles":["cluster_operator"],


],"username":"cluster_operator_STU"},{"password":"dev-VWX-password","roles":["developer"],"username":"developer_VWX"}],"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-YZA-password","username":"gateway_sender_YZA"}}}}

4. CommunicatetheclusterClocators’IPandportaddressestotheclusterACloudFoundryadministrator.

5. UpdatetheclusterAserviceinstanceusingtheclusterACloudFoundrycredentialstoincludetheclusterClocators.TheclusterAserviceinstancemustspecifyas remote_locators thedetailsforallclustersitinteractswith.Forthisexample,thatisbothclustersBandC:

$cfupdate-servicewan1-c'{"remote_clusters":[{"remote_locators":["10.0.24.21[55221]","10.0.24.22[55221]","10.0.24.23[55221]","10.0.32.21[55221]","10.0.32.22[55221]","10.0.32.23[55221]"]}]}'Updatingserviceinstancewan1asadmin







{"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]","10.0.32.21[55221]","10.0.32.22[55221]","10.0.32.23[55221]"


"10.0.32.23[55221]"]]}],"sender_credentials":{"active":{"password":"gws-GHI-password","username":"gateway_sender_GHI"}}}}

7. UsegfshtocreatetheclusterAgatewaysenderandaltertheexistingregion.






AltertheexistingclusterAregionsothatitspecifiesallgatewaysendersassociatedwiththeregion.Therearetwogatewaysendersinthisexample,onethatgoestoclusterBandasecondthatgoestoclusterC.

gfsh>alterregion--name=regionX--gateway-sender-id=send_to_2,send_to_3

8. UsegfshtocreatetheclusterCregion.

ConnectusinggfshandtheclusterC cluster_operator credentials,whichareneededtobeauthorizedforthecreateoperation:

gfsh>connect--url=https://cloudcache-3.example.com/gemfire/v1--use-http--user=cluster_operator_STU--password=cl-op-STU-password


gfsh>createregion--name=regionX--type=PARTITION_REDUNDANT


SettingUpServersforanInlineCacheInthistopic

ImplementaCacheLoaderforReadMisses

ImplementanAsynchronousEventQueueandCacheListenerforWriteBehind

ImplementaCacheWriterforWriteThrough

ConfigureUsinggfshforWriteBehind

ConfigureUsinggfshforWriteThrough

SeeTheInlineCacheforanintroductorydescriptionofaninlinecache.TheimplementationofaninlinecacherequirescustomcodedeployedontheGemFireserverstointeractwiththebackenddatastoreforreadmissesandforwrites.

Thecustomcodealwaysimplementsacacheloaderforreadmisses.Thecustomcodeandconfigurationsetupdiffersforwrites.Awrite-behindimplementationusesanasynchronouseventqueue(AEQ)andanAEQlistener.Awrite-throughimplementationusesacachewriter.

ImplementaCacheLoaderforReadMissesAnapp’sgetoperationisacacheread.Ifthedesiredentryisintheregion,itisacachehit,andthevalueisquicklyreturnedtotheapp.Ifthedesiredentryisnotintheregion,itisacachemiss.Foraninlinecache,thatvalueisacquiredfromthebackenddatastore.Youimplementthe CacheLoader interfacetohandlecachemisses.Eachcachemissinvokesthe CacheLoader.load method.The CacheLoader.load methodmustacquireandreturnthevalueforthespecifiedkey.SeethePivotalGemFireAPIDocumentation fortheinterface’sdetails.



Thevaluereturnedfromthe CacheLoader.load methodwillbeputintotheregionandthenreturnedtothewaitingapp,completingtheapp’sgetoperation.Sincetheappblockswhilewaitingfortheresultofthegetoperation,designthe CacheLoader.load methodtoacquirethevalueasquicklyaspossible.

The CacheLoader implementationmustbethread-safe.Youwilldeploytheimplementationtotheserversduringconfiguration.

The CacheLoader.load methodqueriesthebackenddatastoreforthedesiredentry.Thatcommunicationbetweentheserverprocessandthebackenddatastorerequiresaconnection,andestablishingaconnectionislikelytouseasetofcredentials.YouprovideacustomimplementationoftheCacheLoader.initialize methodtoestablishtheconnection.

Youspecifythecredentialsduringconfigurationwiththegfsh createregion commandbyaddingtheJSONdescriptiontothe --cache-loader option.ThecredentialswillbepassedasparameterstotheinvokedCacheLoader.initialize methodaspartofthe CacheLoader instanceconstruction.

ImplementanAsynchronousEventQueueandCacheListenerforWriteBehindAnapp’sputoperationisacachewrite.Forawrite-behindimplementation,thevalueisplacedintotheregion,anditwillalsobeasynchronouslywrittentothebackenddatastore,allowingtheapp’swriteoperationtocompletewithoutwaitingforthebackend-data-storewritetocomplete.


Anasynchronouseventqueue(AEQ)toqueuethewriteeventstogetherwithanimplementationoftheAsyncEventListener interfaceprovidesthedesiredbehavior.SeethePivotalGemFireAPIDocumentationfortheinterface’sdetails.

WithaconfiguredAEQ,allputoperationsfirstcreateorupdatetheentryinthehostedregionontheserverandthenaddtheeventtotheAEQ.

Youprovideacustomimplementationofthe AsyncEventListener interface.YourAsyncEventListener.processEvents method’staskistoiteratethroughtheeventsintheAEQ,writingeach

newlycreatedorupdatedentryintheAEQtothebackenddatastore.The AsyncEventListener.processEvents

methodisinvokedwheneithertheAEQholdsaconfiguredquantityofevents,oraconfiguredquantityoftimehaselapsedsincetheearliestentryenteredtheAEQ.

Thecommunicationbetweentheserverprocessandthebackenddatastoretodothewritesrequiresaconnection,andestablishingaconnectionislikelytouseasetofcredentials.Youprovideacustomimplementationofthe AsyncEventListener.initialize methodtoestablishtheconnection.

Youspecifythecredentialsduringconfigurationinthegfsh createasync-event-queue commandwiththe--listener-param optionasdescribedinConfigureUsinggfshforWriteBehind.Thecredentialswillbe

passedasparameterstotheinvoked AsyncEventListener.initialize methodaspartof AsyncEventListener

instanceconstruction.



YourconfigurationwillspecifytheAEQaspersistent,suchthatitdoesnotlosequeuedbackend-data-storewritesacrossunexpectedserverrestarts.

ImplementaCacheWriterforWriteThroughAnapp’sputoperationisacachewrite.Forawrite-throughimplementation,thevaluewillbewrittentothebackenddatastorepriortobeingplacedintotheregion.Afterbothwrites,theapp’sputoperationcompletes.

Animplementationofthe CacheWriter interfaceimplementationprovidesthecorrectbehaviorforwritethrough.SeethePivotalGemFireAPIDocumentation fortheinterface’sdetails.Youprovideacustomimplementationofthe CacheWriter.beforeCreate methodtohandlebackend-data-storewritesforputoperationsthataddanewentrytotheregion.YouprovideacustomimplementationoftheCacheWriter.beforeUpdate methodtohandlebackend-data-storewritesforputoperationsthatmodifyan

existingentryintheregion.Youprovideacustomimplementationof CacheWriter.beforeDestroy ,asappropriate,tohandleanupdateofthebackenddatastoreforaregionoperationthatremovesanentry.

The CacheWriter implementationmustbethread-safe.Youwilldeploytheimplementationtotheserversduringconfiguration.



Communicationbetweentheserverprocessandthebackenddatastoretodothewritesrequiresaconnection,andestablishingaconnectionislikelytouseasetofcredentials.Youprovideacustomimplementationofthe CacheWriter.initialize methodtoestablishtheconnection.

Specifythecredentialsinthegfsh createregion commandduringconfigurationasdescribedinConfigureUsinggfshforWriteThrough.AddtheJSONdescriptiontothe --cache-writer option.Thecredentialswillbepassedasparameterstotheinvoked CacheWriter.initialize methodaspartofthe CacheWriter instanceconstruction.

ConfigureUsinggfshforWriteBehindFollowthisproceduretodeployyourcustomimplementationsoftheinterfacestotheservers,createtheAEQ,andconfiguretheregiontousetheAEQandthedeployedinterfaceimplementations.

1. FollowthedirectionsinConnectwithgfshoverHTTPStoconnecttotheclusterwiththecluster-operatorcredentialsfromtheservicekey.


2. DeploythecacheloaderandtheAEQlistenercodetotheserverswithinthePCCserviceinstance:

gfsh>deploy--jars=/path/to/MyLoader.jar,/path/to/MyListener.jar

3. CreatetheAEQ,assigninganamefortheAEQ(called WB-AEQ inthisexample),specifyingtheAEQlistener,andspecifyingtheAEQlistener’sparameters:

gfsh>createasync-event-queue--id=WB-AEQ\--parallel=true--persistent\--listener=com.myCompany.MyListener\--listener-param=url#jdbc:db2:SAMPLE,username#admin,password#gobbledeegook

ThepersistenceoftheAEQusesthedefaultdiskstore,sincenodiskstoreisspecifiedinthiscommand.

4. Createtheregion,specifyingthecacheloader,theAEQlistener,andtheassignedAEQname.

gfsh>createregion--name=myRegion--type=PARTITION_REDUNDANT\--cache-loader=com.myCompany.MyLoader{'url':'jdbc:db2:SAMPLE','username':'admin',password:'gobbledeegook'}--cache-listener=com.myCompany.MyListener--async-event-queue-id=WB-AEQ

ConfigureUsinggfshforWriteThroughFollowthisproceduretodeployyourcustomimplementationsoftheinterfacestotheservers,andconfiguretheregiontousethedeployedinterfaceimplementations.

1. FollowthedirectionsinConnectwithgfshoverHTTPStoconnecttotheclusterwiththecluster-operatorcredentialsfromtheservicekey.

2. DeploythecacheloaderandthecachewritercodetotheserverswithinthePCCserviceinstance:

gfsh>deploy--jars=/path/to/MyLoader.jar,/path/to/MyWriter.jar

3. Createtheregion,specifyingthecacheloaderandthecachewriter:

gfsh>createregion--name=myRegion--type=PARTITION_REDUNDANT\--cache-loader=com.myCompany.MyLoader{'url':'jdbc:db2:SAMPLE','username':'admin',password:'gobbledeegook'}--cache-writer=com.myCompany.MyWriter{'url':'jdbc:db2:SAMPLE','username':'admin',password:'gobbledeegook'}



DeletingaServiceInstanceYoucandeleteserviceinstancesusingthecfCLI.Beforedoingso,youmustremoveanyexistingservicekeysandappbindings.

1. Run cf delete-service-key SERVICE-INSTANCE-NAME KEY-NAME todeletetheservicekey.

2. Run cf unbind-service APP-NAME SERVICE-INSTANCE-NAME tounbindyourappfromtheserviceinstance.

3. Run cf delete-service SERVICE-INSTANCE-NAME todeletetheserviceinstance.

$cfdelete-service-keymy-cloudcachemy-service-key$cfunbind-servicemy-appmy-cloudcache$cfdelete-servicemy-cloudcache

Deletionsareasynchronous.Run cfservices toviewthecurrentstatusoftheserviceinstancedeletion.


UpdatingaPivotalCloudCacheServiceInstanceInthistopic

RebalancingaCluster

RestartingaCluster

AboutChangestotheServicePlan

Youcanapplyalloptionalparameterstoanexistingserviceinstanceusingthe cfupdate-service command.Youcan,forexample,scaleupaclusterbyincreasingthenumberofservers.

Previouslyspecifiedoptionalparametersarepersistedthroughsubsequentupdates.Toreturntheserviceinstancetodefaultvalues,youmustexplicitlyspecifythedefaultsasoptionalparameters.

Forexample,ifyoucreateaserviceinstancewithfiveserversusingaplanthathasadefaultvalueoffourservers:

$cfcreate-servicep-cloudcachesmallmy-cloudcache-c'{"num_servers":5}'

Andyousetthe new_size_percentage to50%:

$cfupdate-servicemy-cloudcache-c'{"new_size_percentage":50}'

Thentheresultingserviceinstancehas 5 serversand new_size_percentage of50%ofheap.

RebalancingaClusterWhenupdatingaclustertoincreasethenumberofservers,theavailableheapsizeisincreased.Whenthishappens,PCCautomaticallyrebalancesdatainthecachetodistributedataacrossthecluster.

Thisautomaticrebalancingdoesnotoccurwhenaserverleavestheclusterandlaterrejoins,forexamplewhenaVMisre-created,ornetworkconnectivitylostandrestored.Inthiscase,youmustmanuallyrebalancetheclusterusingthegfsh rebalance command whileauthenticatedasaclusteroperator.

RestartingaClusterRestartingaclusterstopsandrestartseachclustermemberinturn,issuingarebalanceaseachrestartedserverjoinsthecluster.

Thereisapotentialfordatalosswhenrestartingacluster;theregiontypeandnumberofserversintheclusterdeterminewhetherornotdataislost.

Alldataislostwhenrestartingaclusterwiththeseregiontypesandnumberofservers:

Partitionedregionswithoutredundancyorpersistence.Aseachserverisstopped,theregionentrieshostedinbucketsonthatstoppedserverarepermanentlylost.Replicatedregionswithoutpersistenceonaclusterthathasasingleserver.ADevPlanclusterlosesalldata,asthereisasingleserverandnoregionpersistence.

Nodataislostwhenrestartingtheclusterwiththeseregiontypesandnumberofservers:

Replicatedregionsforclusterswithmorethanoneserver.

Note:Youmustfirstconnectwithgfshbeforeyoucanusethe rebalance command.

warning:Restartofaclustermaycausedataloss.


http://gemfire.docs.pivotal.io/geode/tools_modules/gfsh/command-pages/rebalance.html

Replicatedregionsforclusterswithmorethanoneserver.Persistentregionswillnotlosedata,asalldataisonthediskandavailableuponrestartofaserver.Partitionedregionswithredundancy.Whentheserverwiththeprimarycopyofanentryisstopped,theredundantcopystillexistsonarunningserver.

Torestartacluster,usetheclusteroperatorcredentialstorunthecommand:

cfupdate-serviceSERVICE-INSTANCE-NAME-c'{"restart":true}'

Forexample:

$cfupdate-servicemy-cluster-c'{"restart":true}'

AboutChangestotheServicePlanYourPCFoperatorcanchangedetailsoftheserviceplanavailableontheMarketplace.Ifyouroperatorchangesthedefaultvalueofoneoftheoptionalparameters,thisdoesnotaffectexistingserviceinstances.

However,ifyouroperatorchangestheallowedvaluesofoneoftheoptionalparameters,existinginstancesthatexceedthenewlimitsarenotaffected,butanysubsequentserviceupdatesthatchangetheoptionalparametermustadheretothenewlimits.

Forexample,ifthePCFoperatorchangestheplanbydecreasingthemaximumvaluefor num_servers ,anyfutureserviceupdatesmustadheretothenew num_servers valuelimit.Youmightseethefollowingerrormessagewhenattemptingtoupdateaserviceinstance:

$cfupdate-servicemy-cloudcache-c'{"num_servers":5}'Updatingserviceinstancemy-cloudcacheasadmin...FAILEDServererror,statuscode:502,errorcode:10001,message:Servicebrokererror:Servicecannotbeupdatedatthistime,pleasetryagainlaterorcontactyouroperatorformoreinformation

Thiserrormessageindicatesthattheoperatorhasmadeanupdatetotheplanusedbythisserviceinstance.Youmustwaitfortheoperatortoapplyplanchangestoallserviceinstancesbeforeyoucanmakefurtherserviceinstanceupdates.


gfshCommandRestrictionsDevelopersmayinvokeall gfsh commands.Givencredentialswithsufficientpermissions,those gfsh

commandwillbeexecuted.However,notall gfsh commandsaresupported.Aninvocationofanunsupportedcommandmayleadtoincorrectresults.Thoseresultsrangefromineffectiveresultstoinconsistentregionentries.Donotusetheselisted gfsh commands;eachhasanexplanationwhyitmustnotbeused.

These gfshstart

commandswillbringupmemberscontrarytotheconfiguredplan.Theirconfiguration

willbewrong,andtheirexistenceislikelytocontributetodataloss.Sincetheyarenotpartoftheconfiguredplan,anyupgradewillnotincludethem,andiftheyweretostoporcrash,theBOSHDirectorwillnotrestartthem.

gfshstartlocator

gfshstartserver

Theseclusterstopcommandswilltemporarilystopthememberorcluster.However,theBOSHDirectorwillnoticethatmembersarenotrunningandrestartthem.So,thesecommandswillbeineffective:

gfshstoplocator

gfshstopserver

gfshshutdown

TheseLucene-relatedcommandsarenotsupported:

gfshcreateluceneindex

gfshdescribeluceneindex

gfshdestroyluceneindex

gfshlistluceneindexes

gfshsearchlucene

TheseJNDIbinding-relatedcommandsarenotsupported:

gfshcreatejndi-binding

gfshdescribejndi-binding

gfshdestroyjndi-binding

gfshlistjndi-binding


Thisconfigurecommandwillinstillconfigurationcontrarytothealready-configuredplan.Sinceitisnotpartoftheconfiguredplan,anyupgradewillnotincludeit.Therefore,donotuse:

gfshconfigurepdx

Thecreateofagatewayreceiverwillneverbeappropriateforanysituation.ThePCCclusterwillalreadyhavegatewayreceivers,andthereisnosituationinwhichtheclustercanbenefitfromcreatingmore.Therefore,donotuse:

gfshcreategatewayreceiver

DoNotExportfromaGemFireClustertoaPCCClusterWhiletheexpectationisthatconfigurationanddatacanbeexportedfromaGemFireclusterandthenimportedintoaPCCcluster,thisdoesnotwork.Usingexportandimportcommandswillnothavethedesiredeffectofmigrationfromoneclustertoanother.TheimportofclusterconfigurationrequiresastatethatcannotbeprovidedbyaPCCcluster.ThePCCclusterwillalreadyhaveitsconfiguration,anduponrestartorupgrade,thatsameconfigurationwillbeused.Giventhattheconfigurationcannotbeimported,dataimportisproblematic.Therefore,donotuse:

gfshimportcluster-configuration

gfshimportdata

Note:Therestrictionhereontheuseofthe gfshimportdata doesnotapplytotheprocedureformigratingfromanexistingPCCclusterthatdoesnotuseTLSforencryptiontoaPCCclusterthatdoesuseTLSforencryption.SeeMigratingtoaTLS-EnabledClusterforthatprocedure.


AccessingaServiceInstanceInthistopic

CreateServiceKeys

ConnectwithgfshoverHTTPSCreateaTruststore

EstablishtheConnectionwithHTTPS

EstablishtheConnectionwithHTTPSinaDevelopmentEnvironment

DetermineYourTLSTermination

Afteryouhavecreatedaserviceinstance,youcanstartaccessingit.Usually,yousetupcacheregionsbeforeusingyourserviceinstancefromadeployedCFapp.Youcandothiswiththegfshcommandlinetool.Toconnect,youmustsetupaservicekey.

CreateServiceKeysServicekeysprovideawaytoaccessyourserviceinstanceoutsidethescopeofadeployedCFapp.Runcfcreate-service-keySERVICE-INSTANCE-NAMEKEY-NAME

tocreateaservicekey.Replace

SERVICE-INSTANCE-NAME withthenameyouchoseforyourserviceinstance.Replace KEY-NAME withanameofyourchoice.Youcanusethisnametorefertoyourservicekeywithothercommands.

$cfcreate-service-keymy-cloudcachemy-service-key

Run cfservice-keySERVICE-INSTANCE-NAMEKEY-NAME

toviewthenewlycreatedservicekey.

$cfservice-keymy-cloudcachemy-service-key

The cfservice-key returnsoutputinthefollowingformat:


{"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"}}}}

TheservicekeyspecifiestheuserrolesandURLsthatarepredefinedforinteractingwithandwithinthecluster:

Theclusteroperatoradministersthepool,performingoperationssuchascreatinganddestroyingregions,andcreatinggatewaysenders.Theidentifierassignedforthisroleisoftheformcluster_operator_XXX ,where XXX isauniquestringgenerateduponserviceinstancecreation

andincorporatedinthisuserrole’sname.

Thedeveloperdoeslimitedclusteradministrationsuchasregioncreation,andthedeveloperroleisexpectedtobeusedbyapplicationsthatareinteractingwithregionentries.ThedeveloperdoesCRUDoperationsonregions.Theidentifierassignedforthisroleisoftheform developer_XXX ,whereXXX isauniquestringgenerateduponserviceinstancecreationandincorporatedinthisuserrole’s


name.

Thegatewaysenderwritesdatathatissenttoanothercluster.Theidentifierassignedforthisroleisoftheform gateway_sender_XXX ,where XXX isauniquestringgenerateduponserviceinstancecreationandincorporatedinthisuserrole’sname.

AURLusedtoconnectthegfshclienttotheserviceinstance

AURLusedtoviewthePulsedashboardinawebbrowser,whichallowsmonitoringoftheserviceinstancestatus.Usethedevelopercredentialstoauthenticate.

ConnectwithgfshoverHTTPSWhenconnectingoverHTTPS,youmustusethesamecertificateyouusetosecuretrafficintoPivotalApplicationService(PAS);thatis,thecertificateyouusewhereyourTLSterminationoccurs.SeeDetermineYourTLSTermination.

Beforeyoucanconnect,youmustcreateatruststore.

CreateaTruststore

Tocreateatruststore,usethesamecertificateyouusedtoconfigureTLStermination.Wesuggestusingthe keytool commandlineutilitytocreateatruststorefile.

1. LocatethecertificateyouusetoconfigureTLStermination.SeeDetermineYourTLSTermination.

2. Usingyourcertificate,runthe keytool command:keytool-import-fileCERTIFICATE.CER-keystoreTRUSTSTORE-FILE-PATH-storetypeJKS

where

CERTIFICATE.CER isyourcertificatefileTRUSTSTORE-FILE-PATH isthepathtothelocationwhereyouwanttocreatethetruststore

file,includingthenameyouwanttogivethefile

3. Whenyourunthiscommand,youarepromptedtoenterakeystorepassword.Createapasswordandrememberit!

4. Whenpromptedforthecertificatedetails,enteryestotrustthecertificate.

Thefollowingexampleshowshowtorun keytool andwhattheoutputlookslike:


$keytool-import-file/tmp/loadbalancer.cer-keystore/tmp/truststore/prod.myTrustStore-storetypeJKSEnterkeystorepassword:Re-enternewpassword:Owner:CN=*.url.example.com,OU=CloudFoundry,O=Pivotal,L=NewYork,ST=NewYork,C=USIssuer:CN=*.url.example.com,OU=CloudFoundry,O=Pivotal,L=NewYork,ST=NewYork,C=USSerialnumber:bd84912917b5b665Validfrom:SatJul2909:18:43EDT2017until:MonApr0709:18:43EDT2031Certificatefingerprints:MD5:A9:17:B1:C9:6C:0A:F7:A3:56:51:6D:67:F8:3E:94:35SHA1:BA:DA:23:09:17:C0:DF:37:D9:6F:47:05:05:00:44:6B:24:A1:3D:77SHA256: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:57Signaturealgorithmname:SHA256withRSAVersion:3

Extensions:

#1:ObjectId:2.5.29.10Criticality=trueBasicConstraints:[CA:truePathLen:0]

#2:ObjectId:2.5.29.11Criticality=falseSubjectAlternativeName[DNSName:*.sys.url.example.comDNSName:*.apps.url.example.comDNSName:*.uaa.sys.url.example.comDNSName:*.login.sys.url.example.comDNSName:*.url.example.comDNSName:*.ws.url.example.com]

Trustthiscertificate?[no]:yesCertificatewasaddedtokeystore

EstablishtheConnectionwithHTTPS

Afteryouhavecreatedthetruststore,youcanusethePivotalGemFirecommandlineinterface, gfsh ,toconnecttotheclusteroverHTTPS.

1. Acquirethecorrect gfsh bydownloadingthecorrectPivotalGemFireZIParchivefromPivotalNetwork .ThecorrectversionofPivotalGemFiretodownloadisanypatchversionofthePivotalGemFireversionlistedinthePCCreleasenotes.AlinktothePCCreleasenotesisonPivotalNetworkintheReleaseDetailsforyourPCCversion.NotethataJDKorJREwillalsoberequired,asspecifiedinthereleasenotes.

Note:Anattempttousethewrong gfsh versionwillresultinanerrormessageindicating


https://network.pivotal.io/products/pivotal-gemfire

2. UnzipthePivotalGemFireZIParchive. gfsh iswithinthe bin directoryintheexpandedPivotalGemFire.Use gfsh withUnixor gfsh.bat withWindows.

3. Run gfsh ,andthenissuea connect commandthatspecifiesanHTTPSgfshURLoftheform:

connect--use-http=true--url=HTTPS-gfsh-URL--trust-store=TRUSTSTORE-FILE-PATH--trust-store-password=PASSWORD--user=CLUSTER-OPERATOR-XXX--password=CLUSTER-OPERATOR-PASSWORD

TheHTTPS-gfsh-URL,theclusteroperatorusername,anditspasswordareintheservicekey.SeeCreateServiceKeysforinstructionsonhowtoviewtheservicekey.TRUSTSTORE-FILE-PATHisthepathtothetruststorefileyoucreatedinCreateaTruststore,andPASSWORDistheassociatedtruststorepasswordyoucreated.Ifyouomitthe --trust-store-password optionfromthecommandline,youwillbepromptedtoenterthepassword.

EstablishtheConnectionwithHTTPSinaDevelopmentEnvironment

Whenworkinginanon-production,developmentenvironment,adevelopermaychoosetoworkinalesssecuremannerbyeliminatingthetruststoreandSSLmutualauthentication.

Thestepstoestablishthe gfsh connectionbecome:

1. Acquire gfsh bydownloadingthecorrectPivotalGemFireZIParchivefromPivotalNetwork .ThecorrectversionofPivotalGemFiretodownloadisanypatchversionofthePivotalGemFireversionlistedinthePCCreleasenotes.AlinktothePCCreleasenotesisonPivotalNetworkintheReleaseDetailsforyourPCCversion.NotethataJDKorJREwillalsoberequired,asspecifiedinthereleasenotes.

2. UnzipthePivotalGemFireZIParchive. gfsh iswithinthe bin directoryintheexpandedPivotalGemFire.Use gfsh withUnixor gfsh.bat withWindows.

3. Run gfsh ,andthenissuea connect commandthatspecifiesanHTTPSURLoftheform:

connect--use-http=true--use-ssl--skip-ssl-validation=true--url=<HTTPS-gfsh-URL>--user=<cluster_operator_XXX>--password=<cluster_operator-password>

Theclusteroperatorusernameandpasswordareintheservicekey.SeeCreateServiceKeysforinstructionsonhowtoviewtheservicekey.

thatthereisaversionmismatch.


https://network.pivotal.io/products/pivotal-gemfire

Ateachofthenine gfsh promptsthataskforkeystore,truststore,andSSLdetails,hit Enter tostepthroughthepromptsandconnect.

DetermineYourTLSTerminationToconnectyourPCCserviceinstanceusing gfsh ,youwillneedthecertificatefromwhereyourTLSterminationoccurs.TheTLSterminationmaybeattheGorouter,attheHAProxy,oratyourloadbalancer.RequesttheneededcertificatefromyourPivotalCloudFoundry(PCF)operator.

ThePCFoperatordeterminesthelocationofyourTLStermination:

1. BringuptheOpsManagerdashboard.

2. ClickonthePASproducttile.

3. ClickontheNetworkingsectionundertheSettingstab.

ThechoiceofTLSterminationislabeledwithConfiguresupportfortheX-Forwarded-Client-Cert.

IfthechoicenamestheRouterorHAProxy,thecertificateisinthesamesection,labeledwithCertificateandPrivateKeyforHAProxyandRouter.

Ifthechoicenamestheinfrastructureloadbalancer,thenthePCFoperatorcanretrievethecertificatefromtheloadbalancer.


UsingPivotalCloudCacheInthistopic

CreateRegionswithgfsh

WorkingwithDiskStoresCreateaDiskStore

DestroyaDiskStore

JavaBuildPackRequirements

BindanApptoaServiceInstance

UsethePulseDashboard

AccessServiceInstanceMetrics

AccessServiceBrokerMetrics

ExportgfshLogs

DeployanAppJARFiletotheServers

UsetheGemFire-GreenplumConnector

CreateRegionswithgfshAfterconnectingwithgfshasa cluster_operator_XXX ,youcandefineanewcacheregion.

Thefollowingcommandcreatesapartitionedregionwithasingleredundantcopy:

gfsh>createregion--name=my-cache-region--type=PARTITION_REDUNDANT_HEAP_LRUMember|Status----------------|-------------------------------------------------------cacheserver-z2-1|Region"/my-cache-region"createdon"cacheserver-z2-1"cacheserver-z3-2|Region"/my-cache-region"createdon"cacheserver-z3-2"cacheserver-z1-0|Region"/my-cache-region"createdon"cacheserver-z1-0"cacheserver-z1-3|Region"/my-cache-region"createdon"cacheserver-z1-3"

SeeRegionDesignforguidelinesonchoosingaregiontype.

Youcantestthenewlycreatedregionbywritingandreadingvalueswithgfsh:


gfsh>put--region=/my-cache-region--key=test--value=thevalueResult:trueKeyClass:java.lang.StringKey:testValueClass:java.lang.StringOldValue:NULL

gfsh>get--region=/my-cache-region--key=testResult:trueKeyClass:java.lang.StringKey:testValueClass:java.lang.StringValue:thevalue

Inpractice,youshouldperformtheseget/putoperationsfromadeployedPCFapp.Todothis,youmustbindtheserviceinstancetotheseapps.

WorkingwithDiskStoresPersistentregionsandregionsthatoverflowuponevictionusediskstores.Use gfsh tocreateordestroyadiskstore.

CreateaDiskStore

Tocreateadiskstoreforusewithapersistentoroverflowtypeofregion:

1. UsethedirectionsinConnectwithgfshoverHTTPStoconnecttothePCCserviceinstanceusingtheclusteroperatorcredentials.

2. Createthediskstorewithagfshcommandoftheform:

createdisk-store--name=<name-of-disk-store>--dir=<relative/path/to/diskstore/directory>

Specifyarelativepathforthediskstorelocation.Thatrelativepathwillbecreatedwithin/var/vcap/store/gemfire-server/ .Formoredetailsonfurtheroptions,seethePivotalGemFirecreatedisk-

storeCommandReferencePage .

DestroyaDiskStore

Todestroyadiskstore:


http://gemfire.docs.pivotal.io/geode/tools_modules/gfsh/command-pages/create.html#topic_bkn_zty_ck

1. UsethedirectionsinConnectwithgfshoverHTTPStoconnecttothePCCserviceinstanceusingtheclusteroperatorcredentials.

2. Destroythediskstorewithagfshcommandoftheform:

destroydisk-store--name=<name-of-disk-store>

Formoredetailsonfurtheroptions,seethePivotalGemFiredestroydisk-storeCommandReferencePage .

JavaBuildPackRequirementsToensurethatyourappcanuseallthefeaturesfromPCC,usethelatestbuildpack.ThebuildpackisavailableonGitHubatcloudfoundry/java-buildpack .

BindanApptoaServiceInstanceBindingyourappstoaserviceinstanceenablestheappstoconnecttotheserviceinstanceandreadorwritedatatotheregion.Run cfbind-serviceAPP-NAMESERVICE-INSTANCE-

NAMEtobindanapptoyour

serviceinstance.Replace APP-NAME withthenameoftheapp.Replace SERVICE-INSTANCE-NAME withthenameyouchoseforyourserviceinstance.

$cfbind-servicemy-appmy-cloudcache

Bindinganapptotheserviceinstanceprovidesconnectioninformationthroughthe VCAP_SERVICES

environmentvariable.Yourappcanusethisinformationtoconfigurecomponents,suchastheGemFireclientcache,tousetheserviceinstance.

Thefollowingisasample VCAP_SERVICES environmentvariable:


http://gemfire.docs.pivotal.io/95/geode/tools_modules/gfsh/command-pages/destroy.html#topic_yfr_l2z_ck

https://github.com/cloudfoundry/java-buildpack

{"p-cloudcache":[{"credentials":{"locators":["10.244.0.4[55221]","10.244.1.2[55221]","10.244.0.130[55221]"],"urls":{"gfsh":"https://cloudcache-1.example.com/gemfire/v1","pulse":"https://cloudcache-1.example.com/pulse"},"users":[{"password":"some_developer_password","username":"developer_XXX"},{"password":"some_password","username":"cluster_operator_XXX"}]},"label":"p-cloudcache","name":"test-service","plan":"caching-small","provider":null,"syslog_drain_url":null,"tags":[],"volume_mounts":[]}]}

UsethePulseDashboardYoucanaccessthePulsedashboardforaserviceinstancebyaccessingthepulse-urlyouobtainedfromaservicekeyinawebbrowser.

Useeitherthe cluster_operator_XXX or developer_XX credentialstoauthenticate.

AccessServiceInstanceMetricsToaccessservicemetrics,youmusthaveEnablePlanselectedunderServicePlanAccessonthepagewhereyouconfigureyourtileproperties.(Fordetails,seetheConfigureServicePlanspage.)


PCCserviceinstancesoutputmetricstotheLoggregatorFirehose.YoucanusetheFirehoseplugin toviewmetricsoutputonthecfCLIdirectlyorconnecttheoutputtoanyotherFirehosenozzle ;forexample,thenozzleforDatadog .

PCCsupportsmetricsforthewholeclusterandmetricsforeachmember.Eachserverandlocatorintheclusteroutputsmetrics.

ServiceInstance(Cluster-wide)Metrics

serviceinstance.MemberCount:thenumberofVMsinthecluster

serviceinstance.TotalHeapSize:thetotalMBsofheapavailableinthecluster

serviceinstance.UsedHeapSize:thetotalMBsofheapinuseinthecluster

Member(per-VM)Metrics

member.GarbageCollectionCount:thenumberofJVMgarbagecollectionsthathaveoccurredonthismembersincestartup

member.CpuUsage:thepercentageofCPUtimeusedbytheGemFireprocess

member.GetsAvgLatency:theavglatencyofGETrequeststothisGemFiremember

member.PutsAvgLatency:theavglatencyofPUTrequeststothisGemFiremember

member.JVMPauses:thenumberofJVMpausesthathaveoccurredonthismembersincestartup

member.FileDescriptorLimit:thenumberoffilesthismemberallowstobeopenatonce

member.TotalFileDescriptorOpen:thenumberoffilesthismemberhasopennow

member.FileDescriptorRemaining:thenumberoffilesthatthismembercouldopenbeforehittingitslimit

member.TotalHeapSize:thenumberofmegabytesallocatedfortheheap

member.UsedHeapSize:thenumberofmegabytescurrentlyinusefortheheap

member.UnusedHeapSizePercentage:thepercentageofthetotalheapsizethatisnotcurrentlybeingused

AccessServiceBrokerMetricsServicebrokermetricsareonbydefaultandcanbeaccessedthroughtheFirehosenozzleplugin .Formoreinformationonbrokermetrics,seeOnDemandBrokerMetrics .


https://docs.cloudfoundry.org/loggregator/cli-plugin.html

https://docs.cloudfoundry.org/loggregator/architecture.html#nozzles

https://github.com/cloudfoundry-attic/datadog-firehose-nozzle

https://docs.cloudfoundry.org/loggregator/cli-plugin.html

https://docs.pivotal.io/svc-sdk/odb/0-16/operating.html#metrics

ExportgfshLogsYoucangetlogsand .gfs statsfilesfromyourPCCserviceinstancesusingthe exportlogs commandingfsh.

1. UsetheConnectwithgfshoverHTTPSproceduretoconnecttotheserviceinstanceforwhichyouwanttoseelogs.

2. Run export logs .

3. FindtheZIPfileinthedirectorywhereyoustartedgfsh.Thisfilecontainsafolderforeachmemberofthecluster.Thememberfoldercontainstheassociatedlogfilesandstatsfilesforthatmember.

Formoreinformationaboutthegfshexportcommand,seethegfshexportdocumentation .

DeployanAppJARFiletotheServersYoucandeployorredeployanappJARfiletotheserversinthecluster.

TodoaninitialdeployofanappJARfileafterconnectingwithingfshusingtheclusteroperatorcredentials,runthisgfshcommand:

deploy--jar=PATH-TO-JAR/FILENAME.jar

Forexample,

gfsh>deploy--jar=working-directory/myJar.jar

ToredeployanappJARfileafterconnectingwithingfshusingtheclusteroperatorrole,dothefollowing:

1. RunthisgfshcommandtodeploytheupdatedJARfile:gfsh>deploy--jar=PATH-TO-UPDATED-JAR/FILENAME.jar

Forexample,

gfsh>deploy--jar=newer-jars/myJar.jar

2. RunthiscommandtorestarttheclusterandloadtheupdatedJARfile:cfupdate-serviceSERVICE-INSTANCE-NAME-c'{"restart":true}'

Forexample,


https://gemfire.docs.pivotal.io/geode/tools_modules/gfsh/command-pages/export.html

$cfupdate-servicemy-service-instance-c'{"restart":true}'

UsetheGemFire-GreenplumConnectorTheGemFire-GreenplumconnectorpermitsthetransferofaPCCregionouttoaGreenplumdatabasetableorthetransferofaGreenplumdatabasetableintoaPCCregion. gfsh commandssetuptheconfigurationandinitiatetransfers.SeetheGemFire-GreenplumConnector documentationfordetails.

Connectin gfsh withtheclusteroperatorroletohavethenecessarypermissionstousetheconnector.


http://ggc.docs.pivotal.io

DevelopinganAppUnderTLSAppsthatconnecttoaTLS-enabledPCCserviceinstancerequireatruststorecontainingtheServicesCAcertificatefromCredHub,andtheymustsetpropertiestoconfigurethecommunicationwiththePivotalGemFirecomponentswithinthePCCserviceinstance.

HaveyourPCFoperatorfollowthisproceduretoacquireandprovideyouwiththeServicesCAcertificate:

1. FromtheOpsManagerVM,settheAPItargetoftheCredHubCLItoyourCredHubserver.


credhubapihttps://BOSH-DIRECTOR:8844--ca-cert=/var/tempest/workspaces/default/root_ca_certificate

where BOSH-DIRECTOR istheIPaddressoftheBOSHDirectorVM.

Forexample:

$credhubapihttps://10.0.0.5:8844--ca-cert=/var/tempest/workspaces/default/root_ca_certificate

2. LogintoCredHub.


credhublogin--client-name=credhub--client-secret=CLIENT-SECRET

where CLIENT-SECRET istheclientsecretsetinthecreationoftheUAAClient.

Forexample:

$credhublogin\--client-name=credhub\--client-secret=abcdefghijklm123456789

3. RunthiscommandtoprinttheServicesCAcertificate:

$credhubget--name="/services/tls_ca"-j|jq-r.value.certificate


Followthisproceduretosetupthetruststore:

1. AddtheServicesCAcertificatetoanexistingtruststoreorcreateanewtruststoreintheapp’ssrc/main/resources folder.SeeCreateaTruststoreforinstructions.Thelocationforthis

truststoreisfixed.Iftheappusesatruststorelocatedinadifferentspotthanthesrc/main/resources folder,createanewtruststoreinthisrequiredlocation.

FourGemFirepropertiesmustbesettoconfigurecommunication:

1. Set ssl-enabled-components to all .

2. Set ssl-truststore totheabsolutepathandfilenameofthetruststoreasitwillexistwithintheexpandedJARfileofthedeployedapp.

3. Set ssl-truststore-password tothepasswordchosenwhenthetruststorewascreated.

4. Set ssl-require-authentication to false ,suchthattherewillbeone-wayauthenticationoftheGemFirecomponenttotheapp.

ForaSpringDataGemFireappthatplacesitstruststorein src/main/resources ,thesepropertiesmapto

spring.data.gemfire.security.ssl.truststore=/home/vcap/app/BOOT-INF/classes/truststore.jksspring.data.gemfire.security.ssl.truststore.password=TRUSTSTORE-PASSWORDspring.data.gemfire.security.ssl.require.authentication=false

where TRUSTSTORE-PASSWORD isthepasswordchosenduringtruststorecreation.

Forotherapps,theGemFirepropertiesshouldbe

ssl-enabled-components=allssl-truststore=/home/vcap/app/BOOT-INF/classes/truststore.jksssl-truststore-password=TRUSTSTORE-PASSWORDssl-require-authentication=false

where TRUSTSTORE-PASSWORD isthepasswordchosenduringtruststorecreation.Anappmaysetthesepropertieswiththe ClientCacheFactory.set() method,priortocreatinga ClientCache instance.

Thebuildand cfpush oftheappdoesnotrequireanychangestoworkwithaTLS-enabledPCCserviceinstance.



ConnectingaSpringBootApptoPivotalCloudCachewithSessionStateCachingInthistopic

UsetheTomcatApp

UseaSpringSessionDataGemFireAppUpgradePCCandSpringSessionDataGemFire

ThissectiondescribesthetwowaysinwhichyoucanconnectaSpringBootapptoPCC:

UsingaTomcatappwithaWARfile.ThisisthedefaultmethodforTomcatapps.

Usingthespring-session-data-gemfirelibrary.Thismethodrequiresthatyouusethecorrectversionoftheselibraries.

UsetheTomcatAppInPCCv1.1andlater,togetaSpringBootapprunningwithsessionstatecaching(SSC)onPCC,youmustcreateaWARfileusingthe spring-boot-starter-tomcat plugininsteadofthe spring-boot-maven plugintocreateaJARfile.

Forexample,ifyouwantyourapptouseSSC,youcannotuse spring-boot-maven tobuildaJARfileandpushyourapptoPCF,becausetheJavabuildpackdoesnotpullinthenecessaryJARfilesforSSCwhenitdetectsaSpringJARfile.

TobuildyourWARfile,addthisdependencytoyour pom.xml :

<dependency><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-tomcat</artifactId><scope>provided</scope></dependency>

ForafullexampleofrunningaSpringBootappthatconnectswithSSC,runthisapp andusethisfollowingforyour pom.xml :


https://github.com/cf-gemfire-org/http-session-caching

<?xmlversion="1.0"encoding="UTF-8"?><projectxmlns="http://maven.apache.org/POM/4.0.0"xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"xsi:schemaLocation="http://maven.apache.org/POM/4.0.0http://maven.apache.org/xsd/maven-4.0.0.xsd"><modelVersion>4.0.0</modelVersion>

<groupId>io.pivotal.gemfire.demo</groupId><artifactId>HttpSessionCaching-Webapp</artifactId><version>0.0.1-SNAPSHOT</version><packaging>war</packaging>

<name>HttpSessionCaching-Webapp</name><description>DemoprojectforGemFireHttpSessionStatecaching</description>

<parent><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-parent</artifactId><version>1.5.3.RELEASE</version><relativePath/></parent>

<properties><project.build.sourceEncoding>UTF-8</project.build.sourceEncoding><project.reporting.outputEncoding>UTF-8</project.reporting.outputEncoding><java.version>1.8</java.version></properties>

<dependencies><dependency><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-thymeleaf</artifactId></dependency>

<dependency><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-tomcat</artifactId><scope>provided</scope></dependency>

<dependency><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-test</artifactId><scope>test</scope></dependency></dependencies>

</project>

UseaSpringSessionDataGemFireAppYoucanconnectyourSpringapptoPCCtodosessionstatecaching.Usethecorrectversionofthe


spring-session-data-gemfire library;appsbuiltforPCCv1.3.0andlaterversionsarecompatiblewithSpringSessionDataGemFirev2.0.0.M2andlaterversions.

UpgradePCCandSpringSessionDataGemFire

1. BeforeyouroperatorupgradesPCC,stopyourapp.Thisavoidsbreakingtheappinthisupgradeprocess.

2. UpgradePCC.SeeUpgradingPivotalCloudCachefordetails.

3. Rebuildyourappusinga build.gradle filethatdependsonthecorrectversionofPivotalGemFire.Hereisanexample build.gradle file:


version='0.0.1-SNAPSHOT'

buildscript{ext{springBootVersion='2.0.0.M3'}repositories{mavenCentral()maven{url"https://repo.spring.io/snapshot"}maven{url"https://repo.spring.io/milestone"}}dependencies{classpath("org.springframework.boot:spring-boot-gradle-plugin:${springBootVersion}")}}

applyplugin:'java'applyplugin:'org.springframework.boot'applyplugin:'idea'

idea{module{downloadSources=truedownloadJavadoc=true}}

sourceCompatibility=1.8targetCompatibility=1.8

repositories{mavenCentral()maven{url"https://repo.spring.io/libs-milestone"}maven{url"https://repo.spring.io/milestone"}maven{url"http://repo.springsource.org/simple/ext-release-local"}maven{url"http://repo.spring.io/libs-release/"}maven{url"https://repository.apache.org/content/repositories/snapshots"}}

dependencies{compile("org.springframework.boot:spring-boot-starter-web:2.0.0.M3")compile("org.springframework.session:spring-session-data-gemfire:2.0.0.M2")compile("io.pivotal.spring.cloud:spring-cloud-gemfire-spring-connector:1.0.0.RELEASE")compile("io.pivotal.spring.cloud:spring-cloud-gemfire-cloudfoundry-connector:1.0.0.RELEASE")}

4. Clearthesessionstateregion.

5. Starttherebuiltapp.



CreatingContinuousQueriesUsingSpringDataGemFire

TocreatecontinuousquerieswiththeSpringDataGemFirelibrary,youmusthavethefollowing:

SpringDataGemFirev2.0.1release

SpringBootv2.0.0+

Tocreatecontinuousqueries,dothefollowingitems:

Specifyattributes subscriptionEnabled and readyForEvents forthe ClientCacheApplication annotation.ApplythisannotationtotheSpringBootclientapplicationclass:

@ClientCacheApplication(name="GemFireSpringApplication",readyForEvents=true,subscriptionEnabled=true)

Theannotationforadurableeventqueueforcontinuousqueriesalsosetsthe durableClientId andkeepAlive attributes.Forexample:

@ClientCacheApplication(name="GemFireSpringApplication",durableClientId="durable-client-id",keepAlive=true,readyForEvents=true,subscriptionEnabled=true)

Annotatethemethodthathandlestheeventstospecifythequery.Tomaketheeventqueuedurableacrossserverfailuresandrestarts,includethe durable=true attributeintheannotation,asisdoneintheexample:

@ComponentpublicclassContinuousQuery{

@ContinuousQuery(name="yourQuery",query="SELECT*FROM/yourRegionWHEREsomeAttribute==true",durable=true)publicvoidhandleChanges(CqEventevent){//PERFORMSOMEACTION}}

Theclassthatcontainsthemethodwiththe@ContinuousQueryannotationmusthavethe@Componentannotation,suchthatthecontinuousqueryiswiredupcorrectlyfortheserver.


Formoreinformation,seetheSpringDataGemFiredocumentation .


https://docs.spring.io/spring-data/gemfire/docs/current/reference/html/

ApplicationDevelopmentAnappthatinteractswithaPCCserviceinstancewillusethePivotalGemFire®clusterwithinthatserviceinstance.ArchitectingthedatastoragefortheapprequiressomefamiliaritywithGemFire.

Thissectionintroducesdesignpatternsforstructuringappdesign.ItpresentsaminimalviewofGemFiredataorganizationtohelpwithdataarchitecturedesign.AcompletepresentationofGemFire’scapabilitiesisinthePivotalGemFireDocumentation .

Inthistopic:

DesignPatterns

TheInlineCacheTheLook-AsideCacheBidirectionalReplicationAcrossaWANBlue-GreenDisasterRecoveryCQRSPatternAcrossaWANHub-and-SpokeTopologywithWANReplicationFollow-the-SunPattern

RegionDesign

KeysPartitionedRegionsReplicatedRegionsPersistenceOverflowRegionsasUsedbytheAppAnExampletoDemonstrateRegionDesign

ExampleApplications

ASimpleJavaApp


http://gemfire.docs.pivotal.io/gemfire/about_gemfire.html

DesignPatternsInthistopic

TheInlineCache

TheLook-AsideCache

BidirectionalReplicationAcrossaWAN

Blue-GreenDisasterRecovery

CQRSPatternAcrossaWAN

Hub-and-SpokeTopologywithWANReplication

Follow-the-SunPattern

TheInlineCacheAninlinecacheplacesthecachinglayerbetweentheappandthebackenddatastore.

TheappwillwanttoaccomplishCRUD(create,read,update,delete)operationsonitsdata.Theapp’simplementationoftheCRUDoperationsresultincacheoperationsthatbreakdownintocachelookups(reads)and/orcachewrites.

Thealgorithmforacachelookupquicklyreturnsthecacheentrywhentheentryisinthecache.Thisisacachehit.Iftheentryisnotinthecache,itisacachemiss,andcodeonthecacheserverretrievestheentryfromthebackenddatastore.Inthetypicalimplementation,theentryreturnedfromthebackenddatastoreonacachemissiswrittentothecache,suchthatsubsequentcachelookupsofthatsameentryresultincachehits.

Theimplementationforacachewritetypicallycreatesorupdatestheentrywithinthecache.Italso


createsorupdatesthedatastoreinoneofthefollowingways:

Synchronously,inawrite-throughmanner.Eachwriteoperationfromtheappissentontobewrittentothebackenddatastore.Afterthebackenddatastorewritefinishes,thevalueisalsowrittentothecache.Theappblocksuntilthewritestoboththebackenddatastoreandthecachecomplete.

Asynchronously,inawrite-behindmanner.Thecachegetsupdated,andthevaluetobewrittentothebackenddatastoregetsqueued.Controlthenreturnstotheapp,whichcontinuesindependentofthewritetothebackenddatastore.

Developersdesigntheservercodetoimplementthisinline-cachingpattern.SeeSettingUpServersforanInlineCachefordetailsaboutthecustomservercodeandhowtoconfigureaninlinecache.

TheLook-AsideCacheThelook-asidepatternofcachingplacestheappinchargeofcommunicationwithboththecacheandthebackenddatastore.

TheappwillwanttoaccomplishCRUD(CREATE,READ,UPDATE,DELETE)operationsonitsdata.Thatdatamaybe

inboththedatastoreandthecache

inthedatastore,butnotinthecache


notineitherthedatastoreorthecache

Theapp’simplementationoftheCRUDoperationsresultincacheoperationsthatbreakdownintocachelookups(reads)and/orcachewrites.

Thealgorithmforacachelookupreturnsthecacheentrywhentheentryisinthecache.Thisisacachehit.Iftheentryisnotinthecache,itisacachemiss,andtheappattemptstoretrievetheentryfromthedatastore.Inthetypicalimplementation,theentryreturnedfromthebackenddatastoreiswrittentothecache,suchthatsubsequentcachelookupsofthatsameentryresultincachehits.

Thelook-asidepatternofcachingleavestheappfreetoimplementwhateveritchoosesifthedatastoredoesnothavetheentry.

Thealgorithmforacachewriteimplementsoneofthese:

Theentryiseitherupdatedorcreatedwithinthedatastore,andtheentryisupdatedwithinorwrittentothecache.

Theentryiseitherupdatedorcreatedwithinthebackenddatastore,andthecopycurrentlywithinthecacheisinvalidated.

BidirectionalReplicationAcrossaWANTwoPCCserviceinstancesmaybeconnectedacrossaWANtoformasingledistributedsystemwithasynchronouscommunication.TheclusterwithineachofthePCCserviceinstanceswillhostthesameregion.UpdatestoeitherPCCserviceinstancearepropagatedacrosstheWANtotheotherPCCserviceinstance.ThedistributedsystemimplementsaneventualconsistencyoftheregionthatalsohandleswriteconflictswhichoccurwhenasingleregionentryismodifiedinbothPCCserviceinstancesatthesametime.

Inthisactive-activesystem,anexternalentityimplementsload-balancingbydirectingappconnectionstooneofthetwoserviceinstances.IfoneofthePCCserviceinstancesfails,appsmayberedirectedtotheremainingserviceinstance.

ThisdiagramshowsmultipleinstancesofanappinteractingwithoneofthetwoPCCserviceinstances,clusterAandclusterB.AnychangemadeinclusterAissenttoclusterB,andanychangemadeinclusterBissenttoclusterA.

Note:SDG(SpringDataGemFire)supportsthelook-asidepattern,asdetailedatConfiguringSpring’sCacheAbstraction .


https://docs.spring.io/spring-data/gemfire/docs/current/reference/html/#bootstrap-annotation-config-caching

Blue-GreenDisasterRecoveryTwoPCCserviceinstancesmaybeconnectedacrossaWANtoformasingledistributedsystemwithasynchronouscommunication.Anexpectedusecasepropagatesallchangestoaregion’sdatafromtheclusterwithinoneserviceinstance(theprimary)totheother.Thereplicateincreasesthefaulttoleranceofthesystembyactingasahotspare.Inthescenarioofthefailureofanentiredatacenteroranavailabilityzone,appsconnectedtothefailedsitecanberedirectedbyanexternalload-balancingentitytothereplicate,whichtakesoverastheprimary.

Inthisdiagram,clusterAisprimary,anditreplicatesalldataacrossaWANtoclusterB.


IfclusterAfails,clusterBtakesover.

CQRSPatternAcrossaWANTwoPCCserviceinstancesmaybeconnectedacrossaWANtoformasingledistributedsystemthat


implementsaCQRS(CommandQueryResponsibilitySegregation)pattern.Withinthispattern,commandsarethosethatchangethestate,wherestateisrepresentedbyregioncontents.AllregionoperationsthatchangestatearedirectedtotheclusterwithinonePCCserviceinstance.ThechangesarepropagatedasynchronouslytotheclusterwithintheotherPCCserviceinstanceviaWANreplication,andthatotherclusterprovidesonlyqueryaccesstotheregiondata.

ThisdiagramshowsanappthatmayupdatetheregionwithinthePCCserviceinstanceofclusterA.ChangesarepropagatedacrosstheWANtoclusterB.TheappboundtoclusterBmayonlyquerytheregiondata;itwillnotcreateentriesorupdatetheregion.

Hub-and-SpokeTopologywithWANReplicationMultiplePCCserviceinstancesconnectedacrossaWANformasinglehubandasetofspokes.ThisdiagramshowsPCCserviceinstanceAisthehub,andPCCserviceinstancesB,C,andDarespokes.


Acommonimplementationthatusesthistopologydirectsallappoperationsthatwriteorupdateregioncontentstothehub.WritesandupdatesarethenpropagatedasynchronouslyacrosstheWANfromthehubtothespokes.

Follow-the-SunPatternPerformanceimproveswhenoperationrequestsoriginateincloseproximitytotheserviceinstancethathandlesthoserequests.Yetmanydatasetsarerelevantandusedallovertheworld.Ifthemostactivelocationforwriteandupdateoperationsmovesoverthecourseofaday,thenaperformantdesignpatternisavariationonthehub-and-spokeimplementationthatchangeswhichPCCserviceinstanceisthehubtothemostactivelocation.

FormaringthatcontainseachPCCserviceinstancethatwillactasthehub.Defineatokentoidentifythehub.Overtime,passthetokenfromonePCCserviceinstancetothenext,aroundthering.


ThisdiagramshowsPCCserviceinstanceAisthehub,asithasthetoken,representedinthisdiagramasastar.PCCserviceinstancesB,C,andDarespokes.Writeandupdateoperationsaredirectedtothehub.

ThisdiagramshowsthatthetokenhaspassedfromAtoB,andBhasbecomethehub.



RegionDesignInthistopic

Keys

PartitionedRegionsPartitionedRegionTypesforCreatingRegionsontheServer

ReplicatedRegionsReplicatedRegionTypesforCreatingRegionsontheServer

Persistence

Overflow

RegionsasUsedbytheApp

AnExampletoDemonstrateRegionDesign

CacheddataareheldinGemFireregions.Eachentrywithinaregionisakey/valuepair.Thechoiceofkeyandregiontypeaffecttheperformanceofthedesign.Therearetwobasictypesofregions:partitionedandreplicated.Thedistinctionbetweenthetwotypesisbasedonhowentriesaredistributedamongserversthathosttheregion.

KeysEachregionentrymusthaveauniquekey.Useawrappedprimitivetypeof String , Integer ,or Long .Experienceddesignershaveaslightpreferenceof String over Integer or Long .Usinga String keyenhancesthedevelopmentanddebuggingenvironmentbypermittingtheuseofaRESTAPI(SwaggerUI),asitonlyworkswith String types.

PartitionedRegionsApartitionedregiondistributesregionentriesacrossserversbyusinghashing.Thehashofakeymapsanentrytoabucket.Afixednumberofbucketsaredistributedacrosstheserversthathosttheregion.

Hereisadiagramthatshowsasinglepartitionedregion(highlighted)withveryfewentriestoillustratepartitioning.


Apartitionedregionisthepropertypeofregiontousewhenoneorbothofthesesituationsexist:

Theregionholdsvastquantitiesofdata.Theremaybesomuchdatathatyouneedtoaddmoreserverstoscalethesystemup.PCCcanbescaledupwithoutdowntime;tolearnmore,seeUpdatingaPivotalCloudCacheServiceInstance.

Operationsontheregionarewrite-heavy,meaningthattherearealotofentryupdates.

Redundancyaddsfaulttolerancetoapartitionedregion.Hereisthatsameregion,butwiththeadditionofasingleredundantcopyofeacheachentry.Thebucketsdrawnwithdashedlinesareredundantcopies.Withinthediagram,thepartitionedregionishighlighted.


Withoneredundantcopy,theGemFireclustercantolerateasingleserverfailureoraserviceupgradewithoutlosinganyregiondata.Withonelessserver,GemFirereviseswhichserverholdstheprimarycopyofanentry.

Apartitionedregionwithoutredundancypermanentlylosesdataduringaserviceupgradeorifaservergoesdown.Allentrieshostedinthebucketsonthefailedserverarelost.

PartitionedRegionTypesforCreatingRegionsontheServer

Regiontypesassociateanamewithaparticularregionconfiguration.Thetypeisusedwhencreatingaregion.Althoughmoreregiontypesthantheseexist,useoneofthesetypestoensurethatnoregiondataislostduringserviceupgradesorifaserverfails.Thesepartitionedregiontypesaresupported:

PARTITION_REDUNDANT Regionentriesareplacedintothebucketsthataredistributedacrossallservershostingtheregion.Inaddition,GemFirekeepsandmaintainsadeclarednumberofredundantcopiesofallentries.Thedefaultnumberofredundantcopiesis1.

PARTITION_REDUNDANT_HEAP_LRU Regionentriesareplacedintothebucketsthataredistributedacrossallservershostingtheregion.GemFirekeepsandmaintainsadeclarednumberofredundantcopies.Thedefaultnumberofredundantcopiesis1.Asaserver(JVM)reachesaheapusageof65%ofavailableheap,theserverdestroysentriesasspaceisneededforupdates.Theoldestentryinthebucketwhereanewentrylivesistheonechosenfordestruction.

PARTITION_PERSISTENT Regionentriesareplacedintothebucketsthataredistributedacrossallservershostingtheregion,andallserverspersistallentriestodisk.

PARTITION_REDUNDANT_PERSISTENT Regionentriesareplacedintothebucketsthataredistributed


acrossallservershostingtheregion,andallserverspersistallentriestodisk.Inaddition,GemFirekeepsandmaintainsadeclarednumberofredundantcopiesofallentries.Thedefaultnumberofredundantcopiesis1.

PARTITION_REDUNDANT_PERSISTENT_OVERFLOW Regionentriesareplacedintothebucketsthataredistributedacrossallservershostingtheregion,andallserverspersistallentriestodisk.Inaddition,GemFirekeepsandmaintainsadeclarednumberofredundantcopiesofallentries.Thedefaultnumberofredundantcopiesis1.Asaserver(JVM)reachesaheapusageof65%ofavailableheap,theserveroverflowsentriestodiskwhenitneedstomakespaceforupdates.

PARTITION_PERSISTENT_OVERFLOW Regionentriesareplacedintothebucketsthataredistributedacrossallservershostingtheregion,andallserverspersistallentriestodisk.Asaserver(JVM)reachesaheapusageof65%ofavailableheap,theserveroverflowsentriestodiskwhenitneedstomakespaceforupdates.

ReplicatedRegionsHereisareplicatedregionwithveryfewentries(four)toillustratethedistributionofentriesacrossservers.Forareplicatedregion,allserversthathosttheregionhaveacopyofeveryentry.

GemFiremaintainscopiesofallregionentriesonallservers.GemFiretakescareofdistributionandkeepstheentriesconsistentacrosstheservers.

Areplicatedregionisthepropertypeofregiontousewhenoneormoreofthesesituationsexist:

Theregionentriesdonotchangeoften.Eachwriteofanentrymustbepropagatedtoallserversthathosttheregion.Asaconsequence,performancesufferswhenmanyconcurrentwriteaccessescausesubsequentwritestoallotherservershostingtheregion.

Theoverallquantityofentriesisnotsolargeastopushthelimitsofmemoryspaceforasingleserver.


ThePCFserviceplansetstheservermemorysize.

Theentriesofaregionarefrequentlyaccessedtogetherwithentriesfromotherregions.Theentriesinthereplicatedregionarealwaysavailableontheserverthatreceivestheaccessrequest,leadingtobetterperformance.

ReplicatedRegionTypesforCreatingRegionsontheServer

Regiontypesassociateanameaparticularregionconfiguration.Thesereplicatedregiontypesaresupported:

REPLICATE Allservershostingtheregionhaveacopyofallentries.

REPLICATE_HEAP_LRU Allservershostingtheregionhaveacopyofallentries.Asaserver(JVM)reachesaheapusageof65%ofavailableheap,theserverdestroysentriesasitneedstomakespaceforupdates.

REPLICATE_PERSISTENT Allservershostingtheregionhaveacopyofallentries,andallserverspersistallentriestodisk.

REPLICATE_PERSISTENT_OVERFLOW Allservershostingtheregionhaveacopyofallentries.Asaserver(JVM)reachesaheapusageof65%ofavailableheap,theserveroverflowsentriestodiskasitneedtomakespaceforupdates.

PersistencePersistenceaddsaleveloffaulttolerancetoaPCCserviceinstancebywritingallregionupdatestolocaldisk.Diskdata,henceregiondata,isnotlostuponclusterfailuresthatexceedredundancyfailuretolerances.Uponclusterrestart,regionsarereloadedfromthedisk,avoidingtheslowermethodofrestartthatreacquiresdatausingadatabaseofrecord.

Creatingaregionwithoneoftheregiontypesthatincludes PERSISTENT initsnamecausestheinstantiationoflocaldiskresourceswiththesedefaultproperties:

Synchronouswrites.Allupdatestotheregiongenerateoperatingsystemdiskwritestoupdatethediskstore.

Thedisksizeispartoftheinstanceconfiguration.SeeConfigureServicePlansfordetailsonsettingthepersistentdisktypesfortheserver.Chooseasizethatisatleasttwiceaslargeastheexpectedmaximumquantityofregiondata,withanabsoluteminimumsizeof2GB.Regiondataincludesboththekeysandtheirvalues.

Warningmessagesareissuedwhena90%diskusagethresholdiscrossed.


OverflowRegionoverflowisanevictionactionthatkeepsheapmemoryspaceusagebelowafixedthresholdof65%ofavailableheapmemoryspace.Foraregionthatpushesatthelimitsofmemoryusage,overflowreducesthenumberoforeliminatespausesforstop-the-worldgarbagecollection.

Theactionofoverflowwritesoneormoreleastrecentlyusedregionentriestodisktomakeroominmemoryforanotherentry.Theleastrecentlyusedentrywithinthebuckettowhichnewentrymapsisthechosenoverflowvictim.Thekeyofthevictimremainsinmemory,butthevalueoftheentryiswrittentodisk.Anoperationonanentrythathasoverflowedtodiskcausestheentrytobeswappedbackintomemory.

Ifusingaregiontypewithoverflow,besuretoconfigureaplanwithsufficientdiskspacefortheServerVM,allocatingatleasttheminimumsgivenforthePersistentdisktypefortheServerVMs,asdescribedinConfigureTileProperties.

Ifnodiskstoreiscreated,regioncreationwitharegiontypethatusesadiskstorewillcausethecreationofonecalled DEFAULT withadefaultsize(2Gbyte).Alternatively,createthediskstoreusing gfsh ,asdescribedinWorkingwithDiskStores.Then,createtheregionusingthe --disk-store optiontospecifythecreateddiskstore.Ifthediskstorehasbeencreated,butthegfshregioncreationcommandneglectstospecifyadiskstore,anew DEFAULT diskstorewillbecreatedandused.Formoredetailsonregioncreationoptions,seethePivotalGemFirecreateregionCommandReferencePage .

RegionsasUsedbytheAppTheclientaccessesregionshostedontheserversbycreatingacacheandtheregions.Thetypeoftheclientregiondeterminesifdataisonlyontheserversorifitisalsocachedlocallybytheclientinadditiontobeingontheservers.Locallycacheddatacanintroduceconsistencyissues,becauseregionentriesupdatedonaserverarenotautomaticallypropagatedtotheclient’slocalcache.

Clientregiontypesassociateanamewithaparticularclientregionconfiguration.

PROXY forwardsallregionoperationstotheservers.Noentriesarelocallycached.Usethisclientregiontypeunlessthereisacompellingreasontouseoneoftheothertypes.UsethistypeforallTwelve-Factorappsinordertoassurestatelessprocessesareimplemented.Notcachinganyentrieslocallypreventstheappfromaccidentallycachingstate.

CACHING_PROXY forwardsallregionoperationstotheservers,andentriesarelocallycached.

CACHING_PROXY_HEAP_LRU forwardsallregionoperationstotheservers,andentriesarelocallycached.Locallycachedentriesaredestroyedwhentheapp’susageofcachespacecausesitsJVMtohitthethresholdofbeinglowonmemory.


http://gemfire.docs.pivotal.io/geode/tools_modules/gfsh/command-pages/create.html#topic_54B0985FEC5241CA9D26B0CE0A5EA863

AnExampletoDemonstrateRegionDesignAssumethatonservers,aregionholdsentriesrepresentingcustomerdata.Eachentryrepresentsasinglecustomer.Withanever-increasingnumberofcustomers,thisregiondataisagoodcandidateforapartitionedregion.

Perhapsanotherregionholdscustomerorders.Thisdataalsonaturallymapstoapartitionedregion.Thesamecouldapplytoaregionthatholdsordershipmentdataorcustomerpayments.Ineachcase,thenumberofregionentriescontinuestogrowovertime,andupdatesareoftenmadetothoseentries,makingthedatasomewhatwriteheavy.

Agoodcandidateforareplicatedregionwouldbethedataassociatedwiththecompany’sproducts.Eachregionentryrepresentsasingleproduct.Therearealimitednumberofproducts,andthoseproductsdonotoftenchange.

Considerthatastheclientappgoesbeyondthemostsimplisticofcasesfordatarepresentation,thePCCinstancehostsalloftheseregionssuchthattheappcanaccessalloftheseregions.Operationsoncustomerorders,shipments,andpaymentsallrequireproductinformation.Theproductregionbenefitsfromaccesstoallitsentriesavailableonallthecluster’sservers,againpointingtoaregiontypechoiceofareplicatedregion.


ExampleApplications

TheseexampleapplicationsprovideinsightintoaspectsofappdesignforPCC.

Inthistopic:

ASimpleJavaApp


ASimpleJavaApp

ThesampleJavaclientappathttps://github.com/cf-gemfire-org/cloudcache-sample-app.git

demonstrateshowtoconnectanapptoaserviceinstance.

Theseinstructionsassume:

APCCserviceinstanceisrunning.

YouhaveCloudFoundrycredentialsforaccessingthePCCserviceinstance.

YouhaveaservicekeyforthePCCserviceinstance.

YouhavealoginonthePivotalCommercialMavenRepositoryathttps://commercial-repo.pivotal.io.

Youhavea gfsh clientofthesameversionasisusedwithinyourPCCserviceinstance.

Followtheseinstructionstoruntheapp.

1. ClonethesampleJavaappfromhttps://github.com/cf-gemfire-org/cloudcache-sample-app.git .

2. UpdateyourcloneofthesampleJavaapptoworkwithyourPCCserviceinstance:

Modifythemanifestin manifest.yml byreplacing service0 withthenameofyourPCCserviceinstance.Replacetheusernameandpasswordinthe gradle.properties filewithyourusernameandpasswordforthePivotalCommercialMavenRepository.UpdatetheGemFireversioninthedependenciessectionofthe build.gradle filetobethesameastheversionwithinyourPCCserviceinstance.

3. Buildtheappwith

$./gradlewcleanbuild

4. Inasecondshell,run gfsh .

5. Use gfsh toconnecttothePCCserviceinstanceasdescribedinConnectwithgfshoverHTTPS.

6. Use gfsh tocreatearegionnamed test asdescribedinCreateRegionswithgfsh.Thissampleappplacesasingleentryintotheregion,sotheregiontypeisnotimportant. PARTITION_REDUNDANT


https://github.com/cf-gemfire-org/cloudcache-sample-app.git

https://commercial-repo.pivotal.io

https://github.com/cf-gemfire-org/cloudcache-sample-app.git

isagoodchoice.

7. Intheshellwheretheappwasbuilt,deployandruntheappwith

cfpush-fmanifest.yml

8. Aftertheappstarts,therewillbeanentryof(“1”,“one”)inthe test region.youcanseethatthereisoneentryintheregionwiththe gfsh command:

gfsh>describeregion--name=test

Forthisverysmallregion,youcanprintthecontentsoftheentireregionwitha gfsh query:

gfsh>query--query='SELECT*FROM/test'


TroubleshootingHereareproblemsandfixesrelatedtousingPCC.

Problem:Anerroroccurswhencreatingaserviceinstanceorwhenrunningasmoketest.Theservicecreationissuesanerrormessagethatstartswith

Instanceprovisioningfailed:Therewasaproblemcompletingyourrequest.

GemFireserverlogsat /var/vcap/sys/log/gemfire-server/gemfire/server-<N>.log willcontainadisk-accesserrorwiththestring

ADiskAccessExceptionhasoccurred

andastacktracesimilartothisonethatbeginswith

org.apache.geode.cache.persistence.ConflictingPersistentDataExceptionatorg.apache.geode.internal.cache.persistence.PersistenceAdvisorImpl.checkMyStateOnMembers(PersistenceAdvisorImpl.java:743)atorg.apache.geode.internal.cache.persistence.PersistenceAdvisorImpl.getInitialImageAdvice(PersistenceAdvisorImpl.java:819)atorg.apache.geode.internal.cache.persistence.CreatePersistentRegionProcessor.getInitialImageAdvice(CreatePersistentRegionProcessor.java:52)atorg.apache.geode.internal.cache.DistributedRegion.getInitialImageAndRecovery(DistributedRegion.java:1178)atorg.apache.geode.internal.cache.DistributedRegion.initialize(DistributedRegion.java:1059)atorg.apache.geode.internal.cache.GemFireCacheImpl.createVMRegion(GemFireCacheImpl.java:3089)

CauseoftheProblem:ThePCCVMsareunderprovisioned;thequantityofdiskspaceistoosmall.Solution:UseOpsManagertoprovisionVMsofatleasttheminimumsize.SeeConfigureServicePlansforminimum-sizedetails.


PivotalCloudCacheReleaseNotesInthistopic

v1.5.4

v1.5.3

v1.5.2

v1.5.1

v1.5.0

KnownIssues

v1.5.4ReleaseDate:May8,2019

Featuresincludedinthisrelease:

PCC1.5.4usesPivotalGemFire9.6.2 .

v1.5.3ReleaseDate:April10,2019


IfaClamAVorFileIntegrityMonitorisdetected,availablememoryforGemFireserversisreducedtoallowenoughmemoryforthesePCFadd-ons.ThispreventsafailureduringPCCserviceinstancecreation.

PCC1.5.3usesPivotalGemFire9.6.1.

v1.5.2

BreakingChange:ThispatchreleaseincreasessystemsecuritybyrequiringTLSencryptionforusinggfshandPulse.FollowthestepswithinPreparingforTLSpriortoinstallingthePCCtile.


http://gemfire.docs.pivotal.io/96/gemfire/release_notes.html#ResolvedIssuesGF962

ReleaseDate:January9,2019


PCCnowshipswithOpenJDK1.8_192insteadoftheequivalentOracleJDK.

PCC1.5.2usesPivotalGemFire9.6.

v1.5.1ReleaseDate:November27,2018


SecurityVulnerability:PCCdependsuponthePivotalCloudFoundryOnDemandServicesBroker,whichaddressedthefollowingsecurityvulnerability:

CVE-2018-15759 :OnDemandServicesSDKtimingattackvulnerability

SecurityVulnerability:PCCdependsuponanincludedJavaSE,whichaddressedthefollowingsecurityvulnerabilities:

CVE-2018-3149

CVE-2018-3180

CVE-2018-3183

CVE-2018-3214

PCC1.5.1usesPivotalGemFire9.6.0.

PCCnowrunswithaXenialstemcell,version170.9oramorerecentversion.

v1.5.0ReleaseDate:October22,2018


TLSauthenticationandencryptionmaybeenabledforallcommunicationwithinaPCCserviceinstance.Theauthenticationisoneway,withappsauthenticatingservers.

APCCserviceinstancestorescredentialsinCredHubwhensharingthecredentialswithapplications.

Theupgradeofserviceinstancescanbeexecutedinparallel,aftertryingtheupgradeonasetofcanaryinstancesfirst.


https://pivotal.io/security/cve-2018-15759

https://nvd.nist.gov/vuln/detail/CVE-2018-3149




BOSHerrandsarecolocatedwiththeBrokerVM,whichdecreasestheinstallationtimeforthetile.

Thedevplanmaybeselectedforuseinsmoketests.

PCC1.5.0usesPivotalGemFire9.6.0.Using gfsh withthisGemFireversionrequiresaJDKorJREwithJava8release121oramorerecentversion8update.

TheGemFire-GreenplumConnectorv3.3.0makesitpossibletoimportandexportPCC’sregionentriesfromandtoaGreenplumdatabasetable.SeeUsetheGemFire-GreenplumConnector.

PCCnowsupportsPivotalApplicationService(PAS)2.3.

UsersupgradingfromthePCClimitedavailabilityv1.3.2releasewillautomaticallyupgradetothisPCCv1.5.0releasewithoutupgradingtov1.4.MakesuretoupgradetoPAS/OpsManagerv2.2priortodoingtheupgradefromPCClimitedavailabilityv1.3.2toPCCv1.5.0.

KnownIssuesInstallationsusingHTTPsessionstatereplicationhaveaknownissueissueandworkaroundtocorrecttheissue.TheHTTPsessionmodulecreatesitsregionthatholdsmetadataononlyoneserverwithinacluster.Theregionneedstobehostedonalltheservers.Tocorrecttheissueonarunningcluster,connecttotheclusterusingtheGemFireclusteroperatorcredentials,andrunasingle gfsh commandtocreatethemetadataregiononallservers.Thecommandhastheform:

createregion--name=REGION-NAME--type=REGION-SHORTCUT\--enable-statistics\--entry-idle-time-custom-expiry=org.apache.geode.modules.util.SessionCustomExpiry

Ifthemetadataregion’snameortypehavenotbeenchangedfromtheirdefault,usethis gfsh

command:

gfsh>createregion--name=gemfire_modules_sessions--type=PARTITION_REDUNDANT\--enable-statistics\--entry-idle-time-custom-expiry=org.apache.geode.modules.util.SessionCustomExpiry

Forinstallationsthathavechangedthemetadataregion’snameortype,substitutethechangedvaluesfor REGION-NAME and REGION-SHORTCUT inthecommand.Youcanverifythattheregionishostedonallserverswiththe gfsh command:

gfsh>describeregion--name=gemfire_modules_sessions

ThelocatorlogofaTLS-enabledclusterwillgrowovertimewithrepeatedloggingofthisexceptionat10-secondintervals:


[info2018/08/1423:28:41.343UTClocator-ID<locatorrequestthread[3]>tid=0x75]Exceptioninprocessingrequestfrom127.0.0.1javax.net.ssl.SSLHandshakeException:Remotehostclosedconnectionduringhandshakeatsun.security.ssl.SSLSocketImpl.readRecord(SSLSocketImpl.java:1002)atsun.security.ssl.SSLSocketImpl.performInitialHandshake(SSLSocketImpl.java:1385)atsun.security.ssl.SSLSocketImpl.startHandshake(SSLSocketImpl.java:1413)atsun.security.ssl.SSLSocketImpl.startHandshake(SSLSocketImpl.java:1397)atorg.apache.geode.internal.net.SocketCreator.configureServerSSLSocket(SocketCreator.java:1013)atorg.apache.geode.distributed.internal.tcpserver.TcpServer.lambda$processRequest$0(TcpServer.java:367)atjava.util.concurrent.ThreadPoolExecutor.runWorker(ThreadPoolExecutor.java:1149)atjava.util.concurrent.ThreadPoolExecutor$Worker.run(ThreadPoolExecutor.java:624)atjava.lang.Thread.run(Thread.java:748)Causedby:java.io.EOFException:SSLpeershutdownincorrectlyatsun.security.ssl.InputRecord.read(InputRecord.java:505)atsun.security.ssl.SSLSocketImpl.readRecord(SSLSocketImpl.java:983)...8more

Thisexceptionfromthemonitportcheckofthelocatorprocessmaybeignored.

IfyouupgradetoPCCv1.3aspartoftheprocessofupgradingtothis1.5release,andyoucreatedservicekeysonPCCbeforeyouinstalledv1.3:deleteandrecreatetheservicekeyssothatusersareproperlyassignedrolesforauthenticationandauthorizationwithinthecluster.Then,rebindallyourapps.Forinformationabouthowtoperformthesetasks,seeDeleteaServiceKey ,CreateServiceKeys,andBindanApptoaServiceInstance.

CurrentversionsoftheCloudFoundryCommandLineInterface(CLI)toolhaveaknownbugthatomitsthedocumentationURLwhenusingthe cfservice command.


https://docs.pivotal.io/pivotalcf/2-0/devguide/services/service-keys.html

Date post:	10-Oct-2020
Category:	Documents
Upload:	others
View:	13 times
Download:	0 times

Pivotal Cloud Cache 1 · Redis for PCF Redis Yes Yes (shared-VM plan). Only recommended for test...

Documents