JGroups Discovery Examples

Table of Contents

• Building
• Configuration Properties
• Prerequisites
• KUBE_PING
  • Running on OpenShift Local
  • Debugging
• DNS_PING
  • Running on OpenShift Local
  • Debugging
• Reporting Issues

This project demonstrates how JGroups cluster members discover each other using different discovery protocols.

JGroups is a toolkit for reliable messaging and cluster communication. Before members can exchange messages they must form a cluster, which requires each member to locate the others — a process called discovery.

Two cloud-specific discovery protocols are demonstrated:

• DNS_PING (recommended) — performs a DNS A-record lookup against a headless Kubernetes Service, which returns one IP address per matching pod. Requires no API server access, only a headless service.

• KUBE_PING — queries the Kubernetes API for pods matching a label selector in the same namespace. Requires a ServiceAccount with permission to list pods, but needs no additional network infrastructure.

Each example runs a small application that joins a JGroups cluster and broadcasts a hello message every 5 seconds. View changes (members joining or leaving) are logged, making it easy to observe discovery and cluster formation in action.

Building

Project requires JDK 25 to build.

./mvnw clean install

This builds the following images:

• jgroups/jgroups-discovery-examples-dns-ping — TCP stack with DNS_PING discovery

• jgroups/jgroups-discovery-examples-kube-ping — TCP stack with KUBE_PING discovery

Configuration Properties

The following system properties control the application behaviour:

Property	Default	Description
jgroups.config	/dns_ping.xml	Classpath path to the JGroups stack configuration file.
jgroups.cluster_name	jgroups-discovery-examples	Name of the JGroups cluster to join.

Prerequisites

These examples target OpenShift Local (CRC). Installing CRC guide.

1. Start OpenShift Local:

   crc start

2. Configure the shell and log in:

   eval $(crc oc-env)
   oc login -u developer -p developer https://api.crc.testing:6443

3. Create a project (replace jgroups-discovery-examples with your preferred namespace throughout):

   oc new-project jgroups-discovery-examples

4. Build and publish the images to Quay.io:

   ./mvnw clean install
   
   podman login quay.io
   
   podman tag jgroups/jgroups-discovery-examples-dns-ping:0.0.1.Final-SNAPSHOT quay.io/rhusar/jgroups-discovery-examples-dns-ping:latest
   podman push quay.io/rhusar/jgroups-discovery-examples-dns-ping:latest
   
   podman tag jgroups/jgroups-discovery-examples-kube-ping:0.0.1.Final-SNAPSHOT quay.io/rhusar/jgroups-discovery-examples-kube-ping:latest
   podman push quay.io/rhusar/jgroups-discovery-examples-kube-ping:latest

   Note	Quay.io repositories are private by default when first created. After pushing, make each repository public via Repository Settings → Repository Visibility → Public so OpenShift can pull the images without a pull secret.

KUBE_PING

KUBE_PING discovers cluster members by querying the Kubernetes API for pods in the namespace matching a label selector. A ServiceAccount with a Role granting get/list on pods is required.

Running on OpenShift Local

1. Apply the resources:

   oc apply -f KUBE_PING/ServiceAccount.yaml
   oc apply -f KUBE_PING/Role.yaml
   oc apply -f KUBE_PING/RoleBinding.yaml
   oc apply -f KUBE_PING/Deployment.yaml

2. Verify the pod is running and check logs:

   oc get pods
   oc logs -f deployment/jgroups-discovery-examples-kube-ping

3. Scale up to see cluster formation:

   oc scale deployment jgroups-discovery-examples-kube-ping --replicas=3
   oc logs -f deployment/jgroups-discovery-examples-kube-ping

4. Clean up:

   oc delete -f KUBE_PING/Deployment.yaml
   oc delete -f KUBE_PING/RoleBinding.yaml
   oc delete -f KUBE_PING/Role.yaml
   oc delete -f KUBE_PING/ServiceAccount.yaml

Debugging

• Verify the service account can list pods:

  oc auth can-i list pods --as=system:serviceaccount:jgroups-discovery-examples:jgroups-discovery-examples-kube-ping

DNS_PING

DNS_PING discovers cluster members by performing a DNS query against a headless Kubernetes service, which returns an A record per pod. No API server access is required.

Running on OpenShift Local

1. Apply the resources:

   oc apply -f DNS_PING/Service.yaml
   oc apply -f DNS_PING/Deployment.yaml

2. Verify the pod is running and check logs:

   oc get pods
   oc logs -f deployment/jgroups-discovery-examples-dns-ping

3. Scale up to see cluster formation:

   oc scale deployment jgroups-discovery-examples-dns-ping --replicas=3
   oc logs -f deployment/jgroups-discovery-examples-dns-ping

   Each new pod should trigger a view change logged across all members.

4. Clean up:

   oc delete -f DNS_PING/Deployment.yaml
   oc delete -f DNS_PING/Service.yaml

Debugging

• Verify DNS resolves the headless service correctly from inside the cluster:

  oc run dnstest --image=registry.access.redhat.com/ubi9/ubi-minimal --restart=Never --rm -it -- \
    nslookup jgroups-discovery-examples-dns-ping.jgroups-discovery-examples.svc.cluster.local

Reporting Issues

https://github.com/rhusar/jgroups-discovery-examples/issues