JGroups AWS – S3_PING

Table of Contents

• Maven Coordinates
• Protocol Configuration
  • Configurations Properties
  • Example Stack
• Testing
• Reporting Issues
• Support Matrix

Projects JGroups AWS provides an implementation of S3_PING discovery protocol using AWS S3 buckets as cluster information store. It is based on the original code written by Tobias Sarnowski at Zalando. ^{[1] [2]}

It uses the official AWS SDK ^[3] and does not implement the HTTP protocol on its own. The benefit is a more stable connection as well as usage of IAM server profiles and AWS standardized credential distribution.

Maven Coordinates

<dependency>
    <groupId>org.jgroups.aws</groupId>
    <artifactId>jgroups-aws</artifactId>
    <version>3.0.0.Final</version>
</dependency>

Protocol Configuration

This library implements a JGroups discovery protocol which replaces protocols like MPING or TCPPING.

<aws.S3_PING region_name="us-east-1a"
             bucket_name="jgroups-s3-test"/>

The aws.S3_PING automatically registers itself to JGroups with the magic number 789. You can overwrite this by setting the system property s3ping.magic_number to different number, e.g. -Ds3ping.magic_number=123.

Configurations Properties

Attribute Name System Property	Default	Description
region_name System property: jgroups.aws.s3.region_name	required	The S3 region to use.
bucket_name System property: jgroups.aws.s3.bucket_name	required	The S3 bucket to use.
bucket_prefix System property: jgroups.aws.s3.bucket_prefix		The S3 bucket prefix to use (optional e.g. 'jgroups/').
check_if_bucket_exists System property: jgroups.aws.s3.check_if_bucket_exists	true	Checks if the bucket exists in S3 and creates a new one if missing
endpoint System property: jgroups.aws.s3.endpoint		The S3 endpoint to use (optional).
path_style_access_enabled System property: jgroups.aws.s3.path_style_access_enabled	false	The S3 path-style enable (optional).
kms_key_id System property: jgroups.aws.s3.kms_key_id		Use kms encryption with s3 with the given kms key (optionally - enables KMS Server side encryption (SSE-KMS) using the given kms key)
acl_grant_bucket_owner_full_control System property: jgroups.aws.s3.acl_grant_bucket_owner_full_control	false	Flag indicating whether or not to grant the bucket owner full control over the bucket on each update. This is useful in multi-region deployments where each region exists in its own AWS account.

Note	System properties are supported since JGroups AWS release version 3.0.1.Final. To use properties in the previous version, the property must be explicitly defined in the configuration.

Example Stack

<!--
Based on tcp.xml but with new aws.S3_PING.
-->
<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xmlns="urn:org:jgroups"
        xsi:schemaLocation="urn:org:jgroups http://www.jgroups.org/schema/jgroups.xsd">
    <TCP bind_port="7800"
         recv_buf_size="${tcp.recv_buf_size:5M}"
         send_buf_size="${tcp.send_buf_size:5M}"
         max_bundle_size="64K"
         thread_pool.enabled="true"
         thread_pool.min_threads="2"
         thread_pool.max_threads="8"
         thread_pool.keep_alive_time="5000"/>

    <aws.S3_PING region_name="eu-west-1"
                 bucket_name="jgroups-s3-test"
                 bucket_prefix="jgroups"/>

    <MERGE3 min_interval="10000"
            max_interval="30000"/>

    <FD_SOCK/>
    <FD_ALL timeout="30000" interval="5000"/>
    <VERIFY_SUSPECT timeout="1500"/>
    <pbcast.NAKACK2 use_mcast_xmit="false"
                    discard_delivered_msgs="true"/>

    <UNICAST3/>

    <pbcast.STABLE stability_delay="1000" desired_avg_gossip="50000"
                   max_bytes="4M"/>
    <pbcast.GMS print_local_addr="true" join_timeout="2000"
                view_bundling="true"/>
    <MFC max_credits="2M"
         min_threshold="0.4"/>
    <FRAG2 frag_size="60K"/>
</config>

Testing

Running the automated tests requires having AWS credentials setup with appropriate permissions along with setting the region name and a bucket name.

declare -x AWS_ACCESS_KEY_ID="qF7ujVAaYUp3Tx7m"
declare -x AWS_SECRET_ACCESS_KEY="WzbG3R2KGtx5rsHQUx2PKQPS2f6WzMtf"
declare -x S3_PING_REGION_NAME="eu-central-1"
declare -x S3_PING_BUCKET_NAME="jgroups"
mvn verify

If any of the required properties are not specified tests will be skipped (uses org.junit.Assume).

In case credentials are not provided and running on Linux, tests will be run against mock containerized S3 instance. These require a functioning podman or Docker environment.

Reporting Issues

Project JGroups AWS uses GitHub Issues for tracking:

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

Support Matrix

Version (branch)	JGroups version	AWS SDK
main	5.2.x - 5.3.x	2.x
2.x	5.2.x	1.x
1.x	4.2.x	1.x

---

1. https://libraries.io/github/zalando/jgroups-native-s3-ping

2. https://github.com/jwegne/jgroups-native-s3-ping

3. http://docs.aws.amazon.com/AmazonS3/latest/dev/UsingTheMPDotJavaAPI.html