Hazelcast Discovery Plugin for Kubernetes

Table of Contents

• Hazelcast Discovery SPI
• Configuration Property Documentation
• Configuration
  • REST API Request
  • DNS Lookup

This Hazelcast Discovery Plugin provides the possibility to lookup IP addresses of other members by resolving those requests against a Kubernetes Service Discovery system.

This plugin supports two different options of resolving against the discovery registry.

• A request to the REST API

• DNS Lookup against a given DNS service name

Hazelcast Discovery SPI

Hazelcast, since 3.6, offers a, so called, Discovery SPI to integrate external discovery mechanisms into the system. For more information please rely on the official documentation, available here.

Configuration Property Documentation

The available configuration properties are documented inside the Javadoc of this plugin: Configuration Properties

Configuration

REST API Request

To configure the Kubernetes Service Discovery REST API, you first need to add the plugin to the applications classpath. If using maven, Gradle, sbt or similar tools, this is as easy as adding it to the build configuration.

<project>
  <!-- maven standards -->

  <dependencies>
    <!-- application dependencies -->

    <dependency>
      <groupId>com.hazelcast</groupId>
      <artifactId>hazelcast-kubernetes</artifactId>
      <version>${hazelcast-kubernetes-version}</version>
    </dependency>
  </dependencies>
</project>

This fragment will add the discovery plugin as well as necessary transitive dependencies into your application classpath. The second step is to configure the discovery plugin inside of your Hazelcast configuration. You have 3 options to configure the plugin:

1. Set a namespace, if no property is set the default namespace will be used:
   <property name="namespace">MY-KUBERNETES-NAMESPACE</property>
   If you don’t want to set the namespace in the XML config file, it is also possible to specify the namespace with the environment variables KUBERNETES_NAMESPACE or OPENSHIFT_BUILD_NAMESPACE.

2. Set a service name to scan all endpoints (pods) connected by a service (the query is combined with the namespace)
   <property name="service-name">MY-SERVICE-NAME</property>

3. Set a service label and value. If no endpoints can be found by a given service name, the endpoints are queried by the service label name and value (inside the defined namespace). Multiple services and group can be defined by labels.
   <property name="service-label-name">cluster01</property>
<property name="service-label-value">true</property>

<hazelcast>
  <properties>
    <!-- only necessary prior Hazelcast 3.8 -->
    <property name="hazelcast.discovery.enabled">true</property>
  </properties>

  <network>
    <join>
      <!-- deactivate normal discovery -->
      <multicast enabled="false"/>
      <tcp-ip enabled="false" />

      <!-- activate the Kubernetes plugin -->
      <discovery-strategies>
        <discovery-strategy enabled="true"
            class="com.hazelcast.kubernetes.HazelcastKubernetesDiscoveryStrategy">

          <properties>
            <!-- configure discovery service API lookup -->
            <property name="service-name">MY-SERVICE-NAME</property>
             <property name="service-label-name">cluster01</property>
              <property name="service-label-value">true</property>
            <property name="namespace">MY-KUBERNETES-NAMESPACE</property>
          </properties>
        </discovery-strategy>
      </discovery-strategies>
    </join>
  </network>
</hazelcast>

DNS Lookup

To configure the Kubernetes Hazelcast plugin to use DNS lookup, you first need to add the plugin to the applications classpath. If using maven, Gradle, sbt or similar tools, this is as easy as adding it to the build configuration.

<project>
  <!-- maven standards -->

  <dependencies>
    <!-- application dependencies -->

    <dependency>
      <groupId>com.hazelcast</groupId>
      <artifactId>hazelcast-kubernetes</artifactId>
      <version>${hazelcast-kubernetes-version}</version>
    </dependency>
  </dependencies>
</project>

This fragment will add the discovery plugin as well as necessary transitive dependencies into your application classpath. The second step is to configure the discovery plugin inside of your Hazelcast configuration.

The service-dns value here is defined as documented in the official Kubernetes DNS documentation.

<hazelcast>
  <properties>
    <!-- only necessary prior Hazelcast 3.8 -->
    <property name="hazelcast.discovery.enabled">true</property>
  </properties>

  <network>
    <join>
      <!-- deactivate normal discovery -->
      <multicast enabled="false"/>
      <tcp-ip enabled="false" />

      <!-- activate the Kubernetes plugin -->
      <discovery-strategies>
        <discovery-strategy enabled="true"
            class="com.hazelcast.kubernetes.HazelcastKubernetesDiscoveryStrategy">

          <properties>
            <!-- configure discovery service API lookup -->
            <property name="service-dns">MY-SERVICE-DNS-NAME</property>
            <property name="service-dns-timeout">10</property>
          </properties>
        </discovery-strategy>
      </discovery-strategies>
    </join>
  </network>
</hazelcast>