Migrating to a Cluster with Transport Layer Security (TLS) Enabled
Warning: Pivotal Cloud Cache v1.8 is no longer supported because it has reached the End of General Support (EOGS) phase as defined by the Support Lifecycle Policy. To stay up to date with the latest software and security updates, upgrade to a supported version.
An existing PCC service instance that does not use TLS encryption may be migrated to become a PCC service instance with TLS encryption enabled.
WARNING! This procedure will require downtime for the service instance during the migration.
Follow the procedure given here after these prerequisites have been met:- All steps within Preparing for TLS have been completed.
- The service instance has been upgraded to PCC v1.5.2 or a more recent PCC version. There will be no PCC version change during the migration.
Follow this procedure to migrate the existing PCC service instance:
- As a PCF operator, stop all apps.
First, list all apps to identify the
APP_NAME
.$ cf apps
Then, stop each app with:$ cf stop APP_NAME
- For all non-persistent regions, use the
gfsh
command line tool to export the data.WARNING! Without an export, all non-persistent region entries will be irretrievably lost.
- Complete the steps within
Accessing a Service Instance
to acquire the correct version of
gfsh
, run it, and connect to the cluster using a role that is able to do cluster management operations. - List the regions.
gfsh>list regions
- For each region, use
gfsh describe
to determine if the region is persistent or not and to acquire a server name.gfsh>describe region --name=REGION_NAME
- For each non-persistent region, use this single
gfsh
command to export all the data within the region. TheSERVER_NAME
identifies which GemFire server receives theexport
command and propagates the command to all other GemFire servers within the cluster.gfsh>export data --parallel --region=REGION_NAME --member=SERVER_NAME --dir=/var/vcap/store/gemfire-server
- Complete the steps within
Accessing a Service Instance
to acquire the correct version of
- Your PCF operator needs to target the BOSH Director
in order to acquire the
DEPLOYMENT_NAME
.- Run
$ cf service SERVICE_INSTANCE_NAME
to acquire the digits that uniquely identify the service instance. The digits (XXX-XXX
in the following instructions) are those betweencloudcache-
and the period.
. - Log in to the BOSH Director.
$ bosh log-in
- The
DEPLOYMENT_NAME
will appear in the output of$ bosh deployments | grep XXX-XXX
- Run
- Using PCF operator credentials, stop the BOSH deployment:
$ bosh -d DEPLOYMENT_NAME stop
and type “y” when prompted. - Acquire the BOSH manifest with:
$ bosh -d DEPLOYMENT_NAME manifest > DEPLOYMENT_NAME-manifest.yml
- Edit the acquired BOSH manifest.
There are three locations within the manifest
file that will require additions.
These three locations are identified within this anonymized portion of the
manifest file with the symbols ① ,
② , and ③ .
The first part of the manifest file is omitted,
as its listed values change based on the PCC version.
Real passwords have been replaced with the placeholder
password
, and user names have been replaced with the placeholderuserX
within this example.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-subnet update: canaries: 1 canary_watch_time: 1000-600000 update_watch_time: 1000-600000 max_in_flight: 32 serial: true features: converge_variables: true ③
Add lines to the BOSH manifest, using the lines as shown in red in the following modified version of the manifest. Substitute your digits that uniquely identify your service instance forXXX-XXX
within the added lines.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-subnet update: canaries: 1 canary_watch_time: 1000-600000 update_watch_time: 1000-600000 max_in_flight: 32 serial: true features: 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
- Redeploy the BOSH manifest. Do a BOSH deploy using the edited BOSH manifest:
$ bosh -d SERVICE-INSTANCE-NAME deploy SERVICE-INSTANCE-NAME-manifest.yml
and type “y” when prompted. - Restart the cluster with a sequential BOSH start:
$ bosh start -d SERVICE-INSTANCE-NAME --max-in-flight=1
and type “y” when prompted. - Run
gfsh
and follow the directions in Connect with gfsh over HTTPS to connect to the TLS-enabled cluster. - Use
gfsh
to import all region data that was exported earlier in this procedure. For each earlier-exported region, do:gfsh>import data --parallel --region=REGION_NAME --member=SERVER_NAME --dir=/var/vcap/store/gemfire-server
- Revise the app such that it works with a TLS-enabled PCC service instance by following the instructions within Developing an App Under TLS. Re-build, re-deploy, and start the app.