{"id":46332715,"url":"https://github.com/jgroups-extras/jgroups-aws","last_synced_at":"2026-03-04T18:05:03.172Z","repository":{"id":37432222,"uuid":"81552197","full_name":"jgroups-extras/jgroups-aws","owner":"jgroups-extras","description":"Discovery protocol for JGroups using AWS S3 buckets as cluster information store","archived":false,"fork":false,"pushed_at":"2026-02-27T17:23:54.000Z","size":815,"stargazers_count":16,"open_issues_count":18,"forks_count":12,"subscribers_count":6,"default_branch":"main","last_synced_at":"2026-02-27T20:22:30.849Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"http://jgroups.org","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jgroups-extras.png","metadata":{"files":{"readme":"README.adoc","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":"dco.txt","cla":null}},"created_at":"2017-02-10T10:00:46.000Z","updated_at":"2026-02-27T15:12:23.000Z","dependencies_parsed_at":"2023-10-14T20:17:38.164Z","dependency_job_id":"09007492-b458-411c-a6fc-747d23e1927d","html_url":"https://github.com/jgroups-extras/jgroups-aws","commit_stats":null,"previous_names":["jgroups-extras/native-s3-ping"],"tags_count":13,"template":false,"template_full_name":null,"purl":"pkg:github/jgroups-extras/jgroups-aws","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jgroups-extras%2Fjgroups-aws","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jgroups-extras%2Fjgroups-aws/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jgroups-extras%2Fjgroups-aws/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jgroups-extras%2Fjgroups-aws/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jgroups-extras","download_url":"https://codeload.github.com/jgroups-extras/jgroups-aws/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jgroups-extras%2Fjgroups-aws/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30088349,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-04T15:40:14.053Z","status":"ssl_error","status_checked_at":"2026-03-04T15:40:13.655Z","response_time":59,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-03-04T18:05:02.621Z","updated_at":"2026-03-04T18:05:03.155Z","avatar_url":"https://github.com/jgroups-extras.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"= JGroups AWS – `aws.S3_PING` image:https://github.com/jgroups-extras/jgroups-aws/workflows/CI/badge.svg[CI,link=https://github.com/jgroups-extras/jgroups-aws/actions] image:https://img.shields.io/maven-central/v/org.jgroups.aws/jgroups-aws?logo=apache-maven[Version,link=https://central.sonatype.com/artifact/org.jgroups.aws/jgroups-aws]\n\n:toc:\n\nProjects JGroups AWS provides an implementation of `aws.S3_PING` discovery protocol using AWS S3 buckets as cluster information store.\nIt is based on the https://github.com/jwegne/jgroups-native-s3-ping[original code] written by Tobias Sarnowski at Zalando.\n\nIt uses the https://docs.aws.amazon.com/s3/[official AWS SDK] and does not implement the HTTP protocol on its own.\nThe benefit is a more stable connection as well as usage of IAM server profiles and AWS standardized credential distribution.\n\n== Maven Coordinates\n\n[source,xml]\n----\n\u003cdependency\u003e\n    \u003cgroupId\u003eorg.jgroups.aws\u003c/groupId\u003e\n    \u003cartifactId\u003ejgroups-aws\u003c/artifactId\u003e\n    \u003cversion\u003e4.0.0.Final\u003c/version\u003e\n\u003c/dependency\u003e\n----\n\n== Protocol Configuration\n\nThis library implements a JGroups discovery protocol which replaces protocols like `MPING` or `TCPPING`.\n\n[source,xml]\n----\n\u003caws.S3_PING region_name=\"us-east-1a\"\n             bucket_name=\"jgroups-s3-test\"/\u003e\n----\n\n=== Configurations Properties\n\n// n.b. The order of the following list here is by relevance and related/coupled properties are also grouped.\n\n[align=\"left\",cols=\"3,1,10\",options=\"header\"]\n|===\n| Attribute Name +\nSystem Property +\nEnvironment variable\n| Default\n| Description\n\n| `region_name` +\nSystem property: `jgroups.aws.s3.region_name` +\nEnvironment variable: `JGROUPS_AWS_S3_REGION_NAME`\n| *required*\n| The AWS region with which to communicate.\n\n| `bucket_name` +\nSystem property: `jgroups.aws.s3.bucket_name` +\nEnvironment variable: `JGROUPS_AWS_S3_BUCKET_NAME`\n| *required*\n| The AWS S3 bucket name to use.\n\n| `bucket_prefix` +\nSystem property: `jgroups.aws.s3.bucket_prefix` +\nEnvironment variable: `JGROUPS_AWS_S3_BUCKET_PREFIX`\n|\n| The prefix to prefix all AWS S3 paths with, e.g. `jgroups/`.\n\n| `check_if_bucket_exists` +\nSystem property: `jgroups.aws.s3.check_if_bucket_exists` +\nEnvironment variable: `JGROUPS_AWS_S3_CHECK_IF_BUCKET_EXISTS`\n| `true`\n| Whether to check if the bucket exists in AWS S3 and create a new one if it does not exist yet.\n\n| `endpoint` +\nSystem property: `jgroups.aws.s3.endpoint` +\nEnvironment variable: `JGROUPS_AWS_S3_ENDPOINT`\n|\n| The AWS endpoint with which to communicate.\n\n| `path_style_access_enabled` +\nSystem property: `jgroups.aws.s3.path_style_access_enabled` +\nEnvironment variable: `JGROUPS_AWS_S3_PATH_STYLE_ACCESS_ENABLED`\n| `false`\n| Forces the AWS S3 client to use path-style addressing for buckets.\n\n| `kms_key_id` +\nSystem property: `jgroups.aws.s3.kms_key_id` +\nEnvironment variable: `JGROUPS_AWS_S3_KMS_KEY_ID`\n|\n| KMS key to use for enabling KMS server-side encryption (SSE-KMS) for AWS S3.\n\n| `acl_grant_bucket_owner_full_control` +\nSystem property: `jgroups.aws.s3.acl_grant_bucket_owner_full_control` +\nEnvironment variable: `JGROUPS_AWS_S3_ACL_GRANT_BUCKET_OWNER_FULL_CONTROL`\n| `false`\n| Whether 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.\n\n| System property: `s3ping.magic_number`\n| `790`\n| The protocol automatically registers itself to JGroups with the magic number `790`. This can be overwritten by setting the system property to different number.\n\n|===\n\nNOTE: This protocol implementation extends `FILE_PING` and inherits its configuration, however, since version 4.0.1.Final, the `register_shutdown_hook` is set to `false` by default.\n\nNOTE: System properties are supported since JGroups AWS release version 3.0.1.Final.\n      To use properties in the previous version, the property must be explicitly defined in the configuration, e.g. `\u003caws.S3_PING region_name=\"eu-central-1\" ... /\u003e\"`.\n\nNOTE: Be mindful of how JGroups resolves values at runtime when using system properties or environment variables.\n      For example, consider the configuration `\u003caws.S3_PING bucket_name=\"${my.bucket.property:myBucketDefaultValue}\" ... /\u003e`.\n      JGroups will first attempt to resolve the `my.bucket.property` property.\n      If it is not defined, the default value `myBucketDefaultValue` will be used.\n      If no default value is specified, JGroups will then attempt to resolve `jgroups.aws.s3.bucket_name` system property,\n      followed by the environment variable `JGROUPS_AWS_S3_BUCKET_NAME`.\n\n=== Example Stack\n\n[source,xml]\n----\n\u003c!--\nBased on default tcp.xml with discovery replaced with aws.S3_PING.\n--\u003e\n\u003cconfig xmlns:xsi=\"http://www.w3.org/2001/XMLSchema-instance\"\n        xmlns=\"urn:org:jgroups\"\n        xsi:schemaLocation=\"urn:org:jgroups http://www.jgroups.org/schema/jgroups-5.5.xsd\"\u003e\n    \u003cinclude file=\"${transport-config:tcp-default.xml}\"/\u003e\n    \u003caws.S3_PING/\u003e\n    \u003cMERGE3 min_interval=\"10s\"\n            max_interval=\"30s\"/\u003e\n    \u003cFD_SOCK2/\u003e\n    \u003cFD_ALL3 timeout=\"40s\"\n             interval=\"5s\"/\u003e\n    \u003cVERIFY_SUSPECT2 timeout=\"1.5s\"/\u003e\n    \u003cBARRIER/\u003e\n    \u003cpbcast.NAKACK2 use_mcast_xmit=\"false\"/\u003e\n    \u003cUNICAST3/\u003e\n    \u003cpbcast.STABLE desired_avg_gossip=\"50s\"\n                   max_bytes=\"4M\"/\u003e\n    \u003cpbcast.GMS print_local_addr=\"true\"\n                join_timeout=\"2s\"/\u003e\n    \u003cMFC max_credits=\"10M\"\n         min_threshold=\"0.4\"/\u003e\n    \u003cUFC max_credits=\"10M\"\n         min_threshold=\"0.4\"/\u003e\n    \u003cFRAG2 frag_size=\"60K\"/\u003e\n    \u003cpbcast.STATE_TRANSFER/\u003e\n\u003c/config\u003e\n----\n\n== Testing\n\nRunning the automated tests requires having AWS credentials setup with appropriate permissions\nalong with setting the region name and a bucket name.\n\n[source,shell]\n----\ndeclare -x AWS_ACCESS_KEY_ID=\"...\"\ndeclare -x AWS_SECRET_ACCESS_KEY=\"...\"\ndeclare -x JGROUPS_AWS_S3_REGION_NAME=\"eu-central-1\"\ndeclare -x JGROUPS_AWS_S3_BUCKET_NAME=\"jgroups\"\n./mvnw verify\n----\n\nIf the required AWS credentials are not specified, testing with AWS S3 will be skipped (uses `org.junit.jupiter.api.Assumptions`).\n\nIn case credentials are not provided and running on Linux, tests will be run against mock containerized S3 instance.\nThese require a functioning podman or Docker environment.\n\n== Reporting Issues\n\nProject JGroups AWS uses GitHub Issues for tracking:\n\nhttps://github.com/jgroups-extras/jgroups-aws/issues\n\n== Support Matrix\n\n|===\n|Version/Branch |JGroups Version |AWS SDK Version |Base JDK Version\n\n|`4.x`/`main` |`5.5.x`           |`2.x` |17\n|`3.1.x`      |`5.4.x`           |`2.x` |11\n|`3.0.x`      |`5.2.x` – `5.3.x` |`2.x` |11\n|`2.x`        |`5.2.x`           |`1.x` |11\n|`1.x`        |`4.2.x`           |`1.x` |8\n|===\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjgroups-extras%2Fjgroups-aws","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjgroups-extras%2Fjgroups-aws","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjgroups-extras%2Fjgroups-aws/lists"}