JGroups Azure

Table of Contents

• Configuration
  • Properties
  • WildFly
  • Directly in JGroups
• Building
• Testing
  • Using DefaultAzureCredential
  • Using access key
  • Using connection string
  • Azurite (emulated)
• Reporting Issues
• Support Matrix
• License

Implementation of Azure ping protocol using Azure Storage blobs for JGroups project using official Microsoft Azure Java SDK.

See the design document for architecture and implementation details.

Configuration

Properties

Attribute Name Environment variable	Default	Description
container Environment variable: JGROUPS_AZURE_CONTAINER	required	Container to store ping information in. Must be a valid DNS name as it becomes part of the Azure blob storage URL.
storage_account_name Environment variable: JGROUPS_AZURE_STORAGE_ACCOUNT_NAME	required (unless connection_string is set)	The name of the storage account.
storage_access_key Environment variable: JGROUPS_AZURE_STORAGE_ACCESS_KEY		The secret account access key. If not specified, DefaultAzureCredential is used instead.
use_https Environment variable: JGROUPS_AZURE_USE_HTTPS	true	Whether or not to use HTTPS to connect to Azure.
endpoint_suffix Environment variable: JGROUPS_AZURE_ENDPOINT_SUFFIX	core.windows.net	The endpointSuffix to use.
blob_storage_uri Environment variable: JGROUPS_AZURE_BLOB_STORAGE_URI		The full blob service endpoint URI. When set, overrides use_https and endpoint_suffix.
connection_string Environment variable: JGROUPS_AZURE_CONNECTION_STRING		Azure Storage connection string. When set, overrides storage_account_name, storage_access_key, use_https, endpoint_suffix, and blob_storage_uri.

All properties are supplied via environment variables or system properties. At minimum, storage_account_name and container are required:

export JGROUPS_AZURE_STORAGE_ACCOUNT_NAME=<ACCOUNT_NAME>
export JGROUPS_AZURE_CONTAINER=jgroups-ping

Authentication is resolved automatically using DefaultAzureCredential (e.g. managed identity or az login). Alternatively, an access key or connection string can be provided — see the Properties table for the full list of options.

WildFly

Using a preconfigured profile

WildFly already bundles the required modules in its default distribution. Users can directly use server profile located at wildfly-<version>/docs/examples/configs/standalone-azure-ha.xml.

Upgrading an existing profile

To update an existing profile to use TCP stack by default and azure.AZURE_PING protocol via CLI, start ./bin/jboss-cli.sh and run the following batch:

batch
/subsystem=jgroups/channel=ee:write-attribute(name=stack, value=tcp)
/subsystem=jgroups/stack=tcp/protocol=MPING:remove
/subsystem=jgroups/stack=tcp/protocol=azure.AZURE_PING:add(add-index=1)
run-batch
reload

Note	The add-index might require adjusting so that the original discovery protocol is replaced. The example assumes RED protocol is defined as the first protocol and discovery is defined below it.

Alternatively, users can replace the discovery protocol in their existing server profiles with the following configuration:

<protocol type="azure.AZURE_PING"/>

Directly in JGroups

You can bring in all dependencies via Maven:

<dependency>
    <groupId>org.jgroups.azure</groupId>
    <artifactId>jgroups-azure</artifactId>
    <version>${version.org.jgroups.azure}</version>
</dependency>

Then add or replace an existing discovery protocol in the stack:

<azure.AZURE_PING/>

Building

Use Maven to build:

mvn clean install

Or use Maven wrapper for convenience:

./mvnw clean install

Testing

To run tests against genuine Azure, a storage account name must be provided. If not provided, tests that require it are skipped (using org.junit.Assume).

Using DefaultAzureCredential

When no access key or connection string is provided, DefaultAzureCredential is used. This requires logging in with Azure CLI and having the Storage Blob Data Contributor role assigned:

az login

az group list --output table
az storage account list --output table

az role assignment create \
  --assignee "$(az ad signed-in-user show --query id -o tsv)" \
  --role "Storage Blob Data Contributor" \
  --scope "/subscriptions/<SUBSCRIPTION_ID>/resourceGroups/<RESOURCE_GROUP>/providers/Microsoft.Storage/storageAccounts/<ACCOUNT_NAME>"

Note	Role assignment propagation can take several minutes after initial assignment.

Then run the tests:

mvn test -DJGROUPS_AZURE_STORAGE_ACCOUNT_NAME=<ACCOUNT_NAME>

Using access key

mvn test -DJGROUPS_AZURE_STORAGE_ACCOUNT_NAME=<ACCOUNT_NAME> -DJGROUPS_AZURE_STORAGE_ACCESS_KEY=<ACCESS_KEY>

Using connection string

mvn test -DJGROUPS_AZURE_CONNECTION_STRING="DefaultEndpointsProtocol=https;AccountName=...;AccountKey=...;EndpointSuffix=core.windows.net"

Azurite (emulated)

There are also variants of the tests that run against a mock Blob service running in a container. To run those tests, a valid podman/Docker environment is required.

Note	Depending on your testing environment, you may need to append -Djava.net.preferIPv4Stack=true if you are having IPv6 configuration issues.

Reporting Issues

Project JGroups Azure uses GitHub Issues for tracking:

https://github.com/jgroups-extras/jgroups-azure/issues

Support Matrix

Version (branch)	JGroups version	Azure Storage version	Java version
3.x	5.5.x	12.x	17
2.x	5.1.x - 5.4.x	8.6.6	11
1.3.x	4.2.x	8.6.6	8
1.2.x	4.0.x	6.1.0	8
1.1.x	3.6.13.Final	5.0.0	8
1.0.x	3.6.7.Final	4.0.0	7
0.9.x	3.2.16.Final	5.0.0	6

License

Copyright 2026 Red Hat Inc.

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.