Using Hazelcast IMDG Enterprise for PCF
This topic describes how developers use Hazelcast IMDG Enterprise for Pivotal Cloud Foundry (PCF).
After your PCF operator installs the Hazelcast IMDG Enterprise for PCF tile, it automatically registers itself to the Marketplace.
Follow these steps to create an instance of the Hazelcast service based on an available plan and bind it to your app. The plans available to you are determined by your PCF operator. For more information about configuring plans, see Installing and Configuring Hazelcast IMDG Enterprise for PCF.
Checking Availability
To check availability of Hazelcast IMDG Enterprise for PCF, run the following command:
$ cf marketplaceFor example,
$ cf marketplace Getting services from marketplace in org system / space system as admin... OK
service plans description app-autoscaler bronze, gold Scales bound applications in response to load (beta) hazelcast t2.micro, t2.small, m3.medium Hazelcast Service
Create and Bind a Service to Your App
Create a file named
hazelcast.jsonusing this sample Hazelcast JSON file as a template.Replace
YOUR_LICENSE_KEYwith the active Hazelcast Enterprise License or a trial license. For more information, see License.To create a cluster, run the following command:
$ cf create-service hazelcast PLAN SERVICE_INSTANCE_NAME -c hazelcast.jsonFor example:
$ cf create-service hazelcast t2.micro micro-cluster -c hazelcast.json Creating service instance micro-cluster in org system / space system as admin... OK
Create in progress. Use 'cf services' or 'cf service micro-cluster' to check operation status.To bind the service to your app, run the following commands:
$ cf bind-service MY-APPLICATION SERVICE_INSTANCE_NAME $ cf restage MY-APPLICATIONFor example,
$ cf bind-service myapp micro-cluster $ cf restage myapp
Start using the Hazelcast in-memory data grid (IMDG). Necessary parameters are passed to your application in
VCAP_SERVICESenvironment variable. See this sample Hazelcast Spring Boot application for further information.A hazelcast-full.json sample config is available to show syntax for advanced settings. You can copy the relevant parts to your own config file and change the values according to your needs.
Configuring WAN Replication
For more information on configuring WAN replication in PCF, see the official documentation.
Source Cluster
In this example, we will use the Eureka service registry for target cluster discovery. This was tested with Eureka server v1.4.12.
Edit the hazelcast.json file for the source cluster to include the following wanReplicationConfigs configuration:
"wanReplicationConfigs": {
"my-wan-cluster-batch": {
"name": "my-wan-cluster-batch",
"wanPublisherConfigs": [
{
"groupName": "cluster-name",
"queueCapacity": 10000,
"queueFullBehavior": "DISCARD_AFTER_MUTATION",
"properties": {
"maxEndpoints": 5,
"group.password": "cluster-password",
"batch.max.delay.millis": 1000
},
"className": "com.hazelcast.enterprise.wan.replication.WanBatchReplication",
"awsConfig": {
"enabled": false,
"region": "us-east-1",
"hostHeader": "ec2.amazonaws.com",
"connectionTimeoutSeconds": 5
},
"discoveryConfig": {
"discoveryStrategyConfigs": [
{
"properties": {
"environment": "test",
"shouldUseDns": false,
"serviceUrl.default": "http://<my-eureka>/eureka",
"namespace": "hazelcast",
"name": "hazelcast-target",
"use-classpath-eureka-client-props": false,
"self-registration": false
},
"className": "com.hazelcast.eureka.one.EurekaOneDiscoveryStrategy"
}
]
}
}
]
}
}
Change groupName and group.password to match your existing target cluster configuration, serviceUrl.default to match your Eureka service endpoint, and any other config values to your needs.
In this example we want to set up WAN replication for a map called my-map. This can be achieved by including the following mapConfigs configuration in your hazelcast.json:
"mapConfigs": {
"my-map": {
"name": "my-map",
"backupCount": 1,
"asyncBackupCount": 0,
"timeToLiveSeconds": 0,
"maxIdleSeconds": 0,
"maxSizeConfig": {
"maxSizePolicy": "PER_NODE",
"size": 2147483647
},
"evictionPolicy": "NONE",
"mapStoreConfig": {
"enabled": false,
"writeCoalescing": true,
"writeDelaySeconds": 0,
"writeBatchSize": 1,
"properties": {},
"initialLoadMode": "LAZY"
},
"readBackupData": false,
"cacheDeserializedValues": "INDEX_ONLY",
"mergePolicy": "com.hazelcast.map.merge.PutIfAbsentMapMergePolicy",
"inMemoryFormat": "BINARY",
"wanReplicationRef": {
"name": "my-wan-cluster-batch",
"mergePolicy": "com.hazelcast.map.merge.PassThroughMergePolicy",
"filters": [],
"republishingEnabled": false
},
"statisticsEnabled": true,
"hotRestartConfig": {
"enabled": false,
"fsync": false
}
}
}
Change any value as needed.
Management Center Support
To enable the WAN replication features in Management Center (e.g. manual sync), do not forget to include the following properties configuration:
"properties": {
"hazelcast.rest.enabled": true
}
Target Cluster
This example uses Eureka service registry for cluster member discovery. This allows the other cluster (the source cluster) to find the addresses for this cluster by means of Eureka, as shown in the previous example.
Edit the hazelcast.json file for the target cluster to include the following networkConfig configuration:
"networkConfig": {
"port": 5701,
"portCount": 100,
"portAutoIncrement": true,
"reuseAddress": true,
"interfaces": {
"enabled": false,
"interfaceSet": []
},
"join": {
"multicastConfig": {
"enabled": false,
"multicastGroup": "224.2.2.3",
"multicastPort": 54327,
"multicastTimeoutSeconds": 2,
"multicastTimeToLive": 32,
"trustedInterfaces": [],
"loopbackModeEnabled": false
},
"tcpIpConfig": {
"connectionTimeoutSeconds": 5,
"enabled": false,
"members": []
},
"awsConfig": {
"enabled": false,
"region": "us-east-1",
"hostHeader": "ec2.amazonaws.com",
"connectionTimeoutSeconds": 5
},
"discoveryConfig": {
"discoveryStrategyConfigs": [
{
"properties": {
"environment": "test",
"shouldUseDns": false,
"serviceUrl.default": "http://<my-eureka>/eureka",
"namespace": "hazelcast",
"name": "hazelcast-target",
"use-classpath-eureka-client-props": false
},
"className": "com.hazelcast.eureka.one.EurekaOneDiscoveryStrategy"
}
]
}
}
Change serviceUrl.default to match your Eureka service endpoint, and any other config values to your needs.
Configuring User Code Deployment
This section explains how to configure user code deployment, i.e. how to deploy user code at service creation/start-up time.
Summary of Functionality
You can specify additional jar(s) to be added to the server’s classpath. A new optional JSON configuration key (userCodeUrl) has been defined and can be used to specify one or more URLs for the additional jar(s).
Technical Design
The new JSON configuration key userCodeUrl can be instantiated either as a string or as string[]. For example, a single jar can be specified with the following syntax.
"userCodeUrl": "<usercode-url>"
To specify multiple jars, the following syntax can be used:
"userCodeUrl": [
"<usercode-url-1>", ..., "<usercode-url-n>"
]
Every string specified in userCodeUrl must be a valid, reachable URL.
At server start-up time, the jar(s) will be downloaded and added to Hazelcast member’s classpath.
During service update, all existing user code jars will be removed before re-downloading the jar(s) specified in userCodeUrl. The user is therefore expressly allowed to update, add, or delete user code jars with a service-update operation by changing the userCodeUrl property.
Configuring Transport Layer Security
This section explains how to configure SSL/TLS for secure communication. SSL (Secure Sockets Layer) protocol was introduced to establish an encrypted communication across your cluster with key stores and trust stores. SSL is now deprecated, so you will be using its successor TLS (Transport Layer Security).
Summary of Functionality
Hazelcast allows you to encrypt socket level communication between Hazelcast members and between Hazelcast clients and members, for end to end encryption. For more information, see the official Hazelcast TLS documentation.
Technical Design
The new JSON configuration key tlsArchiveUrl is a string that must contain a valid, reachable URL for a .tar.gz (or .tgz) archive. The archive must contain exactly two files, the Hazelcast key store (file must be named keystore) and the Hazelcast trust store (file must be named truststore).
"tlsArchiveUrl": "<archive-url>"
Example Configuration
The following snippet contains the relevant parts of json configuration for enabling TLS. The tlsArchiveUrl points to an archive containing password-protected key and trust stores. Passwords for the stores are specified in the configuration itself, with keyStorePassword and trustStorePassword. Always specify "protocol": "TLS" and specify the correct keyManagerAlgorithm and trustManagerAlgorithm for your stores.
{
"tlsArchiveUrl": "https://mydomain/myfiles/test.tgz",
...
"networkConfig": {
"port": 5701,
...
"join": {
...
},
"sslConfig": {
"enabled": true,
"properties": {
"protocol": "TLS",
"keyStorePassword": "123456",
"trustStorePassword": "123456",
"keyManagerAlgorithm": "SunX509",
"trustManagerAlgorithm": "SunX509"
}
}
},
...
}
Using OpenSSL
Hazelcast provides integration with OpenSSL, which can provide significant performance improvements. For more information, see the official Hazelcast OpenSSL integration documentation.
The OpenSSL libraries and supporting artifacts are already included with Hazelcast IMDG Enterprise for PCF. To enable the OpenSSL integration the configuration, you must include "factoryClassName": "com.hazelcast.nio.ssl.OpenSSLEngineFactory" in the sslConfig, as in the example below.
{
...
"networkConfig": {
...
"sslConfig": {
"enabled": true,
"factoryClassName": "com.hazelcast.nio.ssl.OpenSSLEngineFactory",
"properties": {
...
}
}
},
...
}