Supported bucket layouts in Ozone

Konstantin Alpashkin

In Ozone, a bucket layout defines how data inside a bucket is organized and how the metadata layer interprets keys (object names). A bucket layout directly affects namespace behavior, performance characteristics, and feature compatibility.

The following bucket layouts are supported in Ozone:

  • FILE_SYSTEM_OPTIMIZED (FSO)

    Hierarchical file system namespace view with directories and files similar to HDFS. It provides high-performance operations on namespace metadata and provides capabilities to read and write using the Amazon S3 connector.

    This layout type is efficient for deep directory trees and a large number of small files. Supports atomic rename operations, which are vital for Spark, Hive, etc. For more information on how this layout handles metadata internally, see the Ozone documentation article.

  • OBJECT_STORE (OBS)

    Provides a flat namespace (key/value) structure similar to Amazon S3. This layout type assumes no traditional directory objects, but uses prefixes instead. Unlike FSO, the rename operations are a little bit more expensive, as they assume copy and delete actions.

    This layout suits S3-compatible workloads or cases when POSIX semantics is not required.

  • LEGACY

    Used for backward compatibility with older versions of Ozone.

TIP
When choosing a bucket layout, use FILE_SYSTEM_OPTIMIZED or OBJECT_STORE buckets, depending on the expected workload. The following table provides a brief summary of the two layout types.
Feature FILE_SYSTEM_OPTIMIZED (FSO) OBJECT_STORE (OBS)

Namespace

Hierarchical

Flat

"Real" directories

Yes

No

Optimized for Hadoop

Yes

No

S3 semantics

Partial

Yes

Set bucket layout

To specify a bucket layout, use the --layout parameter when creating an Ozone bucket. For example:

$ ozone sh bucket create --layout FILE_SYSTEM_OPTIMIZED /vol1/fso-bucket
$ ozone sh bucket create --layout OBJECT_STORE /vol1/obs-bucket

To verify the layout type of a bucket, use bucket info. For example:

$ ozone sh bucket info vol1/fso-bucket

The output:

{
  "metadata" : { },
  "volumeName" : "vol1",
  "name" : "fso-bucket",
  "storageType" : "DISK",
  "versioning" : false,
  "listCacheSize" : 1000,
  "usedBytes" : 0,
  "usedNamespace" : 0,
  "creationTime" : "2026-03-05T08:52:25.331Z",
  "modificationTime" : "2026-03-05T08:52:25.331Z",
  "sourcePathExist" : true,
  "quotaInBytes" : -1,
  "quotaInNamespace" : -1,
  "bucketLayout" : "FILE_SYSTEM_OPTIMIZED",
  "owner" : "konstantin",
  "link" : false
}
$ ozone sh bucket info vol1/obs-bucket

The output:

{
  "metadata" : { },
  "volumeName" : "vol1",
  "name" : "obs-bucket",
  "storageType" : "DISK",
  "versioning" : false,
  "listCacheSize" : 1000,
  "usedBytes" : 0,
  "usedNamespace" : 0,
  "creationTime" : "2026-03-05T08:57:00.517Z",
  "modificationTime" : "2026-03-05T08:57:00.517Z",
  "sourcePathExist" : true,
  "quotaInBytes" : -1,
  "quotaInNamespace" : -1,
  "bucketLayout" : "OBJECT_STORE",
  "owner" : "konstantin",
  "link" : false
}

Ozone interfaces support

Ozone is a multi-protocol storage system with support for the following major interfaces:

  • S3;

  • OFS;

  • O3FS (deprecated, not recommended).

The following table reflects the compatibility of bucket types and client interfaces.

Bucket layout S3-compatible interface O3FS OFS

URL scheme: http://<bucket>.<host>:9878/

URL scheme: o3fs://<bucket>.<volume>.<om-id>/key

URL scheme: ofs://<om-id>/<volume>/<bucket>/key

FSO

✅

✅

✅

OBS

✅

❌

❌
TIP
To denote Ozone storage paths, it is recommended to use ofs:// instead of s3a:// wherever applicable. For example, use ofs://ozn/vol1/test-bucket/key1 instead of s3a://test-bucket/key1.

File listing examples

Below are examples of listing files in Ozone using different interfaces.

  • OFS

  • O3FS

  • S3A

$ hadoop fs -ls ofs://ozn/vol1/test-bucket

Sample output:

-rw-rw-rw-   3 konstantin konstantin         13 2026-03-05 10:32 ofs://ozn/vol1/test-bucket/test.txt
$ hadoop fs -ls o3fs://test-bucket.vol1.ozn

Sample output:

-rw-rw-rw-   3 konstantin konstantin         13 2026-03-05 10:32 o3fs://test-bucket.vol1.ozn/test.txt
$ hadoop fs
    -Dfs.s3a.access.key=test@RU-CENTRAL1.INTERNAL
    -Dfs.s3a.secret.key=ff76210...
    -Dfs.s3a.endpoint=http://<s3-gateway-host>:9878/ (1)
    -Dfs.s3a.change.detection.version.required=false (2)
    -cat s3a://test-bucket//file.txt
1 S3 gateway address.
2 The property to ignore S3 bucket versioning. Ozone doesn’t support S3 bucket versioning, so this property should be set explicitly.

Sample output:

drwxrwxrwx   - konstantin konstantin          13 2026-03-05 11:31 s3a://test-bucket/test.txt
IMPORTANT

An attempt to access data in an OBJECT_STORE bucket via OFS protocol returns the following error:

scala> spark.read.orc("ofs://adho/s3v/obs-bucket/table_orc3")
java.lang.IllegalArgumentException: Bucket: obs-bucket has layout: OBJECT_STORE, which does not support file system semantics. Bucket Layout must be FILE_SYSTEM_OPTIMIZED or LEGACY.

S3A directory markers

To write data to an FSO bucket using the S3 protocol, you have to explicitly specify the following parameter in the Ozone service settings (Custom ozone-site.xml):

fs.s3a.directory.marker.retention=keep

Otherwise, subdirectories will be deleted after a write operation is complete because S3 doesn’t support traditional directories. The S3A connector has the ability to retain directory marker objects for paths containing files or subdirectories.

For more information, see Controlling the S3A Directory Marker Behavior.

Found a mistake? Seleсt text and press Ctrl+Enter to report it