jclouds discovery plugin for hazelcast
Java
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
checkstyle
findbugs
src
.gitignore
LICENSE
README.md
pom.xml

README.md

Table of Contents

Supported Versions

hazelcast-jclouds 3.7+ is compatible with hazelcast 3.7+

Discovering Members with jclouds

Hazelcast members and native clients support jclouds® for discovery. It is useful when you do not want to provide or you cannot provide the list of possible IP addresses on various cloud providers.

To configure your cluster to use jclouds auto-discovery, follow these steps:

  • Add the hazelcast-jclouds.jar dependency to your project. Note that this is also bundled inside hazelcast-all.jar. The Hazelcast jclouds module depends on jclouds; please make sure the necessary JARs for your provider are present on the classpath.
  • Disable the multicast and TCP/IP join mechanisms. To do this, set the enabled attributes of the multicast and tcp-ip elements to false in your hazelcast.xml configuration file
  • Set the enabled attribute of the hazelcast.discovery.enabled property to true.
  • Within the discovery-providers element, provide your credentials (access and secret key), your region, etc.

The following is an example declarative configuration.

 ...
  <properties>
    <property name="hazelcast.discovery.enabled">true</property>
  </properties>
   ....
 <join>
    <multicast enabled="false">
    </multicast>
    <tcp-ip enabled="false">
    </tcp-ip>
    <discovery-strategies>
        <discovery-strategy class="com.hazelcast.jclouds.JCloudsDiscoveryStrategy" enabled="true">
          <properties>
           <property name="provider">google-compute-engine</property>
           <property name="identity">GCE_IDENTITY</property>
           <property name="credential">GCE_CREDENTIAL</property>
          </properties>
        </discovery-strategy>
    </discovery-strategies>
</join>
...

As stated in the first paragraph of this section, Hazelcast native clients also support jclouds for discovery. It means you can also configure your hazelcast-client.xml configuration file to include the element in the same way as with hazelcast.xml.

The table below lists the jclouds configuration properties with their descriptions.

Property Name Type Description
provider String String value that is used to identify ComputeService provider. For example, "google-compute-engine" is used for Google Cloud services. See the full provider list here.
identity String Cloud Provider identity, can be thought of as a user name for cloud services.
credential String Cloud Provider credential, can be thought of as a password for cloud services.
zones String Defines zone for a cloud service (optional). Can be used with comma separated values for multiple values.
regions String Defines region for a cloud service (optional). Can be used with comma separated values for multiple values.
tag-keys String Filters cloud instances with tags (optional). Can be used with comma separated values for multiple values.
tag-values String Filters cloud instances with tags (optional) Can be used with comma separated values for multiple values.
group String Filters instance groups (optional). When used with AWS it maps to security group.
hz-port Int Port which the hazelcast instance service uses on the cluster member. Default value is 5701. (optional)
role-name* String Used for IAM role support specific to AWS (optional, but if defined, no identity or credential should be defined in the configuration).
credentialPath* String Used for cloud providers which require an extra JSON or P12 key file. This denotes the path of that file. Only tested with Google Compute Engine. (Required if Google Compute Engine is used.)

Configuring Dependencies for jclouds via Maven

jclouds depends on many libraries internally and hazelcast-jclouds.jar does not contain any of them. If you want to use jclouds, we recommend that you use its dependency management tool. The following is a simple maven dependency configuration that uses the maven assembly plugin to create an uber JAR with the necessary jclouds properties.

<project xmlns="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.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>
    <groupId>group-id</groupId>
    <artifactId>artifact-id </artifactId>
    <version>version</version>
    <name>compute-basics</name>

    <properties>
        <jclouds.version>latest-version</jclouds.version>
        <hazelcast.version>latest-version</hazelcast.version>
    </properties>

    <dependencies>
        <dependency>
            <groupId>com.hazelcast</groupId>
            <artifactId>hazelcast</artifactId>
            <version>${hazelcast.version}</version>
        </dependency>
        <dependency>
            <groupId>com.hazelcast</groupId>
            <artifactId>hazelcast-jclouds</artifactId>
            <version>${hazelcast.version}</version>
        </dependency>
        <dependency>
            <groupId>org.apache.jclouds</groupId>
            <artifactId>jclouds-compute</artifactId>
            <version>${jclouds.version}</version>
        </dependency>
        <dependency>
            <groupId>org.apache.jclouds</groupId>
            <artifactId>jclouds-allcompute</artifactId>
            <version>${jclouds.version}</version>
        </dependency>
        <dependency>
            <groupId>org.apache.jclouds.labs</groupId>
            <artifactId>google-compute-engine</artifactId>
            <version>${jclouds.version}</version>
        </dependency>
    </dependencies>
    <build>
        <plugins>
            ...
            <plugin>
                <artifactId>maven-assembly-plugin</artifactId>
                <executions>
                    <execution>
                        <phase>package</phase>
                        <goals>
                            <goal>single</goal>
                        </goals>
                    </execution>
                </executions>
                <configuration>
                    <descriptorRefs>
                        <descriptorRef>jar-with-dependencies</descriptorRef>
                    </descriptorRefs>
                </configuration>
            </plugin>
            ...
        </plugins>
    </build>
</project>

Configuring IAM Roles for AWS

IAM roles are used to make secure requests from your clients. You can provide the name of your IAM role that you created previously on your AWS console to the jclouds configuration. IAM roles only work in AWS and when a role name is provided, the other credentials' properties should be empty.

 ...
  <properties>
    <property name="hazelcast.discovery.enabled">true</property>
  </properties>
   ....
 <join>
    <multicast enabled="false">
    </multicast>
    <tcp-ip enabled="false">
    </tcp-ip>
    <discovery-providers>
        <discovery-provider class="com.hazelcast.jclouds.JCloudsDiscoveryStrategy" enabled="true">
          <properties>
                  <property name="provider">aws-ec2</property>
                  <property name="role-name">i-am-role-for-member</property>
                  <property name="credential">AWS_CREDENTIAL</property>
          </properties>
        </discovery-provider>
    </discovery-providers>
</join>
...

Note that, for AWS EC2, you can also configure your cluster using the element as described in Discovering Members within EC2 Cloud.

Discovering Members on Different Regions

You can define multiple regions in your jclouds configuration. By default, Hazelcast Discovery SPI uses private IP addresses for member connections. If you want the members to find each other over a different region, you must set the system property hazelcast.discovery.public.ip.enabled to true. In this way, the members on different regions can connect to each other by using public IPs.

 ...
  <properties>
    <property name="hazelcast.discovery.enabled">true</property>
    <property name="hazelcast.discovery.public.ip.enabled">true</property>
  </properties>
   ....
 <join>
    <multicast enabled="false">
    </multicast>
    <tcp-ip enabled="false">
    </tcp-ip>
    <discovery-providers>
        <discovery-provider class="com.hazelcast.jclouds.JCloudsDiscoveryStrategy" enabled="true">
          <properties>
           <property name="provider">aws-ec2</property>
           <property name="identity">AWS_IDENTITY</property>
           <property name="credential">AWS_CREDENTIAL</property>
          </properties>
        </discovery-provider>
    </discovery-providers>
</join>
...

Using jclouds With ZONE_AWARE Partition Group

When you use jclouds as discovery provider, you can configure Hazelcast Partition Group configuration with jclouds. For more information please read: http://docs.hazelcast.org/docs/3.7/manual/html-single/index.html#partition-group-configuration

...
<partition-group enabled="true" group-type="ZONE_AWARE" />
...