Hazelcast Discovery Auto Detection
Tags: hazelcast, kubernetes, aws, azure
Published: 2021-01-08 15:56:27

![Alt Text](https://dev-to-uploads.s3.amazonaws.com/i/gzpxg52776zjrck0mpcp.png)

<p>Hazelcast was always well integrated with all cloud environments thanks to discovery plugins like <a href="https://github.com/hazelcast/hazelcast-aws">Hazelcast AWS Plugin</a> or <a href="https://github.com/hazelcast/hazelcast-kubernetes">Hazelcast Kubernetes Plugin</a>. 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&#8217;s more, we made it all extensible, so if you develop any discovery plugin by yourself, you can make your plugin auto-discoverable.</p>
<p>In this blog post, I walk through common cloud environments and explain how auto-detection works in each of them. You can also check <a href="https://docs.hazelcast.org/docs/latest/manual/html-single/#discovering-members-auto-detection">Hazelcast Reference Manual: Discovering Members by Auto Detection</a> to find more about the requirements for the discovery auto-detection.</p>
<h2>AWS Auto Detection</h2>
<p>To start Hazelcast on AWS EC2 Instances, you have to perform the following steps for each instance:</p>
<ul>
<li>Configure <span style="text-decoration: underline;">Security Groups</span> to open port <span style="text-decoration: underline;">5701</span> (the default Hazelcast port)</li>
<li>Configure <span style="text-decoration: underline;">IAM Role</span> assigned to EC2 Instance to <span style="text-decoration: underline;">allow</span> the <code>ec2:DescribeInstances</code> permission</li>
<li><a href="https://github.com/hazelcast/hazelcast-command-line#installation">Install Hazelcast CLI</a></li>
</ul>
<p>Now, execute the following command on each of the EC2 Instances.</p>

```
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
]
```

<p>That&#8217;s it! Hazelcast automatically detected that it is running on an EC2 Instance and used the <a href="https://github.com/hazelcast/hazelcast-aws">AWS Discovery Plugin</a> with default parameters (finding all Hazelcast members within the same region). For a more detailed description you can also check <a href="https://guides.hazelcast.org/ec2-cluster/">Hazelcast Guides: Deploy Hazelcast Cluster on AWS EC2</a>.</p>
<h2>Azure Auto Detection</h2>
<p>To start Hazelcast on Azure Virtual Machines, you have to perform the following steps for each VM:</p>
<ul>
<li>Attach <a href="https://docs.microsoft.com/en-us/azure/active-directory/managed-identities-azure-resources/overview">Azure managed identity</a> with the <code>READ</code> role</li>
<li><a href="https://github.com/hazelcast/hazelcast-command-line#installation">Install Hazelcast CLI</a></li>
</ul>
<p>Then, execute the following command on each of your Virtual Machines.</p>

```
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
]
```

<p>Hazelcast members automatically discovered themselves using the <a href="https://github.com/hazelcast/hazelcast-azure">Azure Discovery plugin</a> with default parameters.</p>
<h2>GCP Auto Detection</h2>
<p>To start Hazelcast on GCP VM Instances, you have to perform the following steps for each instance:</p>
<ul>
<li>Configure access to Cloud APIs (at minimum Read Only to Compute Engine API)</li>
<li><a href="https://github.com/hazelcast/hazelcast-command-line#installation">Install Hazelcast CLI</a></li>
</ul>
<p>Then, execute the following command on each of your VM Instances.</p>

```
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
]
```

<p>Hazelcast members automatically discovered themselves using the GCP Discovery plugin with default parameters.</p>
<h2>Kubernetes Auto Detection</h2>
<p>To start Hazelcast on Kubernetes, you need to apply the needed RBAC. Then, you can start a few Hazelcast instances and they&#8217;ll form one Hazelcast cluster.</p>

```
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
```

<p>That&#8217;s it, Hazelcast instances automatically discovered each other using the <a href="https://github.com/hazelcast/hazelcast-kubernetes">Kubernetes Discovery plugin</a> with default parameters. You can check that the Hazelcast cluster was formed.</p>

```
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
]
```

<h2>Auto Detection Under the Hood</h2>
<p>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:</p>
<ol>
<li>Content of the file <code>/sys/hypervisor/uuid</code> starts with &#8220;ec2&#8221;</li>
<li>EC2 Instance Identity Endpoint <code>http://169.254.169.254/latest/dynamic/instance-identity/</code> is reachable</li>
<li>IAM Role is attached to EC2 Instance</li>
</ol>
<p>One other example is Kubernetes, for which we check the following 2 conditions:</p>
<ol>
<li>Kubernetes-specific token file <code>/var/run/secrets/kubernetes.io/serviceaccount/token</code> exists</li>
<li>Kubernetes API is reachable via the default DNS <code>kubernetes.default.svc</code></li>
</ol>
<p>If you&#8217;re interested in details on how we detect each environment, here are the related source code references: <a href="https://github.com/hazelcast/hazelcast-aws/blob/v3.3/src/main/java/com/hazelcast/aws/AwsDiscoveryStrategyFactory.java#L78">AWS</a>, <a href="https://github.com/hazelcast/hazelcast-azure/blob/v2.1/src/main/java/com/hazelcast/azure/AzureDiscoveryStrategyFactory.java#L76">Azure</a>, <a href="https://github.com/hazelcast/hazelcast-gcp/blob/v2.1/src/main/java/com/hazelcast/gcp/GcpDiscoveryStrategyFactory.java#L77">GCP</a>, and <a href="https://github.com/hazelcast/hazelcast-kubernetes/blob/v2.2/src/main/java/com/hazelcast/kubernetes/HazelcastKubernetesDiscoveryStrategyFactory.java#L85">Kubernetes</a>.</p>
<h2>Auto Detection for Your Own Plugin</h2>
<p>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 <code>DiscoveryStrategyFactory.isAutoDetectionApplicable()</code>.</p>


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

<p>That&#8217;s it. Hazelcast can automatically detect the runtime environment for which your plugin is designed.</p>
<h2>Summary</h2>
<p>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!</p>