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:

  1. 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:

  1. <property>
  2. <name>ozone.s3g.domain.name</name>
  3. <value>s3g.internal</value>
  4. </property>

Bucket browser

Buckets could be browsed from the browser by adding ?browser=true to the bucket URL.

For example the content of the ‘testbucket’ could be checked from the browser using the URL http://localhost:9878/testbucket?browser=true

Implemented REST endpoints

Operations on S3Gateway service:

GET serviceimplemented

Operations on Bucket:

GET Bucket (List Objects) Version 2implemented
HEAD Bucketimplemented
DELETE Bucketimplemented
PUT Bucket (Create bucket)implemented
Delete Multiple Objects (POST)implemented

Operation on Objects:

PUT Objectimplemented
GET Objectimplemented
Multipart UploadimplementedExcept the listing of the current MultiPartUploads.
DELETE Objectimplemented
HEAD Objectimplemented


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).

  1. kinit -kt /etc/security/keytabs/testuser.keytab testuser/scm@EXAMPLE.COM
  2. ozone s3 getsecret
  3. awsAccessKey=testuser/scm@EXAMPLE.COM
  4. awsSecret=c261b6ecabf7d37d5f9ded654b1c724adac9bd9f13e247a235e567e8296d2999

Now, you can use the key and the secret to access the S3 endpoint:

  1. export AWS_ACCESS_KEY_ID=testuser/scm@EXAMPLE.COM
  2. export AWS_SECRET_ACCESS_KEY=c261b6ecabf7d37d5f9ded654b1c724adac9bd9f13e247a235e567e8296d2999
  3. aws s3api --endpoint http://localhost:9878 create-bucket --bucket bucket1

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:

  1. ozone sh create volume /s3v
  2. ozone sh create volume /vol1
  3. ozone sh create bucket /vol1/bucket1
  4. 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)



aws CLI could be used by specifying the custom REST endpoint.

  1. aws s3api --endpoint http://localhost:9878 create-bucket --bucket buckettest


  1. aws s3 ls --endpoint http://localhost:9878 s3://buckettest

S3 Fuse driver (goofys)

Goofys is a S3 FUSE driver. It could be used to mount any Ozone bucket as posix file system.

  1. goofys --endpoint http://localhost:9878 bucket1 /mount/bucket1