Reading and Writing Data in Ozone

Apache Ozone provides multiple interfaces for reading and writing data, catering to different use cases and client preferences. This guide explains how to use the three primary interfaces within a Docker environment:

1. Ozone Shell (ozone sh) - The native command-line interface
2. ofs (Ozone File System) - Hadoop-compatible file system interface
3. S3 API - Amazon S3 compatible REST interface

All examples assume you already have a running Ozone cluster using Docker Compose as described in the Docker Installation Guide.

Let's start 5 Datanodes because the Erasure Coding example below requires at least 5 replicas:

docker compose up -d --scale datanode=5

Interface Comparison​

Using Ozone Shell (ozone sh)​

The Ozone Shell provides direct access to all Ozone features through a command-line interface. All commands follow the pattern:

ozone sh <object-type> <action> <path> [options]

Where <object-type> is volume, bucket, or key.

Accessing the Ozone Shell​

To use the Ozone Shell in your Docker environment, execute commands inside the om container:

docker compose exec om bash

Working with Volumes​

Volumes are the top-level namespace in Ozone.

ozone sh volume create /vol1





ozone sh volume list /





ozone sh volume info /vol1





ozone sh volume delete /vol1







ozone sh volume delete -r /vol1

Working with Buckets​

First, create a volume (skip this step if the volume vol1 exists)

ozone sh volume create /vol1

Buckets are containers for keys (objects) within volumes.

ozone sh bucket create /vol1/bucket1





ozone sh bucket list /vol1





ozone sh bucket info /vol1/bucket1





ozone sh bucket delete /vol1/bucket1







ozone sh bucket delete -r /vol1/bucket1

Working with Keys (Objects)​

First, create a bucket (skip this step if the bucket bucket1 exists)

ozone sh bucket create /vol1/bucket1

Keys are the actual data objects stored in Ozone.

echo "Hello Ozone via Shell" > test_shell.txt





ozone sh key put /vol1/bucket1/test_shell.txt test_shell.txt







ozone sh key put -t RATIS -r THREE /vol1/bucket1/key1_ratis test_shell.txt



ozone sh key put -t EC -r rs-3-2-1024k /vol1/bucket1/key1_ec test_shell.txt





ozone sh key get /vol1/bucket1/test_shell.txt ./downloaded_shell.txt





ozone sh key get --force /vol1/bucket1/test_shell.txt ./downloaded_shell.txt





ozone sh key info /vol1/bucket1/test_shell.txt





ozone sh key list /vol1/bucket1









ozone sh key rename /vol1/bucket1 test_shell.txt renamed_shell.txt





ozone sh key delete /vol1/bucket1/renamed_shell.txt

Using ofs (Ozone File System)​

