NeoFS S3 Gateway

NeoFS S3 gateway provides API compatible with Amazon S3 cloud storage service.

Installation

Binaries are provided for all releases, you can also use a Docker image (:latest points to the latest stable release).

Build

Gateway can be built with a simple make. Currently it requires curl and jq to be installed.

Execution

Minimalistic S3 gateway setup needs:

• NeoFS node(s) address (S3 gateway itself is not a NeoFS node) Passed via -p parameter or via S3_GW_PEERS_<N>_ADDRESS and S3_GW_PEERS_<N>_WEIGHT environment variables (gateway supports multiple NeoFS nodes with weighted load balancing).
• a wallet used to fetch key and communicate with NeoFS nodes Passed via --wallet parameter or S3_GW_WALLET_PATH environment variable.
• an RPC (blockchain JSON-RPC) address passed via -r parameter or S3_GW_FSCHAIN_ENDPOINTS environment variable.
• a listen_address parameter, if address localhost:8080 is occupied already.

These two commands are functionally equivalent, they run the gate with one backend node, some keys and otherwise default settings:

$ neofs-s3-gw -r http://192.168.130.72:30333 -p 192.168.130.72:8080 --listen_address=0.0.0.0:19080 --wallet wallet.json

$ S3_GW_PEERS_0_ADDRESS=192.168.130.72:8080 \
  S3_GW_FSCHAIN_ENDPOINTS=http://192.168.130.72:30333 \
  S3_GW_SERVER_0_ADDRESS=0.0.0.0:19080 \
  S3_GW_WALLET=wallet.json \
  neofs-s3-gw

It's also possible to specify uri scheme (grpc or grpcs) when using -p or environment variables:

$ neofs-s3-gw -p grpc://192.168.130.72:8080 --wallet wallet.json

$ S3_GW_PEERS_0_ADDRESS=grpcs://192.168.130.72:8080 \
  S3_GW_WALLET=wallet.json \
  neofs-s3-gw

Domains

By default, s3-gw enable only path-style access. To be able to use both: virtual-hosted-style and path-style access you must configure listen_domains:

$ neofs-s3-gw -p 192.168.130.72:8080 --wallet wallet.json --listen_domains your.first.domain --listen_domains your.second.domain

So now you can use (e.g. HeadBucket. Make sure DNS is properly configured):

$ curl --head http://bucket-name.your.first.domain:8080
HTTP/1.1 200 OK
...

or

$ curl --head http://your.second.domain:8080/bucket-name
HTTP/1.1 200 OK
...

Also, you can configure domains using .env variables or yaml file.

Metrics

Gateway Health Status

You can use the neofs_s3_gw_state_health metric to monitor the health status of the gateway.
The metric exposes the following status codes:

• 0 - Unhealthy: The application cannot process user requests.
• 1 - Starting: The application is starting.
• 2 - Ready: The application has started and is serving user requests.

Documentation

• Configuration
• NeoFS S3 AuthMate
• AWS CLI basic usage
• AWS S3 API compatibility
• AWS S3 Compatibility test results

Credits

Please see CREDITS for details.