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 56f0402c0 HDDS-14282. [Website v2] [Docs] [Core Concepts] Bucket Links
(#229)
56f0402c0 is described below
commit 56f0402c0c84a4b0d8977a87e15c47b2ab3bf36a
Author: Bolin Lin <[email protected]>
AuthorDate: Tue Jan 13 00:19:15 2026 -0500
HDDS-14282. [Website v2] [Docs] [Core Concepts] Bucket Links (#229)
---
.../03-namespace/02-buckets/01-overview.md | 2 +-
.../03-namespace/02-buckets/07-links.md | 56 +++++++++++++++++++++-
2 files changed, 56 insertions(+), 2 deletions(-)
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 386298a42..8f216c4b8 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
@@ -54,7 +54,7 @@ For more details, refer to the [GDPR
documentation](https://ozone.apache.org/doc
### Bucket Linking
Bucket linking allows exposing a bucket from one volume (or even another
bucket) as if it were in a different location, particularly useful for S3
compatibility or cross-tenant access. This creates a symbolic link-like
behavior.
-For more information, see the [S3 Protocol
documentation](../../../04-user-guide/01-client-interfaces/03-s3/01-s3-api.md)
and [S3 Multi-Tenancy
documentation](../../../05-administrator-guide/03-operations/07-s3-multi-tenancy.md).
+For more information, see the [Bucket Links documentation](./07-links.md).
### Access Control Lists (ACLs)
diff --git a/docs/03-core-concepts/03-namespace/02-buckets/07-links.md
b/docs/03-core-concepts/03-namespace/02-buckets/07-links.md
index 6f68b4448..8befff018 100644
--- a/docs/03-core-concepts/03-namespace/02-buckets/07-links.md
+++ b/docs/03-core-concepts/03-namespace/02-buckets/07-links.md
@@ -4,4 +4,58 @@ sidebar_label: Links
# Bucket Links
-**TODO:** File a subtask under
[HDDS-9857](https://issues.apache.org/jira/browse/HDDS-9857) and complete this
page or section.
+Bucket linking allows exposing a bucket from one volume (or even another
bucket) as if it were in a different location, particularly useful for S3
compatibility or cross-tenant access. This creates a symbolic link-like
behavior. For more information, see the [S3 Protocol
documentation](/docs/user-guide/client-interfaces/s3) and [S3 Multi-Tenancy
documentation](/docs/administrator-guide/operations/s3-multi-tenancy).
+
+## Overview
+
+Ozone has one more element in the namespace hierarchy compared to S3: volumes.
By default, all the buckets of the `/s3v` volume can be accessed with the S3
interface, but only the (Ozone) buckets of the `/s3v` volume are exposed.
+
+Bucket linking provides a way to make buckets from any volume accessible
through the S3 interface by creating a "symbolic link" to the target bucket.
+
+## Use Cases
+
+Bucket links are particularly useful for:
+
+- **S3 Compatibility**: Exposing buckets from non-S3 volumes through the S3
interface
+- **Cross-Tenant Access**: Providing access to buckets across different
volumes without data duplication
+- **Namespace Organization**: Creating logical groupings of buckets without
moving data
+- **Access Control**: Controlling visibility of buckets through different
access paths
+
+## Creating Bucket Links
+
+To make any bucket available with the S3 interface, create a symbolic linked
bucket:
+
+```bash
+ozone sh volume create /s3v
+ozone sh volume create /vol1
+
+ozone sh bucket create /vol1/bucket1
+ozone sh bucket link /vol1/bucket1 /s3v/common-bucket
+```
+
+This example exposes the `/vol1/bucket1` Ozone bucket as an S3 compatible
`common-bucket` via the S3 interface.
+
+## How Bucket Links Work
+
+Bucket links are stored in the database the same way as regular buckets, but
with additional information about the source volume and bucket they reference:
+
+1. The source bucket (e.g., `/vol1/bucket1`) continues to store the actual data
+2. The link bucket (e.g., `/s3v/common-bucket`) acts as a symbolic reference
+3. Key operations (list, get, put, etc.) on the link bucket are transparently
redirected to the source bucket
+4. Bucket operations (info, delete, ACL) work on the link object itself
+5. No data is copied or duplicated during the linking process
+
+## Accessing Linked Buckets
+
+Once a bucket link is created, you can access it through the S3 interface just
like any other bucket:
+
+```bash
+# Set up AWS credentials
+export AWS_ACCESS_KEY_ID=your-access-key
+export AWS_SECRET_ACCESS_KEY=your-secret-key
+
+# Access the linked bucket through S3 interface
+aws s3api --endpoint http://localhost:9878 list-objects --bucket common-bucket
+```
+
+For implementation details, refer to the [Volume Management design
document](https://ozone.apache.org/docs/edge/design/volume-management.html).
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
