Versity S3 Gateway

The noop backend is a /dev/null-style backend designed for testing. It accepts all S3 API requests and discards any data written to it. Read operations return empty but valid responses (e.g., empty bucket lists, empty object lists, and empty object bodies).

Use this backend to:

• Load and performance test the gateway without storage I/O acting as a bottleneck.
• Verify gateway configuration and middleware behavior.

To generate metrics for the dashboard to visualize, set up an AWS environment and use the AWS CLI as usual by running the provided setup script:

source metrics-exploration/aws_env_setup.sh

Once the stack is running, the dashboard is automatically provisioned and can be accessed at:

• URL: http://localhost:3000
• Username: admin
• Password: admin

To stop the dashboard stack and remove the containers, use the following command.

Note on Data Persistence:

• The influxdb database will be destroyed when using the -v flag.
• The Grafana database is explicitly not destroyed when shutting down containers.

docker compose -f docker-compose-metrics.yml down -v

Versity S3 Gateway is a high-performance translation service that allows applications to interact with non-S3 storage systems (like POSIX filesystems, Azure Blob Storage, or other S3 servers) using the S3 API. It is stateless and can be clustered behind a load balancer for scalability.

Binary Installation

Download the latest release from the GitHub releases page. Supported platforms include:

• Linux (amd64/arm64)
• MacOS (amd64/arm64)
• BSD (amd64/arm64)
• Windows (amd64/arm64)

Run via Docker

You can use the published Docker image by passing CLI arguments directly to the container:

docker run --rm versity/versitygw:latest --version

Run on Kubernetes

Install using the provided Helm chart:

helm install versitygw oci://ghcr.io/versity/versitygw/charts/versitygw

The versioning of the Helm chart and the versitygw container image are decoupled.

Upgrade the versitygw container image

To upgrade the gateway version, update the image.tag value and re-deploy the chart:

helm upgrade my-versitygw oci://ghcr.io/versity/versitygw/charts/versitygw \
  --reuse-values \
  --set image.tag=v1.3.1

Upgrade the Helm chart version

To upgrade only the Helm chart itself:

helm upgrade my-versitygw oci://ghcr.io/versity/versitygw/charts/versitygw \
  --reuse-values \
  --version 0.2.0

Install the Versity S3 Gateway on Kubernetes using Helm. For a basic single-user installation with a POSIX backend, use the following command.

Production Warning: Avoid passing credentials via --set as they are stored in Helm's release history. Instead, create a Kubernetes Secret containing the keys rootAccessKeyId and rootSecretAccessKey, then reference it using auth.existingSecret=<secret-name>.

helm install my-versitygw oci://ghcr.io/versity/versitygw/charts/versitygw \
  --set auth.accessKey=myaccesskey \
  --set auth.secretKey=mysecretkey \
  --set gateway.backend.type=posix \
  --set persistence.enabled=true

To turn a local filesystem into an S3 server, use the posix command. You must specify a root directory for the data and an optional directory for versioning.

Use the --iam-dir flag to enable simple JSON flat file accounts for testing/authentication.

Command Format: versitygw [global options] command [command options] [arguments...]

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

When setting replicaCount > 1, storage configuration depends on the backend type:

POSIX or Internal IAM (Stateful)

These backends store state locally.

• ReadWriteOnce (RWO): All replicas must be scheduled on the same Kubernetes node. This limits high availability.
• ReadWriteMany (RWX): Replicas can be distributed across multiple nodes. This is the recommended approach for high availability. Use affinity or topologySpreadConstraints to ensure distribution.

Stateless Backends (S3, Azure)

If using a stateless backend and either not using IAM or using an external IAM provider (e.g., LDAP, Vault), you can disable persistence by setting persistence.enabled=false.

The Versity Gateway Dashboard visualizes six metrics emitted by the Versity Gateway using Grafana. The stack uses Telegraf as a bridge to move metrics from the Gateway (which emits in statsd format) to influxdb. This implementation uses the influxql query language.

To start the dashboard stack, run the following command from the root of the repository:

docker compose -f docker-compose-metrics.yml up