Hazelcast Discovery Auto Detection

Hazelcast was always well integrated with all cloud environments thanks to discovery plugins like Hazelcast AWS Plugin or Hazelcast Kubernetes Plugin. With the IMDG 4.1 release, however, we went one step further in making Hazelcast as user friendly as possible. Hazelcast can now automatically discover the environment it is running in and find a suitable discovery plugin. What’s more, we made it all extensible, so if you develop any discovery plugin by yourself, you can make your plugin auto-discoverable.

In this blog post, I walk through common cloud environments and explain how auto-detection works in each of them. You can also check Hazelcast Reference Manual: Discovering Members by Auto Detection to find more about the requirements for the discovery auto-detection.

AWS Auto Detection

To start Hazelcast on AWS EC2 Instances, you have to perform the following steps for each instance:

• Configure Security Groups to open port 5701 (the default Hazelcast port)
• Configure IAM Role assigned to EC2 Instance to allow the ec2:DescribeInstances permission
• Install Hazelcast CLI

Now, execute the following command on each of the EC2 Instances.

hz start
...
Auto-detection selected discovery strategy: class com.hazelcast.aws.AwsDiscoveryStrategyFactory
...
Members {size:2, ver:2} [
        Member [172.31.14.177]:5701 - 383a7f9e-e18c-4646-a998-d12810a677b8
        Member [172.31.3.163]:5701 - 956cf0cb-24d8-4604-9ad3-1a4785d00a3b this
]

That’s it! Hazelcast automatically detected that it is running on an EC2 Instance and used the AWS Discovery Plugin with default parameters (finding all Hazelcast members within the same region). For a more detailed description you can also check Hazelcast Guides: Deploy Hazelcast Cluster on AWS EC2.

Azure Auto Detection

To start Hazelcast on Azure Virtual Machines, you have to perform the following steps for each VM:

• Attach Azure managed identity with the READ role
• Install Hazelcast CLI

Then, execute the following command on each of your Virtual Machines.

hz start
...
Auto-detection selected discovery strategy: class com.hazelcast.azure.AzureDiscoveryStrategyFactory
...
Members {size:2, ver:2} [
        Member [10.11.12.1]:5701 - 3bc13eba-5d00-44cb-8ace-3e6c41bd8ead
        Member [10.11.9.5]:5701 - 6c748770-87d8-4fdf-84b1-da036f7a64bd this
]

Hazelcast members automatically discovered themselves using the Azure Discovery plugin with default parameters.

GCP Auto Detection

To start Hazelcast on GCP VM Instances, you have to perform the following steps for each instance:

• Configure access to Cloud APIs (at minimum Read Only to Compute Engine API)
• Install Hazelcast CLI

Then, execute the following command on each of your VM Instances.

hz start
...
Auto-detection selected discovery strategy: class com.hazelcast.gcp.GcpDiscoveryStrategyFactory
...
Members {size:2, ver:2} [
        Member [10.240.0.38]:5701 - 2aaf7b72-24d3-491c-b04f-3ca0f1aa920b this
        Member [10.240.0.40]:5701 - 222b96b5-9364-4adb-b750-711e99fc12fd
]

Hazelcast members automatically discovered themselves using the GCP Discovery plugin with default parameters.

Kubernetes Auto Detection

To start Hazelcast on Kubernetes, you need to apply the needed RBAC. Then, you can start a few Hazelcast instances and they’ll form one Hazelcast cluster.

kubectl apply -f https://raw.githubusercontent.com/hazelcast/hazelcast-kubernetes/master/rbac.yaml
kubectl run hazelcast-1 --image=hazelcast/hazelcast
kubectl run hazelcast-2 --image=hazelcast/hazelcast

That’s it, Hazelcast instances automatically discovered each other using the Kubernetes Discovery plugin with default parameters. You can check that the Hazelcast cluster was formed.

kubectl logs hazelcast-1
...
Auto-detection selected discovery strategy: class com.hazelcast.kubernetes.HazelcastKubernetesDiscoveryStrategy
...
Members {size:2, ver:2} [
        Member [10.124.1.7]:5701 - 9ed26858-8cd8-438c-a737-35308f68946e this
        Member [10.124.2.5]:5701 - d24d06f8-3ff8-4484-bdb4-759b2d459270
]

Auto Detection Under the Hood

Detecting each cloud environment requires checking some environment-specific properties. For example, to check whether Hazelcast runs on AWS EC2 Instance, we check 3 conditions and they all need to be satisfied:

1. Content of the file /sys/hypervisor/uuid starts with “ec2”
2. EC2 Instance Identity Endpoint http://169.254.169.254/latest/dynamic/instance-identity/ is reachable
3. IAM Role is attached to EC2 Instance

One other example is Kubernetes, for which we check the following 2 conditions:

1. Kubernetes-specific token file /var/run/secrets/kubernetes.io/serviceaccount/token exists
2. Kubernetes API is reachable via the default DNS kubernetes.default.svc

If you’re interested in details on how we detect each environment, here are the related source code references: AWS, Azure, GCP, and Kubernetes.

Auto Detection for Your Own Plugin

You can extend your own Hazelcast discovery plugin with the auto-detection functionality. Then, whenever your plugin is in the classpath, your logic checks the runtime environment and enables the plugin if needed. All you need to write is an implementation of the method DiscoveryStrategyFactory.isAutoDetectionApplicable().

public class YourDiscoveryStrategyFactory implements DiscoveryStrategyFactory {
    @Override
    public boolean isAutoDetectionApplicable() {
        // your logic to check the runtime environment
    }
}

That’s it. Hazelcast can automatically detect the runtime environment for which your plugin is designed.

Summary

Hazelcast Auto Detection feature allows you to run Hazelcast with zero configuration on your cloud environment of choice. While in the real production environment you would probably still want to provide the full Hazelcast configuration file, Auto Detection is a great way to get started!