From 4c5e57405d06547eb10fa81fcb6e2361159e901e Mon Sep 17 00:00:00 2001 From: Wei-Chiu Chuang Date: Wed, 18 Feb 2026 17:18:26 -0800 Subject: [PATCH] HDDS-14465: Update 'Bucket Level Default Replication Type' documentation Replaced placeholder page for 'Bucket Level Default Replication Type' with comprehensive documentation. The content explains how Ozone determines default replication for buckets, including server-side properties, client-side settings, and their order of precedence. The page was refactored to clearly distinguish between explicitly setting default replication on a bucket and falling back to cluster-wide defaults for keys when no bucket default is specified. --- .../02-buckets/05-default-replication.mdx | 63 +++++++++++++++++++ .../03-namespace/02-buckets/05-replication.md | 7 --- 2 files changed, 63 insertions(+), 7 deletions(-) create mode 100644 docs/03-core-concepts/03-namespace/02-buckets/05-default-replication.mdx delete mode 100644 docs/03-core-concepts/03-namespace/02-buckets/05-replication.md diff --git a/docs/03-core-concepts/03-namespace/02-buckets/05-default-replication.mdx b/docs/03-core-concepts/03-namespace/02-buckets/05-default-replication.mdx new file mode 100644 index 0000000000..ac8229c7ce --- /dev/null +++ b/docs/03-core-concepts/03-namespace/02-buckets/05-default-replication.mdx @@ -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 +``` + +## 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 + + ozone.server.default.replication.type + RATIS + OZONE + + The cluster-wide default replication type (e.g., RATIS, EC) used for keys + when their bucket has no default replication set. + + + + ozone.server.default.replication + 3 + OZONE + + The cluster-wide default replication value used for keys when their + bucket has no default replication set. +
    +
  • For RATIS: 1, 3
    • +
  • For EC (Erasure Coding): Formatted as {Codec}-{Data}-{Parity}-{ChunkSize}. +
      +
    • Codec: XOR, RS
      • +
    • Data-Parity Blocks: 3-2, 6-3, 10-4
      • +
    • ChunkSize: e.g., 1024k, 2048k
      • +
    +
    • +
+ + +``` + +**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`). diff --git a/docs/03-core-concepts/03-namespace/02-buckets/05-replication.md b/docs/03-core-concepts/03-namespace/02-buckets/05-replication.md deleted file mode 100644 index d46c3422af..0000000000 --- a/docs/03-core-concepts/03-namespace/02-buckets/05-replication.md +++ /dev/null @@ -1,7 +0,0 @@ ---- -sidebar_label: Default Replication Type ---- - -# Bucket Level Default Replication Type - -**TODO:** File a subtask under [HDDS-9857](https://issues.apache.org/jira/browse/HDDS-9857) and complete this page or section.