ofs provides a Hadoop-compatible file system interface (ofs://), making it seamless to use with applications designed for HDFS.

Basic ofs Operations​

ofs uses standard Hadoop filesystem commands.

ozone fs -mkdir -p ofs://om/vol1/bucketofs





echo "Hello from OFS" > local_ofs.txt

ozone fs -put local_ofs.txt ofs://om/vol1/bucketofs/





ozone fs -copyFromLocal local_ofs.txt ofs://om/vol1/bucketofs/remote_file.txt





ozone fs -ls ofs://om/vol1/bucketofs/





ozone fs -ls -R ofs://om/vol1/bucketofs/





ozone fs -get ofs://om/vol1/bucketofs/local_ofs.txt ./downloaded_ofs.txt





ozone fs -cat ofs://om/vol1/bucketofs/local_ofs.txt





ozone fs -mv ofs://om/vol1/bucketofs/local_ofs.txt ofs://om/vol1/bucketofs/moved_ofs.txt





ozone fs -cp ofs://om/vol1/bucketofs/moved_ofs.txt ofs://om/vol1/bucketofs/copy_ofs.txt





ozone fs -rm ofs://om/vol1/bucketofs/copy_ofs.txt





ozone fs -rm -skipTrash ofs://om/vol1/bucketofs/moved_ofs.txt





ozone fs -touchz ofs://om/vol1/bucketofs/empty_file.txt

Advanced ofs Operations​

ozone fs -checksum ofs://om/vol1/bucketofs/empty_file.txt

Using S3 API​

The S3 API provides compatibility with applications designed for Amazon S3. It's accessible via the S3 Gateway service, typically running on port 9878 in the Docker setup.

S3 Credentials​

In the default non-secure Docker setup, you can use any values for credentials.

export AWS_ACCESS_KEY_ID=testuser

export AWS_SECRET_ACCESS_KEY=testuser-secret

export AWS_ENDPOINT_URL=http://s3g:9878

(Note: Setting AWS_ENDPOINT_URL simplifies the aws commands below)

Using AWS CLI​

The AWS CLI can be used from your local machine (if installed) or from within a container that has it.

aws s3api create-bucket --bucket=s3bucket





aws s3api list-buckets





echo "Hello S3" > s3_test.txt

aws s3 cp s3_test.txt s3://s3bucket/





aws s3 ls s3://s3bucket/





aws s3 cp s3://s3bucket/s3_test.txt ./downloaded_s3.txt





aws s3 rm s3://s3bucket/s3_test.txt





aws s3api delete-bucket --bucket=s3bucket

Cross-Interface Operations​

Ozone allows accessing the same data through different interfaces.

Namespace Mapping​

Data LocationOzone Shell Pathofs PathS3 Path

vol1/bucket1/file.txt/vol1/bucket1/file.txt``ofs://<ozone service id>/vol1/bucket1/file.txt``s3://bucket1/file.txt
(if S3V configured to serve vol1)

s3v/s3bucket/file.txt/s3v/s3bucket/file.txt``ofs://<ozone service id>/s3v/s3bucket/file.txt``s3://s3bucket/file.txt

(Note: om in ofs:// path refers to the Ozone Manager service address)

Accessing S3 Data via Ozone Shell/ofs​

Objects created via S3 reside in the special /s3v volume.

Access via Ozone Shell (inside OM/client container)​

docker compose exec om bash

ozone sh key list /s3v/s3bucket

ozone sh key get /s3v/s3bucket/s3_test.txt /tmp/from_s3.txt

exit

Access via ofs (inside OM/client container)​

Create a FSO bucket in the /s3v

ozone sh bucket create /s3v/fsobucket --layout fso

Upload a file using AWS CLI

aws s3 cp s3_test.txt s3://fsobucket/

Access the file via ofs

ozone fs -ls ofs://om/s3v/fsobucket/



ozone fs -cat ofs://om/s3v/fsobucket/s3_test.txt

Exposing Non-S3 Buckets via S3 (Bucket Linking)​

You can make buckets created outside /s3v accessible via the S3 Gateway using links.

docker compose exec om bash





ozone sh volume create /myvol

ozone sh bucket create /myvol/mybucket





ozone sh bucket link /myvol/mybucket /s3v/linkedbucket

exit





aws s3 cp local_file.txt s3://linkedbucket/

aws s3 ls s3://linkedbucket/

Bucket Layouts (FSO vs OBS)​

Ozone buckets can have different internal layouts:

1. FILE_SYSTEM_OPTIMIZED (FSO): Default. Better for hierarchical operations (like ozone fs -mkdir), supports trash for ozone fs -rm. Recommended for Hadoop/filesystem workloads.
2. OBJECT_STORE (OBS): Legacy layout. May offer slight performance benefits for flat object access patterns. No trash support.

ozone sh bucket create /vol1/fsobucket --layout fso

ozone sh bucket create /vol1/obsbucket --layout obs

Most operations work on both, but FSO is generally preferred unless specific OBS characteristics are needed.

Summary​

You have learned how to perform basic read/write operations in Ozone using three different interfaces: Ozone Shell, ofs, and the S3 API. Each interface has its strengths, and Ozone's multi-protocol design allows you to choose the best tool for the job while accessing the same underlying data.

• Interface Comparison

• Using Ozone Shell (ozone sh)

  • Accessing the Ozone Shell
  • Working with Volumes
  • Working with Buckets
  • Working with Keys (Objects)

• Using ofs (Ozone File System)

  • Basic ofs Operations
  • Advanced ofs Operations

• Using S3 API

  • S3 Credentials
  • Using AWS CLI

• Cross-Interface Operations

  • Namespace Mapping
  • Accessing S3 Data via Ozone Shell/ofs
  • Exposing Non-S3 Buckets via S3 (Bucket Linking)
  • Bucket Layouts (FSO vs OBS)

• Summary