Skip to content

HDDS-14465. Update 'Bucket Level Default Replication Type' documentation #348

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
jojochuang wants to merge 1 commit into
base: master
Choose a base branch
from
+63 −8
Open

HDDS-14465. Update 'Bucket Level Default Replication Type' documentation #348

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
63 changes: 63 additions & 0 deletions docs/03-core-concepts/03-namespace/02-buckets/05-default-replication.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,63 @@
---
title: Default Bucket Replication
sidebar_label: Default Replication
---

# Default Bucket Replication

The data redundancy for keys within an Apache Ozone bucket is determined by a replication configuration (type and value). This configuration can be set as an explicit default on the bucket itself, or it can be inherited from cluster-wide defaults if not set on the bucket. This document explains this process.

## Setting a Default Replication on a Bucket

When a bucket is created, a default replication configuration can be explicitly stored on the bucket. This bucket-level default will apply to all keys created within it, unless a key is written with its own specific replication override.

Ozone uses the following order of precedence to set a default replication property **on a bucket** during creation:

1. **Explicit Flags:** Using both the `--type` and `--replication` flags in the `ozone sh bucket create` command. This is the most direct way to set a bucket's default replication.
2. **Client-Side Value with Type Flag:** Using the `--type` flag during bucket creation in combination with the `ozone.replication` property set in the client's `ozone-site.xml`.

**Example:**
If `ozone.replication=1` is set on the client, the following command sets the default replication for `bucket2` to `RATIS-1`:
```bash
ozone sh bucket create vol1/bucket2 -t RATIS
```

Comment on lines +19 to +24
Copy link
Copy Markdown
Contributor

@smengcl smengcl Apr 2, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Did you mean to include an example output here as well? IIRC the output would echo the replication type actually set

Copy link
Copy Markdown
Contributor Author

@jojochuang jojochuang Apr 2, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actually it doesn't print that now:

bash-5.1$ ozone sh volume create vol1
bash-5.1$ ozone sh bucket create vol1/bucket2 -t RATIS
bash-5.1$

## Fallback to Cluster-Wide Defaults

If no default replication is set on the bucket during creation (i.e., neither of the methods above is used), the bucket is created **without** an explicit default replication property.

In this scenario, any key created within that bucket will fall back to using the cluster-wide default replication settings defined in the Ozone Manager's `ozone-site.xml`.

```xml
<property>
<name>ozone.server.default.replication.type</name>
<value>RATIS</value>
<tag>OZONE</tag>
<description>
The cluster-wide default replication type (e.g., RATIS, EC) used for keys
when their bucket has no default replication set.
</description>
</property>
<property>
<name>ozone.server.default.replication</name>
<value>3</value>
<tag>OZONE</tag>
<description>
The cluster-wide default replication value used for keys when their
bucket has no default replication set.
<ul>
<li><b>For RATIS:</b> 1, 3</li>
<li><b>For EC (Erasure Coding):</b> Formatted as {Codec}-{Data}-{Parity}-{ChunkSize}.
<ul>
<li><b>Codec:</b> XOR, RS</li>
<li><b>Data-Parity Blocks:</b> 3-2, 6-3, 10-4</li>
<li><b>ChunkSize:</b> e.g., 1024k, 2048k</li>
</ul>
</li>
</ul>
</description>
</property>
```

**Example:**
If you run `ozone sh bucket create vol1/bucket1` (with no flags or client properties), the bucket `bucket1` is created with no default replication. When a key is later written to `bucket1` without a specific replication override, it will use the cluster-wide server defaults (e.g., `RATIS-3`).
8 changes: 0 additions & 8 deletions docs/03-core-concepts/03-namespace/02-buckets/05-replication.md
View file
Open in desktop

This file was deleted.

Loading