This is an automated email from the ASF dual-hosted git repository.
weichiu pushed a commit to branch HDDS-9225-website-v2
in repository https://gitbox.apache.org/repos/asf/ozone-site.git
The following commit(s) were added to refs/heads/HDDS-9225-website-v2 by this
push:
new c24991357 HDDS-14404. [Website v2] [Docs] [Core Concepts] Ozone
Volume/Bucket name allowed characters (#238)
c24991357 is described below
commit c2499135748c48ccb4b5627c9e0c30e0b1f8d45d
Author: Bolin Lin <[email protected]>
AuthorDate: Tue Jan 13 01:22:27 2026 -0500
HDDS-14404. [Website v2] [Docs] [Core Concepts] Ozone Volume/Bucket name
allowed characters (#238)
---
.../03-namespace/01-volumes/01-overview.md | 25 ++++++++++++++++++++++
.../03-namespace/02-buckets/01-overview.md | 25 ++++++++++++++++++++++
2 files changed, 50 insertions(+)
diff --git a/docs/03-core-concepts/03-namespace/01-volumes/01-overview.md
b/docs/03-core-concepts/03-namespace/01-volumes/01-overview.md
index 0239e9e76..7de170b3e 100644
--- a/docs/03-core-concepts/03-namespace/01-volumes/01-overview.md
+++ b/docs/03-core-concepts/03-namespace/01-volumes/01-overview.md
@@ -14,6 +14,31 @@ A **Volume** in Ozone is the highest level of the namespace
hierarchy. It serves
- **Storage Accounting:** Volumes are used as the basis for storage
accounting, allowing administrators to track resource usage per volume.
- **Container for Buckets:** A volume can contain any number of buckets.
+:::note Volume/Bucket Naming Convention
+
+To maintain S3 compatibility, Ozone volume and bucket name follows S3 naming
convention.
+
+This means volume/bucket names in Ozone:
+
+Allowed Characters and Length:
+
+- Allowed characters: Lowercase letters (a-z), numbers (0-9), dots (.), and
hyphens (-)
+- Length: Must be between 3 and 63 characters long
+- Start and End: Must begin and end with a letter or a number
+
+Prohibitions:
+
+- Cannot contain uppercase letters or underscores (_)
+- Cannot be formatted as an IP address (e.g., 192.168.5.4)
+- Cannot have consecutive periods (e.g., my..bucket) or have dashes adjacent
to periods (e.g., my-.bucket)
+- Cannot end with a dash
+
+This can cause trouble when migrating HDFS workloads to Ozone, since HDFS path
names are POSIX-compliant.
+
+To relax the compliance check, configure the property
`ozone.om.namespace.s3.strict` to `false` in the `ozone-site.xml` of Ozone
Manager.
+
+:::
+
## Details
### Creation and Management
diff --git a/docs/03-core-concepts/03-namespace/02-buckets/01-overview.md
b/docs/03-core-concepts/03-namespace/02-buckets/01-overview.md
index 8f216c4b8..d02b1e83d 100644
--- a/docs/03-core-concepts/03-namespace/02-buckets/01-overview.md
+++ b/docs/03-core-concepts/03-namespace/02-buckets/01-overview.md
@@ -15,6 +15,31 @@ They serve as containers for keys (data objects).
- **Container for Keys:** A bucket can contain any number of keys.
- **No Nested Buckets:** Unlike directories, buckets cannot contain other
buckets.
+:::note Volume/Bucket Naming Convention
+
+To maintain S3 compatibility, Ozone volume and bucket name follows S3 naming
convention.
+
+This means volume/bucket names in Ozone:
+
+Allowed Characters and Length:
+
+- Allowed characters: Lowercase letters (a-z), numbers (0-9), dots (.), and
hyphens (-)
+- Length: Must be between 3 and 63 characters long
+- Start and End: Must begin and end with a letter or a number
+
+Prohibitions:
+
+- Cannot contain uppercase letters or underscores (_)
+- Cannot be formatted as an IP address (e.g., 192.168.5.4)
+- Cannot have consecutive periods (e.g., my..bucket) or have dashes adjacent
to periods (e.g., my-.bucket)
+- Cannot end with a dash
+
+This can cause trouble when migrating HDFS workloads to Ozone, since HDFS path
names are POSIX-compliant.
+
+To relax the compliance check, configure the property
`ozone.om.namespace.s3.strict` to `false` in the `ozone-site.xml` of Ozone
Manager.
+
+:::
+
## Details
### Creation and Management
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
