S3 Protocol
Ozone provides S3 compatible REST interface to use the object store data with any S3 compatible tools.
S3 buckets are stored under the /s3v
volume.
Getting started
S3 Gateway is a separated component which provides the S3 compatible APIs. It should be started additional to the regular Ozone components.
You can start a docker based cluster, including the S3 gateway from the release package.
Go to the compose/ozone
directory, and start the server:
docker-compose up -d --scale datanode=3
You can access the S3 gateway at http://localhost:9878
URL Schema
Ozone S3 gateway supports both the virtual-host-style URL s3 bucket addresses (eg. http://bucketname.host:9878) and the path-style addresses (eg. http://host:9878/bucketname)
By default it uses the path-style addressing. To use virtual host style URLs set your main domain name in your ozone-site.xml
:
<property>
<name>ozone.s3g.domain.name</name>
<value>s3g.internal</value>
</property>
Implemented REST Endpoints
The Ozone S3 Gateway implements a substantial subset of the Amazon S3 REST API. The tables below summarize each API’s support status, its feature, and any relevant notes, including known deviations from AWS S3 behavior.
Bucket Operations
API Name | Feature | Note |
---|---|---|
✅ ListBuckets | Lists all buckets owned by the authenticated user. | Returns the full bucket list. |
✅ CreateBucket | Creates a new bucket. | Non-compliant behavior: The default bucket ACL may include extra group permissions instead of being strictly private. Bucket names must adhere to S3 naming conventions. |
✅ HeadBucket | Checks for the existence of a bucket. | Returns a 200 status if the bucket exists. |
✅ DeleteBucket | Deletes a bucket. | Bucket must be empty before deletion. |
✅ GetBucketLocation | Retrieves the location (region) of a bucket. | Typically returns a default region (e.g., us-east-1 ), which may differ from AWS if region-specific responses are expected. |
Object Operations
API Name | Feature | Note |
---|---|---|
✅ GetObject | Retrieves the contents of an object. | Non-compliant behavior: For non-existent objects, Ozone may return a generic 404 without the structured XML error body defined by AWS S3. |
✅ HeadObject | Retrieves metadata for an object. | Similar to GET Object, error responses for missing objects might lack detailed AWS-style error XML. |
✅ PutObject | Uploads a new object. | Supports both single PUT and multipart uploads. Non-compliant behavior: Any ACL headers provided in the request are ignored. |
✅ DeleteObject | Deletes a single object. | Returns standard error codes for missing objects. |
✅ DeleteObjects | Deletes multiple objects in one request. | Bulk delete operation with aggregated error reporting. |
✅ CopyObject | Copies an object (intra- or inter-bucket). | Supports metadata directives (COPY/REPLACE). Non-compliant behavior: Self-copying for metadata updates may differ slightly from AWS S3. |
✅ ListObjectsV2 | Lists objects in a bucket with filtering and pagination. | Supports prefix, delimiter, and continuation tokens. |
Object Tagging Operations
API Name | Feature | Note |
---|---|---|
✅ PutObjectTagging | Adds or updates tags on an object. | Fully supported; updates replace any existing tag set. |
✅ GetObjectTagging | Retrieves the tag set of an object. | Returns the tag set as defined by the S3 API. |
✅ DeleteObjectTagging | Removes the tag set from an object. | Clears all tags associated with the object. |
Multipart Upload Operations
API Name | Feature | Note |
---|---|---|
✅ CreateMultipartUpload | Starts a multipart upload session. | Returns an UploadId for subsequent parts. |
✅ UploadPart | Uploads an individual part for a multipart upload. | Part numbering and ETag computation follow AWS semantics. |
✅ ListMultipartUploads | Lists in-progress multipart uploads in a bucket. | Up to 1000 multipart uploads are returned in a batch by default. |
✅ ListParts | Lists uploaded parts for an in-progress multipart upload. | Supports pagination if many parts exist. |
✅ CompleteMultipartUpload | Assembles all uploaded parts into a final object. | Returns an ETag that follows AWS multipart rules. |
✅ AbortMultipartUpload | Aborts an in-progress multipart upload. | Frees up storage used by uploaded parts. Incomplete multipart uploads older than 7 days are automatically aborted by Ozone. |
Additional Operations
API Name | Feature | Note |
---|---|---|
✅ Generate Presigned URL | Generates a temporary URL for accessing an object. | Uses AWS Signature V4. Non-compliant behavior: The generated URL may include a fixed default region rather than dynamically reflecting the bucket’s location. Currently, Ozone only supports generating presigned URLs for GetObject . Support for other operations is tracked in HDDS-5195 and HDDS-13393. |
Additional Notes:
- Advanced Features Not Supported:
- ACLs, Bucket Policies, CORS Configuration, and Website Hosting: These are not fully implemented; Ozone uses an internal permission model that deviates from AWS S3.
- Bucket Versioning, Object Locking, Server-Side Encryption, and S3 Select: These features are currently not supported.
- Conditional Requests: Support for conditional requests (e.g.,
If-Match
,If-None-Match
) is planned and tracked in HDDS-13117.- Lifecycle configuration, cross region replication, S3 event notifications are being implemented and in the roadmap.
- While Ozone S3 Gateway provides extensive support for common S3 operations, users should be aware of the above non-compliant behaviors and limitations when integrating with applications expecting full AWS S3 functionality.
- While Ozone S3 Gateway does not support S3 Server-Side Encryption, it does support encrypted buckets using Apache Ranger KMS. For more information, see the Transparent Data Encryption documentation.
Security
If security is not enabled, you can use any AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY
If security is enabled, you can get the key and the secret with the ozone s3 getsecret
command (*Kerberos based authentication is required).
kinit -kt /etc/security/keytabs/testuser.keytab testuser/scm@EXAMPLE.COM
ozone s3 getsecret
awsAccessKey=testuser/scm@EXAMPLE.COM
awsSecret=c261b6ecabf7d37d5f9ded654b1c724adac9bd9f13e247a235e567e8296d2999
Note: Starting in Ozone 1.4.0, the secret will be shown only once when generated with getsecret
. If the secret is lost, the user would have to revokesecret
first before regenerating a new secret with getsecret
.
Now, you can use the key and the secret to access the S3 endpoint:
export AWS_ACCESS_KEY_ID=testuser/scm@EXAMPLE.COM
export AWS_SECRET_ACCESS_KEY=c261b6ecabf7d37d5f9ded654b1c724adac9bd9f13e247a235e567e8296d2999
aws s3api --endpoint http://localhost:9878 create-bucket --bucket bucket1
To invalidate/revoke the secret, use ozone s3 revokesecret
command. Parameter ‘-y’ can be appended to skip the interactive confirmation.
ozone s3 revokesecret
Enter 'y' to confirm S3 secret revocation for 'testuser/scm@EXAMPLE.COM': y
S3 secret revoked.
Ozone Manager administrators can run ozone s3 getsecret
and ozone s3 revokesecret
command with -u
parameter to specify another users.
# Obtained Kerberos TGT for testuser/scm@EXAMPLE.COM with kinit,
# testuser/scm@EXAMPLE.COM is an OM admin.
ozone s3 getsecret -u om/om@EXAMPLE.COM
awsAccessKey=om/om@EXAMPLE.COM
awsSecret=1e9379d0424cce6669b1a501ff14834e46dee004ee868b41a313b49eabcfb68f
ozone s3 revokesecret -u om/om@EXAMPLE.COM -y
S3 secret revoked.
Expose any volume
Ozone has one more element in the name-space hierarchy compared to S3: the volumes. By default, all the buckets of the /s3v
volume can be accessed with S3 interface but only the (Ozone) buckets of the /s3v
volumes are exposed.
To make any other buckets available with the S3 interface a “symbolic linked” bucket can be created:
ozone sh volume create /s3v
ozone sh volume create /vol1
ozone sh bucket create /vol1/bucket1
ozone sh bucket link /vol1/bucket1 /s3v/common-bucket
This example expose the /vol1/bucket1
Ozone bucket as an S3 compatible common-bucket
via the S3 interface.
(Note: the implementation details of the bucket-linking feature can be found in the design doc)
Clients
AWS Cli
aws
CLI could be used by specifying the custom REST endpoint.
aws s3api --endpoint http://localhost:9878 create-bucket --bucket buckettest
Or
aws s3 ls --endpoint http://localhost:9878 s3://buckettest
Compatible third-party applications
Ozone’s S3 Gateway enables integration with a wide range of cloud-native and analytics applications. Here are some examples of tools and platforms known to work with Ozone (in alphabetical order):
- Clickhouse
- Fluentd can send logs directly to Ozone via the S3 Gateway.
- JuiceFS
- Starburst (Starburst also supports Ozone
ofs://
) - Teradata NOS
- CyberDuck See the tutorial page
This list is not exhaustive—any application that supports the S3 protocol can potentially connect to Ozone, making it easy to adopt Ozone in modern data pipelines and cloud-native workflows.
Next >>