535cc9d521
* rdma: add the hipobj-rc-v2 control routes to the vgwrdma gateway Mount the three control routes (prepare, ready, cancel) on the S3 port behind the standard SigV4 middleware. The routes own authentication-adjacent policy the C server cannot see: the middleware wrapper yields to the handler on success, READY and CANCEL re-read the account through the IAM cache bypass so mid-flow deletions and credential rotations take effect immediately, and every object access re-authorizes against the decoded bucket and key. The READY handler implements the session ownership contract: the completion-reference finalizer installs only after the transfer claim succeeds, the PUT path hands the reference to the put view exactly at the borrow point, and the FINAL reply carries the stored object's metadata. Backend I/O runs under a context merged with the RC service context so shutdown unblocks in-flight handlers, with a bounded pool for the fresh IAM lookups. vgwrdma starts the session server alongside the gateway when an RDMA interface is configured, tears it down on exit, and shuts the IAM service down on any startup failure. embedgw learns the readonly flag for the object access checks the routes share. Signed-off-by: Jihyeon Gim <potatogim@potatogim.net> * rdma: add the missing stub handlers for non-Linux builds The non-Linux rcroutes stub exposed only Register while the vgwrdma gateway registers the prepare/ready/cancel handlers directly, so cross-compiling cmd/vgwrdma failed with undefined methods. Add the three stub handlers answering 501 Not Implemented and let Register reuse them, matching the Linux Handler API surface. * auth: drop the duplicated GetUserAccountFresh definition The rebase onto main (which already carries GetUserAccountFresh from the iam-cache-fresh change) kept both copies of the method, breaking the build with a redeclaration error. Remove the second copy so the method is defined once. * rdma: address the review findings on the control route wiring Drop the unused Handler.Register from both build variants: the gateway mounts the three control routes through s3api.WithRoute so the SigV4 verifier wrapper (rcAuth) runs in front of each handler, and nothing else calls Register. Clear iamOwned only when RunVersityGW returns nil. It shuts the IAM service down itself at the end of its shutdown sequence, but its early failure paths return before reaching that point, so the deferred shutdown must keep covering those errors. Remove the unused rcserver.SessionInfo parameter from sizeOf; the transferred byte count comes from the READY response alone. * rdma: keep transient IAM failures retryable in the fresh revalidation The fresh account revalidation turned every GetUserAccountFresh error into 403, which reports transient backend failures (LDAP timeouts, network errors) as a revoked account and leaves the client no room to retry. Only a confirmed missing account (auth.ErrNoSuchUser) means that; answer anything else with 503 so clients can retry the request. * rdma: make the IAM shutdown exactly-once and keep gateway errors visible The gateway and RunVersityGW share the IAM service, and which side shut it down could not be told from the return value: runtime failures return after RunVersityGW already shut the service down, while early setup failures return before any shutdown happens. The iamOwned flag therefore either shut the service down twice or leaked it depending on the error, and the error itself was dropped. Wrap the service so Shutdown runs exactly once no matter which side calls it, keep the deferred shutdown for every early failure path, and return the gateway error again. The wrapper re-exposes the optional interfaces (fresh account reads, signing keys, policy evaluation, fixed bucket ownership) so feature detection through the IAM service keeps working. * rdma: reuse the SigV4 account for RC control requests READY and CANCEL are independently authenticated SigV4 requests. Use the account resolved by the normal SigV4 path instead of bypassing the IAM cache a second time. This aligns RC revocation latency with other signed S3 requests and removes the extra backend IAM lookup, its concurrency cap, and the RC-specific IAM error mapping. The session owner check and the READY target and operation authorization are unchanged. * rdma: reword the READY reauthorization comment The comment implied a revocation inside the session window always takes effect at READY, but the account used here is the one SigV4 resolved, which may be a cached entry. State what the check does without claiming account-cache freshness. * rdma: preserve IAM cache behavior and standalone region --------- Signed-off-by: Jihyeon Gim <potatogim@potatogim.net> Co-authored-by: Ben McClelland <ben.mcclelland@versity.com>
The Versity S3 Gateway:
A High-Performance S3 Translation Service
Binary release builds
Download latest release
| Linux amd64/arm64 | MacOS amd64/arm64 | BSD amd64/arm64 | Windows amd64/arm64 |
|---|---|---|---|
| ✔️ | ✔️ | ✔️ | ✔️ |
Use Cases
- Turn your local filesystem into an S3 server with a single command!
- Proxy S3 requests to S3 storage
- Simple to deploy S3 server with a single command
- Protocol compatibility in
posixallows common access to files via posix or S3 - Simplified interface for adding new storage system support
WebGUI
Get more details about the new (optional) WebGUI management/explorer here: https://github.com/versity/versitygw/wiki/WebGUI
S3 RDMA
VersityGW supports S3 over RDMA (Remote Direct Memory Access), enabling high-throughput, low-latency object transfers that bypass the kernel network stack. This is particularly useful for HPC and data-intensive workloads where network overhead is a bottleneck. See the S3 RDMA wiki page for setup and usage details.
vgwrdma is a VersityGW-based service that exposes a standard S3 API accelerated with NVIDIA's cuObject (GPUDirect Storage for Objects) protocol.
Static Website Hosting
Serve S3 buckets as static websites with index documents, custom error pages, and routing rules.
Enable a separate website endpoint with --website :8090 --website-domain example.com for virtual-host style routing (blog.example.com serves bucket blog, example.com serves bucket example.com).
When --website-domain is omitted, catch-all mode is used: the full hostname becomes the bucket name (name your buckets as FQDNs, e.g. blog.example.com).
See Global Options for all --website-* flags.
News
Check out latest wiki articles: https://github.com/versity/versitygw/wiki/Articles
Mailing List
Keep up to date with latest gateway announcements by signing up to the versitygw mailing list.
Documentation
See project documentation on the wiki.
Need help?
Ask questions in the community discussions.
Contact Versity Sales to discuss enterprise support.
Overview
Versity Gateway, a simple to use tool for seamless inline translation between AWS S3 object commands and storage systems. The Versity Gateway bridges the gap between S3-reliant applications and other storage systems, enabling enhanced compatibility and integration while offering exceptional scalability.
The server translates incoming S3 API requests and transforms them into equivalent operations to the backend service. By leveraging this gateway server, applications can interact with the S3-compatible API on top of already existing storage systems. This project enables leveraging existing infrastructure investments while seamlessly integrating with S3-compatible systems, offering increased flexibility and compatibility in managing data storage.
The Versity Gateway is focused on performance, simplicity, and expandability. The Versity Gateway is designed with modularity in mind, enabling future extensions to support additional backend storage systems. At present, the Versity Gateway supports any generic POSIX file backend storage, Versity’s open source ScoutFS filesystem, Azure Blob Storage, and other S3 servers.
The gateway is completely stateless. Multiple Versity Gateway instances may be deployed in a cluster to increase aggregate throughput. The Versity Gateway’s stateless architecture allows any request to be serviced by any gateway thereby distributing workloads and enhancing performance. Load balancers may be used to evenly distribute requests across the cluster of gateways for optimal performance.
The S3 HTTP(S) server and routing is implemented using the Fiber web framework. This framework is actively developed with a focus on performance. S3 API compatibility leverages the official aws-sdk-go-v2 whenever possible for maximum service compatibility with AWS S3.
Getting Started
See the Quickstart documentation.
Run the gateway with posix backend:
mkdir /tmp/vgw /tmp/vers
ROOT_ACCESS_KEY="testuser" ROOT_SECRET_KEY="secret" ./versitygw --port :10000 --iam-dir /tmp/vgw posix --versioning-dir /tmp/vers /tmp/vgw
This will enable an S3 server on the current host listening on port 10000 and hosting the directory /tmp/vgw with older object versions in /tmp/vers. It's fine if both of these directories are within the same filesystem. The --iam-dir option enables simple JSON flat file accounts for testing.
To get the usage output, run the following:
./versitygw --help
The command format is
versitygw [global options] command [command options] [arguments...]
The global options are specified before the backend type and the backend options are specified after.
Testing & Production Readiness
VersityGW is battle-tested and production-ready. Every pull request must pass our comprehensive test suite before it can be reviewed or merged. All code reviews are done by at least one human in the loop. LLMs may be used to augment the review process, but are never the sole reviewer or decision maker. See Testing for high level testing documentation.
Comprehensive Test Coverage
Our multi-layered testing strategy includes:
- Go Unit Test Files - Extensive unit tests with race detection and code coverage analysis covering core functionality, edge cases, and error handling.
- Integration Test Scripts - Real-world scenario testing across multiple backends (POSIX, S3, Azure) and configurations.
- Functional/Regression Tests - End-to-end SDK tests validating complete workflows including full-flow operations, POSIX-specific behavior, and IAM functionality populated with regression tests as issues are addressed.
- Static Analysis - Static Analysis checks using staticcheck.
- System Tests - Protocol-level validation using industry-standard S3 clients:
- AWS CLI - Official AWS command-line tools
- s3cmd - Popular S3 client
- Direct REST API testing with curl for request/response validation
- Security Testing - Both HTTP and HTTPS configurations tested. Vulnerability scanning with govulncheck. And regular dependency updates with dependabot.
- Compatibility Testing - Multiple backends, versioning scenarios, static bucket modes, and various authentication methods.
Run the gateway in Docker
Use the published image like the native binary by passing CLI arguments:
docker run --rm versity/versitygw:latest --version
See Docker for more documentation for running within Docker.
Run on Kubernetes
A Helm chart is provided to easily run Versity in Kubernetes environments:
helm install versitygw oci://ghcr.io/versity/versitygw/charts/versitygw
Please refer to the chart's README for more information and configuration parameters.
Versity gives you clarity and control over your archival storage, so you can allocate more resources to your core mission.
Contact
info@versity.com
+1 844 726 8826
@versitysoftware
