You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@ozone.apache.org by we...@apache.org on 2026/08/27 22:19:25 UTC
(ozone-site) branch master updated: HDDS-16107. Add Ozone 2.2.1 download and release notes
This is an automated email from the ASF dual-hosted git repository.
jojochuang pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/ozone-site.git
The following commit(s) were added to refs/heads/master by this push:
new 7f991e94d0 HDDS-16107. Add Ozone 2.2.1 download and release notes
7f991e94d0 is described below
commit 7f991e94d0250406d4e6af0345cbd42e00312a1c
Author: Wei-Chiu Chuang <we...@apache.org>
AuthorDate: Thu Aug 27 15:19:19 2026 -0700
HDDS-16107. Add Ozone 2.2.1 download and release notes
Co-authored-by: Cursor <cu...@cursor.com>
---
cspell.yaml | 1 +
src/pages/download.md | 10 +-
src/pages/release-notes/2.2.1.md | 92 +++
versioned_docs/version-2.2.1/01-overview.md | 103 ++++
.../02-quick-start/01-installation/01-docker.md | 96 ++++
.../01-installation/02-kubernetes.md | 132 +++++
.../01-installation/03-bare-metal.md | 287 ++++++++++
.../02-quick-start/01-installation/README.mdx | 11 +
.../02-quick-start/01-installation/quickstart.gif | Bin 0 -> 1151479 bytes
.../02-quick-start/02-reading-writing-data.md | 348 ++++++++++++
.../version-2.2.1/02-quick-start/README.mdx | 11 +
.../01-architecture/01-overview.md | 47 ++
.../01-architecture/02-ozone-manager.md | 99 ++++
.../03-storage-container-manager.md | 97 ++++
.../01-architecture/04-s3-gateway.md | 111 ++++
.../01-architecture/05-datanodes.md | 95 ++++
.../03-core-concepts/01-architecture/06-recon.md | 105 ++++
.../01-architecture/ContainerMetadata.png | Bin 0 -> 98493 bytes
.../01-architecture/FunctionalOzone.png | Bin 0 -> 78741 bytes
.../01-architecture/OzoneArchitectureDiagram.png | Bin 0 -> 60252 bytes
.../01-architecture/OzoneBlock.png | Bin 0 -> 4650 bytes
.../01-architecture/OzoneManager-ReadPath.png | Bin 0 -> 81030 bytes
.../01-architecture/OzoneManager-WritePath.png | Bin 0 -> 96696 bytes
.../01-architecture/OzoneManager.png | Bin 0 -> 13327 bytes
.../03-core-concepts/01-architecture/README.mdx | 11 +
.../01-architecture/ReconHighLevelDesign.png | Bin 0 -> 239168 bytes
.../01-architecture/ReconOmDesign.png | Bin 0 -> 162797 bytes
.../01-architecture/ReconScmDesign.png | Bin 0 -> 181628 bytes
.../01-architecture/StorageContainerManager.png | Bin 0 -> 13336 bytes
.../02-replication/01-storage-containers.md | 26 +
.../02-replication/02-write-pipelines.md | 298 ++++++++++
.../03-core-concepts/02-replication/03-ratis.md | 24 +
.../02-replication/04-erasure-coding.md | 120 ++++
.../02-replication/ContainerMetadata.png | Bin 0 -> 98493 bytes
.../03-core-concepts/02-replication/Containers.png | Bin 0 -> 24775 bytes
.../02-replication/EC-Chunk-Layout.png | Bin 0 -> 179275 bytes
.../02-replication/EC-Reads-With-No-Failures.png | Bin 0 -> 194800 bytes
.../02-replication/EC-Reconstructional-Read.png | Bin 0 -> 221681 bytes
.../EC-Write-Block-Allocation-in-Containers.png | Bin 0 -> 194715 bytes
.../03-core-concepts/02-replication/README.mdx | 11 +
.../03-core-concepts/03-namespace/01-overview.md | 23 +
.../03-namespace/01-volumes/01-overview.md | 105 ++++
.../03-namespace/01-volumes/02-owners.md | 176 ++++++
.../03-namespace/01-volumes/03-quotas.md | 54 ++
.../03-namespace/01-volumes/README.mdx | 11 +
.../03-namespace/02-buckets/01-overview.md | 87 +++
.../03-namespace/02-buckets/02-owners.md | 116 ++++
.../03-namespace/02-buckets/03-quotas.md | 10 +
.../02-buckets/04-layouts/01-object-store.md | 179 ++++++
.../04-layouts/02-file-system-optimized.md | 78 +++
.../03-namespace/02-buckets/04-layouts/README.mdx | 11 +
.../03-namespace/02-buckets/05-replication.md | 7 +
.../03-namespace/02-buckets/06-encryption.md | 11 +
.../03-namespace/02-buckets/07-links.md | 61 ++
.../03-namespace/02-buckets/08-snapshots.md | 14 +
.../03-namespace/02-buckets/README.mdx | 11 +
.../03-namespace/03-keys/01-overview.md | 58 ++
.../03-namespace/03-keys/README.mdx | 11 +
.../03-core-concepts/03-namespace/README.mdx | 11 +
.../03-core-concepts/04-security/01-kerberos.md | 9 +
.../04-security/02-acls/01-native-acls.md | 227 ++++++++
.../04-security/02-acls/02-ranger-acls.md | 52 ++
.../04-security/02-acls/README.mdx | 11 +
.../03-core-concepts/04-security/README.mdx | 11 +
.../05-high-availability/01-scm-ha.md | 17 +
.../05-high-availability/02-om-ha.md | 30 +
.../05-high-availability/HA-OM.png | Bin 0 -> 60888 bytes
.../05-high-availability/README.mdx | 11 +
.../03-core-concepts/06-comparison.md | 59 ++
.../version-2.2.1/03-core-concepts/README.mdx | 11 +
.../04-user-guide/01-client-interfaces/01-o3.md | 301 ++++++++++
.../04-user-guide/01-client-interfaces/02-ofs.md | 409 ++++++++++++++
.../01-client-interfaces/03-s3/01-s3-api.md | 194 +++++++
.../01-client-interfaces/03-s3/02-securing-s3.md | 114 ++++
.../01-client-interfaces/03-s3/README.mdx | 7 +
.../04-user-guide/01-client-interfaces/04-s3a.md | 189 +++++++
.../01-client-interfaces/05-httpfs.md | 233 ++++++++
.../01-client-interfaces/06-java-client-api.md | 141 +++++
.../01-client-interfaces/07-python.md | 235 ++++++++
.../01-client-interfaces/08-csi-protocol.md | 73 +++
.../01-client-interfaces/08-native-cpp.md | 121 ++++
.../04-user-guide/01-client-interfaces/CSI.png | Bin 0 -> 27210 bytes
.../04-user-guide/01-client-interfaces/README.mdx | 7 +
.../persistent-volume-test-web-ui.png | Bin 0 -> 13830 bytes
.../04-user-guide/02-clients/01-ozone.md | 13 +
.../04-user-guide/02-clients/02-hdfs.md | 9 +
.../04-user-guide/02-clients/03-s3.md | 13 +
.../04-user-guide/02-clients/README.mdx | 11 +
.../04-user-guide/03-integrations/01-hive.md | 164 ++++++
.../04-user-guide/03-integrations/02-hue.md | 3 +
.../04-user-guide/03-integrations/03-iceberg.md | 262 +++++++++
.../04-user-guide/03-integrations/04-impala.md | 83 +++
.../04-user-guide/03-integrations/05-oozie.md | 3 +
.../04-user-guide/03-integrations/06-spark.md | 195 +++++++
.../04-user-guide/03-integrations/07-trino.md | 3 +
.../03-integrations/08-hadoop-distcp.md | 159 ++++++
.../04-user-guide/03-integrations/09-flink.md | 178 ++++++
.../04-user-guide/03-integrations/09-hbase.md | 60 ++
.../04-user-guide/03-integrations/README.mdx | 11 +
.../version-2.2.1/04-user-guide/README.mdx | 7 +
.../01-installation/01-deployment-architecture.md | 3 +
.../01-installation/02-reference-architecture.md | 15 +
.../01-installation/03-hardware-and-sizing.md | 150 +++++
.../01-installation/04-installing-binaries.md | 47 ++
.../01-installation/05-initializing-cluster.md | 125 +++++
.../01-installation/README.mdx | 11 +
.../01-basic/01-configuration-files.md | 45 ++
.../01-basic/02-environment-variables.md | 85 +++
.../01-basic/02-network/01-ozone-manager.md | 7 +
.../02-network/02-storage-container-manager.md | 7 +
.../01-basic/02-network/03-datanode.md | 7 +
.../01-basic/02-network/04-recon.md | 7 +
.../01-basic/02-network/05-s3-gateway.md | 7 +
.../01-basic/02-network/07-default-ports.md | 88 +++
.../01-basic/02-network/README.mdx | 11 +
.../01-basic/03-directories/01-ozone-manager.md | 15 +
.../03-directories/02-storage-container-manager.md | 7 +
.../01-basic/03-directories/03-datanode.md | 7 +
.../01-basic/03-directories/04-recon.md | 7 +
.../01-basic/03-directories/README.mdx | 11 +
.../02-configuration/01-basic/README.mdx | 11 +
.../02-logging/01-application-logs.md | 68 +++
.../02-configuration/02-logging/02-audit-logs.md | 53 ++
.../02-configuration/02-logging/README.mdx | 11 +
.../03-security/01-administrators.md | 45 ++
.../02-configuration/03-security/02-kerberos.md | 93 ++++
.../02-configuration/03-security/03-https.md | 119 ++++
.../02-configuration/03-security/04-knox.md | 7 +
.../01-network-encryption/01-hadoop-rpc.md | 24 +
.../05-encryption/01-network-encryption/02-grpc.md | 39 ++
.../01-network-encryption/03-web-ui-https.md | 268 +++++++++
.../05-encryption/01-network-encryption/README.mdx | 11 +
.../02-transparent-data-encryption.md | 209 +++++++
.../03-security/05-encryption/README.mdx | 11 +
.../02-configuration/03-security/05-ranger.md | 36 ++
.../03-security/06-securing-s3-secrets.md | 112 ++++
.../02-configuration/03-security/README.mdx | 11 +
.../04-performance/01-placeholder.md | 71 +++
.../02-configuration/04-performance/02-topology.md | 207 +++++++
.../04-performance/03-multi-raft.md | 123 ++++
.../02-configuration/04-performance/04-rocksdb.md | 200 +++++++
.../04-performance/04-streaming-write-pipeline.md | 140 +++++
.../06-calculating-ec-pipeline-limits.md | 39 ++
.../07-calculating-ratis-pipeline-limits.md | 63 +++
.../04-performance/07-s3-gateway-load-balancing.md | 18 +
.../04-performance/08-fair-call-queue.md | 116 ++++
.../04-performance/10-httpfs-load-balancer.md | 99 ++++
.../02-configuration/04-performance/README.mdx | 11 +
.../05-high-availability/01-scm-ha.md | 205 +++++++
.../05-high-availability/02-om-ha.md | 175 ++++++
.../05-high-availability/03-client-failover.md | 69 +++
.../05-high-availability/README.mdx | 11 +
.../05-high-availability/scm-secure-ha.png | Bin 0 -> 46757 bytes
.../02-configuration/99-appendix.md | 7 +
.../02-configuration/README.mdx | 11 +
.../03-operations/01-start-and-stop.md | 84 +++
.../03-operations/02-upgrade-and-downgrade.md | 82 +++
.../01-ozone-manager.md | 22 +
.../02-storage-container-manager.md | 37 ++
.../03-datanodes/01-datanode-decommission.md | 123 ++++
.../03-datanodes/02-datanode-maintenance.md | 69 +++
.../03-datanodes/README.mdx | 17 +
.../README.mdx | 11 +
.../04-disk-replacement/01-ozone-manager.md | 111 ++++
.../02-storage-container-manager.md | 146 +++++
.../04-disk-replacement/03-datanodes.md | 235 ++++++++
.../03-operations/04-disk-replacement/04-recon.md | 131 +++++
.../03-operations/04-disk-replacement/README.mdx | 7 +
.../05-container-replication-report.md | 62 +++
.../05-data-balancing/01-container-balancer.md | 93 ++++
.../03-operations/05-data-balancing/README.mdx | 9 +
.../05-data-balancing/diskBalancer.png | Bin 0 -> 116124 bytes
.../03-operations/06-certificate-rotation.md | 5 +
.../07-s3-multi-tenancy/01-overview.md | 46 ++
.../03-operations/07-s3-multi-tenancy/02-setup.md | 72 +++
.../07-s3-multi-tenancy/03-tenant-commands.md | 456 +++++++++++++++
.../07-s3-multi-tenancy/04-access-control.md | 76 +++
.../03-operations/07-s3-multi-tenancy/README.mdx | 11 +
.../03-operations/08-snapshots/01-overview.md | 251 +++++++++
.../08-snapshots/02-configuration-properties.md | 76 +++
.../03-operations/08-snapshots/README.mdx | 11 +
.../03-operations/09-observability/01-cli.md | 144 +++++
.../09-observability/02-recon/01-recon-web-ui.md | 3 +
.../02-recon/02-recon-rest-api.mdx | 9 +
.../09-observability/02-recon/README.mdx | 7 +
.../03-operations/09-observability/03-web-uis.md | 53 ++
.../09-observability/04-prometheus.md | 32 ++
.../03-operations/09-observability/05-grafana.md | 57 ++
.../09-observability/06-distributed-tracing.md | 27 +
.../09-observability/GrafanaOzoneObjectMetrics.png | Bin 0 -> 319286 bytes
.../09-observability/GrafanaOzoneOverall.png | Bin 0 -> 507556 bytes
.../09-observability/GrafanaOzoneRPCMetrics.png | Bin 0 -> 447935 bytes
.../03-operations/09-observability/README.mdx | 7 +
.../03-operations/09-observability/om-ui.png | Bin 0 -> 391465 bytes
.../03-operations/09-observability/scm-ui.png | Bin 0 -> 366483 bytes
.../10-leader-transfer/01-ozone-manager.md | 32 ++
.../02-storage-container-manager.md | 34 ++
.../03-operations/10-leader-transfer/README.mdx | 7 +
.../03-operations/11-quota.md | 111 ++++
.../03-operations/11-tools/01-ozone-repair.md | 274 +++++++++
.../03-operations/11-tools/02-ozone-admin.md | 60 ++
.../11-tools/03-ozone-debug/01-ldb-tool.md | 470 ++++++++++++++++
.../11-tools/03-ozone-debug/02-debug-om.md | 42 ++
.../11-tools/03-ozone-debug/03-debug-datanode.md | 19 +
.../11-tools/03-ozone-debug/04-debug-replicas.md | 101 ++++
.../11-tools/03-ozone-debug/05-ratis-log-parser.md | 18 +
.../03-ozone-debug/06-audit-parser-exact.md | 59 ++
.../07-container-replica-debugger-tool.md | 250 +++++++++
.../11-tools/03-ozone-debug/README.mdx | 26 +
.../03-operations/11-tools/README.mdx | 55 ++
.../03-operations/12-trash.md | 56 ++
.../03-operations/13-dynamic-property-reload.md | 185 ++++++
.../03-operations/README.mdx | 11 +
.../05-administrator-guide/README.mdx | 11 +
.../version-2.2.1/06-troubleshooting/01-startup.md | 9 +
.../06-troubleshooting/02-safemode.md | 9 +
.../06-troubleshooting/03-read-write.md | 9 +
.../version-2.2.1/06-troubleshooting/04-delete.md | 9 +
.../version-2.2.1/06-troubleshooting/05-recon.md | 7 +
.../06-troubleshooting/06-performance.md | 9 +
.../07-integrations/01-placeholder.md | 5 +
.../06-troubleshooting/07-integrations/README.mdx | 11 +
.../08-security/01-certificates.md | 7 +
.../08-security/02-authentication.md | 13 +
.../08-security/03-authorization.md | 13 +
.../06-troubleshooting/08-security/README.mdx | 11 +
.../06-troubleshooting/09-upgrade-downgrade.md | 7 +
.../10-decommission-maintenance.md | 7 +
.../06-troubleshooting/11-write-pipelines.md | 7 +
.../06-troubleshooting/12-storage-containers.md | 7 +
.../version-2.2.1/06-troubleshooting/13-ratis.md | 7 +
.../version-2.2.1/06-troubleshooting/14-rocksdb.md | 7 +
.../version-2.2.1/06-troubleshooting/15-docker.md | 7 +
.../16-om-ha-snapshot-installation-issues.md | 25 +
.../version-2.2.1/06-troubleshooting/README.mdx | 7 +
.../01-ozone-manager/01-disk-layout.md | 6 +
.../01-ozone-manager/02-rocksdb-schema.md | 7 +
.../01-ozone-manager/03-in-memory-storage.md | 11 +
.../01-ozone-manager/04-startup-sequence.md | 7 +
.../01-components/01-ozone-manager/05-roles.md | 7 +
.../01-ozone-manager/06-write-request-flow.md | 7 +
.../01-ozone-manager/07-read-request-flow.md | 7 +
.../01-ozone-manager/08-high-availability.md | 67 +++
.../01-ozone-manager/HA-OM-doublebuffer.png | Bin 0 -> 77661 bytes
.../01-components/01-ozone-manager/HA-OM.png | Bin 0 -> 60888 bytes
.../01-components/01-ozone-manager/README.mdx | 11 +
.../02-storage-container-manager/01-disk-layout.md | 7 +
.../02-rocksdb-schema.md | 7 +
.../03-in-memory-storage.md | 7 +
.../04-startup-sequence.md | 7 +
.../02-storage-container-manager/05-roles.md | 9 +
.../06-admin-write-request-flow.md | 7 +
.../07-admin-read-request-flow.md | 7 +
.../02-storage-container-manager/README.mdx | 11 +
.../01-components/03-datanode/01-disk-layout.md | 7 +
.../01-components/03-datanode/02-rocksdb-schema.md | 53 ++
.../03-datanode/03-in-memory-storage.md | 7 +
.../03-datanode/04-startup-sequence.md | 7 +
.../03-datanode/06-write-request-flow.md | 7 +
.../03-datanode/07-read-request-flow.md | 7 +
.../01-components/03-datanode/README.mdx | 11 +
.../01-components/04-recon/01-disk-layout.md | 7 +
.../01-components/04-recon/02-rocksdb-schema.md | 7 +
.../01-components/04-recon/03-sql-schema.md | 7 +
.../01-components/04-recon/04-in-memory-storage.md | 7 +
.../01-components/04-recon/05-startup-sequence.md | 7 +
.../04-recon/06-syncing-data-from-om.md | 7 +
.../04-recon/07-syncing-data-from-scm.md | 7 +
.../04-recon/08-syncing-data-from-datanodes.md | 7 +
.../01-components/04-recon/README.mdx | 11 +
.../01-components/05-s3-gateway/01-overview.md | 13 +
.../01-components/05-s3-gateway/02-request-flow.md | 7 +
.../01-components/05-s3-gateway/README.mdx | 11 +
.../01-components/06-client/01-startup-sequence.md | 10 +
.../06-client/02-in-memory-storage.md | 10 +
.../01-components/06-client/03-jars.md | 9 +
.../01-components/06-client/README.mdx | 11 +
.../01-components/07-httpfs-gateway/01-overview.md | 19 +
.../01-components/07-httpfs-gateway/README.mdx | 11 +
.../07-system-internals/01-components/README.mdx | 11 +
.../02-data-operations/01-write.md | 36 ++
.../02-data-operations/02-read.md | 28 +
.../02-data-operations/03-delete.md | 25 +
.../02-data-operations/04-hsync.md | 13 +
.../02-data-operations/README.mdx | 11 +
.../03-data-integrity/01-checksums.md | 9 +
.../03-data-integrity/02-container-scanner.md | 3 +
.../03-data-integrity/03-volume-scanner.md | 3 +
.../03-data-integrity/README.mdx | 11 +
.../04-replication/01-metadata.md | 9 +
.../02-data/01-write-pipelines/01-overview.md | 7 +
.../02-data/01-write-pipelines/02-types.md | 9 +
.../02-data/01-write-pipelines/03-states.md | 7 +
.../02-data/01-write-pipelines/04-reports.md | 7 +
.../02-data/01-write-pipelines/05-creation.md | 7 +
.../02-data/01-write-pipelines/06-persistence.md | 9 +
.../02-data/01-write-pipelines/07-destruction.md | 9 +
.../02-data/01-write-pipelines/README.mdx | 11 +
.../02-data/02-containers/01-overview.md | 7 +
.../02-data/02-containers/02-types.md | 9 +
.../02-data/02-containers/03-states.md | 9 +
.../02-data/02-containers/04-reports.md | 7 +
.../02-data/02-containers/05-creation.md | 7 +
.../02-data/02-containers/06-persistence.md | 9 +
.../02-data/02-containers/07-destruction.md | 7 +
.../02-data/02-containers/08-replication.md | 159 ++++++
.../02-containers/09-offline-reconstruction.md | 9 +
.../02-data/02-containers/README.mdx | 11 +
.../02-data/03-replication-manager.md | 277 +++++++++
.../02-data/04-container-balancer.md | 3 +
.../04-replication/02-data/README.mdx | 11 +
.../02-data/container-states-visualized.png | Bin 0 -> 8253598 bytes
.../07-system-internals/04-replication/README.mdx | 11 +
.../07-system-internals/05-security/01-kerberos.md | 124 +++++
.../05-security/02-symmetric-encryption.md | 194 +++++++
.../07-system-internals/05-security/03-tokens.md | 95 ++++
.../05-security/04-certificates.md | 9 +
.../07-system-internals/05-security/05-tls.md | 9 +
.../07-system-internals/05-security/06-sasl.md | 7 +
.../05-security/07-s3-credentials.md | 9 +
.../07-system-internals/05-security/README.mdx | 11 +
.../06-network-protocols/01-overview.md | 9 +
.../06-network-protocols/02-client.md | 23 +
.../06-network-protocols/03-server.md | 22 +
.../06-network-protocols/README.mdx | 11 +
.../07-features/01-filesystem-optimization.md | 61 ++
.../07-features/02-upgrade-downgrade.md | 7 +
.../03-bucket-snapshot-deletion-lifecycle.md | 51 ++
.../07-features/03-bucket-snapshots.md | 11 +
.../07-features/04-erasure-coding.md | 7 +
.../07-features/05-ratis-streaming.md | 9 +
.../07-features/06-snapshot-defragmentation.md | 467 ++++++++++++++++
.../08-om-bootstrapping-with-snapshots.md | 173 ++++++
.../07-features/PrefixFSO-Delete.png | Bin 0 -> 253792 bytes
.../07-features/PrefixFSO-Format.png | Bin 0 -> 270550 bytes
.../07-features/PrefixFSO-Rename.png | Bin 0 -> 227851 bytes
.../07-system-internals/07-features/README.mdx | 11 +
.../version-2.2.1/07-system-internals/README.mdx | 7 +
.../08-developer-guide/01-build/01-maven.md | 160 ++++++
.../08-developer-guide/01-build/02-intellij.md | 9 +
.../01-build/03-docker-images.md | 110 ++++
.../08-developer-guide/01-build/README.mdx | 11 +
.../08-developer-guide/02-run/01-intellij.md | 7 +
.../08-developer-guide/02-run/02-docker-compose.md | 173 ++++++
.../08-developer-guide/02-run/03-kubernetes.md | 63 +++
.../08-developer-guide/02-run/README.mdx | 11 +
.../08-developer-guide/03-test/01-unit-tests.md | 8 +
.../03-test/02-integration-tests.md | 7 +
.../03-test/03-acceptance-tests.md | 138 +++++
.../03-test/04-continuous-integration.md | 14 +
.../03-test/05-static-analysis.md | 180 ++++++
.../08-developer-guide/03-test/README.mdx | 11 +
.../04-project/01-branches-and-tags.md | 13 +
.../04-project/02-release-guide.md | 618 +++++++++++++++++++++
.../08-developer-guide/04-project/03-javadoc.md | 13 +
.../08-developer-guide/04-project/README.mdx | 11 +
.../version-2.2.1/08-developer-guide/README.mdx | 7 +
versioned_sidebars/version-2.2.1-sidebars.json | 8 +
versions.json | 2 +-
359 files changed, 18871 insertions(+), 6 deletions(-)
diff --git a/cspell.yaml b/cspell.yaml
index efbcf2de02..3c7768ae02 100644
--- a/cspell.yaml
+++ b/cspell.yaml
@@ -72,6 +72,7 @@ words:
# Apache Software Foundation words
- ASF
- PMC
+- TBD
# Ozone specific words
- HDDS
- ratis
diff --git a/src/pages/download.md b/src/pages/download.md
index 99276b129c..d96c9c9168 100644
--- a/src/pages/download.md
+++ b/src/pages/download.md
@@ -2,7 +2,7 @@
| Version | Release Date | Source Download | Binary Download [...]
| ------- | ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- [...]
-| 2.2.0 | 2026 Jul 15 | [Source](https://www.apache.org/dyn/closer.cgi/ozone/2.2.0/ozone-2.2.0-src.tar.gz)<br/>[Checksum](https://downloads.apache.org/ozone/2.2.0/ozone-2.2.0-src.tar.gz.sha512)<br/>[Signature](https://downloads.apache.org/ozone/2.2.0/ozone-2.2.0-src.tar.gz.asc) | [Binary](https://www.apache.org/dyn/closer.cgi/ozone/2.2.0/ozone-2.2.0.tar.gz)<br/>[Checksum](https://downloads.apache.org/ozone/2.2.0/ozone-2.2.0.tar.gz.sha512)<br/>[Signature](https://downloads.apache.org/o [...]
+| 2.2.1 | 2026 Aug 27 | [Source](https://www.apache.org/dyn/closer.cgi/ozone/2.2.1/ozone-2.2.1-src.tar.gz)<br/>[Checksum](https://downloads.apache.org/ozone/2.2.1/ozone-2.2.1-src.tar.gz.sha512)<br/>[Signature](https://downloads.apache.org/ozone/2.2.1/ozone-2.2.1-src.tar.gz.asc) | [Binary](https://www.apache.org/dyn/closer.cgi/ozone/2.2.1/ozone-2.2.1.tar.gz)<br/>[Checksum](https://downloads.apache.org/ozone/2.2.1/ozone-2.2.1.tar.gz.sha512)<br/>[Signature](https://downloads.apache.org/o [...]
| 2.1.1 | 2026 Jun 21 | [Source](https://www.apache.org/dyn/closer.cgi/ozone/2.1.1/ozone-2.1.1-src.tar.gz)<br/>[Checksum](https://downloads.apache.org/ozone/2.1.1/ozone-2.1.1-src.tar.gz.sha512)<br/>[Signature](https://downloads.apache.org/ozone/2.1.1/ozone-2.1.1-src.tar.gz.asc) | [Binary](https://www.apache.org/dyn/closer.cgi/ozone/2.1.1/ozone-2.1.1.tar.gz)<br/>[Checksum](https://downloads.apache.org/ozone/2.1.1/ozone-2.1.1.tar.gz.sha512)<br/>[Signature](https://downloads.apache.org/o [...]
| 2.0.0 | 2025 Apr 30 | [Source](https://www.apache.org/dyn/closer.cgi/ozone/2.0.0/ozone-2.0.0-src.tar.gz)<br/>[Checksum](https://downloads.apache.org/ozone/2.0.0/ozone-2.0.0-src.tar.gz.sha512)<br/>[Signature](https://downloads.apache.org/ozone/2.0.0/ozone-2.0.0-src.tar.gz.asc) | [Binary](https://www.apache.org/dyn/closer.cgi/ozone/2.0.0/ozone-2.0.0.tar.gz)<br/>[Checksum](https://downloads.apache.org/ozone/2.0.0/ozone-2.0.0.tar.gz.sha512)<br/>[Signature](https://downloads.apache.org/o [...]
@@ -34,10 +34,10 @@ Finally, verify the signature of the release file.
gpg --verify <file>.asc <file>
```
-For example, to verify the signature of `ozone-2.2.0-src.tar.gz`:
+For example, to verify the signature of `ozone-2.2.1-src.tar.gz`:
```bash
-gpg --verify ozone-2.2.0-src.tar.gz.asc ozone-2.2.0-src.tar.gz
+gpg --verify ozone-2.2.1-src.tar.gz.asc ozone-2.2.1-src.tar.gz
```
### SHA512 Checksums
@@ -48,10 +48,10 @@ To verify the SHA512 checksum, you can use the `sha512sum` command.
sha512sum -c <file>.sha512
```
-For example, to verify the checksum of `ozone-2.2.0-src.tar.gz`:
+For example, to verify the checksum of `ozone-2.2.1-src.tar.gz`:
```bash
-sha512sum -c ozone-2.2.0-src.tar.gz.sha512
+sha512sum -c ozone-2.2.1-src.tar.gz.sha512
```
## License
diff --git a/src/pages/release-notes/2.2.1.md b/src/pages/release-notes/2.2.1.md
new file mode 100644
index 0000000000..2c09780621
--- /dev/null
+++ b/src/pages/release-notes/2.2.1.md
@@ -0,0 +1,92 @@
+# Release 2.2.1 Available
+
+
+
+## Release Notes
+
+Apache Ozone 2.2.1 is a maintenance release on top of Ozone 2.2.0 with bug fixes, performance improvements, and dependency updates.
+
+## Notable Fixes
+
+### [HDDS-15783](https://issues.apache.org/jira/browse/HDDS-15783) — SCM fails to deserialize empty lists from Ratis log
+
+Fixed deserialization failure when SCM Ratis log entries contained empty lists, which could block SCM startup or state replay.
+
+---
+
+### [HDDS-15578](https://issues.apache.org/jira/browse/HDDS-15578) — InvalidStateTransitionException can crash SCM
+
+SCM no longer crashes from uncaught InvalidStateTransitionException during container state updates.
+
+---
+
+### [HDDS-15791](https://issues.apache.org/jira/browse/HDDS-15791) — EC RECOVERING container data loss after idle scrub
+
+Fixed EC offline reconstruction data loss when idle RECOVERING containers were scrubbed and auto-recreated as partial CLOSED replicas.
+
+---
+
+### [HDDS-15849](https://issues.apache.org/jira/browse/HDDS-15849) — gRPC client shutdown slows parallel reads
+
+Fixed a performance regression where gRPC client shutdown blocked the Datanode client cache lock for 100 ms or more per close, causing severe slowdown in parallel read workloads such as EC reconstruction.
+
+---
+
+### [HDDS-15665](https://issues.apache.org/jira/browse/HDDS-15665) — Datanode transaction iterator race condition
+
+Fixed a race condition in the Datanode transaction iterator that could cause already-deleted transactions to be loaded and reprocessed after a flush.
+
+---
+
+### [HDDS-12669](https://issues.apache.org/jira/browse/HDDS-12669) — ContainerSet recoveringContainerMap race condition
+
+Fixed a race condition in ContainerSet#recoveringContainerMap that could cause incorrect container recovery state during Datanode restarts.
+
+---
+
+### [HDDS-15552](https://issues.apache.org/jira/browse/HDDS-15552) — Prometheus scraping fails on Ozone metrics
+
+Fixed Prometheus metrics endpoints failing to scrape Ozone services because Ratis event strings were published as metric names containing invalid characters.
+
+---
+
+### [HDDS-11772](https://issues.apache.org/jira/browse/HDDS-11772) — Recon reports incorrect Ozone used capacity
+
+Fixed incorrect Ozone used capacity reporting in Recon that could show vastly inflated values compared to the actual data written.
+
+---
+
+## Changelog
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+### Fixed
+
+- Fixed SCM deserialization failure for empty lists in Ratis log entries. ([HDDS-15783](https://issues.apache.org/jira/browse/HDDS-15783))
+- Fixed SCM crashes from uncaught InvalidStateTransitionException during container state updates. ([HDDS-15578](https://issues.apache.org/jira/browse/HDDS-15578))
+- Fixed EC offline reconstruction data loss for idle RECOVERING containers. ([HDDS-15791](https://issues.apache.org/jira/browse/HDDS-15791))
+- Fixed gRPC client shutdown performance regression under parallel read workloads. ([HDDS-15849](https://issues.apache.org/jira/browse/HDDS-15849))
+- Fixed Datanode transaction iterator race condition after flush. ([HDDS-15665](https://issues.apache.org/jira/browse/HDDS-15665))
+- Fixed ContainerSet#recoveringContainerMap race condition during Datanode restarts. ([HDDS-12669](https://issues.apache.org/jira/browse/HDDS-12669))
+- Fixed Prometheus metrics scraping failures caused by invalid Ratis event metric names. ([HDDS-15552](https://issues.apache.org/jira/browse/HDDS-15552))
+- Fixed incorrect Ozone used capacity reporting in Recon. ([HDDS-11772](https://issues.apache.org/jira/browse/HDDS-11772))
+
+### Changed
+
+- Upgraded Netty to 4.1.135. ([HDDS-15722](https://issues.apache.org/jira/browse/HDDS-15722))
+- Upgraded Netty to 4.1.136. ([HDDS-15900](https://issues.apache.org/jira/browse/HDDS-15900))
+- Upgraded BouncyCastle to 1.85. ([HDDS-15974](https://issues.apache.org/jira/browse/HDDS-15974))
+- Upgraded Protobuf to 3.25.9. ([HDDS-15674](https://issues.apache.org/jira/browse/HDDS-15674))
+- Upgraded Ratis thirdparty to 1.0.11. ([HDDS-15727](https://issues.apache.org/jira/browse/HDDS-15727))
+
+## Downloads
+
+- [Download tar.gz](https://www.apache.org/dyn/closer.cgi/ozone/2.2.1/ozone-2.2.1.tar.gz) ([checksum](https://downloads.apache.org/ozone/2.2.1/ozone-2.2.1.tar.gz.sha512), [signature](https://downloads.apache.org/ozone/2.2.1/ozone-2.2.1.tar.gz.asc))
+- [Download src](https://www.apache.org/dyn/closer.cgi/ozone/2.2.1/ozone-2.2.1-src.tar.gz) ([checksum](https://downloads.apache.org/ozone/2.2.1/ozone-2.2.1-src.tar.gz.sha512), [signature](https://downloads.apache.org/ozone/2.2.1/ozone-2.2.1-src.tar.gz.asc))
+
+## Documentation
+
+- [Ozone 2.2.1 Documentation](https://ozone.apache.org/docs/2.2.1)
+
+**Release Date:** 2026 Aug 27
diff --git a/versioned_docs/version-2.2.1/01-overview.md b/versioned_docs/version-2.2.1/01-overview.md
new file mode 100644
index 0000000000..6ec52a9879
--- /dev/null
+++ b/versioned_docs/version-2.2.1/01-overview.md
@@ -0,0 +1,103 @@
+---
+# Make this the default docs landing page.
+slug: /
+---
+
+# Overview
+
+## What is Apache Ozone?
+
+Apache Ozone is a scalable, distributed object store designed for lakehouse workloads,
+AI/ML, and cloud-native applications.
+Originating from the BigData analytics ecosystem, it handles both small and large files,
+supporting deployments up to billions of objects and exabytes of capacity.
+Ozone provides strong consistency guarantees,
+multiple protocol interfaces (including S3 compatibility), and configurable durability options.
+
+## What it does?
+
+Ozone includes features relevant to large-scale storage requirements:
+
+### Scale
+
+Ozone's architecture separates metadata management from data storage. The Ozone Manager (OM) and
+Storage Container Manager (SCM) handle metadata operations, while Datanodes manage the physical storage of data blocks.
+This design allows for independent scaling of these components and supports incremental cluster growth.
+
+### Flexible Durability
+
+Ozone offers configurable data durability options per bucket or per object:
+
+- **Replication (RATIS):** Uses 3-way replication via the [Ratis (Raft)](https://ratis.apache.org) consensus protocol for high availability.
+- **Erasure Coding (EC):** Supports various EC codecs (e.g., Reed-Solomon) to reduce storage overhead compared to replication while maintaining specified durability levels.
+
+### Secure
+
+Security features are integrated at multiple layers:
+
+- **Authentication:** Supports Kerberos integration for user and service authentication.
+- **Authorization:** Provides Access Control Lists (ACLs) for managing permissions at the volume, bucket, and key levels. Supports Apache Ranger integration for centralized policy management.
+- **Encryption:** Supports TLS/SSL for data in transit and Transparent Data Encryption (TDE) for data at rest.
+- **Tokens:** Uses delegation tokens and block tokens for access control in distributed operations.
+
+### Performance
+
+Ozone's design considers performance for different access patterns:
+
+- **Throughput:** Intended for streaming reads and writes of large files. Data can be served directly from Datanodes after initial metadata lookup.
+- **Latency:** Metadata operations are managed by OM and SCM, designed for low-latency access.
+- **Small File Handling:** Includes mechanisms for managing metadata and storage for large quantities of small files.
+
+### Multiple Protocols
+
+Applications can access data stored in Ozone through several interfaces:
+
+- **S3 Protocol:** Provides an S3-compatible REST API, allowing use with S3-native applications and tools.
+- **Hadoop Compatible File System (ofs):** Offers the `ofs://` scheme for integration with Hadoop ecosystem tools (e.g., Iceberg, Spark, Hive, Flink, MapReduce).
+- **Native Java Client API:** A client library for Java applications.
+- **Command Line Interface (CLI):** Provides tools for administrative tasks and data interaction.
+
+### Efficient Storage Use
+
+Ozone includes features aimed at optimizing storage utilization:
+
+- **Erasure Coding:** Can reduce the physical storage footprint compared to 3x replication.
+- **Small File Handling:** Manages metadata and block allocation for small files.
+- **Containerization:** Groups data blocks into larger Storage Containers, which can simplify management and disk I/O.
+
+### Storage Management
+
+Ozone uses a hierarchical namespace and provides management tools:
+
+- **Namespace:** Organizes data into Volumes (often mapped to tenants) and Buckets (containers for objects), which hold Keys (objects/files).
+- **Quotas:** Administrators can set storage quotas at the Volume and Bucket levels.
+- **Snapshots:** Supports point-in-time, read-only snapshots of buckets for data protection and versioning.
+
+### Strong Consistency
+
+Ozone provides strong consistency for metadata and data operations. Reads reflect the results of the latest successfully completed write operations.
+
+## Key Characteristics
+
+The design of Ozone leads to certain characteristics relevant for large-scale data management:
+
+### Storage Costs
+
+Factors influencing storage costs include:
+
+- **Storage Efficiency:** Erasure Coding can reduce physical storage requirements.
+- **Hardware:** Designed to run on commodity hardware.
+- **Licensing:** Apache Ozone is open-source software under the Apache License 2.0.
+- **Scalability:** Clusters can be expanded by adding nodes or racks. Data rebalancing mechanisms help manage utilization.
+
+### Operations
+
+Aspects related to storage administration include:
+
+- **Unified Storage:** Can potentially serve as a common storage layer for different types of workloads.
+- **Management Tools:** Includes the Recon web UI for monitoring and CLI tools for administration.
+- **Maintenance:** Supports features like rolling upgrades, node decommissioning, and data balancing.
+
+### Hybrid Cloud Scenarios
+
+Ozone's S3 compatibility allows applications developed for S3 to run on-premises using Ozone. This can be relevant for hybrid cloud strategies or migrating workloads between on-premises and cloud environments.
diff --git a/versioned_docs/version-2.2.1/02-quick-start/01-installation/01-docker.md b/versioned_docs/version-2.2.1/02-quick-start/01-installation/01-docker.md
new file mode 100644
index 0000000000..235c3ad48e
--- /dev/null
+++ b/versioned_docs/version-2.2.1/02-quick-start/01-installation/01-docker.md
@@ -0,0 +1,96 @@
+---
+sidebar_label: Docker
+---
+
+# Try Ozone With Docker
+
+Apache Ozone can be quickly deployed using Docker Compose, making it ideal for development, testing, and evaluation purposes. This guide walks you through setting up a multi-node Ozone cluster using pre-built Docker images.
+
+
+
+## Prerequisites
+
+- [Docker Engine](https://docs.docker.com/engine/install/) - Latest stable version
+- [Docker Compose](https://docs.docker.com/compose/install/) - Latest stable version
+
+## Running Ozone
+
+### Obtain the Docker Compose Configuration
+
+First, obtain Ozone's sample Docker Compose configuration:
+
+```bash
+# Download the latest Docker Compose configuration file
+curl -O https://raw.githubusercontent.com/apache/ozone-docker/refs/heads/latest/docker-compose.yaml
+```
+
+### Start the Cluster
+
+Start your Ozone cluster with three Datanodes using the following command:
+
+```bash
+docker compose up -d --scale datanode=3
+```
+
+This command will:
+
+- Automatically pull required images from Docker Hub
+- Create a multi-node cluster with the core Ozone services
+- Start all components in detached mode
+
+### Verify the Deployment
+
+1. Check the status of your Ozone cluster components:
+
+ ```bash
+ docker compose ps
+ ```
+
+ You should see output similar to this:
+
+ ```bash
+ NAME IMAGE COMMAND SERVICE CREATED STATUS PORTS
+ docker-datanode-1 apache/ozone:1.4.1-rocky "/usr/local/bin/dumb…" datanode 14 seconds ago Up 13 seconds 0.0.0.0:32958->9864/tcp, :::32958->9864/tcp
+ docker-datanode-2 apache/ozone:1.4.1-rocky "/usr/local/bin/dumb…" datanode 14 seconds ago Up 13 seconds 0.0.0.0:32957->9864/tcp, :::32957->9864/tcp
+ docker-datanode-3 apache/ozone:1.4.1-rocky "/usr/local/bin/dumb…" datanode 14 seconds ago Up 12 seconds 0.0.0.0:32959->9864/tcp, :::32959->9864/tcp
+ docker-om-1 apache/ozone:1.4.1-rocky "/usr/local/bin/dumb…" om 14 seconds ago Up 13 seconds 0.0.0.0:9874->9874/tcp, :::9874->9874/tcp
+ docker-recon-1 apache/ozone:1.4.1-rocky "/usr/local/bin/dumb…" recon 14 seconds ago Up 13 seconds 0.0.0.0:9888->9888/tcp, :::9888->9888/tcp
+ docker-s3g-1 apache/ozone:1.4.1-rocky "/usr/local/bin/dumb…" s3g 14 seconds ago Up 13 seconds 0.0.0.0:9878->9878/tcp, :::9878->9878/tcp
+ docker-scm-1 apache/ozone:1.4.1-rocky "/usr/local/bin/dumb…" scm 14 seconds ago Up 13 seconds 0.0.0.0:9876->9876/tcp, :::9876->9876/tcp
+ ```
+
+2. Check the Ozone version
+
+ ```bash
+ docker compose exec om bash
+ ozone version
+ ```
+
+3. Access the Ozone Recon server, which provides monitoring and management capabilities by navigating to the [Recon server home page](http://localhost:9888).
+
+## Configuration
+
+You can customize your Ozone deployment by modifying the configuration parameters in the `docker-compose.yaml` file:
+
+1. **Common Configurations**: Located under the `x-common-config` section
+2. **Service-Specific Settings**: Found under the `environment` section of individual services
+
+As an example, to update the port on which Recon listens to, append the following configuration:
+
+```yaml
+x-common-config:
+ ...
+ OZONE-SITE.XML_ozone.recon.http-address: 0.0.0.0:9090
+```
+
+Refer to the [Configuring Ozone For Production](../../administrator-guide/configuration) page for more configuration guidelines.
+
+## Next Steps
+
+Now that your Ozone cluster is up and running, you can enter any container and explore the environment.
+
+```bash
+docker compose exec om bash
+```
+
+Next, learn how to [read and write data](../reading-writing-data) into Ozone.
diff --git a/versioned_docs/version-2.2.1/02-quick-start/01-installation/02-kubernetes.md b/versioned_docs/version-2.2.1/02-quick-start/01-installation/02-kubernetes.md
new file mode 100644
index 0000000000..d57508b9dd
--- /dev/null
+++ b/versioned_docs/version-2.2.1/02-quick-start/01-installation/02-kubernetes.md
@@ -0,0 +1,132 @@
+---
+sidebar_label: Kubernetes
+---
+
+# Try Ozone With Kubernetes
+
+Ozone is designed to work well under Kubernetes. This document provides a guide for deploying and experimenting with Ozone on K8s, using Helm Chart, MiniKube or a self-hosted Kubernetes cluster.
+
+## Helm Chart
+
+For a streamlined deployment of Apache Ozone on Kubernetes, consider using the [Apache Ozone Helm Chart](https://apache.github.io/ozone-helm-charts/). This Helm Chart simplifies the installation and management of an Ozone cluster by packaging best practices into a set of configurable Kubernetes resources.
+
+1. **Add the Ozone Helm Repository**
+
+ First, add the Apache Ozone Helm repository and update your local Helm repo cache:
+
+ ```bash
+ helm repo add ozone-helm https://apache.github.io/ozone-helm-charts/
+ helm repo update
+ ```
+
+2. Install the Chart
+
+ Install the Ozone Helm Chart using the following command. This command deploys a default Ozone cluster:
+
+ ```bash
+ helm install my-ozone-cluster ozone-helm/ozone
+ ```
+
+3. Customize Your Deployment
+
+ To customize the configuration, create or modify a values.yaml file with your desired settings and install the chart as follows:
+
+ ```bash
+ helm install my-ozone-cluster -f values.yaml ozone-helm/ozone
+ ```
+
+For more detailed documentation and advanced configuration options, please refer to the [Apache Ozone Helm Chart](https://apache.github.io/ozone-helm-charts/) documentation.
+
+## Minikube
+
+### Requirements
+
+- Working minikube setup
+- kubectl
+
+### Deploy the Services
+
+The `kubernetes/examples` directory of the Ozone distribution contains Kubernetes deployment resource files for multiple use cases. By default the Kubernetes resource files are configured to use the [apache/ozone](https://hub.docker.com/r/apache/ozone) image from Docker Hub.
+
+To deploy it to minikube, use the minikube configuration set:
+
+``` bash
+cd kubernetes/examples/minikube
+kubectl apply -k .
+```
+
+And you can check the results with
+
+``` bash
+kubectl get pod
+kubectl exec scm-0 -- ozone version
+```
+
+:::note
+
+the `kubernetes/examples/minikube` resource set is optimized for minikube usage:
+
+- You can have multiple Datanodes even if you have only one host (in a real production cluster usually you need one Datanode per physical host)
+- The services are published with node port
+
+:::
+
+### Access the services
+
+Now you can access any of the services. For each web endpoint an additional NodeType service is defined in the minikube k8s resource set. NodeType services are available via a generated port on any of the host nodes:
+
+``` bash
+kubectl get svc
+NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE
+datanode ClusterIP None <none> <none> 27s
+kubernetes ClusterIP 10.96.0.1 <none> 443/TCP 118m
+om ClusterIP None <none> 9874/TCP 27s
+om-public NodePort 10.108.48.148 <none> 9874:32649/TCP 27s
+s3g ClusterIP None <none> 9878/TCP 27s
+s3g-public NodePort 10.97.133.137 <none> 9878:31880/TCP 27s
+scm ClusterIP None <none> 9876/TCP 27s
+scm-public NodePort 10.105.231.28 <none> 9876:32171/TCP 27s
+```
+
+Minikube provides a convenience command to access any of the NodePort services:
+
+``` bash
+minikube service s3g-public
+Opening kubernetes service default/s3g-public in default browser...
+```
+
+## Hosted Kubernetes Cluster
+
+**Note:** The Kubernetes examples and scripts here have been tested with Kubernetes 1.34.2 (k3s v1.34.2+k3s1).
+
+### Requirements
+
+- Working Kubernetes cluster (LoadBalancer, PersistentVolume are not required)
+- kubectl
+
+### Deploy to Kubernetes
+
+As [apache/ozone](https://hub.docker.com/r/apache/ozone) images are available from Docker Hub, the deployment process is very similar to Minikube deployment. The only big difference is that we have dedicated set of k8s files for hosted clusters (for example we can use one Datanode per host)
+
+To deploy to a hosted cluster, use the Ozone subdirectory:
+
+``` bash
+cd kubernetes/examples/ozone
+kubectl apply -k .
+```
+
+And you can check the results with
+
+``` bash
+kubectl get pod
+kubectl exec scm-0 -- ozone version
+```
+
+### Access the services
+
+Now you can access any of the services. By default the services are not published but you can access them with port-forward rules.
+
+``` bash
+kubectl port-forward s3g-0 9878:9878
+kubectl port-forward scm-0 9876:9876
+```
diff --git a/versioned_docs/version-2.2.1/02-quick-start/01-installation/03-bare-metal.md b/versioned_docs/version-2.2.1/02-quick-start/01-installation/03-bare-metal.md
new file mode 100644
index 0000000000..00fb0ba5f2
--- /dev/null
+++ b/versioned_docs/version-2.2.1/02-quick-start/01-installation/03-bare-metal.md
@@ -0,0 +1,287 @@
+---
+sidebar_label: Bare Metal
+---
+
+# Try Ozone on Bare Metal
+
+This guide covers setting up Apache Ozone on physical or virtual machines. Choose between manual installation or automated deployment using the Ozone Installer tool.
+
+## Ozone Components
+
+1. **Ozone Manager (OM)** - Manages the namespace (volumes, buckets, keys)
+2. **Storage Container Manager (SCM)** - Block manager that provides blocks for data writes
+3. **Datanodes (DN)** - Store containers and handle data read/write operations
+4. **Recon** (Optional) - Management and monitoring interface
+5. **S3 Gateway (S3G)** (Optional) - Provides S3-compatible API access to Ozone
+
+Learn more: [Ozone Architecture Overview](https://ozone.apache.org/docs/edge/concept/overview.html)
+
+## Prerequisites
+
+**All Nodes:**
+
+- Linux OS (RHEL/CentOS 7+, Ubuntu 20.04+)
+- Java 11 or Java 17 (OpenJDK)
+- Minimum 4 GB RAM
+- SSH access
+- Network connectivity between nodes
+
+**For Manual Installation:**
+
+- Root/sudo access on all nodes
+- wget or curl for downloading binaries
+
+**For Automated Installation:**
+
+- **Controller node:** Python 3.10-3.12, Ansible Community 10.x
+- **Managed nodes:** Python 3.7+, sudo access
+
+---
+
+## Method 1: Manual Installation
+
+:::note
+We will be using `/opt/ozone` as the base directory for Ozone configs and binaries, and `/data/ozone` for the application data and metadata in all of our examples. Feel free to use any path as per your environment.
+:::
+
+### Step 1: Install Java
+
+```bash
+jdk_version=11 # or 17
+# RHEL/CentOS/Rocky Linux
+sudo yum install -y java-${jdk_version}-openjdk-devel
+
+# Ubuntu/Debian
+sudo apt-get update
+sudo apt-get install -y openjdk-${jdk_version}-jdk
+
+# Verify installation
+java -version
+```
+
+Set `JAVA_HOME`:
+
+```bash
+# Find Java location
+sudo update-alternatives --config java
+
+# Add to ~/.bashrc or /etc/profile
+export JAVA_HOME=/usr/lib/jvm/java-11-openjdk
+export PATH=$PATH:$JAVA_HOME/bin
+```
+
+### Step 2: Create Service User
+
+```bash
+# Create ozone user and group
+sudo groupadd ozone
+sudo useradd -g ozone -m -s /bin/bash ozone
+
+# Create data directories
+sudo mkdir -p /data/ozone/{metadata,datanode/id,datanode/data}
+sudo chown -R ozone:ozone /data/ozone
+
+# Create installation directory
+sudo mkdir -p /opt/ozone
+sudo chown ozone:ozone /opt/ozone
+```
+
+### Step 3: Download and Extract Ozone
+
+Check [GitHub releases](https://github.com/apache/ozone/releases/latest) for the latest version.
+
+```bash
+# Switch to ozone user
+sudo su - ozone
+
+# Download Ozone (latest: 2.1.0)
+wget https://downloads.apache.org/ozone/2.1.0/ozone-2.1.0.tar.gz
+
+# Extract on all nodes
+tar -xzf ozone-2.1.0.tar.gz -C /opt/
+ln -s /opt/ozone /opt/ozone-2.1.0
+cd /opt/ozone
+```
+
+### Step 4: Generate and Configure
+
+```bash
+# Generate configuration template
+bin/ozone genconf /opt/ozone/etc/hadoop/
+```
+
+Edit `/opt/ozone/etc/hadoop/ozone-site.xml`:
+
+```xml
+<configuration>
+ <property>
+ <name>ozone.metadata.dirs</name>
+ <value>/data/ozone/metadata</value>
+ </property>
+
+ <property>
+ <name>ozone.scm.names</name>
+ <value>scm-host.example.com</value>
+ </property>
+
+ <property>
+ <name>ozone.om.address</name>
+ <value>om-host.example.com</value>
+ </property>
+
+ <property>
+ <name>ozone.scm.datanode.id.dir</name>
+ <value>/data/ozone/datanode/id</value>
+ </property>
+
+ <property>
+ <name>hdds.datanode.dir</name>
+ <value>/data/ozone/datanode/data</value>
+ </property>
+
+ <property>
+ <name>ozone.replication</name>
+ <value>3</value>
+ <!-- Use 1 for single node deployment -->
+ </property>
+
+ <!-- Optional: S3 Gateway Configuration -->
+ <property>
+ <name>ozone.s3g.http-address</name>
+ <value>0.0.0.0:9878</value>
+ </property>
+</configuration>
+```
+
+**Configuration Resources:**
+
+- [Configuration Properties Reference](https://ozone.apache.org/docs/edge/start/onprem.html#ozone-settings-summary)
+- [Network Ports Reference](https://ozone.apache.org/docs/edge/concept/ports.html)
+- [S3 Gateway Setup Guide](https://ozone.apache.org/docs/edge/interface/s3.html)
+- [Security Configuration](https://ozone.apache.org/docs/edge/security/secureozone.html)
+- [High Availability Setup](https://ozone.apache.org/docs/edge/feature/om-ha.html)
+
+Copy `ozone-site.xml` to all nodes.
+
+### Step 5: Initialize Services
+
+```bash
+# On SCM node (as ozone user)
+bin/ozone scm --init
+
+# On OM node (requires SCM to be running)
+bin/ozone om --init
+```
+
+### Step 6: Start Services
+
+```bash
+# Start SCM (on SCM node, as ozone user)
+bin/ozone --daemon start scm
+
+# Start OM (on OM node, as ozone user)
+bin/ozone --daemon start om
+
+# Start Datanodes (on all datanode nodes, as ozone user)
+bin/ozone --daemon start datanode
+
+# Optional: Start Recon (on Recon node, as ozone user)
+bin/ozone --daemon start recon
+
+# Optional: Start S3 Gateway (on S3G node, as ozone user)
+bin/ozone --daemon start s3g
+```
+
+### Step 7: Verify Installation
+
+```bash
+# Check running processes
+jps
+# Should list all ozone process
+
+# Test basic operations
+bin/ozone sh volume create /vol1
+bin/ozone sh bucket create /vol1/bucket1
+echo "Hello Ozone" > /tmp/test.txt
+bin/ozone sh key put /vol1/bucket1/key1 /tmp/test.txt
+bin/ozone sh key list /vol1/bucket1
+```
+
+### Stop Services (when needed)
+
+```bash
+bin/ozone --daemon stop s3g
+bin/ozone --daemon stop datanode
+bin/ozone --daemon stop om
+bin/ozone --daemon stop scm
+bin/ozone --daemon stop recon
+```
+
+---
+
+## Method 2: Automated Installation (Recommended)
+
+The [ozone-installer](https://github.com/apache/ozone-installer) is an Ansible-based tool that automates Ozone deployment. It handles Java installation, user creation, and all configuration steps automatically.
+
+### Installation Steps
+
+**1. Clone and setup:**
+
+```bash
+git clone https://github.com/apache/ozone-installer.git
+cd ozone-installer
+pip install -r requirements.txt
+```
+
+**2. Run the installer:**
+
+```bash
+# Single node
+python3 ozone_installer.py -H hostname.example.com -v 2.1.0
+
+# Multi-node (HA with 3+ hosts)
+python3 ozone_installer.py -H "host{1..5}.example.com" -v 2.1.0
+
+# Using host file
+python3 ozone_installer.py -F hosts.txt -v 2.1.0
+
+# Specify Python interpreter (if needed)
+python3 ozone_installer.py -H hosts -v 2.1.0 --python-interpreter /usr/bin/python3.9
+
+# Cleanup and reinstall
+python3 ozone_installer.py --clean -H hosts -v 2.1.0
+```
+
+### What Gets Installed
+
+**Automated setup includes:**
+
+- Java 11 or 17 installation (if not present)
+- Service user (`ozone`) creation
+- Directory structure setup
+- Ozone binary installation and configuration
+- S3 Gateway setup
+
+**Non-HA (1-2 nodes):**
+
+- First host: OM + SCM + Recon (+ S3G if enabled)
+- All hosts: Datanodes
+
+**HA (3+ nodes):**
+
+- First 3 hosts: OM + SCM (HA)
+- First host: Recon + S3G (if enabled)
+- All hosts: Datanodes
+
+**Default paths:**
+
+- Install: `/opt/ozone`
+- Data: `/data/ozone`
+- Service user: `ozone:ozone`
+
+**For more details, see the [ozone-installer repository](https://github.com/apache/ozone-installer).**
+
+## References
+
+- [Single Node Deployment Guide](https://cwiki.apache.org/confluence/display/OZONE/Single+Node+Deployment)
+- [Ozone Installer on GitHub](https://github.com/apache/ozone-installer)
diff --git a/versioned_docs/version-2.2.1/02-quick-start/01-installation/README.mdx b/versioned_docs/version-2.2.1/02-quick-start/01-installation/README.mdx
new file mode 100644
index 0000000000..cbf05164be
--- /dev/null
+++ b/versioned_docs/version-2.2.1/02-quick-start/01-installation/README.mdx
@@ -0,0 +1,11 @@
+---
+sidebar_label: Installation
+---
+
+# Ozone Installation Quick Start
+
+import DocCardList from '@theme/DocCardList';
+
+This section provides instructions to quickly install an Ozone instance on your local machine that can be used for testing and evaluation. For instructions to install a production Ozone instance, see the [Administrator Guide](../../administrator-guide/installation).
+
+<DocCardList/>
diff --git a/versioned_docs/version-2.2.1/02-quick-start/01-installation/quickstart.gif b/versioned_docs/version-2.2.1/02-quick-start/01-installation/quickstart.gif
new file mode 100644
index 0000000000..60d5c69d04
Binary files /dev/null and b/versioned_docs/version-2.2.1/02-quick-start/01-installation/quickstart.gif differ
diff --git a/versioned_docs/version-2.2.1/02-quick-start/02-reading-writing-data.md b/versioned_docs/version-2.2.1/02-quick-start/02-reading-writing-data.md
new file mode 100644
index 0000000000..e9238129df
--- /dev/null
+++ b/versioned_docs/version-2.2.1/02-quick-start/02-reading-writing-data.md
@@ -0,0 +1,348 @@
+# Reading and Writing Data in Ozone
+
+Apache Ozone provides multiple interfaces for reading and writing data, catering to different use cases and client
+preferences. This guide explains how to use the three primary interfaces within a Docker environment:
+
+1. **Ozone Shell (`ozone sh`)** - The native command-line interface
+2. **ofs (Ozone File System)** - Hadoop-compatible file system interface
+3. **S3 API** - Amazon S3 compatible REST interface
+
+All examples assume you already have a running Ozone cluster using Docker Compose as described in
+the [Docker Installation Guide](./installation/docker).
+
+Let's start 5 Datanodes because the Erasure Coding example below requires at least 5 replicas:
+
+```bash
+docker compose up -d --scale datanode=5
+```
+
+## Interface Comparison
+
+| Interface | Strengths | Use Cases |
+|:----------------|:----------------------------------------------------------------------------------------|:---------------------------------------------------------------------------|
+| **Ozone Shell** | - Full feature access Advanced operations Detailed metadata | - Administrative tasks Bucket/volume management Quota/ACL management |
+| **ofs** | - Familiar HDFS-like commands Works with existing Hadoop applications Full cluster view | - Hadoop ecosystem integration Applications that need filesystem semantics |
+| **S3 API** | - Industry standard Works with existing S3 clients Language-independent | - Web applications Multi-language environments Existing S3 applications |
+
+## Using Ozone Shell (ozone sh)
+
+The Ozone Shell provides direct access to all Ozone features through a command-line interface. All commands follow the
+pattern:
+
+```bash
+ozone sh <object-type> <action> <path> [options]
+```
+
+Where `<object-type>` is `volume`, `bucket`, or `key`.
+
+### Accessing the Ozone Shell
+
+To use the Ozone Shell in your Docker environment, execute commands inside the `om` container:
+
+```bash
+# Example for Docker Compose
+docker compose exec om bash
+
+# Now you can run 'ozone sh' commands
+```
+
+### Working with Volumes
+
+Volumes are the top-level namespace in Ozone.
+
+```bash
+# Create a volume
+ozone sh volume create /vol1
+
+# List all volumes
+ozone sh volume list /
+
+# Get volume details
+ozone sh volume info /vol1
+
+# Delete a volume (must be empty)
+ozone sh volume delete /vol1
+
+# Delete a volume recursively (deletes all buckets and keys within the volume, then the volume itself)
+# WARNING: No recovery option after using this command, and no trash for FSO buckets. Requires confirmation.
+ozone sh volume delete -r /vol1
+```
+
+### Working with Buckets
+
+First, create a volume (skip this step if the `volume` vol1 exists)
+
+```bash
+ozone sh volume create /vol1
+```
+
+Buckets are containers for keys (objects) within volumes.
+
+```bash
+# Create a bucket
+ozone sh bucket create /vol1/bucket1
+
+# List all buckets in a volume
+ozone sh bucket list /vol1
+
+# Get bucket details
+ozone sh bucket info /vol1/bucket1
+
+# Delete a bucket (must be empty)
+ozone sh bucket delete /vol1/bucket1
+
+# Delete a bucket recursively (deletes all keys within the bucket, then the bucket itself)
+# WARNING: No recovery option, deleted keys won't move to trash. Requires confirmation.
+ozone sh bucket delete -r /vol1/bucket1
+```
+
+### Working with Keys (Objects)
+
+First, create a bucket (skip this step if the bucket bucket1 exists)
+
+```bash
+ozone sh bucket create /vol1/bucket1
+```
+
+Keys are the actual data objects stored in Ozone.
+
+```bash
+# Create a test file locally
+echo "Hello Ozone via Shell" > test_shell.txt
+
+# Upload a file (put source to destination)
+ozone sh key put /vol1/bucket1/test_shell.txt test_shell.txt
+
+# Upload with specific replication type
+# For RATIS: use -r ONE or THREE
+ozone sh key put -t RATIS -r THREE /vol1/bucket1/key1_ratis test_shell.txt
+# For EC: use format CODEC-DATA-PARITY-CHUNKSIZE (e.g., rs-3-2-1024k, rs-6-3-1024k, rs-10-4-1024k)
+ozone sh key put -t EC -r rs-3-2-1024k /vol1/bucket1/key1_ec test_shell.txt
+
+# Download a file (get source to destination)
+ozone sh key get /vol1/bucket1/test_shell.txt ./downloaded_shell.txt
+
+# Force overwrite when downloading (use -f or --force)
+ozone sh key get --force /vol1/bucket1/test_shell.txt ./downloaded_shell.txt
+
+# Get key information
+ozone sh key info /vol1/bucket1/test_shell.txt
+
+# List keys in a bucket
+ozone sh key list /vol1/bucket1
+
+# Copy a key within Ozone (not directly supported, use put/get or other interfaces)
+
+# Rename a key
+ozone sh key rename /vol1/bucket1 test_shell.txt renamed_shell.txt
+
+# Delete a key
+ozone sh key delete /vol1/bucket1/renamed_shell.txt
+
+# Note: In FSO buckets, deleted keys are moved to trash at /<volume>/<bucket>/.Trash/<user>
+# In OBS buckets, deletion is permanent.
+```
+
+## Using ofs (Ozone File System)
+
+ ofs provides a Hadoop-compatible file system interface (`ofs://`), making it seamless to use with applications designed
+for HDFS.
+
+### Basic ofs Operations
+
+ofs uses standard Hadoop filesystem commands.
+
+```bash
+# Create volume and bucket (using filesystem semantics)
+ozone fs -mkdir -p ofs://om/vol1/bucketofs
+
+# Upload a file
+echo "Hello from OFS" > local_ofs.txt
+ozone fs -put local_ofs.txt ofs://om/vol1/bucketofs/
+
+# Copy from local with explicit destination path
+ozone fs -copyFromLocal local_ofs.txt ofs://om/vol1/bucketofs/remote_file.txt
+
+# List files in a bucket
+ozone fs -ls ofs://om/vol1/bucketofs/
+
+# List recursively (lists all keys under /vol1/bucketofs)
+ozone fs -ls -R ofs://om/vol1/bucketofs/
+
+# Download a file
+ozone fs -get ofs://om/vol1/bucketofs/local_ofs.txt ./downloaded_ofs.txt
+
+# Display file contents
+ozone fs -cat ofs://om/vol1/bucketofs/local_ofs.txt
+
+# Move a file (rename)
+ozone fs -mv ofs://om/vol1/bucketofs/local_ofs.txt ofs://om/vol1/bucketofs/moved_ofs.txt
+
+# Copy a file within the filesystem
+ozone fs -cp ofs://om/vol1/bucketofs/moved_ofs.txt ofs://om/vol1/bucketofs/copy_ofs.txt
+
+# Delete a file (moves to trash if enabled and bucket is FSO)
+ozone fs -rm ofs://om/vol1/bucketofs/copy_ofs.txt
+
+# Delete a file and skip trash (permanently delete without moving to trash)
+ozone fs -rm -skipTrash ofs://om/vol1/bucketofs/moved_ofs.txt
+
+# Create an empty file
+ozone fs -touchz ofs://om/vol1/bucketofs/empty_file.txt
+```
+
+### Advanced ofs Operations
+
+```bash
+# Get file checksum
+ozone fs -checksum ofs://om/vol1/bucketofs/empty_file.txt
+```
+
+## Using S3 API
+
+The S3 API provides compatibility with applications designed for Amazon S3. It's accessible via the S3 Gateway service,
+typically running on port `9878` in the Docker setup.
+
+### S3 Credentials
+
+In the default non-secure Docker setup, you can use any values for credentials.
+
+```bash
+# Set environment variables (can be done outside the containers)
+export AWS_ACCESS_KEY_ID=testuser
+export AWS_SECRET_ACCESS_KEY=testuser-secret
+export AWS_ENDPOINT_URL=http://s3g:9878
+```
+
+*(Note: Setting `AWS_ENDPOINT_URL` simplifies the `aws` commands below)*
+
+### Using AWS CLI
+
+The AWS CLI can be used from your local machine (if installed) or from within a container that has it.
+
+```bash
+# Ensure AWS CLI is installed locally or use a container with it.
+
+# Create a bucket (maps to /s3v/<bucket-name> in Ozone namespace)
+aws s3api create-bucket --bucket=s3bucket
+
+# List buckets
+aws s3api list-buckets
+
+# Upload a file
+echo "Hello S3" > s3_test.txt
+aws s3 cp s3_test.txt s3://s3bucket/
+
+# List objects in a bucket
+aws s3 ls s3://s3bucket/
+
+# Download a file
+aws s3 cp s3://s3bucket/s3_test.txt ./downloaded_s3.txt
+
+# Delete an object
+aws s3 rm s3://s3bucket/s3_test.txt
+
+# Delete a bucket (must be empty)
+aws s3api delete-bucket --bucket=s3bucket
+```
+
+## Cross-Interface Operations
+
+Ozone allows accessing the same data through different interfaces.
+
+### Namespace Mapping
+
+| Data Location | Ozone Shell Path | ofs Path | S3 Path |
+|:----------------------|:-------------------------|:-------------------------------------------------|:---------------------------------------------------------------|
+| vol1/bucket1/file.txt | `/vol1/bucket1/file.txt` | `ofs://<ozone service id>/vol1/bucket1/file.txt` | `s3://bucket1/file.txt` <br/>(if S3V configured to serve vol1) |
+| s3v/s3bucket/file.txt | `/s3v/s3bucket/file.txt` | `ofs://<ozone service id>/s3v/s3bucket/file.txt` | `s3://s3bucket/file.txt` |
+
+*(Note: `om` in `ofs://` path refers to the Ozone Manager service address)*
+
+### Accessing S3 Data via Ozone Shell/ofs
+
+Objects created via S3 reside in the special `/s3v` volume.
+
+#### Access via Ozone Shell (inside OM/client container)
+
+```bash
+# Assuming 's3bucket' was created via S3 API and contains 's3_test.txt'
+
+docker compose exec om bash
+ozone sh key list /s3v/s3bucket
+ozone sh key get /s3v/s3bucket/s3_test.txt /tmp/from_s3.txt
+exit
+```
+
+#### Access via ofs (inside OM/client container)
+
+Create a FSO bucket in the /s3v
+
+```bash
+ozone sh bucket create /s3v/fsobucket --layout fso
+```
+
+Upload a file using AWS CLI
+
+```bash
+aws s3 cp s3_test.txt s3://fsobucket/
+```
+
+Access the file via ofs
+
+```bash
+
+ozone fs -ls ofs://om/s3v/fsobucket/
+
+ozone fs -cat ofs://om/s3v/fsobucket/s3_test.txt
+
+```
+
+### Exposing Non-S3 Buckets via S3 (Bucket Linking)
+
+You can make buckets created outside `/s3v` accessible via the S3 Gateway using links.
+
+```bash
+# Inside om/client container
+docker compose exec om bash
+
+# Create a regular bucket
+ozone sh volume create /myvol
+ozone sh bucket create /myvol/mybucket
+
+# Create an S3-accessible link (target must exist, link name becomes S3 bucket name)
+ozone sh bucket link /myvol/mybucket /s3v/linkedbucket
+exit
+
+# Now access 'linkedbucket' via S3 CLI (outside container)
+aws s3 cp local_file.txt s3://linkedbucket/
+aws s3 ls s3://linkedbucket/
+```
+
+### Bucket Layouts (FSO vs OBS)
+
+Ozone buckets can have different internal layouts:
+
+1. **FILE_SYSTEM_OPTIMIZED (FSO):** Default. Better for hierarchical operations (like `ozone fs -mkdir`), supports trash
+ for `ozone fs -rm`. Recommended for Hadoop/filesystem workloads.
+2. **OBJECT_STORE (OBS):** Legacy layout. May offer slight performance benefits for flat object access patterns. No
+ trash support.
+
+```bash
+# Create buckets with specific layouts (inside om/client container)
+# Short form
+ozone sh bucket create /vol1/fsobucket --layout fso
+ozone sh bucket create /vol1/obsbucket --layout obs
+
+# Long form
+# ozone sh bucket create /vol1/fsobucket --layout FILE_SYSTEM_OPTIMIZED
+# ozone sh bucket create /vol1/obsbucket --layout OBJECT_STORE
+```
+
+Most operations work on both, but FSO is generally preferred unless specific OBS characteristics are needed.
+
+## Summary
+
+You have learned how to perform basic read/write operations in Ozone using three different interfaces: Ozone Shell, ofs,
+and the S3 API. Each interface has its strengths, and Ozone's multi-protocol design allows you to choose the best tool
+for the job while accessing the same underlying data.
diff --git a/versioned_docs/version-2.2.1/02-quick-start/README.mdx b/versioned_docs/version-2.2.1/02-quick-start/README.mdx
new file mode 100644
index 0000000000..66546a4e42
--- /dev/null
+++ b/versioned_docs/version-2.2.1/02-quick-start/README.mdx
@@ -0,0 +1,11 @@
+---
+sidebar_label: Quick Start
+---
+
+# Quick Start
+
+import DocCardList from '@theme/DocCardList';
+
+This section provides instructions to quickly start an Ozone instance on your local machine and run basic operations against it.
+
+<DocCardList/>
diff --git a/versioned_docs/version-2.2.1/03-core-concepts/01-architecture/01-overview.md b/versioned_docs/version-2.2.1/03-core-concepts/01-architecture/01-overview.md
new file mode 100644
index 0000000000..d83884646b
--- /dev/null
+++ b/versioned_docs/version-2.2.1/03-core-concepts/01-architecture/01-overview.md
@@ -0,0 +1,47 @@
+---
+sidebar_label: Overview
+---
+
+# Overview
+
+Ozone is a fault-tolerant, distributed object store optimized for Big Data workloads. Its primary design goal is scalability, aiming to support billions of objects.
+
+Ozone achieves better scalability by separating namespace management from block space management.
+
+- The **Ozone Manager (OM)** daemon handles namespace-related tasks, like managing volumes, buckets, and keys.
+- The **Storage Container Manager (SCM)** manages the physical storage layer, including the data nodes and the blocks that form the data.
+
+## Core Components
+
+The block diagram below illustrates Ozone's main components and their interactions.
+
+
+
+- **Clients** interact with Ozone to read and write data.
+- The **Ozone Manager (OM)** acts as the namespace manager. It handles client requests for creating, deleting, or looking up keys.
+- The **Storage Container Manager (SCM)** is the manager of the physical data layer. It manages the **Datanodes** and the replication of data.
+- **Datanodes** are responsible for storing the actual data, which is organized into logical units called **blocks**.
+- **Recon** is a management server for Ozone. It provides a user interface and API to monitor and manage the Ozone cluster.
+
+## Namespace and Storage
+
+Ozone's namespace is organized into a hierarchy of volumes, buckets, and keys.
+
+- **Volumes** are similar to home directories and can only be created by an administrator. They are the basis for storage accounting.
+- **Buckets** are contained within volumes. Users can create many buckets within a volume.
+- **Keys** hold the actual data and reside within buckets.
+
+This separation of the logical namespace from the physical storage layer is a key aspect of Ozone's scalability.
+
+## Functional Layers
+
+Another way to understand Ozone is by looking at its functional layers.
+
+
+
+- The **Metadata Management Layer** is composed of the Ozone Manager and Storage Container Manager.
+- The **Data Storage Layer** consists of the Datanodes, which are managed by SCM. Data is stored in logical blocks, which are grouped into containers for replication.
+- The **Replication Layer** is powered by [Ratis](../replication/ratis), a Java-based implementation of the Raft consensus protocol. Ratis ensures that metadata is reliably replicated across OM and SCM instances and maintains data consistency during write operations on the Datanodes.
+- The **Protocol Bus** allows Ozone to be extended with different protocols. Currently, it supports an S3-compatible protocol. This bus allows new object store or file system protocols to be implemented on top of Ozone's native protocol.
+
+This layered architecture, combined with a clear separation of metadata and data management, allows Ozone to scale to handle billions of objects while maintaining high performance and fault tolerance.
diff --git a/versioned_docs/version-2.2.1/03-core-concepts/01-architecture/02-ozone-manager.md b/versioned_docs/version-2.2.1/03-core-concepts/01-architecture/02-ozone-manager.md
new file mode 100644
index 0000000000..19cb5c3acd
--- /dev/null
+++ b/versioned_docs/version-2.2.1/03-core-concepts/01-architecture/02-ozone-manager.md
@@ -0,0 +1,99 @@
+---
+sidebar_label: Ozone Manager
+---
+
+# Ozone Manager
+
+
+
+Ozone Manager (OM) is the namespace manager for Ozone.
+
+This means that when you want to write some data, you ask Ozone Manager for a block and Ozone Manager gives you a block and remembers that information. When you want to read that file back, you need to find the address of the block and the Ozone Manager returns it to you.
+
+Ozone Manager also allows users to organize keys under a volume and bucket. Volumes and buckets are part of the namespace and managed by Ozone Manager.
+
+Each Ozone volume is the root of an independent namespace under OM. This is very different from HDFS which provides a single rooted file system.
+
+Ozone's namespace is a collection of volumes or is a forest instead of a single rooted tree as in HDFS. This property makes it easy to deploy multiple OMs for scaling(pending future development).
+
+## Ozone Manager Metadata
+
+OM maintains a list of volumes, buckets, and keys. For each user, it maintains a list of volumes. For each volume, the list of buckets and for each bucket the list of keys.
+
+Ozone Manager will use [Apache Ratis](https://ratis.apache.org/) (A Raft protocol implementation) to replicate Ozone Manager state. <!-- TODO: Link to OM HA page when created --> This will ensure High Availability for Ozone Manager.
+
+## Ozone Manager and Storage Container Manager
+
+<!-- TODO: Link to SCM page when created --> The relationship between Ozone Manager and Storage Container Manager (SCM) is best understood if we trace what happens during a key write and key read.
+
+### Key Write
+
+
+
+- To write a key to Ozone, a client tells Ozone Manager that it would like to write a key into a bucket that lives inside a specific volume. Once Ozone Manager determines that you are allowed to write a key to the specified bucket, OM needs to allocate a block for the client to write data.
+
+- To allocate a block, Ozone Manager sends a request to Storage Container Manager (SCM); <!-- TODO: Link to Datanodes page when created --> SCM is the manager of data nodes. SCM picks three data nodes into which client can write data. SCM allocates the block and returns the block ID to Ozone Manager.
+
+- Ozone Manager records this block information in its metadata and returns the block and a <!-- TODO: Link to block token/security page when created --> block token (a security permission to write data to the block) to the client.
+
+- The client uses the block token to prove that it is allowed to write data to the block and writes data to the data node.
+
+- Once the write is complete on the data node, the client will update the block information on Ozone Manager.
+
+### Key Reads
+
+
+
+- Key reads are simpler, the client requests the block list from the Ozone Manager
+- Ozone Manager will return the block list and block tokens which allows the client to read the data from data nodes.
+- Client connects to the data node and presents the block token and reads the data from the data node.
+
+## Main Components of the Ozone Manager
+
+For a detailed view of Ozone Manager this section gives a quick overview about the provided network services and the stored persisted data.
+
+### Network Services Provided by Ozone Manager
+
+Ozone provides a network service for the client and for administration commands. The main service calls:
+
+- Key, Bucket, Volume / CRUD
+- Multipart upload (Initiate, Complete…)
+ - Supports upload of huge files in multiple steps
+- FS related calls (optimized for hierarchical queries instead of a flat ObjectStore namespace)
+ - GetFileStatus, CreateDirectory, CreateFile, LookupFile
+- ACL related
+ - Managing ACLs if [Native ACLs](../security/acls/native-acls) are used instead of [Ranger ACLs](../security/acls/ranger-acls)
+- <!-- TODO: Link to delegation token/security page when created --> Delegation token (Get / Renew / Cancel)
+ - For security
+- Admin APIs
+ - Get S3 secret
+ - ServiceList (used for service discovery)
+ - <!-- TODO: Link to Recon page when created --> DBUpdates (used by Recon downloads snapshots)
+
+### Persisted State
+
+The following data is persisted in Ozone Manager side in a specific RocksDB directory:
+
+- Volume / Bucket / Key tables
+ - This is the main responsibility of OM
+ - Key metadata contains the block id (which includes container id) to find the data
+- OpenKey table
+ - for keys which are created, but not yet committed
+- Delegation token table
+ - for security
+- PrefixInfo table
+ - specific index table to store directory level ACL and to provide better performance for hierarchical queries
+- S3 secret table
+ - For S3 secret management
+- Multipart info table
+ - Inflight uploads should be tracked
+- Deleted table
+ - To track the blocks which should be deleted from the Datanodes
+
+## Notable Configurations
+
+| Key | Default | Description |
+|-----|---------|-------------|
+| `ozone.om.address` | 0.0.0.0:9862 | RPC address of the OM. Required by the client. |
+| `ozone.om.http-address` | 0.0.0.0:9874 | Default port of the HTTP server. |
+| `ozone.metadata.dirs` | none | Directory to store persisted data (RocksDB). |
diff --git a/versioned_docs/version-2.2.1/03-core-concepts/01-architecture/03-storage-container-manager.md b/versioned_docs/version-2.2.1/03-core-concepts/01-architecture/03-storage-container-manager.md
new file mode 100644
index 0000000000..6bf6123b2d
--- /dev/null
+++ b/versioned_docs/version-2.2.1/03-core-concepts/01-architecture/03-storage-container-manager.md
@@ -0,0 +1,97 @@
+---
+sidebar_label: Storage Container Manager
+---
+
+# Storage Container Manager
+
+Storage Container Manager (SCM) is the leader node of the *block space management*.
+The main responsibility is to create and manage [containers](../replication/storage-containers) which is the main replication unit of Ozone.
+
+
+
+## Main responsibilities
+
+Storage Container Manager provides multiple critical functions for the Ozone cluster.
+SCM acts as the cluster manager, Certificate authority, Block manager and the Replica manager.
+
+SCM is in charge of creating an Ozone cluster. When an SCM is booted up via `init` command, SCM creates the cluster identity and root certificates needed for the SCM certificate authority. SCM manages the life cycle of a data node in the cluster.
+
+1. SCM is the block manager. SCM allocates blocks and assigns them to data nodes. Clients read and write these blocks directly.
+
+2. SCM keeps track of all the block replicas. If there is a loss of data node or a disk, SCM detects it and instructs data nodes to make copies of the missing blocks to ensure high availability.
+
+3. **SCM's Certificate Authority** is in
+charge of issuing identity certificates for each and every
+service in the cluster. This certificate infrastructure makes
+it easy to enable mTLS at network layer and the block
+token infrastructure depends on this certificate infrastructure.
+
+## Main components
+
+For a detailed view of Storage Container Manager this section gives a quick overview about the provided network services and the stored persisted data.
+
+### Network services provided by Storage Container Manager
+
+- Pipelines: List/Delete/Activate/Deactivate
+ - Pipelines are set of Datanodes to form replication groups
+ - Raft groups are planned by SCM
+- Containers: Create / List / Delete containers
+- Admin related requests
+- Safemode status/modification
+- Replication manager start / stop
+- CA authority service
+- Required by other sever components
+- Datanode HeartBeat protocol
+ - From Datanode to SCM (30 sec by default)
+ - Datanodes report the status of containers, node...
+ - SCM can add commands to the response
+
+:::note
+Client doesn't connect directly to the SCM.
+:::
+
+### Persisted state
+
+The following data is persisted in Storage Container Manager side in a specific RocksDB directory
+
+- Pipelines
+ - Replication group of servers. Maintained to find a group for new container/block allocations.
+- Containers
+ - Containers are the replication units. Data is required to act in case of data under/over replicated.
+- Deleted blocks
+ - Block data is deleted in the background. Need a list to follow the progress.
+- Valid cert
+- Used by the internal Certificate Authority to authorize other Ozone services
+
+## Safe Mode
+
+SCM (Storage Container Manager) enters safe mode on startup. This is a protective state that allows the system to become stable before it becomes fully operational. During safe mode, certain operations like block allocation are restricted.
+
+### How to Exit Safe Mode
+
+There are two ways to exit safe mode:
+
+1. **Automatic Exit:** SCM will automatically exit safe mode when a set of predefined `SafeModeExitRule`s are satisfied. These rules ensure that the cluster is in a healthy state. The primary rules are:
+ - **`DataNodeSafeModeRule`**: Checks if a minimum number of Datanodes have registered with the SCM. This is configured by `hdds.scm.safemode.min.datanode` (default: `3`).
+ - **`RatisContainerSafeModeRule`**: Checks if a certain percentage of containers with at least one replica reported are available. This is configured by `hdds.scm.safemode.threshold.pct` (default: `0.99`).
+ - **`HealthyPipelineSafeModeRule`**: Checks if a certain percentage of pipelines are healthy. This is configured by `hdds.scm.safemode.healthy.pipeline.pct` (default: `0.10`).
+ - **`OneReplicaPipelineSafeModeRule`**: Checks if a certain percentage of pipelines have at least one replica reported. This is configured by `hdds.scm.safemode.atleast.one.node.reported.pipeline.pct` (default: `0.90`).
+ - **`ECContainerSafeModeRule`**: Checks if a certain percentage of erasure coded block groups are healthy. This is also configured by `hdds.scm.safemode.threshold.pct` (default: `0.99`).
+
+2. **Manual Exit:** You can force SCM to exit safe mode using the `ozone admin safemode --force-exit` command.
+
+### Safe Mode Pre-Check
+
+There's also a "pre-check" phase. SCM will not exit safe mode until all pre-check rules are satisfied.
+The `DataNodeSafeModeRule` is a pre-check rule.
+This means that SCM will wait for a minimum number of Datanodes to be available before it even considers the other conditions for exiting safe mode.
+
+## Notable configurations
+
+| Key | Default | Description |
+| --- | ------- | ----------- |
+| `ozone.scm.container.size` | 5GB | Default container size used by Ozone |
+| `ozone.scm.block.size` | 256MB | The default size of a data block. |
+| `hdds.scm.safemode.min.datanode` | 3 | Minimum number of Datanodes to start the real work. |
+| `ozone.scm.http-address` | 0.0.0.0:9876 | HTTP address of the SCM server |
+| `ozone.metadata.dirs` | none | Directory to store persisted data (RocksDB). |
diff --git a/versioned_docs/version-2.2.1/03-core-concepts/01-architecture/04-s3-gateway.md b/versioned_docs/version-2.2.1/03-core-concepts/01-architecture/04-s3-gateway.md
new file mode 100644
index 0000000000..a5c2ad9e79
--- /dev/null
+++ b/versioned_docs/version-2.2.1/03-core-concepts/01-architecture/04-s3-gateway.md
@@ -0,0 +1,111 @@
+---
+sidebar_label: Ozone S3 Gateway
+---
+
+# Ozone S3 Gateway
+
+Apache Ozone’s S3 Gateway (often called **S3G**) is a component that provides an Amazon S3-compatible REST interface for Ozone’s object store.
+In essence, it allows any S3 client or tool to read and write data in Ozone as if it were talking to AWS S3.
+The S3 Gateway runs as a **separate, stateless service** on top of Ozone, translating HTTP S3 API calls into Ozone’s native storage operations.
+
+This design lets users leverage the rich ecosystem of S3-compatible applications with Ozone, without modifying those applications.
+
+## High-Level Overview of the S3 Gateway
+
+Ozone’s S3 Gateway acts as a **REST front-end** that speaks the S3 protocol and bridges it to the Ozone backend.
+It is **stateless**, meaning it does not persist data or metadata locally between requests – all state is stored in the Ozone cluster itself.
+
+Being stateless allows multiple S3 Gateway instances to run in parallel behind a load balancer for scaling and high availability.
+The idea of stateless also allows S3G to be deployed in Kubernetes quite easily.
+The gateway supports a broad set of S3 operations – create/delete buckets, PUT/GET objects, list objects, perform multipart uploads – using standard S3 SDKs or CLI tools.
+
+Under the hood, each operation is translated into the appropriate Ozone calls:
+
+- A PUT object request becomes a `putKey` write operation.
+- A GET object becomes a `getKey` read operation.
+
+### Mapping S3 to Ozone Concepts
+
+In Ozone, data is organized into **volumes**, **buckets**, and **keys**. By default, the S3 Gateway uses a special
+volume named `/s3v` to store all S3 buckets (this is configurable via the `ozone.s3g.volume.name` property).
+
+Each S3 bucket created is represented as a bucket under the `/s3v` volume in Ozone. Objects (keys) are stored within those buckets. This mapping is transparent to the end user.
+
+The default bucket layout for S3 buckets (`OBJECT_STORE`) can be configured using the `ozone.s3g.default.bucket.layout` property. This property defines the storage layout for buckets created via the S3 Gateway.
+
+## S3 Gateway in the Ozone Architecture
+
+The S3 Gateway does the following:
+
+- It receives S3 REST API calls from clients.
+- It translates them and forwards metadata operations to OM.
+- It streams data directly to and from Datanodes.
+
+This stateless gateway can be scaled horizontally.
+
+## Internal Components and Design
+
+### HTTP Server and REST API Layer
+
+Runs an embedded HTTP server exposing REST endpoints like:
+
+- `PUT /<bucket>/<key>`
+- `GET /<bucket>/<key>`
+
+Handles authentication headers, content length, and routing.
+
+### Request Handlers / Protocol Translation
+
+Each S3 operation is mapped to Ozone APIs:
+
+- Create Bucket → create in `/s3v` volume
+- List Buckets → query all user-owned buckets under `/s3v`
+- Put/Get Object → `putKey` / `getKey`
+
+It also assembles proper S3-compliant response formats.
+
+### Ozone Client Integration
+
+Uses Ozone client libraries to:
+
+- Call OM for metadata operations
+- Stream data to/from Datanodes
+
+Bulk data does not flow through OM – it goes directly between gateway and Datanodes.
+
+### Statelessness and Caching
+
+The gateway:
+
+- Does not persist state
+- Uses lightweight in-memory caches
+- Depends on OM for coordination and user/token validation
+
+This simplifies scaling and failure recovery.
+
+### Authentication and Security
+
+Supports AWS Signature-style authentication (if enabled):
+
+- Only AWS Signature V4 is supported (the older AWS Signature V2 is not).
+- Validates access/secret keys via OM
+- Uses OM’s stored credentials
+- Relies on OM for final authorization
+
+Supports Kerberos authentication for secure clusters; In unsecured mode, allows anonymous or dummy access.
+
+## Summary
+
+The Ozone S3 Gateway is a **protocol adapter**:
+
+- It translates REST S3 operations into native Ozone calls.
+- It doesn’t store or manage data – it delegates to OM and Datanodes.
+- Its stateless, scalable design enables multiple instances behind load balancers.
+- It enables seamless use of existing S3-compatible clients and tools.
+
+For more details, refer to the other documentation:
+
+- [Ozone S3 Gateway Interface](../../user-guide/client-interfaces/s3/s3-api)
+- [S3 Multi-Tenancy](../../administrator-guide/operations/s3-multi-tenancy/overview)
+- [Securing S3](../../user-guide/client-interfaces/s3/securing-s3)
+- [Network Ports](../../administrator-guide/configuration/basic/network/default-ports)
diff --git a/versioned_docs/version-2.2.1/03-core-concepts/01-architecture/05-datanodes.md b/versioned_docs/version-2.2.1/03-core-concepts/01-architecture/05-datanodes.md
new file mode 100644
index 0000000000..a45a6370e5
--- /dev/null
+++ b/versioned_docs/version-2.2.1/03-core-concepts/01-architecture/05-datanodes.md
@@ -0,0 +1,95 @@
+---
+sidebar_label: Datanodes
+---
+
+# Datanodes
+
+Datanodes are the worker bees of Ozone. All data is stored on data nodes. Clients write data in terms of blocks.
+Datanode aggregates these blocks into a storage container. A storage container is the data streams and metadata about
+the blocks written by the clients.
+
+## Storage Containers
+
+
+
+A storage container is a self-contained super block. It has a list of Ozone blocks that reside inside it, as well as on-disk
+files which contain the actual data streams. This is the default Storage container format. From Ozone's perspective, container
+is a protocol spec, actual storage layouts does not matter. In other words, it is trivial to extend or bring new container layouts.
+Hence this should be treated as a reference implementation of containers under Ozone.
+
+## Understanding Ozone Blocks and Containers
+
+When a client wants to read a key from Ozone, the client sends the name of the key to the Ozone Manager. Ozone Manager returns
+the list of Ozone blocks that make up that key.
+
+An Ozone block contains the container ID and a local ID. The figure below shows the logical layout of the Ozone block.
+
+
+
+The container ID lets the clients discover the location of the container.
+The authoritative information about where a container is located is with the Storage Container Manager (SCM). In most cases,
+the container location will be cached by Ozone Manager and will be returned along with the Ozone blocks.
+
+Once the client is able to locate the container, the client will connect to the Datanode and read the data stream specified
+by *Container ID:Local ID*. In other words, the local ID serves as index into the container which describes what data stream to read from.
+
+## Discovering Container Locations
+
+How does SCM know where the containers are located? This is very similar to what HDFS does; the data nodes regularly send
+container reports like block reports. Container reports are far more concise than block reports. For example, an Ozone deployment
+with a 196 TB data node will have around 40 thousand containers, compared to HDFS block count of million and half blocks—a 40x
+reduction in the block reports.
+
+This extra indirection helps tremendously with scaling Ozone. SCM has far less block data to process and the namespace
+service (Ozone Manager) as a different service are critical to scaling Ozone.
+
+## Data Volume Management
+
+### What is a Volume?
+
+In the context of an Ozone Datanode, a "volume" refers to a physical disk or storage device managed by the Datanode. Each
+volume can store many containers, which are the fundamental units of storage in Ozone. This is different from the "volume"
+concept in Ozone Manager, which refers to a namespace for organizing buckets and keys.
+
+The status of volumes, including used space, available space and whether or not they are operational (healthy) or failed,
+can be looked up from Datanode Web UI.
+
+### Defining Volumes with `hdds.datanode.dir`
+
+The property `hdds.datanode.dir` defines the set of volumes (disks) managed by a Datanode. You can specify one or more
+directories, separated by commas. Each directory represents a volume. For example: `/data1/disk1,/data2/disk2`, which configures
+the Datanode to manage two volumes.
+
+### Volume Choosing Policy
+
+When a Datanode needs to select a volume to store new data, it uses a volume choosing policy. The policy is controlled by
+the property `hdds.datanode.volume.choosing.policy`. There are two main policies:
+
+- **CapacityVolumeChoosingPolicy (default)**: This policy randomly selects two volumes with enough available space and chooses the one with
+ lower utilization (i.e., more free space). This approach increases the likelihood that less-used disks are chosen, helping to balance disk usage over time.
+
+- **RoundRobinVolumeChoosingPolicy**: This policy selects volumes in a round-robin order, cycling through all available volumes.
+ It does not consider the current utilization of each disk, but ensures even distribution of new containers across all disks.
+
+### Volume-Related Configuration Properties
+
+| Property Name | Default Value | Description |
+|---------------|---------------|-------------|
+| `hdds.datanode.volume.choosing.policy` | `CapacityVolumeChoosingPolicy` | The policy used to select a volume for new containers. |
+| `hdds.datanode.volume.min.free.space` | `20GB` | Minimum free space required on a volume to be eligible for new containers. |
+| `hdds.datanode.volume.min.free.space.percent` | `0.02` | Minimum free space percentage required on a volume to be eligible for new containers. |
+
+### Disk Balancer
+
+Over time, operations like adding or replacing disks can cause uneven disk usage. Ozone provides a **Disk Balancer** feature to automatically balance disk usage across Datanode volumes. The Disk Balancer can be enabled via the `hdds.datanode.disk.balancer.enabled` configuration property and is managed through CLI commands.
+
+## Notable Configurations
+
+| Key | Default | Description |
+|-----|---------|-------------|
+| `dfs.container.ratis.datanode.storage.dir` | none | This directory is used for storing Ratis metadata like logs. |
+| `ozone.scm.datanode.id.dir` | none | The path that Datanodes will use to store the Datanode ID. |
+| `hdds.datanode.dir` | none | Determines where HDDS data will be stored on the local filesystem. |
+| `hdds.datanode.dir.du.reserved` | none | Reserved space in bytes per volume. Always leave this much space free for non dfs use. |
+| `ozone.metadata.dirs` | none | Directory to store persisted data (RocksDB). |
+| `ozone.recon.address` | 0.0.0.0:9891 | RPC address of the Recon. Use host:port to connect Recon. |
diff --git a/versioned_docs/version-2.2.1/03-core-concepts/01-architecture/06-recon.md b/versioned_docs/version-2.2.1/03-core-concepts/01-architecture/06-recon.md
new file mode 100644
index 0000000000..7a98760cb4
--- /dev/null
+++ b/versioned_docs/version-2.2.1/03-core-concepts/01-architecture/06-recon.md
@@ -0,0 +1,105 @@
+---
+sidebar_label: Recon
+---
+
+# Recon
+
+Recon serves as a management and monitoring console for Ozone. It gives a bird's-eye view of Ozone and helps users troubleshoot any issues by presenting the current state of the cluster through REST based APIs and rich web UI.
+
+## High Level Design
+
+
+
+On a high level, Recon collects and aggregates metadata from Ozone Manager (OM), Storage Container Manager (SCM) and Datanodes (DN) and acts as a central management and monitoring console. Ozone administrators can use Recon to query the current state of the system without overloading OM or SCM.
+
+Recon maintains multiple databases to enable batch processing, faster querying and to persist aggregate information. It maintains a local copy of OM db and SCM db along with a SQL database for persisting aggregate information.
+
+Recon also integrates with Prometheus to provide a HTTP endpoint to query Prometheus for Ozone metrics and also to display a few crucial point in time metrics in the web UI.
+
+## Recon and Ozone Manager
+
+
+
+Recon gets a full snapshot of OM rocks db initially from the leader OM's HTTP endpoint, untars the file and initializes RocksDB for querying locally. The database is kept in sync by periodically requesting delta updates from the leader OM via RPC calls from the last applied sequence id. If for any reason, the delta updates could not be retrieved or applied to the local db, a full snapshot is requested again to keep the local db in sync with OM db. Due to this, Recon can show stale inform [...]
+
+The db updates retrieved from OM is then converted into a batch of events for further processing by OM db tasks via [Recon Task Framework](#task-framework).
+
+## Recon and Storage Container Manager
+
+
+
+Recon also acts as a passive SCM for Datanodes. When Recon is configured in the cluster, all the Datanodes register with Recon and send heartbeats, container reports, incremental container reports etc. to Recon similar to SCM. Recon uses all the information it gets from Datanodes to construct its own copy of SCM rocks db locally. Recon never sends any command to Datanodes in response and just acts as a passive SCM for faster lookup of SCM metadata.
+
+## Task Framework
+
+Recon has its own Task framework to enable batch processing of data obtained from OM and SCM. A task can listen to and act upon db events such as `PUT`, `DELETE`, `UPDATE`, etc. on either OM db or SCM db. Based on this, a task either implements `org.apache.hadoop.ozone.recon.tasks.ReconOmTask` or extends `org.apache.hadoop.ozone.recon.scm.ReconScmTask`.
+
+An example `ReconOmTask` is `ContainerKeyMapperTask` that persists the container -> key mapping in RocksDB. This is useful to understand which keys were part
+of the container when the container is reported missing or is in a bad health state. Another example is FileSizeCountTask which keeps track of count of
+files within a given file size range in a SQL database. These tasks have implementations for two scenarios:
+
+- Full snapshot (`reprocess()`)
+- Delta updates (`process()`)
+
+When a full snapshot of OM db is obtained from the leader OM, the `reprocess()` is called on all the registered OM tasks. On subsequent delta updates, `process()` is called on these OM tasks.
+
+An example `ReconScmTask` is `ContainerHealthTask` that runs in configurable intervals to scan the list of all the containers and to persist the state of unhealthy containers (`MISSING`, `MIS_REPLICATED`, `UNDER_REPLICATED`, `OVER_REPLICATED`) in a SQL table. This information is used to determine if there are any missing containers in the cluster.
+
+## Recon and Prometheus
+
+Recon can integrate with any Prometheus instance configured to collected metrics and can display useful information in Recon UI in Datanodes and Pipelines pages. Recon also exposes a proxy endpoint
+([/metrics](https://ozone.apache.org/docs/edge/interface/reconapi.html#metrics)) to query Prometheus. This integration can be enabled by setting this configuration `ozone.recon.prometheus.http.endpoint` to the Prometheus endpoint like `ozone.recon.prometheus.http.endpoint=http://prometheus:9090`.
+
+## API Reference
+
+[Link to complete API Reference](../../administrator-guide/operations/observability/recon/recon-rest-api)
+
+## Persisted state
+
+- A local copy of [OM database](./ozone-manager#persisted-state)
+- A local copy of [SCM database](./storage-container-manager#persisted-state)
+
+The following data is persisted in Recon in the specified RocksDB directory:
+
+- **ContainerKey table**
+ - Stores the mapping (container, key) -> count
+- **ContainerKeyCount table**
+ - Stores containerID -> no. of keys count within the container
+
+The following data is stored in the configured SQL database (**default is Derby**):
+
+- **GlobalStats table**
+ - A Key -> Value table to store aggregate information like total number of volumes / buckets / keys present in the cluster
+- **FileCountBySize table**
+ - Keeps track of the number of files present within a file size range in the cluster
+- **ReconTaskStatus table**
+ - Keeps track of the status and last run timestamp of the registered OM and SCM db tasks in the [Recon Task Framework](#task-framework)
+- **ContainerHistory table**
+ - Stores ContainerReplica -> Datanode mapping with last known timestamp. This is used to determine the last known Datanodes when a container is reported missing
+- **UnhealthyContainers table**
+ - Keeps track of all the Unhealthy Containers (MISSING, UNDER_REPLICATED, OVER_REPLICATED, MIS_REPLICATED) in the cluster at any given time
+
+## Notable configurations
+
+| Key | Default | Description |
+|-----|------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------|
+| `ozone.recon.http-address` | 0.0.0.0:9888 | The address and the base port where the Recon web UI will listen on. |
+| `ozone.recon.address` | 0.0.0.0:9891 | RPC address of the Recon. |
+| `ozone.recon.heatmap.provider` | none | HeatMapProvider for Recon. |
+| `ozone.recon.db.dir` | none | Directory where the Recon Server stores its metadata. |
+| `ozone.recon.om.db.dir` | none | Directory where the Recon Server stores its OM snapshot DB. |
+| `ozone.recon.om.snapshot.task.interval.delay` | 10m | Interval in MINUTES by Recon to request OM DB Snapshot / delta updates. |
+| `ozone.recon.task.missingcontainer.interval` | 300s | Time interval of the periodic check for Unhealthy Containers in the cluster. |
+| `ozone.recon.task.safemode.wait.threshold` | 300s | Max time for Recon to wait before it exits out of safe or warmup mode. |
+| `ozone.recon.sql.db.jooq.dialect` | DERBY | Please refer to [SQL Dialect](https://www.jooq.org/javadoc/latest/org.jooq/org/jooq/SQLDialect.html) to specify a different dialect. |
+| `ozone.recon.sql.db.jdbc.url` | `jdbc:derby:${ozone.recon.db.dir}`<br></br>`/ozone_recon_derby.db` | Recon SQL database jdbc url. |
+| `ozone.recon.sql.db.username` | none | Recon SQL database username. |
+| `ozone.recon.sql.db.password` | none | Recon SQL database password. |
+| `ozone.recon.sql.db.driver` | `org.apache.derby.jdbc.EmbeddedDriver` | Recon SQL database jdbc driver. |
+| `ozone.recon.prometheus.http.endpoint` | none | Prometheus HTTP endpoint URL for Recon to integrate with Prometheus. Enables display of metrics in Recon UI and exposes a proxy endpoint to query Prometheus. Example: `http://prometheus:9090`. |
+| `ozone.recon.scmconfig` | none | Prefix for SCM configuration. |
+| `ozone.recon.db.dirs.permissions` | `750` | Permissions for the metadata directories for Recon. The permissions can either be octal or symbolic. If the default permissions are not set then the default value of 750 will be used. |
+| `ozone.recon.datanode.address` | none | Datanode address for Recon. |
+| `ozone.recon.heatmap.enable` | `false` | To enable/disable Recon heatmap feature. Along with this config, user must also provide the implementation of `org.apache.hadoop.ozone.recon.heatmap.IHeatMapProvider` interface and configure in `ozone.recon.heatmap.provider` configuration. |
+| `ozone.recon.https-address` | `0.0.0.0:9889` | The address and the base port where the Recon web UI will listen on using HTTPS. If the port is 0 then the server will start on a free port. |
+| `ozone.recon.datanode.bind.host` | `0.0.0.0` | Bind host for Datanode address. |
diff --git a/versioned_docs/version-2.2.1/03-core-concepts/01-architecture/ContainerMetadata.png b/versioned_docs/version-2.2.1/03-core-concepts/01-architecture/ContainerMetadata.png
new file mode 100644
index 0000000000..48bd1c43c0
Binary files /dev/null and b/versioned_docs/version-2.2.1/03-core-concepts/01-architecture/ContainerMetadata.png differ
diff --git a/versioned_docs/version-2.2.1/03-core-concepts/01-architecture/FunctionalOzone.png b/versioned_docs/version-2.2.1/03-core-concepts/01-architecture/FunctionalOzone.png
new file mode 100644
index 0000000000..641b7db2fa
Binary files /dev/null and b/versioned_docs/version-2.2.1/03-core-concepts/01-architecture/FunctionalOzone.png differ
diff --git a/versioned_docs/version-2.2.1/03-core-concepts/01-architecture/OzoneArchitectureDiagram.png b/versioned_docs/version-2.2.1/03-core-concepts/01-architecture/OzoneArchitectureDiagram.png
new file mode 100644
index 0000000000..67e449027b
Binary files /dev/null and b/versioned_docs/version-2.2.1/03-core-concepts/01-architecture/OzoneArchitectureDiagram.png differ
diff --git a/versioned_docs/version-2.2.1/03-core-concepts/01-architecture/OzoneBlock.png b/versioned_docs/version-2.2.1/03-core-concepts/01-architecture/OzoneBlock.png
new file mode 100644
index 0000000000..9583bd5ee7
Binary files /dev/null and b/versioned_docs/version-2.2.1/03-core-concepts/01-architecture/OzoneBlock.png differ
diff --git a/versioned_docs/version-2.2.1/03-core-concepts/01-architecture/OzoneManager-ReadPath.png b/versioned_docs/version-2.2.1/03-core-concepts/01-architecture/OzoneManager-ReadPath.png
new file mode 100644
index 0000000000..5e68f6fc1c
Binary files /dev/null and b/versioned_docs/version-2.2.1/03-core-concepts/01-architecture/OzoneManager-ReadPath.png differ
diff --git a/versioned_docs/version-2.2.1/03-core-concepts/01-architecture/OzoneManager-WritePath.png b/versioned_docs/version-2.2.1/03-core-concepts/01-architecture/OzoneManager-WritePath.png
new file mode 100644
index 0000000000..924b61c31a
Binary files /dev/null and b/versioned_docs/version-2.2.1/03-core-concepts/01-architecture/OzoneManager-WritePath.png differ
diff --git a/versioned_docs/version-2.2.1/03-core-concepts/01-architecture/OzoneManager.png b/versioned_docs/version-2.2.1/03-core-concepts/01-architecture/OzoneManager.png
new file mode 100644
index 0000000000..f71bfacc41
Binary files /dev/null and b/versioned_docs/version-2.2.1/03-core-concepts/01-architecture/OzoneManager.png differ
diff --git a/versioned_docs/version-2.2.1/03-core-concepts/01-architecture/README.mdx b/versioned_docs/version-2.2.1/03-core-concepts/01-architecture/README.mdx
new file mode 100644
index 0000000000..a556727d3c
--- /dev/null
+++ b/versioned_docs/version-2.2.1/03-core-concepts/01-architecture/README.mdx
@@ -0,0 +1,11 @@
+---
+sidebar_label: Architecture
+---
+
+# Architecture
+
+import DocCardList from '@theme/DocCardList';
+
+This section describes the architecture and components within Ozone.
+
+<DocCardList/>
diff --git a/versioned_docs/version-2.2.1/03-core-concepts/01-architecture/ReconHighLevelDesign.png b/versioned_docs/version-2.2.1/03-core-concepts/01-architecture/ReconHighLevelDesign.png
new file mode 100644
index 0000000000..3bd6443d84
Binary files /dev/null and b/versioned_docs/version-2.2.1/03-core-concepts/01-architecture/ReconHighLevelDesign.png differ
diff --git a/versioned_docs/version-2.2.1/03-core-concepts/01-architecture/ReconOmDesign.png b/versioned_docs/version-2.2.1/03-core-concepts/01-architecture/ReconOmDesign.png
new file mode 100644
index 0000000000..20ea6a3360
Binary files /dev/null and b/versioned_docs/version-2.2.1/03-core-concepts/01-architecture/ReconOmDesign.png differ
diff --git a/versioned_docs/version-2.2.1/03-core-concepts/01-architecture/ReconScmDesign.png b/versioned_docs/version-2.2.1/03-core-concepts/01-architecture/ReconScmDesign.png
new file mode 100644
index 0000000000..32d07e02d2
Binary files /dev/null and b/versioned_docs/version-2.2.1/03-core-concepts/01-architecture/ReconScmDesign.png differ
diff --git a/versioned_docs/version-2.2.1/03-core-concepts/01-architecture/StorageContainerManager.png b/versioned_docs/version-2.2.1/03-core-concepts/01-architecture/StorageContainerManager.png
new file mode 100644
index 0000000000..605c48c355
Binary files /dev/null and b/versioned_docs/version-2.2.1/03-core-concepts/01-architecture/StorageContainerManager.png differ
diff --git a/versioned_docs/version-2.2.1/03-core-concepts/02-replication/01-storage-containers.md b/versioned_docs/version-2.2.1/03-core-concepts/02-replication/01-storage-containers.md
new file mode 100644
index 0000000000..566b4fe63c
--- /dev/null
+++ b/versioned_docs/version-2.2.1/03-core-concepts/02-replication/01-storage-containers.md
@@ -0,0 +1,26 @@
+---
+sidebar_label: Storage Containers
+---
+
+# Storage Containers
+
+Storage Containers, or Containers (not to be confused with Docker containers) are the fundamental replication unit of Ozone, they are managed by the Storage Container Manager (SCM) service.
+
+Containers are big binary units (5GB by default) which can contain multiple blocks:
+
+
+
+Blocks are local information and not managed by SCM. Therefore even if billions of small files are created in the system (which means billions of blocks are created), only of the status of the containers will be reported by the Datanodes and containers will be replicated.
+When Ozone Manager requests a new Block allocation from the SCM, SCM will identify the suitable container and generate a block id which contains `ContainerId` + `LocalId`. Client will connect to the Datanode which stores the Container, and Datanode can manage the separated block based on the `LocalId`.
+
+## Open vs. Closed containers
+
+When a container is created it starts in an OPEN state. When it's full (~5GB data is written), container will be closed and becomes a CLOSED container.
+
+The fundamental differences between OPEN and CLOSED containers:
+
+| OPEN | CLOSED |
+| ----------------------------------- | ------------------------------------ |
+| Mutable | Immutable |
+| Replicated with RAFT (Ratis) | Replicated with async container copy |
+| Raft leader is used to READ / WRITE | All the nodes can be used to READ |
diff --git a/versioned_docs/version-2.2.1/03-core-concepts/02-replication/02-write-pipelines.md b/versioned_docs/version-2.2.1/03-core-concepts/02-replication/02-write-pipelines.md
new file mode 100644
index 0000000000..e194d987cd
--- /dev/null
+++ b/versioned_docs/version-2.2.1/03-core-concepts/02-replication/02-write-pipelines.md
@@ -0,0 +1,298 @@
+---
+sidebar_label: Write Pipelines
+---
+
+# Write Pipelines
+
+Write pipelines are a fundamental component of Apache Ozone's storage architecture, enabling reliable data storage across distributed nodes. This document provides a comprehensive overview of write pipelines, covering both replication and erasure coding approaches, their architecture, implementation details, and usage patterns.
+
+## What are Write Pipelines?
+
+Write pipelines are groups of Datanodes that work together as a unit to store and replicate data in Ozone. They serve as the foundation for Ozone's data redundancy strategy, providing:
+
+- A coordinated path for write operations across multiple nodes
+- Consistency guarantees for data replication
+- Efficient management of data distribution and storage
+
+The Storage Container Manager (SCM) is responsible for creating and managing write pipelines, selecting appropriate Datanodes based on factors like availability, capacity, and network topology.
+
+## Pipeline Types
+
+Ozone supports different types of write pipelines to accommodate various durability and storage efficiency requirements:
+
+### 1. Ratis Pipelines (Replicated)
+
+Ratis pipelines use the [Apache Ratis](https://ratis.apache.org/) implementation of the Raft consensus protocol for strongly consistent replication.
+
+- **Structure**: Typically consists of three Datanodes (one leader, multiple followers)
+- **Consistency**: Provides strong consistency through synchronous replication
+- **Durability**: Data is fully replicated on all nodes in the pipeline
+- **Use Case**: Default replication strategy for most Ozone deployments
+
+
+
+#### Ratis Pipeline V1: Async API
+
+The original Ozone replication pipeline (V1) uses the Ratis Async API for data replication across multiple Datanodes:
+
+1. Client buffers data locally until a certain threshold is reached
+2. Data is sent to the leader Datanode in the pipeline
+3. Leader replicates data to follower Datanodes
+4. Once a quorum of Datanodes acknowledge the write, the operation is considered successful
+
+This approach ensures data consistency but has some limitations in terms of network topology awareness and buffer handling efficiency.
+
+#### Ratis Pipeline V2: Streaming API
+
+The newer Streaming Write Pipeline (V2) in Ozone leverages the Ratis Streaming API to provide significant performance improvements:
+
+**Key Enhancements:**
+
+- Better network topology awareness
+- Elimination of unnecessary buffer copying (Netty zero copy)
+- Improved CPU and disk utilization on Datanodes
+- More efficient parallelism in data processing
+
+The Streaming Write Pipeline introduces a new network protocol that enables direct streaming of data from client to Datanodes, reducing overhead and improving throughput.
+
+**Configuration:**
+
+To enable the Streaming Write Pipeline (V2), configure these properties in `ozone-site.xml`:
+
+```xml
+<property>
+ <name>hdds.container.ratis.datastream.enabled</name>
+ <value>true</value>
+ <description>Enable data stream of container</description>
+</property>
+
+<property>
+ <name>hdds.container.ratis.datastream.port</name>
+ <value>9855</value>
+ <description>The datastream port number of container</description>
+</property>
+
+<property>
+ <name>ozone.fs.datastream.enabled</name>
+ <value>true</value>
+ <description>Enable filesystem write via ratis streaming</description>
+</property>
+```
+
+### 2. Erasure Coded Pipelines
+
+Erasure coded (EC) pipelines use mathematical techniques to achieve data durability with lower storage overhead than full replication.
+
+- **Structure**: Distributes data chunks and parity chunks across multiple Datanodes
+- **Efficiency**: Requires less storage space than full replication (e.g., 50% overhead instead of 200%)
+- **Recovery**: Can reconstruct data from a subset of available chunks
+- **Use Case**: Optimized for large data sets where storage efficiency is critical
+
+
+
+#### Striping and Data Layout
+
+EC in Ozone uses a striping data model where:
+
+1. Data is divided into fixed-size chunks (typically 1MB)
+2. The chunks are organized into stripes
+3. For each stripe, parity chunks are computed
+4. The chunks are distributed across Datanodes
+
+For example, with an RS (Reed-Solomon) 6-3 configuration:
+
+- Data is split into 6 data chunks
+- 3 parity chunks are computed
+- These 9 chunks together form a "Stripe"
+- Multiple stripes using the same set of Datanodes form a "BlockGroup"
+
+This approach provides 50% storage overhead compared to 200% with 3x replication, while maintaining similar durability guarantees.
+
+#### EC Configuration
+
+To use Erasure Coding in Ozone, you can configure EC at the bucket level or per key:
+
+**Setting EC at bucket creation:**
+
+```bash
+ozone sh bucket create <bucket path> --type EC --replication rs-6-3-1024k
+```
+
+**Changing EC configuration for an existing bucket:**
+
+```bash
+ozone sh bucket set-replication-config <bucket path> --type EC --replication rs-3-2-1024k
+```
+
+**Setting EC when creating a key:**
+
+```bash
+ozone sh key put <Ozone Key Object Path> <Local File> --type EC --replication rs-6-3-1024k
+```
+
+Supported EC configurations include:
+
+- `RS-3-2-1024k`: Reed-Solomon with 3 data chunks, 2 parity chunks, 1MB chunk size
+- `RS-6-3-1024k`: Reed-Solomon with 6 data chunks, 3 parity chunks, 1MB chunk size (recommended)
+- `XOR-2-1-1024k`: XOR coding with 2 data chunks, 1 parity chunk, 1MB chunk size
+
+## Pipeline Lifecycle
+
+Write pipelines follow a well-defined lifecycle, managed by the Storage Container Manager:
+
+1. **Creation**: SCM selects appropriate Datanodes and creates a pipeline
+2. **Active**: Pipeline accepts write operations and manages replication
+3. **Closing**: Pipeline stops accepting new writes when it reaches capacity limits
+4. **Closed**: Pipeline becomes read-only after all write operations complete
+5. **Recovery/Reconstruction**: If a node fails, SCM may initiate recovery procedures
+
+## How Write Pipelines Work
+
+The write operation in Ozone follows these steps through the pipeline:
+
+1. **Client Request**: Client contacts the Ozone Manager (OM) to create or write to a key
+2. **Block Allocation**: OM requests block allocation from SCM
+3. **Pipeline Selection**: SCM selects an appropriate pipeline for the write operation
+4. **Data Transfer**: Client streams data directly to the leader Datanode in the pipeline
+5. **Replication**: For Ratis pipelines, the leader replicates data to followers using the Raft protocol; for EC pipelines, the client distributes different chunks to different Datanodes
+6. **Acknowledgment**: Once all replicas are written, the client receives confirmation
+
+
+
+### Implementation Details
+
+#### Replication Pipeline Implementation
+
+The replication write pipeline is implemented through several key classes:
+
+- **BlockOutputStream**: Base class that manages the overall write process
+- **RatisBlockOutputStream**: Implements the Ratis-specific functionality for replication
+- **CommitWatcher**: Tracks commit status across all Datanodes in the pipeline
+- **XceiverClient**: Handles communication with Datanodes
+
+The write process follows these steps:
+
+1. Client creates a `BlockOutputStream` for the allocated block
+2. Data is written in chunks, which are buffered locally
+3. When buffer fills or flush is triggered, data is written to Datanodes
+4. Each chunk is assigned a sequential index and checksummed
+5. After all data is written, a putBlock operation finalizes the block
+
+#### EC Pipeline Implementation
+
+EC write pipeline implementation involves several key components:
+
+- **ECKeyOutputStream**: Main client-side class that manages EC writes
+- **ECChunkBuffers**: Maintains buffers for both data and parity chunks
+- **ECBlockOutputStreamEntry**: Manages Datanode connections and write operations
+- **RawErasureEncoder**: Performs the mathematical encoding to generate parity chunks
+
+The EC write process follows these steps:
+
+1. **Data Buffering**: Client buffers incoming data into chunks
+2. **Stripe Formation**: When all data chunks for a stripe are filled, parity is generated
+3. **Parallel Write**: Data and parity chunks are written to different Datanodes
+4. **Commit**: After all chunks are written, the stripe is committed
+
+## Containers and Pipelines
+
+Containers are the fundamental storage units in Ozone, and their relationship with pipelines is essential to understand:
+
+- Each container (typically 5GB) is associated with a specific pipeline
+- Multiple containers can exist within a single pipeline
+- When a container is in the OPEN state, it actively receives data via its pipeline
+- Once a container is CLOSED, its data can be accessed via any replica node
+
+## Comparing Replication and Erasure Coding
+
+| Feature | Replication (RATIS/THREE) | Erasure Coding (RS-6-3) |
+| ------- | ------------------------- | ----------------------- |
+| Storage Overhead | 200% (3x copies) | 50% (9 chunks for 6 data chunks) |
+| Write Performance | Higher throughput for small writes | Better for large sequential writes |
+| Read Performance | Consistent performance, any replica can serve | Slightly lower for intact data, reconstruction penalty for lost chunks |
+| CPU Usage | Lower | Higher (encoding/decoding overhead) |
+| Network Bandwidth | Higher during writes | Lower during writes |
+| Minimum Nodes | 3 | Depends on config (9 for RS-6-3) |
+| Use Cases | Hot data, random access, small files | Warm/cold data, large files, archival |
+
+**When to use Replication:**
+
+- For frequently accessed "hot" data
+- For workloads with small random writes
+- When raw write performance is critical
+- When CPU resources are limited
+
+**When to use Erasure Coding:**
+
+- For "warm" or "cold" data with lower access frequency
+- For large files with sequential access patterns
+- To optimize storage costs while maintaining durability
+- For archival or backup storage
+
+## Advanced Topics
+
+### Error Handling and Recovery
+
+Both write pipelines implement sophisticated error handling:
+
+**Replication Pipeline:**
+
+- Uses Ratis consensus protocol to handle failures
+- Automatically recovers from minority Datanode failures
+- Supports pipeline reconstruction if leader fails
+- Implements idempotent operations for retries
+
+**EC Pipeline:**
+
+- Tracks failures at the individual chunk level
+- Can retry specific chunk writes to failed Datanodes
+- Maintains stripe status to ensure consistency
+- Implements checksum validation for data integrity
+
+### Performance Considerations
+
+**Optimizing Replication Write Pipeline:**
+
+- Adjust buffer sizes based on workload (`hdds.client.buffer.size.max`)
+- Configure flush periods for write-heavy workloads
+- Use Streaming Pipeline (V2) for high-throughput scenarios
+- Consider network topology when placing Datanodes
+
+**Optimizing EC Write Pipeline:**
+
+- Choose EC configuration based on workload characteristics
+- Enable ISA-L hardware acceleration for better performance
+- Adjust chunk size for optimal performance
+- Balance between parallelism and overhead
+
+### Monitoring and Metrics
+
+Both write pipelines expose metrics that can be monitored through Ozone's Prometheus endpoint or JMX interface:
+
+**Key Metrics for Replication Pipeline:**
+
+- Write throughput
+- Average chunk write latency
+- Pipeline creation time
+- Ratis consensus latency
+
+**Key Metrics for EC Pipeline:**
+
+- Encode time per stripe
+- Chunk distribution latency
+- Success rate of first-time stripe writes
+- Parity calculation overhead
+
+## Benefits of Write Pipelines
+
+The pipeline architecture in Ozone provides several key benefits:
+
+1. **Reliability**: Automatic failure detection and recovery mechanisms
+2. **Consistency**: Strong consistency guarantees for data replication
+3. **Scalability**: Efficient management of write operations across thousands of nodes
+4. **Flexibility**: Support for different replication strategies depending on needs
+5. **Performance**: Optimized data flow paths that minimize network overhead
+
+## Conclusion
+
+Write pipelines form the backbone of Apache Ozone's data redundancy architecture, ensuring data is reliably stored and replicated across the cluster. By understanding how write pipelines work, administrators and users can make informed decisions about their Ozone deployment and effectively tune it for specific use cases. Whether you need the raw performance of replication or the storage efficiency of erasure coding, Ozone's write pipelines provide the foundation for durable and consisten [...]
diff --git a/versioned_docs/version-2.2.1/03-core-concepts/02-replication/03-ratis.md b/versioned_docs/version-2.2.1/03-core-concepts/02-replication/03-ratis.md
new file mode 100644
index 0000000000..9bc846574f
--- /dev/null
+++ b/versioned_docs/version-2.2.1/03-core-concepts/02-replication/03-ratis.md
@@ -0,0 +1,24 @@
+---
+sidebar_label: Ratis
+---
+
+# Ratis
+
+[Apache Ratis](https://ratis.apache.org/) is a highly customizable open-source Java implementation
+of the [Raft consensus protocol](https://raft.github.io/). Raft is an easily understandable consensus
+algorithm designed to manage replicated state. Unlike ZooKeeper or other Raft implementations such as etcd,
+Ratis is designed as a library rather than a standalone consensus server, which simplifies its management
+and integration.
+
+Ozone leverages Ratis to replicate system states across multiple nodes, ensuring high availability and
+redundancy. When using Ratis for replication, each piece of data written by clients is replicated to 3 Datanodes.
+Within Ozone, Ratis is employed in critical components such as the [Ozone Manager](../namespace/overview),
+[Storage Container Manager](../architecture/overview), and Datanodes. It forms the central pillar for the
+High Availability (HA) mechanisms of both the Ozone Manager (OM-HA) and Storage Container Manager (SCM-HA).
+
+For more detailed information, please visit the [Apache Ratis website](https://ratis.apache.org/).
+
+<!--
+For troubleshooting Ratis problems encountered in production, please refer to
+[Troubleshooting Ratis](../../troubleshooting/ratis).
+-->
diff --git a/versioned_docs/version-2.2.1/03-core-concepts/02-replication/04-erasure-coding.md b/versioned_docs/version-2.2.1/03-core-concepts/02-replication/04-erasure-coding.md
new file mode 100644
index 0000000000..75254c5caa
--- /dev/null
+++ b/versioned_docs/version-2.2.1/03-core-concepts/02-replication/04-erasure-coding.md
@@ -0,0 +1,120 @@
+# Erasure Coding
+
+## Background
+
+Distributed systems basic expectation is to provide the data durability.
+To provide the higher data durability, many popular storage systems use replication
+approach which is expensive. The Apache Ozone supports `RATIS/THREE` replication scheme.
+The Ozone default replication scheme `RATIS/THREE` has 200% overhead in storage
+space and other resources (e.g., network bandwidth).
+However, for warm and cold datasets with relatively low I/O activities, additional
+block replicas are rarely accessed during normal operations, but still consume the same
+amount of resources as the first replica.
+
+Therefore, a natural improvement is to use Erasure Coding (EC) in place of replication,
+which provides the same level of fault-tolerance with much less storage space.
+In typical EC setups, the storage overhead is no more than 50%. The replication factor of an EC file is meaningless.
+Instead of replication factor, we introduced ReplicationConfig interface to specify the required type of replication,
+either `RATIS/THREE` or `EC`.
+
+Integrating EC with Ozone can improve storage efficiency while still providing similar
+data durability as traditional replication-based Ozone deployments.
+As an example, a 3x replicated file with 6 blocks will consume 6*3 = `18` blocks of disk space.
+But with EC (6 data, 3 parity) deployment, it will only consume `9` blocks of disk space.
+
+## Architecture
+
+The storage data layout is a key factor in the implementation of EC. After deep analysis
+and several technical consideration, the most fitting data layout is striping model.
+The data striping layout is not new. The striping model already adapted by several other
+file systems(Ex: Quantcast File System, Hadoop Distributed File System etc) successfully before.
+
+For example, with the EC (6 data, 3 parity) scheme, the data chunks will be distributed to first 6 data nodes in order
+and then client generates the 3 parity chunks and transfer to remaining 3 nodes in order.
+These 9 chunks together we call as "Stripe". Next 6 chunks will be distributed to the same first 6 data nodes again
+and the parity to remaining 3 nodes. These 9 data nodes stored blocks together called as "BlockGroup".
+
+If the application is continuing to write beyond the size of `6 * BLOCK_SIZE`, then client will request new block group from Ozone Manager.
+
+### Erasure Coding Write
+
+The core logic of erasure coding writes are placed at Ozone client.
+When client creates the file, Ozone Manager allocates the block group(`d + p`)
+number of nodes from the pipeline provider and return the same to client.
+As data is coming in from the application, client will write first d number of chunks
+to d number of data nodes in block group. It will also cache the d number chunks
+to generate the parity chunks. Once parity chunks generated, it will transfer the
+same to the remaining p nodes in order. Once all blocks reached their configured sizes,
+client will request the new block group nodes.
+
+Below diagram depicts the block allocation in containers as logical groups.
+For interest of space, we assumed EC(3, 2) Replication Config for the diagram.
+
+
+
+Let's zoom out the blockID: 1 data layout from the above picture, that showed in the following picture.
+This picture shows how the chunks will be laid out in data node blocks.
+
+
+
+Currently, the EC client re-used the data transfer end-points to transfer the data to data nodes.
+The XceiverClientGRPC client used for writing data and putBlock info.
+The Datanode side changes are minimal as we reused the same existing transfer protocols.
+The EC data block written at the Datanode is same as any other block in non-EC mode.
+In a single block group, container id numbers are same in all nodes. A file can have multiple block groups.
+Each block group will have `d+p` number of block and all ids are same.
+
+**d** - Number of data blocks in a block group
+
+**p** - Number of parity blocks in a block group
+
+### Erasure Coding Read
+
+For reads, OM will provide the node location details as part of key lookup.
+If the key is erasure coded, Ozone client reads it in EC fashion. Since the data layout
+is different(see the previous section about write path), reads should consider the layout and do the reads accordingly.
+
+The EC client will open the connections to DNs based on the expected locations. When all data locations are available,
+it will attempt to do plain reads chunk by chunk in round robin fashion from d data blocks.
+
+Below picture shows the order when there are no failures while reading.
+
+
+
+Until it sees read failures, there is no need of doing EC reconstruction.
+
+#### Erasure Coding On-the-fly Reconstruction Reads
+
+When client detects there are failures while reading or when starting the reads,
+Ozone EC client is capable of reconstructing/recovering the lost data by doing the EC decoding.
+To do the EC decoding it needs to read parity replicas. This is a degraded read as it needs to do reconstruction.
+This reconstruction is completely transparent to the applications.
+
+Below picture depicts how it uses parity replicas in reconstruction.
+
+
+
+### Erasure Coding Replication Config
+
+Apache Ozone built with the pure 'Object Storage' semantics. However, many big data
+eco system projects still uses file system APIs. To provide both worlds best access to Ozone,
+it's provided both faces of interfaces. In both cases, keys/files would be written into buckets under the hood.
+So, EC Replication Configs can be set at bucket level.
+The EC policy encapsulates how to encode/decode a file.
+
+Each EC Replication Config defined by the following pieces of information:
+
+ 1. **data:** Data blocks number in an EC block group.
+ 2. **parity:** Parity blocks number in an EC block group.
+ 3. **ecChunkSize:** The size of a striping chunk. This determines the granularity of striped reads and writes.
+ 4. **codec:** This is to indicate the type of EC algorithms (e.g., `RS`(Reed-Solomon), `XOR`).
+
+To pass the EC Replication Config in command line or configuration files, we need to use the following format:
+*codec*-*num data blocks*-*num parity blocks*-*EC chunk size*
+
+Currently, there are three built-in EC Replication Configs supported: `RS-3-2-1024k`, `RS-6-3-1024k`, `RS-10-4-1024k`.
+The most recommended option is `RS-6-3-1024k`. When a key/file created without specifying the Replication Config,
+it inherits the EC Replication Config of its bucket if it's available.
+
+Changing the bucket level EC Replication Config only affect new files created within the bucket.
+Once a file has been created, its EC Replication Config cannot be changed currently.
diff --git a/versioned_docs/version-2.2.1/03-core-concepts/02-replication/ContainerMetadata.png b/versioned_docs/version-2.2.1/03-core-concepts/02-replication/ContainerMetadata.png
new file mode 100644
index 0000000000..48bd1c43c0
Binary files /dev/null and b/versioned_docs/version-2.2.1/03-core-concepts/02-replication/ContainerMetadata.png differ
diff --git a/versioned_docs/version-2.2.1/03-core-concepts/02-replication/Containers.png b/versioned_docs/version-2.2.1/03-core-concepts/02-replication/Containers.png
new file mode 100644
index 0000000000..3d2df0f313
Binary files /dev/null and b/versioned_docs/version-2.2.1/03-core-concepts/02-replication/Containers.png differ
diff --git a/versioned_docs/version-2.2.1/03-core-concepts/02-replication/EC-Chunk-Layout.png b/versioned_docs/version-2.2.1/03-core-concepts/02-replication/EC-Chunk-Layout.png
new file mode 100644
index 0000000000..d7b6785264
Binary files /dev/null and b/versioned_docs/version-2.2.1/03-core-concepts/02-replication/EC-Chunk-Layout.png differ
diff --git a/versioned_docs/version-2.2.1/03-core-concepts/02-replication/EC-Reads-With-No-Failures.png b/versioned_docs/version-2.2.1/03-core-concepts/02-replication/EC-Reads-With-No-Failures.png
new file mode 100644
index 0000000000..7dd4cab6ef
Binary files /dev/null and b/versioned_docs/version-2.2.1/03-core-concepts/02-replication/EC-Reads-With-No-Failures.png differ
diff --git a/versioned_docs/version-2.2.1/03-core-concepts/02-replication/EC-Reconstructional-Read.png b/versioned_docs/version-2.2.1/03-core-concepts/02-replication/EC-Reconstructional-Read.png
new file mode 100644
index 0000000000..427e73a2ab
Binary files /dev/null and b/versioned_docs/version-2.2.1/03-core-concepts/02-replication/EC-Reconstructional-Read.png differ
diff --git a/versioned_docs/version-2.2.1/03-core-concepts/02-replication/EC-Write-Block-Allocation-in-Containers.png b/versioned_docs/version-2.2.1/03-core-concepts/02-replication/EC-Write-Block-Allocation-in-Containers.png
new file mode 100644
index 0000000000..3945662c0a
Binary files /dev/null and b/versioned_docs/version-2.2.1/03-core-concepts/02-replication/EC-Write-Block-Allocation-in-Containers.png differ
diff --git a/versioned_docs/version-2.2.1/03-core-concepts/02-replication/README.mdx b/versioned_docs/version-2.2.1/03-core-concepts/02-replication/README.mdx
new file mode 100644
index 0000000000..41904c8299
--- /dev/null
+++ b/versioned_docs/version-2.2.1/03-core-concepts/02-replication/README.mdx
@@ -0,0 +1,11 @@
+---
+sidebar_label: Replication
+---
+
+# Data and Metadata Replication
+
+import DocCardList from '@theme/DocCardList';
+
+This section describes how data and metadata are replicated consistently within Ozone.
+
+<DocCardList/>
diff --git a/versioned_docs/version-2.2.1/03-core-concepts/03-namespace/01-overview.md b/versioned_docs/version-2.2.1/03-core-concepts/03-namespace/01-overview.md
new file mode 100644
index 0000000000..60b3e3a98f
--- /dev/null
+++ b/versioned_docs/version-2.2.1/03-core-concepts/03-namespace/01-overview.md
@@ -0,0 +1,23 @@
+---
+sidebar_label: Overview
+---
+
+# Overview of Ozone's Namespace
+
+Apache Ozone organizes data in a three-level hierarchy: Volumes, Buckets, and Keys. This structure provides a flexible and scalable way to manage large datasets, similar to how traditional file systems use directories and files, but optimized for object storage.
+
+## Overview of the Hierarchy
+
+- **[Volumes](volumes/overview):** The top-level organizational unit, akin to user accounts or home directories.
+- **[Buckets](buckets/overview):** Reside within volumes, similar to directories or folders, and contain the actual data objects.
+- **[Keys](keys/overview):** The fundamental data objects, analogous to files, stored inside buckets.
+
+```text
+Volume
+└─── Bucket
+ ├─── Key 1
+ ├─── Key 2
+ └─── ...
+```
+
+This hierarchy is managed by the Ozone Manager, which is the principal namespace service of Ozone.
diff --git a/versioned_docs/version-2.2.1/03-core-concepts/03-namespace/01-volumes/01-overview.md b/versioned_docs/version-2.2.1/03-core-concepts/03-namespace/01-volumes/01-overview.md
new file mode 100644
index 0000000000..e34f2b8b46
--- /dev/null
+++ b/versioned_docs/version-2.2.1/03-core-concepts/03-namespace/01-volumes/01-overview.md
@@ -0,0 +1,105 @@
+---
+sidebar_label: Overview
+---
+
+# Volumes Overview
+
+## What is a Volume?
+
+A **Volume** in Ozone is the highest level of the namespace hierarchy. It serves as a logical container for one or more buckets. Conceptually, a volume can be thought of as a user's home directory or a project space, providing a clear separation of data ownership and management.
+
+**Key Characteristics:**
+
+- **Administrative Control:** Only administrators can create or delete volumes. This ensures proper resource allocation and access control at the highest level.
+- **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 allow underscore (`_`) in volume and bucket names while still enforcing the other S3 naming rules, configure the property `ozone.om.namespace.s3.strict` to `false` in the `ozone-site.xml` of Ozone Manager. (This does not relax the rules for other non-S3 characters.)
+
+:::
+
+## Details
+
+### Creation and Management
+
+Volumes are typically created and managed using the Ozone command-line interface (CLI). For example:
+
+```bash
+ozone sh volume create /myvolume
+```
+
+For more details on volume operations, refer to the [Ozone CLI documentation](../../../user-guide/client-interfaces/o3#volume-operations).
+
+### Maximum User Volume Count
+
+Ozone enforces a configurable limit on the number of volumes a user can own. This limit is controlled by the configuration property:
+
+**Maximum number of volumes a user can own:**
+
+- **Default:** 1024 volumes per user
+- **Configuration property:** `ozone.om.user.max.volume`
+- **Error:** If exceeded, the operation fails with **USER_TOO_MANY_VOLUMES** error and message: `"Too many volumes for user: {owner}"`
+
+```xml
+<property>
+ <name>ozone.om.user.max.volume</name>
+ <value>1024</value>
+ <description>Maximum number of volumes a user can own</description>
+</property>
+```
+
+### Quota Management
+
+Volumes can have quotas applied to them, limiting the total storage space or the number of namespaces (buckets) they can consume. This is crucial for multi-tenant environments to prevent any single user or project from monopolizing resources.
+
+- **Storage Space Quota:** Limits the total data size within the volume.
+- **Namespace Quota:** Limits the number of buckets that can be created within the volume.
+
+For comprehensive information on configuring and managing quotas, see the [Quota Management documentation](../../../administrator-guide/operations/quota).
+
+### Access Control Lists (ACLs)
+
+Access to volumes is controlled via ACLs, which define permissions for users and groups. These permissions determine who can create buckets within a volume, list its contents, or perform other operations.
+
+- **Create:** Allows creating buckets within the volume.
+- **List:** Allows listing buckets within the volume.
+- **Read:** Allows reading metadata of the volume.
+- **Write:** Allows writing metadata of the volume.
+- **Delete:** Allows deleting the volume (if empty or recursively).
+
+ACLs can be set and managed using the Ozone CLI. Refer to the [Security ACLs documentation](../../security/acls/native-acls) for more in-depth information.
+
+### S3 Gateway Integration (`/s3v` Volume)
+
+For compatibility with the S3 API, Ozone uses a special volume, typically `/s3v`. By default, all buckets accessed via the S3 interface are stored under this volume. It's also possible to expose buckets from other Ozone volumes via the S3 interface using "bucket linking."
+For more details, refer to the [S3 Protocol documentation](../../../user-guide/client-interfaces/s3/s3-api) and [S3 Multi-Tenancy documentation](../../../administrator-guide/operations/s3-multi-tenancy/overview).
+
+### Datanode Physical Volumes vs. Ozone Manager Logical Volumes
+
+It's important to distinguish between the logical "volumes" managed by the Ozone Manager (as described above) and the physical "volumes" (disks) managed by the Datanodes.
+
+- **Ozone Manager Volumes:** Logical namespace containers for buckets and keys.
+- **Datanode Volumes:** Physical storage devices (disks) on a Datanode where actual data blocks are stored in containers.
+
+For more information on Datanode volume management, refer to the [Datanodes documentation](../../architecture/datanodes).
diff --git a/versioned_docs/version-2.2.1/03-core-concepts/03-namespace/01-volumes/02-owners.md b/versioned_docs/version-2.2.1/03-core-concepts/03-namespace/01-volumes/02-owners.md
new file mode 100644
index 0000000000..f84de0e1f7
--- /dev/null
+++ b/versioned_docs/version-2.2.1/03-core-concepts/03-namespace/01-volumes/02-owners.md
@@ -0,0 +1,176 @@
+---
+sidebar_label: Owners
+---
+
+# Volume Owners
+
+## 1. Overview
+
+Every volume in Ozone has an **owner** property that identifies the user who owns the volume. The volume owner is a fundamental concept in Ozone's access control and resource management system. It plays a crucial role in determining permissions, storage accounting, and multi-tenant isolation.
+
+While volumes also have an `admin` field in their metadata structure, **with Native ACLs** (`OzoneNativeAuthorizer`), this field is stored but not functionally used by Ozone Manager for authorization or access control purposes. Authorization checks rely on ACLs and the volume owner instead.
+The behavior of the `admin` field may differ when using `RangerOzoneAuthorizer`.
+
+## 2. Setting the Volume Owner
+
+### During Volume Creation
+
+When creating a volume, the owner can be explicitly specified using the `--user` command-line option:
+
+```bash
+ozone sh volume create /myvolume --user alice
+ozone sh volume info /myvolume
+{
+ "metadata" : { },
+ "name" : "myvolume",
+ "admin" : "om",
+ "owner" : "alice",
+ ...
+}
+```
+
+If the `--user` option is not provided during volume creation, Ozone automatically sets the owner to the **authenticated user identity** as determined by `UserGroupInformation.getCurrentUser()`. The behavior differs based on the cluster security configuration:
+
+- **Secure/Kerberos mode**: The owner is set to the Kerberos principal (or its short name) of the authenticated user. For example, if authenticated as Kerberos principal `om@REALM`, the volume owner will be `om`.
+
+- **Non-secure mode**: The owner is typically set to the Linux user running the CLI command. For example, if you run the command as Linux user `root`, the volume owner will be `root`.
+
+```bash
+# Owner defaults to authenticated user
+ozone sh volume create /myvolume
+
+# secure mode kerberos authenticated user
+ozone sh volume info /myvolume
+{
+ "metadata" : { },
+ "name" : "myvolume",
+ "admin" : "om",
+ "owner" : "om",
+ ...
+}
+
+# unsecure mode linux user root
+ozone sh volume info /myvolume
+{
+ "metadata" : { },
+ "name" : "myvolume",
+ "admin" : "root",
+ "owner" : "root",
+ ...
+}
+```
+
+**Default Behavior:**
+
+- If `--user` is not provided, the owner defaults to the authenticated user creating the volume.
+- The `ozone sh volume create` command does not allow setting the admin user. The admin can only be set using the Ozone o3 native Java API.
+
+**Example Output:**
+
+When viewing volume information, you can see the default ACLs:
+
+```bash
+# Volume created with explicit owner
+$ ozone sh volume create /myvolume --user alice
+$ ozone sh volume info /myvolume
+{
+ "name" : "myvolume",
+ "admin" : "om",
+ "owner" : "alice",
+ "acls" : [ {
+ "type" : "USER",
+ "name" : "alice",
+ "aclScope" : "ACCESS",
+ "aclList" : [ "ALL" ]
+ } ]
+}
+
+# Volume created without specifying owner (defaults to authenticated user)
+$ ozone sh volume create /myvol1
+$ ozone sh volume info /myvol1
+{
+ "name" : "myvol1",
+ "admin" : "om",
+ "owner" : "om",
+ "acls" : [ {
+ "type" : "USER",
+ "name" : "om",
+ "aclScope" : "ACCESS",
+ "aclList" : [ "ALL" ]
+ }, {
+ "type" : "GROUP",
+ "name" : "om",
+ "aclScope" : "ACCESS",
+ "aclList" : [ "READ", "LIST" ]
+ } ]
+}
+```
+
+**Note:** While the volume owner has these default ACLs, they typically don't need them because owner privileges bypass ACL checks entirely. However, these ACLs are useful for:
+
+- Audit and compliance tracking
+- Documentation of intended permissions
+- Cases where ACLs might be evaluated before owner checks
+
+### Changing Volume Ownership
+
+The volume owner can be changed after creation using the volume update command:
+
+```bash
+ozone sh volume update /myvolume --user bob
+{
+ "metadata" : { },
+ "name" : "myvolume",
+ "admin" : "om",
+ "owner" : "bob",
+ "quotaInBytes" : -1,
+ "quotaInNamespace" : -1,
+ "usedNamespace" : 0,
+ "creationTime" : "2026-01-25T15:12:12.922Z",
+ "modificationTime" : "2026-01-25T15:20:35.530Z",
+ "acls" : [ {
+ "type" : "USER",
+ "name" : "alice",
+ "aclScope" : "ACCESS",
+ "aclList" : [ "ALL" ],
+ "aclSet" : [ "ALL" ]
+ } ],
+ "refCount" : 0
+}
+```
+
+**Requirements for Changing Ownership:**
+
+- **Permissions:** The user attempting to change ownership must have `WRITE_ACL` permission on the volume. This ensures that only authorized users can transfer ownership.
+
+**Owner vs. ACLs:**
+
+Changing the volume owner via `ozone sh volume update --user <new_user>` updates the ownership metadata but **does not automatically modify ACLs**. The previous owner's ACL entries remain unchanged. If you need to revoke the old owner's access entirely, you must manage ACLs separately using ACL update commands.
+
+:::note Volume-Level Operations and Permissions
+Volume-level operations with respect to permissions can differ between Native ACL and Ranger ACL implementations. The permission requirements described here are specific to Native ACLs.
+:::
+
+For detailed information on how permissions and operations work for both **Native ACL** and **Ranger ACL**, refer to the [ACLs documentation](../../security/acls).
+
+## 3. Volume Owner Privileges
+
+The volume owner receives special privileges that provide comprehensive access to the volume and all resources within it. These privileges are enforced by Ozone's native authorizer (`OzoneNativeAuthorizer`) and bypass standard ACL checks.
+
+### Bypass ACL Checks
+
+The volume owner can perform operations on buckets, keys, and prefixes within their volume **without requiring explicit ACL permissions**. This means the owner has **implicit access** to all resources in their volume, regardless of ACL settings on those resources. The owner check happens before any ACL evaluation, providing a fast-path for owner operations.
+
+### Volume Deletion by Owner
+
+Volume owners **can delete their own volumes** because volumes are created with default ACLs that grant the owner `ALL` permissions, which includes `DELETE` permission.
+
+**Requirements for Volume Deletion:**
+
+- **DELETE Permission:** The requester must have `DELETE` ACL permission on the volume.
+- **Empty Volume:** The volume must contain no buckets. All buckets must be deleted before the volume can be deleted.
+- **Zero Reference Count:** The volume's `refCount` must be 0. If `refCount > 0`, it indicates that Ozone features (like multi-tenancy) hold a "lock" on the volume. The lock must be released first (e.g., via `ozone tenant delete <tenantId>`).
+
+:::note
+Volume creation is still an **administrative operation** that requires administrator privileges. Only administrators can create volumes.
+:::
diff --git a/versioned_docs/version-2.2.1/03-core-concepts/03-namespace/01-volumes/03-quotas.md b/versioned_docs/version-2.2.1/03-core-concepts/03-namespace/01-volumes/03-quotas.md
new file mode 100644
index 0000000000..96ae3cdd81
--- /dev/null
+++ b/versioned_docs/version-2.2.1/03-core-concepts/03-namespace/01-volumes/03-quotas.md
@@ -0,0 +1,54 @@
+---
+sidebar_label: Quotas
+---
+
+# Volume Quotas
+
+## What are Volume Quotas?
+
+Volume quotas in Ozone provide a mechanism to limit resource consumption at the volume level. They enable administrators to control and manage storage resources in multi-tenant environments, preventing any single volume from monopolizing cluster resources.
+
+Quotas act as upper bounds that constrain how much storage space and how many objects can be stored within a volume. When quotas are set, Ozone enforces these limits during write operations, ensuring that resource usage stays within the defined boundaries.
+
+## Quota Management
+
+Ozone defines two types of quota: namespace quota and storage space quota.
+
+- **Namespace Quota:** A namespace quota limits the number of objects in a volume. This number cannot be greater than `LONG.MAX_VALUE` in Java.
+- **Storage Space Quota:** A storage space quota limits the maximum used space of a volume. It allows the use of units B, KB, MB, GB and TB.
+
+### Key Characteristics
+
+- **Hierarchical Enforcement:** Volume quotas apply to the aggregate of all contained buckets
+- **Visibility:** Quota usage and limits can be monitored through the CLI and management interfaces
+- **Enforcement:** When a quota is reached, write operations fail with a descriptive error message
+
+:::note Important Notes
+
+- By default, the volume quota is unlimited.
+- The total quota of the buckets cannot exceed the volume quota.
+- Volume quota has no effect if bucket quota is not set.
+- Volume having linked bucket do not consume space quota for keys within linked bucket. Linked bucket keys will consume space quota of source volume and source bucket.
+- If the cluster is upgraded from old version less than 1.1.0, use of quota on older volumes and buckets (We can confirm by looking at the info for the volume or bucket, and if the quota value is -2 the volume or bucket is old) is not recommended. Since the old key is not counted to the bucket's usedBytes and namespace quota, the quota setting is inaccurate at this point.
+
+:::
+
+## Setting Both Quotas Simultaneously
+
+You can set both space and namespace quotas at the same time:
+
+```bash
+# Set both space (1TB) and namespace (1 million objects) quotas simultaneously
+ozone sh volume setquota --space-quota=1TB --namespace-quota=1000000 /volume1
+
+# Check current quota settings and usage
+ozone sh volume info /volume1
+
+# Clear the space quota (set space limit to unlimited)
+ozone sh volume clrquota --space-quota /volume1
+
+# Clear the namespace quota (set object count limit to unlimited)
+ozone sh volume clrquota --namespace-quota /volume1
+```
+
+For detailed information on how to set and manage both types of volume quotas using CLI commands separately, see the [Quota Operations Guide](../../../administrator-guide/operations/quota).
diff --git a/versioned_docs/version-2.2.1/03-core-concepts/03-namespace/01-volumes/README.mdx b/versioned_docs/version-2.2.1/03-core-concepts/03-namespace/01-volumes/README.mdx
new file mode 100644
index 0000000000..260fd860f5
--- /dev/null
+++ b/versioned_docs/version-2.2.1/03-core-concepts/03-namespace/01-volumes/README.mdx
@@ -0,0 +1,11 @@
+---
+sidebar_label: Volumes
+---
+
+# Volumes
+
+import DocCardList from '@theme/DocCardList';
+
+This section documents configuration and use cases for volumes: Ozone's highest level of namespace organization.
+
+<DocCardList/>
diff --git a/versioned_docs/version-2.2.1/03-core-concepts/03-namespace/02-buckets/01-overview.md b/versioned_docs/version-2.2.1/03-core-concepts/03-namespace/02-buckets/01-overview.md
new file mode 100644
index 0000000000..6bab44394d
--- /dev/null
+++ b/versioned_docs/version-2.2.1/03-core-concepts/03-namespace/02-buckets/01-overview.md
@@ -0,0 +1,87 @@
+---
+sidebar_label: Overview
+---
+
+# Buckets Overview
+
+## What is a Bucket?
+
+A **Bucket** is the second level in the Ozone data hierarchy, residing within a volume. Buckets are analogous to directories or folders in a traditional file system.
+They serve as containers for keys (data objects).
+
+**Key Characteristics:**
+
+- **Contained within Volumes:** Every bucket must belong to a volume.
+- **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 allow underscore (`_`) in volume and bucket names while still enforcing the other S3 naming rules, configure the property `ozone.om.namespace.s3.strict` to `false` in the `ozone-site.xml` of Ozone Manager. (This does not relax the rules for other non-S3 characters.)
+
+:::
+
+## Details
+
+### Creation and Management
+
+Buckets are created within a specified volume.
+
+```bash
+ozone sh bucket create /myvolume/mybucket
+```
+
+For more details on bucket operations, refer to the [Ozone CLI documentation](../../../user-guide/client-interfaces/o3#bucket-operations).
+
+### Bucket Layouts (Object Store vs. File System Optimized)
+
+Ozone supports different bucket layouts, primarily:
+
+- **Object Store (OBS):** The traditional object storage layout, where keys are stored with their full path names. This is suitable for S3-like access patterns.
+For more details, refer to the [Object Store documentation](./layouts/object-store).
+- **File System Optimized (FSO):** An optimized layout for Hadoop Compatible File System (HCFS) semantics, where intermediate directories are stored separately, improving performance for file system operations like listing and renaming.
+For more details, refer to the [Prefix FSO documentation](./layouts/file-system-optimized).
+
+### Erasure Coding
+
+Erasure Coding (EC) can be enabled at the bucket level to define data redundancy strategies. This allows for more efficient storage compared to replication, especially for large datasets.
+For more information, see the [Erasure Coding documentation](../../replication/erasure-coding).
+
+### Snapshots
+
+Ozone's snapshot feature allows users to take point-in-time consistent images of a given bucket. These snapshots are immutable and can be used for backup, recovery, archival, and incremental replication purposes.
+For more details, refer to the [Ozone Snapshot documentation](./snapshots).
+
+### GDPR Compliance
+
+Ozone provides features to support GDPR compliance, particularly the "right to be forgotten." When a GDPR-compliant bucket is created, encryption keys for deleted data are immediately removed, making the data unreadable even if the underlying blocks haven't been physically purged yet.
+For more details, refer to the [GDPR documentation](https://ozone.apache.org/docs/edge/security/gdpr.html).
+
+### 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 [Bucket Links documentation](./links).
+
+### Access Control Lists (ACLs)
+
+ACLs define permissions for buckets, controlling who can list keys, read/write data, or delete the bucket.
+For more details, refer to the [Security ACLs documentation](../../security/acls/native-acls).
diff --git a/versioned_docs/version-2.2.1/03-core-concepts/03-namespace/02-buckets/02-owners.md b/versioned_docs/version-2.2.1/03-core-concepts/03-namespace/02-buckets/02-owners.md
new file mode 100644
index 0000000000..7427cacab2
--- /dev/null
+++ b/versioned_docs/version-2.2.1/03-core-concepts/03-namespace/02-buckets/02-owners.md
@@ -0,0 +1,116 @@
+---
+sidebar_label: Owners
+---
+
+# Bucket Owners
+
+## 1. Overview
+
+Every bucket in Ozone has an **owner** property that identifies the user who owns the bucket. A bucket has a single owner. The bucket owner plays a role in access control and property management, particularly when using Ozone's native ACL authorization.
+
+## 2. Setting the Bucket Owner
+
+### During Bucket Creation
+
+When creating a bucket, the owner can be explicitly specified using the `--user` or `-u` command-line option:
+
+```bash
+ozone sh bucket create /myvolume/mybucket --user alice
+```
+
+If the owner is not specified during creation, the owner defaults based on the authentication method:
+
+- **S3 Authentication:** Owner defaults to the short username derived from the S3 access ID.
+- **Standard Authentication:** Owner defaults to the current user's short username (`UserGroupInformation.getCurrentUser().getShortUserName()`).
+
+**Example:**
+
+```bash
+# Create bucket without specifying owner (defaults to current user)
+$ ozone sh bucket create /myvol1/buck1
+$ ozone sh bucket info /myvol1/buck1
+{
+ "volumeName" : "myvol1",
+ "name" : "buck1",
+ "owner" : "om",
+ ...
+}
+```
+
+### Changing Bucket Ownership
+
+The bucket owner can be changed after creation using the bucket update command:
+
+```bash
+ozone sh bucket update <volume>/<bucket> --user <new_owner>
+```
+
+Or using the short form:
+
+```bash
+ozone sh bucket update <volume>/<bucket> -u <new_owner>
+```
+
+**Example:**
+
+```bash
+$ ozone sh bucket update /myvol1/buck1 --user bob
+{
+ "volumeName" : "myvol1",
+ "name" : "buck1",
+ "owner" : "bob",
+ "modificationTime" : "2026-01-25T16:06:38.516Z",
+ ...
+}
+```
+
+**Requirements for Changing Ownership:**
+
+- **Permissions:** When Ozone ACL is enabled, the user attempting to change ownership must have `WRITE_ACL` permission on the bucket. This ensures that only authorized users can transfer ownership.
+
+**Owner vs. ACLs:**
+
+Changing the bucket owner via `ozone sh bucket update -u <new_owner>` updates the ownership metadata but **does not automatically modify ACLs**. The previous owner's ACL entries remain unchanged. If you need to revoke the old owner's access entirely, you must manage ACLs separately using ACL update commands.
+
+## 3. Bucket Owner Privileges
+
+### Property Updates
+
+When using Ozone's native ACL authorization, the bucket owner can update bucket properties. Bucket properties include:
+
+- Storage type
+- Versioning
+- Encryption settings
+- Quotas (space and namespace)
+- Bucket layout
+- Other bucket metadata
+
+**Access Control Check:**
+
+For native ACL authorization, bucket property updates are allowed by:
+
+- Administrators
+- Bucket owners
+
+For Ranger authorization, bucket property updates are determined by Ranger policies.
+
+## 4. Volume Owner vs. Bucket Owner
+
+**Volume Owner Privileges:**
+
+The volume owner has broader privileges than the bucket owner:
+
+- Volume owners bypass ACL checks for all resources (buckets, keys, prefixes) within their volume.
+- Volume owners have implicit access to all buckets in their volume, regardless of bucket ownership or ACLs.
+
+**Bucket Owner Privileges:**
+
+Bucket owners have limited privileges:
+
+- Bucket owners can update bucket properties (when using native ACL authorization).
+- Bucket owners do **not** bypass ACL checks for keys or prefixes within the bucket.
+- Bucket ownership is primarily used for property management, not access control bypass.
+
+:::note
+Volume ownership takes precedence over bucket ownership in access control decisions. If a user is the volume owner, they have full access regardless of bucket ownership.
+:::
diff --git a/versioned_docs/version-2.2.1/03-core-concepts/03-namespace/02-buckets/03-quotas.md b/versioned_docs/version-2.2.1/03-core-concepts/03-namespace/02-buckets/03-quotas.md
new file mode 100644
index 0000000000..5656bc3879
--- /dev/null
+++ b/versioned_docs/version-2.2.1/03-core-concepts/03-namespace/02-buckets/03-quotas.md
@@ -0,0 +1,10 @@
+---
+sidebar_label: Quotas
+---
+
+# Bucket Quotas
+
+## Quota Management
+
+Similar to volumes, buckets can also have storage space and namespace quotas applied to them.
+For comprehensive information on configuring and managing quotas, see the [Quota Management documentation](../../../administrator-guide/operations/quota).
diff --git a/versioned_docs/version-2.2.1/03-core-concepts/03-namespace/02-buckets/04-layouts/01-object-store.md b/versioned_docs/version-2.2.1/03-core-concepts/03-namespace/02-buckets/04-layouts/01-object-store.md
new file mode 100644
index 0000000000..7d352a27b8
--- /dev/null
+++ b/versioned_docs/version-2.2.1/03-core-concepts/03-namespace/02-buckets/04-layouts/01-object-store.md
@@ -0,0 +1,179 @@
+---
+sidebar_label: Object Store (OBS)
+---
+
+# Object Store Buckets (OBS)
+
+## 1. Overview
+
+Object Store bucket layout stores keys with their full path names in a flat namespace, optimized for S3-compatible access patterns. Each key is stored independently with its complete path (e.g., `dir1/dir2/file.txt`), similar to Amazon S3.
+
+Unlike File System Optimized (FSO) buckets, Object Store buckets:
+
+- Do not create intermediate directory entries
+- Preserve key names exactly as provided (no path normalization)
+- Prioritize S3 API compatibility over file system semantics
+
+:::note
+Apache Ozone supports three bucket layout types:
+
+- **OBJECT_STORE (OBS)**, **FILE_SYSTEM_OPTIMIZED (FSO)** and **LEGACY** (deprecated layout for backward compatibility).
+
+:::
+
+## 2. How It Works
+
+- Keys are stored with their full path names as single entries. When creating `dir1/dir2/file.txt`, only the key itself is stored—no intermediate directories are created.
+
+- Operations support prefix-based listing and filtering. Keys are independent objects—deleting one does not affect others, even if they share a common prefix.
+
+- Object Store is the **default layout** for buckets created through the **S3 Gateway**, ensuring S3 API compatibility.
+
+### Example: Creating Keys
+
+When you create keys in an Object Store bucket:
+
+```bash
+# Create these keys:
+ozone sh key put /myvolume/mybucket/images/photo1.jpg photo1.jpg
+ozone sh key put /myvolume/mybucket/images/subfolder/photo3.jpg photo3.jpg
+ozone sh key put /myvolume/mybucket/data/2024/01/report.json report.json
+```
+
+The KeyTable will contain three independent entries:
+
+- `/myvolume/mybucket/images/photo1.jpg`
+- `/myvolume/mybucket/images/subfolder/photo3.jpg`
+- `/myvolume/mybucket/data/2024/01/report.json`
+
+**No intermediate directories are created** - the paths (`images/`, `images/subfolder/`, `data/2024/01/`) are just part of the key names themselves.
+
+**Comparison with File System Optimized Layout:**
+
+```text
+Object Store (OBS) Structure: File System Optimized (FSO) Structure:
+┌─────────────────────────┐ ┌─────────────────────────┐
+│ KeyTable │ │ DirectoryTable │
+│ (Flat, full paths) │ │ (Hierarchical IDs) │
+│ │ │ │
+│ /vol/bucket/dir/file │ │ /volID/bucketID/dirID │
+│ /vol/bucket/dir/file2 │ │ /volID/bucketID/dir2ID │
+│ /vol/bucket/dir2/file3 │ │ │
+└─────────────────────────┘ │ FileTable │
+ │ (Files with parent IDs) │
+ │ │
+ │ dirID/file │
+ │ dirID/file2 │
+ │ dir2ID/file3 │
+ └─────────────────────────┘
+```
+
+## 3. Command Line Operations
+
+### Creating an Object Store Bucket
+
+To create a bucket with Object Store layout, use the `--layout` option with the value `obs` or `OBJECT_STORE`:
+
+```bash
+# Using short form 'obs'
+ozone sh bucket create /myvolume/mybucket --layout obs
+
+# Using full form 'OBJECT_STORE'
+ozone sh bucket create /myvolume/mybucket --layout OBJECT_STORE
+```
+
+**Example:**
+
+```bash
+$ ozone sh bucket create /s3v/myapp-data --layout obs
+Bucket myapp-data is created
+```
+
+### Checking Bucket Layout
+
+To verify the layout of an existing bucket, use the `bucket info` command:
+
+```bash
+ozone sh bucket info /myvolume/mybucket
+```
+
+The output will include the `bucketLayout` field:
+
+```json
+{
+ "volumeName" : "myvolume",
+ "name" : "mybucket",
+ "bucketLayout" : "OBJECT_STORE",
+ "storageType" : "DISK",
+ "versioning" : false,
+ "creationTime" : "2024-01-15T10:30:00.000Z",
+ "modificationTime" : "2024-01-15T10:30:00.000Z"
+}
+```
+
+### Deleting Keys
+
+Delete keys from an Object Store bucket:
+
+```bash
+# Delete a single key
+ozone sh key delete /myvolume/mybucket/dir1/dir2/file.txt
+
+# Delete multiple keys (requires prefix matching)
+ozone sh key delete /myvolume/mybucket/dir1/ --recursive
+```
+
+**Note**: The `--recursive` flag deletes all keys with the specified prefix, but this is not an atomic operation - it deletes keys one by one.
+
+### Deleting Buckets
+
+Delete an Object Store bucket:
+
+```bash
+# Delete empty bucket
+ozone sh bucket delete /myvolume/mybucket
+
+# Delete bucket with all keys (recursive)
+ozone sh bucket delete /myvolume/mybucket --recursive
+```
+
+**Warning**: Recursive deletion permanently removes all keys in the bucket. There is no recovery option.
+
+## 4. Configuration
+
+### Default Bucket Layout
+
+You can configure the default bucket layout used when creating buckets without specifying the `--layout` option. Set this in `ozone-site.xml`:
+
+```xml
+<property>
+ <name>ozone.default.bucket.layout</name>
+ <value>OBJECT_STORE</value>
+</property>
+```
+
+### S3 Gateway Default Layout
+
+For buckets created through the S3 Gateway, configure the default layout:
+
+```xml
+<property>
+ <name>ozone.s3g.default.bucket.layout</name>
+ <value>OBJECT_STORE</value>
+</property>
+```
+
+## 5. Limitations
+
+When using Object Store bucket layout, be aware of the following limitations:
+
+- No atomic rename (copy and delete required)
+- No atomic directory delete
+- No directory operations (directories are part of key names)
+- Limited Hadoop file system compatibility
+- No path normalization
+
+## 6. Best Practices
+
+- Use Object Store layout for S3 APIs; use FSO for file system operations
+- Organize keys with consistent prefixes (e.g., `year/month/day/file.txt`)
diff --git a/versioned_docs/version-2.2.1/03-core-concepts/03-namespace/02-buckets/04-layouts/02-file-system-optimized.md b/versioned_docs/version-2.2.1/03-core-concepts/03-namespace/02-buckets/04-layouts/02-file-system-optimized.md
new file mode 100644
index 0000000000..13fa8f1447
--- /dev/null
+++ b/versioned_docs/version-2.2.1/03-core-concepts/03-namespace/02-buckets/04-layouts/02-file-system-optimized.md
@@ -0,0 +1,78 @@
+---
+sidebar_label: File System Optimized (FSO)
+---
+
+# File System Optimized Buckets (FSO)
+
+## Overview
+
+**File System Optimized** (FSO) is a bucket layout optimized for Hadoop Compatible File System (HCFS) operations. Unlike the Object Store (OBS) layout, FSO maintains separate entries for intermediate directories, enabling efficient file system operations like directory listing, renaming, and deletion.
+FSO buckets support **atomic rename** and **delete operations** on directories at any level in constant time, regardless of directory depth or the number of files contained within.
+
+For example, in an FSO bucket, keys are stored with their hierarchical structure preserved:
+
+```text
+/mybucket/data/2025/nov/report
+/mybucket/data/2025/dec/summary
+/mybucket/archive/2024/logs/applog
+```
+
+Each intermediate directories (`data`, `2025`, `nov`, etc.) are stored as a separate entry, allowing efficient directory-level operations.
+
+:::note
+FSO is the default bucket layout in Ozone. To explicitly specify FSO layout when creating a bucket, use the `--layout` flag:
+
+```bash
+ozone sh bucket create /<volume-name>/<bucket-name> --layout FILE_SYSTEM_OPTIMIZED
+```
+
+:::
+
+## Why FSO for Ozone?
+
+### 1. Atomic Operations (The O(1) Factor)
+
+In a standard Object Store, if you rename a directory containing **1 million files**, the system has to:
+
+- Find all 1 million keys
+- Copy them to a new path string
+- Delete the 1 million old keys
+
+This is **O(n)** operation — the more files you have, the longer it takes.
+
+In FSO, a **rename** is just a metadata pointer update. To rename `/data` to `/archive`, Ozone simply finds the entry for `data` in the `DirectoryTable` and updates its name to `archive`. All the children (the millions of files) stay exactly where they are because they point to the `unique ID` of that directory, not its name.
+
+### 2. Delete operations
+
+Deleting a directory with millions of files is efficient because all child entries share the same parent ID prefix, allowing Ozone to quickly locate and remove them using prefix-based queries, rather than scanning the entire namespace.
+
+## When to Use FSO vs Object Store (OBS)
+
+Choose **File System Optimized (FSO)** when:
+
+- Using Hadoop Compatible File System interfaces
+- Storing data for analytics workloads (Hive, Spark ...)
+- Working with hierarchical directory structures
+- Requiring atomic directory operations (rename, delete)
+- Needing trash/recycle bin functionality
+
+Choose **Object Store (OBS)** when:
+
+- Primarily using S3-compatible APIs
+- Working with flat object access patterns
+
+## Configuration
+
+To update the default layout when creating buckets, configure these properties in `ozone-site.xml`:
+
+| Property | Default Value | Description |
+|----------|---------------|-------------|
+| `ozone.default.bucket.layout` | none | Sets the default layout for all buckets if no layout is specified during creation by the client |
+| `ozone.client.fs.default.bucket.layout` | `FILE_SYSTEM_OPTIMIZED` | Sets the default layout for buckets created using the OFS client |
+| `ozone.s3g.default.bucket.layout` | `OBJECT_STORE` | Defines the default layout for buckets created through the S3 API |
+
+For detailed technical information about the internal metadata structure and implementation
+
+<!--
+see the [File System Optimization System Internals](../../../../system-internals/features/filesystem-optimization) documentation.
+-->
diff --git a/versioned_docs/version-2.2.1/03-core-concepts/03-namespace/02-buckets/04-layouts/README.mdx b/versioned_docs/version-2.2.1/03-core-concepts/03-namespace/02-buckets/04-layouts/README.mdx
new file mode 100644
index 0000000000..04ff0e1887
--- /dev/null
+++ b/versioned_docs/version-2.2.1/03-core-concepts/03-namespace/02-buckets/04-layouts/README.mdx
@@ -0,0 +1,11 @@
+---
+sidebar_label: Layouts
+---
+
+# Bucket Layouts
+
+import DocCardList from '@theme/DocCardList';
+
+This section documents the different bucket layouts supported by Ozone and their use cases.
+
+<DocCardList/>
diff --git a/versioned_docs/version-2.2.1/03-core-concepts/03-namespace/02-buckets/05-replication.md b/versioned_docs/version-2.2.1/03-core-concepts/03-namespace/02-buckets/05-replication.md
new file mode 100644
index 0000000000..d46c3422af
--- /dev/null
+++ b/versioned_docs/version-2.2.1/03-core-concepts/03-namespace/02-buckets/05-replication.md
@@ -0,0 +1,7 @@
+---
+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.
diff --git a/versioned_docs/version-2.2.1/03-core-concepts/03-namespace/02-buckets/06-encryption.md b/versioned_docs/version-2.2.1/03-core-concepts/03-namespace/02-buckets/06-encryption.md
new file mode 100644
index 0000000000..5cf09826d4
--- /dev/null
+++ b/versioned_docs/version-2.2.1/03-core-concepts/03-namespace/02-buckets/06-encryption.md
@@ -0,0 +1,11 @@
+---
+sidebar_label: Encryption
+---
+
+# Bucket Level Encryption
+
+## Transparent Data Encryption - TDE
+
+Buckets can be configured for Transparent Data Encryption (TDE) at the time of creation.
+When TDE is enabled, all data written to the bucket is automatically encrypted at rest using a specified encryption key.
+For detailed steps on setting up and using TDE, refer to the [Securing TDE documentation](../../../administrator-guide/configuration/security/encryption/transparent-data-encryption).
diff --git a/versioned_docs/version-2.2.1/03-core-concepts/03-namespace/02-buckets/07-links.md b/versioned_docs/version-2.2.1/03-core-concepts/03-namespace/02-buckets/07-links.md
new file mode 100644
index 0000000000..715fc02a26
--- /dev/null
+++ b/versioned_docs/version-2.2.1/03-core-concepts/03-namespace/02-buckets/07-links.md
@@ -0,0 +1,61 @@
+---
+sidebar_label: Links
+---
+
+# Bucket Links
+
+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](../../../user-guide/client-interfaces/s3) and [S3 Multi-Tenancy documentation](../../../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).
diff --git a/versioned_docs/version-2.2.1/03-core-concepts/03-namespace/02-buckets/08-snapshots.md b/versioned_docs/version-2.2.1/03-core-concepts/03-namespace/02-buckets/08-snapshots.md
new file mode 100644
index 0000000000..d5da5df52c
--- /dev/null
+++ b/versioned_docs/version-2.2.1/03-core-concepts/03-namespace/02-buckets/08-snapshots.md
@@ -0,0 +1,14 @@
+---
+sidebar_label: Snapshots
+---
+
+# Bucket Snapshots
+
+A Snapshot is a point-in-time, read-only image of a Bucket.
+It captures the exact state of the bucket at the moment of creation, allowing users to access historical data or perform backups without interrupting ongoing write operations.
+
+## Snapshot Key characteristics
+
+- **Instantaneous**: Snapshot creation is an O(1) operation. It utilizes metadata within the Ozone Manager, making it extremely fast regardless of the bucket's size.
+- **Efficient**: Snapshots do not duplicate data blocks physically. Storage space is claimed only when the live data is modified or deleted, ensuring storage efficiency.
+- **Accessible**: Users can access snapshot data through the virtual `.snapshot` directory.
diff --git a/versioned_docs/version-2.2.1/03-core-concepts/03-namespace/02-buckets/README.mdx b/versioned_docs/version-2.2.1/03-core-concepts/03-namespace/02-buckets/README.mdx
new file mode 100644
index 0000000000..4c2df2c8a9
--- /dev/null
+++ b/versioned_docs/version-2.2.1/03-core-concepts/03-namespace/02-buckets/README.mdx
@@ -0,0 +1,11 @@
+---
+sidebar_label: Buckets
+---
+
+# Buckets
+
+import DocCardList from '@theme/DocCardList';
+
+This section documents configuration and use cases for buckets: the second level of organization in Ozone's namespace.
+
+<DocCardList/>
diff --git a/versioned_docs/version-2.2.1/03-core-concepts/03-namespace/03-keys/01-overview.md b/versioned_docs/version-2.2.1/03-core-concepts/03-namespace/03-keys/01-overview.md
new file mode 100644
index 0000000000..b4f3c42c50
--- /dev/null
+++ b/versioned_docs/version-2.2.1/03-core-concepts/03-namespace/03-keys/01-overview.md
@@ -0,0 +1,58 @@
+---
+sidebar_label: Overview
+---
+
+# Keys
+
+## What is a Key?
+
+A **Key** is the fundamental data object in Ozone, analogous to a file in a traditional file system. Keys are stored within buckets and represent the actual data that users interact with.
+
+**Key Characteristics:**
+
+- **Contained within Buckets:** Every key must reside within a bucket.
+- **Immutable Data Blocks:** Once written, the underlying data blocks of a key are immutable. Updates or modifications to a key typically result in new versions or new data blocks being written, with the metadata pointing to the latest version.
+
+## Details
+
+### Creation, Reading, and Management
+
+Keys are created, read, and managed using the Ozone CLI or various client APIs (Java, S3, etc.).
+
+```bash
+ozone sh key put /myvolume/mybucket/mykey.txt /path/to/local/file.txt
+```
+
+For more details on key operations, refer to the [Ozone CLI documentation](../../../user-guide/client-interfaces/o3#key-operations).
+
+### Key Write and Read Process
+
+When a client writes a key, the Ozone Manager handles the metadata (key name, location of data blocks), and the Datanodes store the actual data blocks. For reads, the Ozone Manager provides the client with the locations of the data blocks, which the client then retrieves directly from the Datanodes.
+
+<!-- TODO: Link to Ozone Manager documentation -->
+For a deeper dive into the key write and read process, refer to the Ozone Manager documentation.
+
+### Atomic Key Replacement
+
+Ozone supports atomic key replacement, ensuring that a key is only overwritten if it hasn't changed since it was last read. This prevents lost updates in concurrent write scenarios.
+
+<!-- TODO: Link to overwrite-key-only-if-unchanged design document when created -->
+For more details, refer to the Overwriting Key Only If Unchanged design document.
+
+### Trash
+
+When keys are deleted from File System Optimized (FSO) buckets, they are moved to a trash directory, allowing for recovery. For Object Store (OBS) buckets, keys are permanently deleted.
+
+For more information on the trash feature, refer to the [Trash documentation](../../../administrator-guide/operations/trash).
+
+### Encryption
+
+If the parent bucket is encrypted, all keys written to that bucket will be transparently encrypted.
+
+For more details, refer to the [Transparent Data Encryption documentation](../../../administrator-guide/configuration/security/encryption/transparent-data-encryption).
+
+### Access Control Lists (ACLs)
+
+ACLs can also be applied to individual keys, providing fine-grained control over read and write permissions.
+
+For more details, refer to the [Native ACLs documentation](../../security/acls/native-acls).
diff --git a/versioned_docs/version-2.2.1/03-core-concepts/03-namespace/03-keys/README.mdx b/versioned_docs/version-2.2.1/03-core-concepts/03-namespace/03-keys/README.mdx
new file mode 100644
index 0000000000..6ac2896436
--- /dev/null
+++ b/versioned_docs/version-2.2.1/03-core-concepts/03-namespace/03-keys/README.mdx
@@ -0,0 +1,11 @@
+---
+sidebar_label: Keys
+---
+
+# Keys
+
+import DocCardList from '@theme/DocCardList';
+
+This section documents the fundamental data objects in Ozone: keys, which are analogous to files in a traditional file system.
+
+<DocCardList/>
diff --git a/versioned_docs/version-2.2.1/03-core-concepts/03-namespace/README.mdx b/versioned_docs/version-2.2.1/03-core-concepts/03-namespace/README.mdx
new file mode 100644
index 0000000000..7d7a88c452
--- /dev/null
+++ b/versioned_docs/version-2.2.1/03-core-concepts/03-namespace/README.mdx
@@ -0,0 +1,11 @@
+---
+sidebar_label: Namespace
+---
+
+# Namespace Layout
+
+import DocCardList from '@theme/DocCardList';
+
+This section documents the layout of Ozone's namespace.
+
+<DocCardList/>
diff --git a/versioned_docs/version-2.2.1/03-core-concepts/04-security/01-kerberos.md b/versioned_docs/version-2.2.1/03-core-concepts/04-security/01-kerberos.md
new file mode 100644
index 0000000000..1c87e740a6
--- /dev/null
+++ b/versioned_docs/version-2.2.1/03-core-concepts/04-security/01-kerberos.md
@@ -0,0 +1,9 @@
+---
+sidebar_label: Kerberos
+---
+
+# Authentication with Kerberos
+
+**TODO:** File a subtask under [HDDS-9857](https://issues.apache.org/jira/browse/HDDS-9857) and complete this page or section.
+
+## Using SPNEGO to Authenticate with Kerberos over HTTP
diff --git a/versioned_docs/version-2.2.1/03-core-concepts/04-security/02-acls/01-native-acls.md b/versioned_docs/version-2.2.1/03-core-concepts/04-security/02-acls/01-native-acls.md
new file mode 100644
index 0000000000..d6b18436cf
--- /dev/null
+++ b/versioned_docs/version-2.2.1/03-core-concepts/04-security/02-acls/01-native-acls.md
@@ -0,0 +1,227 @@
+---
+sidebar_label: Native ACLs
+---
+
+# Native ACLs
+
+Ozone supports a set of native ACLs.
+These ACLs can be used independently of Ozone ACL plugin such as Ranger.
+Add the following properties to the `ozone-site.xml` to enable native ACLs.
+
+| Property | Value |
+| -------- | ----- |
+| `ozone.acl.enabled` | `true` |
+| `ozone.acl.authorizer.class` | `org.apache.hadoop.ozone.security.acl.OzoneNativeAuthorizer` |
+
+Ozone ACLs are a super set of Posix and S3 ACLs.
+
+The general format of an ACL is *object*:*who*:*rights*:*scope*.
+
+Where an *object* can be:
+
+1. **Volume** - An Ozone volume. e.g. */volume*
+2. **Bucket** - An Ozone bucket. e.g. */volume/bucket*
+3. **Key** - An object key or an object. e.g. */volume/bucket/key*
+4. **Prefix** - A path prefix for a specific key. e.g. */volume/bucket/prefix1/prefix2*
+
+Where a *who* can be:
+
+1. **User** - A user in the Kerberos domain. User like in Posix world can be
+named or unnamed.
+2. **Group** - A group in the Kerberos domain. Group also like in Posix world
+can be named or unnamed.
+3. **World** - All authenticated users in the Kerberos domain. This maps to
+others in the Posix domain.
+4. **Anonymous** - Ignore the user field completely. This is an extension to
+the Posix semantics, This is needed for S3 protocol, where we express that
+we have no way of knowing who the user is or we don't care.
+
+:::tip
+A S3 user accessing Ozone via AWS v4 signature protocol will be translated to the appropriate Kerberos user by Ozone Manager.
+:::
+
+Where a *right* can be:
+
+1. **Create** – This ACL provides a user the ability to create buckets in a
+volume and keys in a bucket. Please note: Under Ozone, Only admins can create volumes.
+2. **List** – This ACL allows listing of buckets and keys. This ACL is attached
+ to the volume and buckets which allow listing of the child objects. Please note: The user and admins can list the volumes owned by the user.
+3. **Delete** – Allows the user to delete a volume, bucket or key.
+4. **Read** – Allows the user to read the metadata of a Volume and Bucket and
+data stream and metadata of a key.
+5. **Write** - Allows the user to write the metadata of a Volume and Bucket and
+allows the user to overwrite an existing Ozone key.
+6. **Read_ACL** – Allows a user to read the ACL on a specific object.
+7. **Write_ACL** – Allows a user to write the ACL on a specific object.
+
+Where an *scope* can be:
+
+1. **ACCESS** – Access ACL is applied only to the specific object and not inheritable. It controls the access to the object itself.
+2. **DEFAULT** - Default ACL is applied to the specific object and will be inherited by object's descendants. Default ACLs cannot be set on keys (as there can be no objects under a key).
+
+ :::note
+ ACLs inherited from parent's Default ACLs will follow the following rules based on different bucket layout:
+
+ - **Legacy with EnableFileSystem or FSO**: inherit the immediate parent's DEFAULT ACLs. If none, inherit the bucket DEFAULT ACLs.
+ - **Legacy with DisableFileSystem or OBS**: inherit the bucket DEFAULT ACLs.
+
+ :::
+
+## Ozone Native ACL APIs
+
+The ACLs can be manipulated by a set of APIs supported by Ozone. The APIs
+supported are:
+
+1. **SetAcl** – This API will take user principal, the name, type
+ of the Ozone object and a list of ACLs.
+2. **GetAcl** – This API will take the name and type of the Ozone object
+ and will return a list of ACLs.
+3. **AddAcl** - This API will take the name, type of the Ozone object, the
+ ACL, and add it to existing ACL entries of the Ozone object.
+4. **RemoveAcl** - This API will take the name, type of the
+ ozone object and the ACL that has to be removed.
+
+## ACL Manipulation Using Ozone CLI
+
+The ACLs can also be manipulated by using the `ozone sh` commands.
+
+Usage:
+
+```bash
+ozone sh <object> <action> [-a=<value>[,<value>...]] <object-uri>
+```
+
+`-a` is for the comma separated list of ACLs. It is required for all subcommands except `getacl`.
+
+`<value>` is of the form **`type:name:rights[scope]`**.
+
+- **type** can be user, group, world or anonymous.
+- **name** is the name of the user/group. For world and anonymous type, name should either be left empty or be WORLD or ANONYMOUS respectively.
+- **rights** can be (read=r, write=w, delete=d, list=l, all=a, none=n, create=c, read_acl=x, write_acl=y)
+- **scope** can be **ACCESS** or **DEFAULT**. If not specified, default is **ACCESS**.
+
+:::warning
+When the object is a prefix, the path-to-object must contain the full path from volume till the directory or prefix of the key. i.e.,
+
+```bash
+ /volume/bucket/some/key/prefix/
+```
+
+Note: the tail "/" is required.
+:::
+
+Following are the supported ACL actions.
+
+### `setacl`
+
+```shell
+$ ozone sh bucket setacl -a user:testuser2:a /vol1/bucket1
+ ACLs set successfully.
+$ ozone sh bucket setacl -a user:om:a,group:om:a /vol1/bucket2
+ ACLs set successfully.
+$ ozone sh bucket setacl -a=anonymous::lr /vol1/bucket3
+ ACLs set successfully.
+$ ozone sh bucket setacl -a world::a /vol1/bucket4
+ ACLs set successfully.
+```
+
+### `getacl`
+
+```shell
+$ ozone sh bucket getacl /vol1/bucket2
+[ {
+ "type" : "USER",
+ "name" : "om/om@EXAMPLE.COM",
+ "aclScope" : "ACCESS",
+ "aclList" : [ "ALL" ]
+}, {
+ "type" : "GROUP",
+ "name" : "om",
+ "aclScope" : "ACCESS",
+ "aclList" : [ "ALL" ]
+} ]
+```
+
+### `addacl`
+
+```shell
+$ ozone sh bucket addacl -a user:testuser2:a /vol1/bucket2
+ACL user:testuser2:a[ACCESS] added successfully.
+
+$ ozone sh bucket addacl -a user:testuser:rxy[DEFAULT] /vol1/bucket2
+ACL user:testuser:rxy[DEFAULT] added successfully.
+
+$ ozone sh prefix addacl -a user:testuser2:a[DEFAULT] /vol1/buck3/dir1/
+ACL user:testuser2:a[DEFAULT] added successfully.
+```
+
+### `removeacl`
+
+```shell
+$ ozone sh bucket removeacl -a user:testuser:r[DEFAULT] /vol1/bucket2
+ACL user:testuser:r[DEFAULT] removed successfully.
+```
+
+## Differences Between Ozone ACL and S3 ACL
+
+Ozone ACLs and S3 ACLs differ primarily in their scope and support.
+
+- **S3 ACLs**: Currently, only S3 Bucket ACL is implemented in Ozone (a beta feature). S3 Object ACL is not yet implemented. Any `PutObjectAcl` request will result in a `501: Not Implemented` response code.
+- **Ozone ACLs**: Ozone ACLs provide a more comprehensive and flexible access control mechanism. They are designed to work seamlessly with Ozone's native architecture and support various rights and scopes as mentioned above.
+
+## Ozone File System ACL API
+
+- ACL-related APIs in Ozone file system implementation (`ofs` and `o3fs`), such as `getAclStatus`, `setAcl`, `modifyAclEntries`, `removeAclEntries`, `removeDefaultAcl`, and `removeAcl` are not supported. These operations will throw an UnsupportedOperationException.
+- Similarly, HttpFS ACL-related APIs.
+
+These limitations should be taken into account when integrating Ozone with applications that rely on S3 or file system ACL operations.
+
+## Permission comparison table
+
+The table below shows the mapping between Ozone operations and the required Native ACL permissions.
+
+`<admin>`: for native ACL, all access is granted for all operations
+
+`<owner>`: for native ACL, owner of volume / bucket have all access to further hierarchy
+
+### Volume related operation
+
+| `Operation` | `Volume permission` |
+|--------------------------|---------------------|
+| `Create volume` | `<admin>` |
+| `List volume` | `<admin>, <configuration: listall>` |
+| `Get volume info` | `READ, <admin>, <owner>` |
+| `Delete volume` | `DELETE, <admin>, <owner>` |
+| `Set Quota` | `WRITE, <admin>, <owner>` |
+| `Set Owner` | `WRITE_ACL, <admin>, <owner>` |
+| `Create Tenant (and volume)` | `CREATE, <admin>, <owner>` |
+| `Delete Tenant` | `WRITE_ACL, <admin>, <owner>` |
+| `Read ACL` | `READ_ACL, <admin>, <owner>` |
+| `Write ACL` | `WRITE_ACL, <admin>, <owner>` |
+
+### Bucket related operation
+
+| `Operation` | `Volume permission` | `Bucket permission` |
+|--------------------------|---------------------|---------------------|
+| `Create bucket` | `WRITE, <admin>, <owner>` | |
+| `List bucket` | `LIST, <admin>, <owner>` | |
+| `Get bucket info` | `READ, <admin>, <owner>` | `READ, <admin>, <owner>` |
+| `Delete bucket` | `READ, <admin>, <owner>` | `DELETE, <admin>, <owner>` |
+| `Update bucket property (quota, replication, ...)` | `READ` | `<admin>, <owner>` |
+| `List Snapshot` | `READ, <admin>, <owner>` | `LIST, <admin>, <owner>` |
+| `List Trash` | `READ, <admin>, <owner>` | `LIST, <admin>, <owner>` |
+| `Trash Recover` | `READ, <admin>, <owner>` | `WRITE, <admin>, <owner>` |
+| `Set Owner` | `READ, <admin>, <owner>` | `WRITE_ACL, <admin>, <owner>` |
+| `Read ACL` | `READ, <admin>, <owner>` | `READ_ACL, <admin>, <owner>` |
+| `Write ACL` | `READ, <admin>, <owner>` | `WRITE_ACL, <admin>, <owner>` |
+
+### FSO / OBS related operation for key and files
+
+| `Operation` | `Volume permission` | `Bucket permission` | `Key permission` |
+|--------------------------|---------------------|---------------------|------------------|
+| `List key` | `READ, <admin>, <owner>` | `LIST, READ, <admin>, <owner>` | |
+| `Write key` | `READ, <admin>, <owner>` | `WRITE, <admin>, <owner>` | `CREATE, WRITE, <admin>` |
+| `Delete key` | `READ, <admin>, <owner>` | `READ, <admin>, <owner>` | `DELETE (*recursive check all child), <admin>` |
+| `Read key` | `READ, <admin>, <owner>` | `READ, <admin>, <owner>` | `READ, <admin>, <owner>` |
+| `Read ACL` | `READ, <admin>, <owner>` | `READ, <admin>, <owner>` | `READ_ACL, <admin>, <owner>` |
+| `Write ACL` | `READ, <admin>, <owner>` | `READ, <admin>, <owner>` | `WRITE_ACL, <admin>, <owner>` |
diff --git a/versioned_docs/version-2.2.1/03-core-concepts/04-security/02-acls/02-ranger-acls.md b/versioned_docs/version-2.2.1/03-core-concepts/04-security/02-acls/02-ranger-acls.md
new file mode 100644
index 0000000000..94bc2bcce3
--- /dev/null
+++ b/versioned_docs/version-2.2.1/03-core-concepts/04-security/02-acls/02-ranger-acls.md
@@ -0,0 +1,52 @@
+---
+sidebar_label: Ranger authorization policies
+---
+
+# Ranger authorization policies
+
+Ozone supports two authorization models: **Native ACLs** and **Apache Ranger policies**.
+
+- [**Native ACLs**](./native-acls) are managed through Ozone's command-line interface or APIs and are stored internally within Ozone's metadata. They are suitable for simpler security requirements and for environments where Ozone is run as a standalone service.
+
+- **Apache Ranger** provides centralized security administration for the entire Hadoop ecosystem. If you are already using Ranger to manage permissions for other components like HDFS, Hive, or HBase, integrating Ozone with Ranger allows you to manage all access policies in one place. Ranger offers a user-friendly UI, centralized auditing, and more advanced policy features. For more information about configuring Apache Ranger authorization for Ozone, refer to [configuring Apache Ranger](. [...]
+
+When Ranger is enabled, it becomes the sole authority for access control, and native ACLs are ignored.
+
+## Permission comparison table
+
+The table below shows the mapping between Ozone operations and the required Ranger permissions. An Ozone Manager plugin synchronizes these policies from Ranger.
+
+### Volume related operation
+
+| `Operation` | `Volume permission` |
+|--------------------------|---------------------|
+| `Create volume` | `CREATE` |
+| `List volume` | `LIST` |
+| `Get volume info` | `READ` |
+| `Delete volume` | `DELETE` |
+| `Set Quota` | `WRITE` |
+| `Set Owner` | `WRITE_ACL` |
+| `Create Tenant (and volume)` | `CREATE` |
+| `Delete Tenant` | `WRITE_ACL` |
+
+### Bucket related operation
+
+| `Operation` | `Volume permission` | `Bucket permission` |
+|--------------------------|---------------------|---------------------|
+| `Create bucket` | `READ` | `CREATE` |
+| `List bucket` | `LIST, READ` | |
+| `Get bucket info` | `READ` | `READ` |
+| `Delete bucket` | `READ` | `DELETE` |
+| `Update bucket property (quota, replication, ...)` | `READ` | `WRITE` |
+| `List Snapshot` | `READ` | `LIST` |
+| `List Trash` | `READ` | `LIST` |
+| `Trash Recover` | `READ` | `WRITE` |
+| `Set Owner` | `READ` | `WRITE_ACL` |
+
+### FSO / OBS related operation for key and files
+
+| `Operation` | `Volume permission` | `Bucket permission` | `Key permission` |
+|--------------------------|---------------------|---------------------|------------------|
+| `List key` | `READ` | `LIST, READ` | |
+| `Write key` | `READ` | `READ` | `CREATE, WRITE` |
+| `Read key` | `READ` | `READ` | `READ` |
diff --git a/versioned_docs/version-2.2.1/03-core-concepts/04-security/02-acls/README.mdx b/versioned_docs/version-2.2.1/03-core-concepts/04-security/02-acls/README.mdx
new file mode 100644
index 0000000000..8423fefc72
--- /dev/null
+++ b/versioned_docs/version-2.2.1/03-core-concepts/04-security/02-acls/README.mdx
@@ -0,0 +1,11 @@
+---
+sidebar_label: ACLs
+---
+
+# Authorization With ACLs
+
+import DocCardList from '@theme/DocCardList';
+
+This section covers Ozone's ACL support, which can be used to restrict access to different portions of the namespace once a user has authenticated with [Kerberos](../kerberos). To configure access for administrator operations that do not involve the Ozone namespace, see the [Administrator Guide](../../../administrator-guide/configuration/security/administrators).
+
+<DocCardList/>
diff --git a/versioned_docs/version-2.2.1/03-core-concepts/04-security/README.mdx b/versioned_docs/version-2.2.1/03-core-concepts/04-security/README.mdx
new file mode 100644
index 0000000000..7b0006bb3e
--- /dev/null
+++ b/versioned_docs/version-2.2.1/03-core-concepts/04-security/README.mdx
@@ -0,0 +1,11 @@
+---
+sidebar_label: Security
+---
+
+# Using a Secure Ozone Cluster
+
+import DocCardList from '@theme/DocCardList';
+
+This section documents the primary mechanisms Ozone uses for authentication and authorization of users and administrators. To configure encryption and other security mechanisms within an Ozone cluster, see the [Administrator Guide](../../administrator-guide/configuration/security).
+
+<DocCardList/>
diff --git a/versioned_docs/version-2.2.1/03-core-concepts/05-high-availability/01-scm-ha.md b/versioned_docs/version-2.2.1/03-core-concepts/05-high-availability/01-scm-ha.md
new file mode 100644
index 0000000000..277bb12fa9
--- /dev/null
+++ b/versioned_docs/version-2.2.1/03-core-concepts/05-high-availability/01-scm-ha.md
@@ -0,0 +1,17 @@
+---
+sidebar_label: SCM High Availability
+---
+
+# SCM High Availability
+
+Ozone has two metadata-manager nodes (*Ozone Manager* for key space management and *Storage Container Management* for block space management) and multiple storage nodes (Datanode). Data is replicated between Datanodes with the help of RAFT consensus algorithm.
+
+To avoid any single point of failure the metadata-manager nodes also should have a HA setup.
+
+Both Ozone Manager and Storage Container Manager supports HA. In this mode the internal state is replicated via RAFT (with Apache Ratis)
+
+Please check the [OM HA documentation](om-ha) for HA setup of Ozone Manager (OM). While they can be setup for HA independently, a reliable, full HA setup requires enabling HA for both services.
+
+## Service ID and SCM Host Mapping
+
+To select between the available SCM nodes, a logical name (a `serviceId`) is required for each of the clusters which can be resolved to the IP addresses (and domain names) of the Storage Container Managers. Check out the [SCM HA configuration documentation](../../administrator-guide/configuration/high-availability/scm-ha) for details on how to configure the service ID and map it to individual SCM nodes.
diff --git a/versioned_docs/version-2.2.1/03-core-concepts/05-high-availability/02-om-ha.md b/versioned_docs/version-2.2.1/03-core-concepts/05-high-availability/02-om-ha.md
new file mode 100644
index 0000000000..daf2ae8689
--- /dev/null
+++ b/versioned_docs/version-2.2.1/03-core-concepts/05-high-availability/02-om-ha.md
@@ -0,0 +1,30 @@
+---
+sidebar_label: Ozone Manager High Availability
+---
+
+# Ozone Manager High Availability
+
+Ozone has two metadata-manager nodes (*Ozone Manager* for key space management and *Storage Container Manager* for block space management) and multiple storage nodes (Datanode). Data is replicated between Datanodes with the help of RAFT consensus algorithm.
+
+To avoid any single point of failure the metadata-manager nodes also should have a HA setup.
+
+Both Ozone Manager and Storage Container Manager supports HA. In this mode the internal state is replicated via RAFT (with Apache Ratis).
+
+This page explains the HA setup of Ozone Manager (OM). Please check the [SCM High Availability](./scm-ha) page for SCM HA. While they can be setup for HA independently, a reliable, full HA setup requires enabling HA for both services.
+
+## How It Works
+
+A single Ozone Manager uses [RocksDB](https://github.com/facebook/rocksdb/) to persist metadata (volumes, buckets, keys) locally. HA version of Ozone Manager does exactly the same but all the data is replicated with the help of the RAFT consensus algorithm to follower Ozone Manager instances.
+
+
+
+Client connects to the Leader Ozone Manager which processes the request and schedules the replication with RAFT. When the request is replicated to all the followers the leader can return with the response.
+
+## Learn More
+
+- **Configuration**: For detailed configuration instructions on setting up OM HA, see the [OM HA Configuration](../../administrator-guide/configuration/high-availability/om-ha) documentation.
+- **Implementation Details**: For in-depth technical details about the OM HA implementation, including the double buffer approach and automatic snapshot installation
+
+<!--
+- see the [OM HA Implementation Details](../../system-internals/components/ozone-manager/high-availability) documentation.
+-->
diff --git a/versioned_docs/version-2.2.1/03-core-concepts/05-high-availability/HA-OM.png b/versioned_docs/version-2.2.1/03-core-concepts/05-high-availability/HA-OM.png
new file mode 100644
index 0000000000..b1ff506f78
Binary files /dev/null and b/versioned_docs/version-2.2.1/03-core-concepts/05-high-availability/HA-OM.png differ
diff --git a/versioned_docs/version-2.2.1/03-core-concepts/05-high-availability/README.mdx b/versioned_docs/version-2.2.1/03-core-concepts/05-high-availability/README.mdx
new file mode 100644
index 0000000000..46728a6e57
--- /dev/null
+++ b/versioned_docs/version-2.2.1/03-core-concepts/05-high-availability/README.mdx
@@ -0,0 +1,11 @@
+---
+sidebar_label: High Availability
+---
+
+# High Availability
+
+import DocCardList from '@theme/DocCardList';
+
+This section describes how Ozone achieves high availability for its metadata managers to eliminate single points of failure.
+
+<DocCardList/>
diff --git a/versioned_docs/version-2.2.1/03-core-concepts/06-comparison.md b/versioned_docs/version-2.2.1/03-core-concepts/06-comparison.md
new file mode 100644
index 0000000000..aab93354b5
--- /dev/null
+++ b/versioned_docs/version-2.2.1/03-core-concepts/06-comparison.md
@@ -0,0 +1,59 @@
+---
+sidebar_label: Comparison with Other Storage Technologies
+---
+
+# Comparison with Other Storage Technologies
+
+This document provides a high-level comparison of Apache Ozone with other storage technologies.
+
+## Open Source Scale-out Storage Comparison
+
+Ozone is most often compared against other open source storage systems.
+
+| Tech | Type | Consistency | Scale | Big Data Integration | License | Notes |
+| ---- | ---- | ----------- | ----- | -------------------- | ------- | ----- |
+| **Ozone** | Object / File | Strong | Exabyte scale, tens of billions keys | Native | Apache 2.0 | Modern Hadoop-native object store with S3 API |
+| **HDFS** | File | Strong | PBs, billions files | Native | Apache 2.0 | Classic Hadoop FS, no S3 API, tight Hadoop integration |
+| **Ceph** | Object / Block / File | Tunable / Eventual | Multi-PB, very large | Via S3 Gateway/CephFS | LGPLv2.1 / Ceph Foundation | General-purpose: underlying RADOS (object), RGW (object), CephFS (file) |
+| **MinIO** | Object | Strong | Petabyte scale | Via S3 connectors | AGPLv3 (SSPL-like) | Cloud-native S3 API, lightweight, fast, no FS semantics |
+| **Lustre** | Parallel File (POSIX) | Strong | PB scale, HPC | None | GPLv2 | HPC clusters, high-throughput parallel file system |
+| **GlusterFS** | File (POSIX) | Eventually consistent | Large, multi-PB | None | GPLv3 | General-purpose scale-out distributed file storage |
+| **OpenStack Swift** | Object | Eventual | Large, multi-PB | Via connectors | Apache 2.0 | S3-like multi-tenant object storage for private clouds |
+
+Ozone shines when users are in need of an Apache licensed, strongly consistent storage system that can scale to billions of keys/files and hundreds of PBs to EBs.
+
+## Proprietary Scale-Out Storage Comparison
+
+| Tech | Type | Consistency | Scale | Big Data Integration | Performance Focus | Notes |
+| ---- | ---- | ----------- | ----- | -------------------- | ----------------- | ----- |
+| **Isilon (Dell PowerScale)** | File (Scale-Out NAS) | Strong | PBs, billions of files | Indirect | High throughput, good mixed I/O | Enterprise NAS, POSIX compliant, good for mixed workloads, backup, analytics |
+| **VAST** | File / Object | Strong | PBs | Yes, AI workloads | Ultra-low latency, all-flash NVMe | All-flash, NFS/S3, great for AI/ML and large unstructured datasets |
+| **WEKA** | Parallel File | Strong | PBs | HPC, AI | Ultra-low latency, high IOPS | High-performance file, GPU clusters, NFS/SMB/S3 |
+| **Spectrum Scale (GPFS)** | File (POSIX) | Strong | PBs | HPC, AI | High throughput, scale-out metadata | IBM, used in HPC/AI, policy tiering, good POSIX compliance |
+| **Scality** | Object | Strong | PBs | Some | Good throughput for large objects | Enterprise S3 API, multi-region, backup archives, hybrid cloud |
+| **Cloudian** | Object | Strong | PBs | Some | Good throughput for backup/archive | S3-compatible object storage, ransomware protection, hybrid cloud |
+
+The proprietary systems offer enterprise-grade quality, but they often require proprietary or certified hardware.
+Ozone shines when users look for commodity hardware, open systems and embrace the vibrant Apache big data open source community.
+
+## Cloud-Native Object Storage Comparison
+
+| Tech | Type | Consistency | Scale | Big Data Integration | Notes |
+| ---- | ---- | ----------- | ----- | -------------------- | ----- |
+| **AWS S3** | Object | Strong | Exabyte+ | Native to cloud ecosystem | The de-facto standard for object storage; massive durability, S3 API leader |
+| **Azure ABFS** | File/Object (Data Lake Storage) | Strong | Exabyte+ | Azure-native | HDFS-like semantics for Spark/Hadoop; optimized for analytics |
+| **Google GCS** | Object | Strong | Exabyte+ | Native to cloud ecosystem | Globally distributed; strong consistency; well-integrated with BigQuery |
+| **OCI Object Storage** | Object | Strong | Exabyte+ | Via S3 API & native services | Oracle’s S3-compatible storage; integrates with OCI Data Flow |
+| **Alibaba OSS** | Object | Strong | Exabyte+ | Via S3 API & native services | S3-compatible, huge China/APAC footprint |
+| **IBM Cloud Object Storage** | Object | Strong | Exabyte+ | Via S3 API & native services | S3-compatible, geo-dispersed erasure coding for durability |
+
+These cloud storage offerings are only available from their respective public cloud vendors. In contrast, Ozone runs on-prem or in your private cloud, giving you full control.
+
+## Summary
+
+In summary, Ozone is the best fit in the following scenarios:
+
+1. Large on-prem big data clusters migrating from HDFS.
+2. You want S3 APIs but need strong Hadoop integration.
+3. You want to avoid vendor lock-in and grow cost-effectively on commodity hardware.
+4. You’re building a private or hybrid cloud with other open-source tools.
diff --git a/versioned_docs/version-2.2.1/03-core-concepts/README.mdx b/versioned_docs/version-2.2.1/03-core-concepts/README.mdx
new file mode 100644
index 0000000000..b129e86e25
--- /dev/null
+++ b/versioned_docs/version-2.2.1/03-core-concepts/README.mdx
@@ -0,0 +1,11 @@
+---
+sidebar_label: Core Concepts
+---
+
+# Core Concepts
+
+import DocCardList from '@theme/DocCardList';
+
+This section covers Ozone concepts that are helpful for both users and administrators to understand. Topics in this section will be referenced throughout the documentation.
+
+<DocCardList/>
diff --git a/versioned_docs/version-2.2.1/04-user-guide/01-client-interfaces/01-o3.md b/versioned_docs/version-2.2.1/04-user-guide/01-client-interfaces/01-o3.md
new file mode 100644
index 0000000000..0d5593698c
--- /dev/null
+++ b/versioned_docs/version-2.2.1/04-user-guide/01-client-interfaces/01-o3.md
@@ -0,0 +1,301 @@
+---
+sidebar_label: Ozone Shell
+---
+
+# Ozone Shell (`ozone sh`)
+
+Ozone shell is the primary interface to interact with Ozone from the command line. Behind the scenes it uses the [Java API](./java-client-api).
+
+There are some functionality which couldn't be accessed without using `ozone sh` commands. For example:
+
+1. Creating volumes with quota
+2. Managing internal ACLs
+3. Creating buckets with encryption key
+
+All of these are one-time, administration tasks. Applications can use Ozone without this CLI using other interface like Hadoop Compatible File System (o3fs or ofs) or S3 interface.
+
+Ozone shell help can be invoked at *object* level or at *action* level.
+
+For example:
+
+```bash
+ozone sh volume --help
+```
+
+will show all possible actions for volumes.
+
+Or it can be invoked to explain a specific action like:
+
+```bash
+ozone sh volume create --help
+```
+
+which will print the command line options of the `create` command for volumes.
+
+## General Command Format
+
+Ozone shell commands take the following form:
+
+> *ozone sh object action url*
+
+**ozone** script is used to invoke all Ozone sub-commands. The Ozone shell is
+invoked via `sh` command.
+
+Object can be volume, bucket or key. Actions are various verbs like
+create, list, delete etc.
+
+Depending on the action, Ozone URL can point to a volume, bucket or key in the following format:
+
+```text
+[schema][server:port]/volume/bucket/key
+```
+
+Where,
+
+1. **Schema** - This should be `o3` which is the native RPC protocol to access
+ Ozone API. The usage of the schema is optional.
+
+2. **Server:Port** - This is the address of the Ozone Manager. If the port is
+omitted the default port from `ozone-site.xml` will be used.
+
+Please see volume commands, bucket commands, and key commands section for more
+detail.
+
+## Volume operations
+
+Volume is the top level element of the hierarchy, managed only by administrators. Optionally, quota and the owner user can be specified.
+
+Example commands:
+
+```shell
+ozone sh volume create /vol1
+```
+
+```shell
+$ ozone sh volume info /vol1
+{
+ "metadata" : { },
+ "name" : "vol1",
+ "admin" : "hadoop",
+ "owner" : "hadoop",
+ "creationTime" : "2020-07-28T12:31:50.112Z",
+ "modificationTime" : "2020-07-28T12:31:50.112Z",
+ "acls" : [ {
+ "type" : "USER",
+ "name" : "hadoop",
+ "aclScope" : "ACCESS",
+ "aclList" : [ "ALL" ]
+ }, {
+ "type" : "GROUP",
+ "name" : "users",
+ "aclScope" : "ACCESS",
+ "aclList" : [ "ALL" ]
+ } ],
+ "quota" : 1152921504606846976
+}
+```
+
+```shell
+$ ozone sh volume list /
+[ {
+ "metadata" : { },
+ "name" : "s3v",
+ "admin" : "hadoop",
+ "owner" : "hadoop",
+ "creationTime" : "2020-07-27T11:32:22.314Z",
+ "modificationTime" : "2020-07-27T11:32:22.314Z",
+ "acls" : [ {
+ "type" : "USER",
+ "name" : "hadoop",
+ "aclScope" : "ACCESS",
+ "aclList" : [ "ALL" ]
+ }, {
+ "type" : "GROUP",
+ "name" : "users",
+ "aclScope" : "ACCESS",
+ "aclList" : [ "ALL" ]
+ } ],
+ "quota" : 1152921504606846976
+}, {
+ ....
+} ]
+```
+
+If the volume is empty, we can delete the volume using the command below.
+
+```shell
+$ ozone sh volume delete /vol1
+Volume vol1 is deleted
+```
+
+If the volume contains any buckets or keys, we can delete the volume recursively. This will delete all keys and buckets within the volume, and then delete the volume itself.
+After running this command there is no way to recover deleted contents.
+
+```shell
+$ ozone sh volume delete -r /vol1
+This command will delete volume recursively.
+There is no recovery option after using this command, and no trash for FSO buckets.
+Delay is expected running this command.
+Enter 'yes' to proceed': yes
+Volume vol1 is deleted
+```
+
+## Bucket operations
+
+Bucket is the second level of the object hierarchy, and is similar to AWS S3 buckets. Users can create buckets in volumes, if they have the necessary permissions.
+
+Command examples:
+
+```shell
+ozone sh bucket create /vol1/bucket1
+```
+
+```shell
+$ ozone sh bucket info /vol1/bucket1
+{
+ "metadata" : { },
+ "volumeName" : "vol1",
+ "name" : "bucket1",
+ "storageType" : "DISK",
+ "versioning" : false,
+ "creationTime" : "2020-07-28T13:14:45.091Z",
+ "modificationTime" : "2020-07-28T13:14:45.091Z",
+ "encryptionKeyName" : null,
+ "sourceVolume" : null,
+ "sourceBucket" : null
+}
+```
+
+If the bucket is empty we can delete the bucket using the command below.
+
+```shell
+$ ozone sh bucket delete /vol1/bucket1
+Bucket bucket1 is deleted
+```
+
+If the bucket contains any keys, we can delete the bucket recursively. This will delete all the keys within the bucket, and then the bucket itself.
+After running this command there is no way to recover deleted contents.
+
+```shell
+$ ozone sh bucket delete -r /vol1/bucket1
+This command will delete bucket recursively.
+There is no recovery option after using this command, and deleted keys won't move to trash.
+Enter 'yes' to proceed': yes
+Bucket bucket1 is deleted
+```
+
+[Transparent Data Encryption](../../administrator-guide/configuration/security/encryption/transparent-data-encryption) can be enabled at the bucket level.
+
+## Key operations
+
+Key is the object which can store the data.
+
+```shell
+ozone sh key put /vol1/bucket1/README.md README.md
+```
+
+:::warning
+In this case the standard `ozone sh <object_type> <action> <url>` scheme may be a bit confusing at first, as it results in the syntax `ozone sh key put <destination> <source>` instead of the arguably more natural order of `<source> <destination>`.
+:::
+
+```shell
+$ ozone sh key info /vol1/bucket1/README.md
+{
+ "volumeName" : "vol1",
+ "bucketName" : "bucket1",
+ "name" : "README.md",
+ "dataSize" : 3841,
+ "creationTime" : "2020-07-28T13:17:20.749Z",
+ "modificationTime" : "2020-07-28T13:17:21.979Z",
+ "replicationType" : "RATIS",
+ "replicationFactor" : 1,
+ "ozoneKeyLocations" : [ {
+ "containerID" : 1,
+ "localID" : 104591670688743424,
+ "length" : 3841,
+ "offset" : 0
+ } ],
+ "metadata" : { },
+ "fileEncryptionInfo" : null
+}
+```
+
+```shell
+ozone sh key get /vol1/bucket1/README.md /tmp/
+```
+
+```shell
+ozone sh key delete /vol1/bucket1/key1
+```
+
+If the key is in an [FSO](../../core-concepts/namespace/buckets/layouts/file-system-optimized) bucket it will be moved to the trash when deleted. Below is the trash location:
+
+```shell
+/<volume>/<bucket>/.Trash/<user>
+```
+
+If the key is in an OBS bucket it will be permanently deleted.
+
+## Querying CLI Results
+
+Ozone CLI returns JSON responses. [jq](https://stedolan.github.io/jq/manual/) is a command line JSON processor that can be used to filter CLI output for desired information.
+
+For example:
+
+- List FSO buckets that are not links.
+
+```shell
+$ ozone sh bucket list /s3v | jq '.[] | select(.link==false and .bucketLayout=="FILE_SYSTEM_OPTIMIZED")'
+{
+ "metadata": {},
+ "volumeName": "s3v",
+ "name": "fso-bucket",
+ "storageType": "DISK",
+ "versioning": false,
+ "usedBytes": 0,
+ "usedNamespace": 0,
+ "creationTime": "2023-02-01T05:18:46.974Z",
+ "modificationTime": "2023-02-01T05:18:46.974Z",
+ "quotaInBytes": -1,
+ "quotaInNamespace": -1,
+ "bucketLayout": "FILE_SYSTEM_OPTIMIZED",
+ "owner": "om",
+ "link": false
+}
+```
+
+- List EC buckets with their replication config.
+
+```shell
+$ ozone sh bucket list /vol1 | jq -r '.[] | select(.replicationConfig.replicationType == "EC") | {"name": .name, "replicationConfig": .replicationConfig}'
+{
+ "name": "ec5",
+ "replicationConfig": {
+ "data": 3,
+ "parity": 2,
+ "ecChunkSize": 1048576,
+ "codec": "RS",
+ "replicationType": "EC",
+ "requiredNodes": 5
+ }
+}
+{
+ "name": "ec9",
+ "replicationConfig": {
+ "data": 6,
+ "parity": 3,
+ "ecChunkSize": 1048576,
+ "codec": "RS",
+ "replicationType": "EC",
+ "requiredNodes": 9
+ }
+}
+```
+
+- List names of encrypted buckets and their encryption key names in tab-separated-value format.
+
+```shell
+$ ozone sh bucket list /vol1 | jq -r '.[] | select(.encryptionKeyName != null) | [.name, .encryptionKeyName] | @tsv'
+ec5 key1
+encrypted-bucket key1
+```
diff --git a/versioned_docs/version-2.2.1/04-user-guide/01-client-interfaces/02-ofs.md b/versioned_docs/version-2.2.1/04-user-guide/01-client-interfaces/02-ofs.md
new file mode 100644
index 0000000000..3ceab69b02
--- /dev/null
+++ b/versioned_docs/version-2.2.1/04-user-guide/01-client-interfaces/02-ofs.md
@@ -0,0 +1,409 @@
+---
+sidebar_label: ofs
+---
+
+# ofs: Hadoop Compatible Interface
+
+The Hadoop compatible file system interface allows storage backends like Ozone to be easily integrated into Hadoop eco-system. Ozone file system is a Hadoop compatible file system.
+
+:::warning
+Currently, Ozone supports two schemes: `o3fs://` and `ofs://`.
+
+The biggest difference between `o3fs` and `ofs` is that `o3fs` supports operations only at a **single bucket**, while `ofs` supports operations across all volumes and buckets and provides a full view of all the volume/buckets.
+:::
+
+## The Basics
+
+Examples of valid ofs paths:
+
+```text
+ofs://om1/
+ofs://om3:9862/
+ofs://omservice/
+ofs://omservice/volume1/
+ofs://omservice/volume1/bucket1/
+ofs://omservice/volume1/bucket1/dir1
+ofs://omservice/volume1/bucket1/dir1/key1
+
+ofs://omservice/tmp/
+ofs://omservice/tmp/key1
+```
+
+Volumes and mount(s) are located at the root level of an ofs Filesystem.
+Buckets are listed naturally under volumes.
+Keys and directories are under each buckets.
+
+Note that for mounts, only temp mount `/tmp` is supported at the moment.
+
+## Configuration
+
+Please add the following entry to the `core-site.xml`.
+
+```xml
+<property>
+ <name>fs.ofs.impl</name>
+ <value>org.apache.hadoop.fs.ozone.RootedOzoneFileSystem</value>
+</property>
+<property>
+ <name>fs.defaultFS</name>
+ <value>ofs://om-host.example.com/</value>
+</property>
+```
+
+This will make all the volumes and buckets to be the default Hadoop compatible file system and register the ofs file system type.
+
+You also need to add the Ozone filesystem JAR file to the classpath:
+
+```bash
+export HADOOP_CLASSPATH=/opt/ozone/share/ozone/lib/ozone-filesystem-hadoop3-*.jar:$HADOOP_CLASSPATH
+```
+
+:::note
+With Hadoop 2.x, use the Hadoop 2.x version.
+:::
+
+Once the default Filesystem has been setup, users can run commands like ls, put, mkdir, etc.
+For example:
+
+```bash
+hdfs dfs -ls /
+```
+
+Note that ofs works on all buckets and volumes. Users can create buckets and volumes using mkdir, such as create volume named volume1 and bucket named bucket1:
+
+```bash
+hdfs dfs -mkdir /volume1
+hdfs dfs -mkdir /volume1/bucket1
+```
+
+Or use the put command to write a file to the bucket.
+
+```bash
+hdfs dfs -put /etc/hosts /volume1/bucket1/test
+```
+
+For more usage, see: https://issues.apache.org/jira/secure/attachment/12987636/Design%20ofs%20v1.pdf
+
+## Differences from o3fs
+
+<!-- TODO: Link to o3fs documentation when created -->
+
+### Creating files
+
+ofs doesn't allow creating keys(files) directly under root or volumes.
+Users will receive an error message when they try to do that:
+
+```bash
+ozone fs -touch /volume1/key1
+# Output: touch: Cannot create file under root or volume.
+```
+
+### Simplify fs.defaultFS
+
+With ofs, fs.defaultFS (in `core-site.xml`) no longer needs to have a specific volume and bucket in its path like o3fs did.
+Simply put the OM host or service ID (in case of HA):
+
+```xml
+<property>
+ <name>fs.defaultFS</name>
+ <value>ofs://omservice</value>
+</property>
+```
+
+The client would then be able to access every volume and bucket on the cluster without specifying the hostname or service ID.
+
+```bash
+ozone fs -mkdir -p /volume1/bucket1
+```
+
+### Volume and bucket management directly from FileSystem shell
+
+Admins can create and delete volumes and buckets easily with Hadoop FS shell.
+Volumes and buckets are treated similar to directories so they will be created if they don't exist with `-p`:
+
+```bash
+ozone fs -mkdir -p ofs://omservice/volume1/bucket1/dir1/
+```
+
+Note that the supported volume and bucket name character set rule still applies.
+For instance, bucket and volume names don't take underscore(`_`):
+
+```bash
+$ ozone fs -mkdir -p /volume_1
+mkdir: Bucket or Volume name has an unsupported character : _
+```
+
+## Mounts and Configuring /tmp
+
+In order to be compatible with legacy Hadoop applications that use /tmp/, we have a special temp mount located at the root of the FS.
+This feature may be expanded in the feature to support custom mount paths.
+
+Currently Ozone supports two configurations for /tmp. The first (default), is a tmp directory for each user comprised of a mount volume with a user specific temp bucket. The second (configurable through `ozone-site.xml`), a sticky-bit like tmp directory common to all users comprised of a mount volume and a common temp bucket.
+
+Important: To use it, first, an **admin** needs to create the volume tmp (the volume name is hardcoded for now) and set its ACL to world ALL access.
+Namely:
+
+```bash
+ozone sh volume create tmp
+ozone sh volume setacl tmp -al world::a
+```
+
+These commands only need to be done **once per cluster**.
+
+### For /tmp directory per user (default)
+
+Then, **each user** needs to mkdir first to initialize their own temp bucket once.
+
+```bash
+$ ozone fs -mkdir /tmp
+2020-06-04 00:00:00,050 [main] INFO rpc.RpcClient: Creating Bucket: tmp/0238 ...
+```
+
+After that they can write to it just like they would do to a regular directory. e.g.:
+
+```bash
+ozone fs -touch /tmp/key1
+```
+
+### For a sharable /tmp directory common to all users
+
+To enable the sticky-bit common /tmp directory, update the `ozone-site.xml` with the following property
+
+```xml
+<property>
+ <name>ozone.om.enable.ofs.shared.tmp.dir</name>
+ <value>true</value>
+</property>
+```
+
+Then after setting up the volume tmp as **admin**, also configure a tmp bucket that serves as the common /tmp directory for all users, for example,
+
+```bash
+$ ozone sh bucket create /tmp/tmp
+$ ozone sh volume setacl tmp -a user:anyuser:rwlc \
+ user:adminuser:a,group:anyuser:rwlc,group:adminuser:a tmp/tmp
+```
+
+where, anyuser is username(s) admin wants to grant access and, adminuser is the admin username.
+
+Users then access the tmp directory as,
+
+```bash
+ozone fs -put ./NOTICE.txt ofs://om/tmp/key1
+```
+
+## Delete with trash enabled
+
+In order to enable trash in Ozone, Please add these configs to `core-site.xml`
+
+```xml
+<property>
+ <name>fs.trash.interval</name>
+ <value>10</value>
+</property>
+<property>
+ <name>fs.trash.classname</name>
+ <value>org.apache.hadoop.fs.ozone.OzoneTrashPolicy</value>
+</property>
+```
+
+When keys are deleted with trash enabled, they are moved to a trash directory under each bucket, because keys aren't allowed to be moved(renamed) between buckets in Ozone.
+
+```bash
+$ ozone fs -rm /volume1/bucket1/key1
+2020-06-04 00:00:00,100 [main] INFO fs.TrashPolicyDefault: Moved: 'ofs://id1/volume1/bucket1/key1' to trash at: ofs://id1/volume1/bucket1/.Trash/hadoop/Current/volume1/bucket1/key1
+```
+
+This is very similar to how the HDFS encryption zone handles trash location.
+
+### Note
+
+1. The flag `-skipTrash` can be used to delete files permanently without being moved to trash.
+
+2. Deletes at bucket or volume level with trash enabled are not allowed. One must use skipTrash in such cases.
+ i.e `ozone fs -rm -R ofs://vol1/bucket1` or `ozone fs -rm -R o3fs://bucket1.vol1` are not allowed without skipTrash
+
+## Recursive listing
+
+ofs supports recursive volume, bucket and key listing.
+
+i.e. `ozone fs -ls -R ofs://omservice/` will recursively list all volumes, buckets and keys the user has LIST permission to if ACL is enabled.
+If ACL is disabled, the command would just list literally everything on that cluster.
+
+This feature wouldn't degrade server performance as the loop is on the client.
+Think it as a client is issuing multiple requests to the server to get all the information.
+
+## Migrating from HDFS
+
+This guide helps you migrate applications from HDFS to Ozone by detailing the API-level compatibility of the Ozone File System (ofs).
+
+To ensure a smooth transition, you should first verify that your existing applications will work with ofs. You can check for potential incompatibilities by identifying the HDFS APIs your applications use.
+
+- **For Cluster Administrators**: Analyze the NameNode audit logs on your source HDFS cluster to identify the operations performed by your applications.
+- **For Application Developers**: Review your application's source code to identify which `FileSystem` or `DistributedFileSystem` APIs are being called.
+
+Once you have a list of APIs, compare it against the tables below to identify any unsupported operations.
+
+### Supported FileSystem APIs
+
+The following standard `FileSystem` APIs are supported by ofs.
+
+| Operation | NameNode audit log | Description | Support |
+|-------------------------|---------------------------|-----------------------------------------------------|---------------|
+| `access` | `checkAccess` | Checks if the user can access a path. | Supported |
+| `create` | `create` | Creates a new file. | Supported |
+| `open` | `open` | Opens a file for reading. | Supported |
+| `rename` | `rename` | Renames a file or directory. | Supported [[1]](#footnote-1) |
+| `delete` | `delete` | Deletes a file or directory. | Supported [[2]](#footnote-2) |
+| `listStatus` | `listStatus` | Lists the status of files in a directory. | Supported [[3]](#footnote-3) |
+| `mkdirs` | `mkdirs` | Creates a directory and its parents. | Supported |
+| `getFileStatus` | `getfileinfo` | Gets the status of a file. | Supported |
+| `setTimes` | `setTimes` | Sets the modification and access times. | Supported |
+| `getLinkTarget` | `getfileinfo` | Gets the target of a symbolic link. | Supported [[4]](#footnote-4) |
+| `getFileChecksum` | `open` | Gets the checksum of a file. | Supported |
+| `setSafeMode` | `safemode_leave`, `safemode_enter`, `safemode_get`, `safemode_force_exit` | Enters or leaves safe mode. | Supported |
+| `recoverLease` | `recoverLease` | Recovers a file lease. | Supported |
+| `isFileClosed` | `isFileClosed` | Checks if a file is closed. | Supported |
+| `createSnapshot` | `createSnapshot` | Creates a snapshot. | Supported [[5]](#footnote-5) |
+| `deleteSnapshot` | `deleteSnapshot` | Deletes a snapshot. | Supported [[5]](#footnote-5) |
+| `renameSnapshot` | `renameSnapshot` | Renames a snapshot. | Supported [[5]](#footnote-5) |
+| `getSnapshotDiffReport` | `computeSnapshotDiff` | Gets a snapshot diff report. | Supported [[5]](#footnote-5) |
+| `getContentSummary` | `contentSummary` | Gets the content summary of a path. | Supported |
+| `getDelegationToken` | `getDelegationToken` | Gets a delegation token. | Supported |
+| `globStatus` | `listStatus` | Finds files matching a pattern. | Supported |
+| `copyFromLocalFile` | `getfileinfo` | Copies a file from the local filesystem. | Supported |
+| `exists` | `getfileinfo` | Checks if a path exists. | Supported |
+| `getFileBlockLocations` | `open` | Gets file block locations. | Supported |
+| `getTrashRoot` | `listSnapshottableDirectory`, `getEZForPath` | Gets the trash root for a path. | Supported |
+| `getTrashRoots` | `listStatus`, `listEncryptionZones` | Gets all trash roots. | Supported |
+| `isDirectory` | `getfileinfo` | Checks if a path is a directory. | Supported |
+| `isFile` | `getfileinfo` | Checks if a path is a file. | Supported |
+| `listFiles` | `listStatus` | Returns a remote iterator for files. | Supported |
+| `listLocatedStatus` | `listStatus` | Returns a remote iterator for located file statuses.| Supported |
+| `listStatusIterator` | `listStatus` | Returns a remote iterator for file statuses. | Supported |
+| `getDefaultBlockSize` | N/A | Gets the default block size. | Supported |
+| `getDefaultReplication` | N/A | Gets the default replication factor. | Supported |
+| `getHomeDirectory` | N/A | Gets the user's home directory. | Supported |
+| `getServerDefaults` | N/A | Gets the server default values. | Supported |
+| `getWorkingDirectory` | N/A | Gets the current working directory. | Supported |
+| `hasPathCapability` | N/A | Queries for a path capability. | Supported |
+| `setWorkingDirectory` | N/A | Sets the current working directory. | Supported |
+| `supportsSymlinks` | N/A | Checks if symbolic links are supported. | Supported |
+
+*Note: An audit log of N/A means the API is client-side only and does not access the NameNode.*
+
+### Unsupported FileSystem APIs
+
+The following standard `FileSystem` APIs are not supported by ofs.
+
+| Operation | NameNode audit log | Description |
+|--------------------|----------------------|--------------------------------|
+| `append` | `append` | Appends to an existing file. |
+| `setPermission` | `setPermission` | Sets the permission of a file. |
+| `setOwner` | `setOwner` | Sets the owner of a file. |
+| `setReplication` | `setReplication` | Sets the replication factor. |
+| `createSymlink` | `createSymlink` | Creates a symbolic link. |
+| `resolveLink` | `getfileinfo` | Resolves a symbolic link. |
+| `setXAttr` | `setXAttr` | Sets an extended attribute. |
+| `getXAttr` | `getXAttrs` | Gets an extended attribute. |
+| `getXAttrs` | `getXAttrs` | Gets extended attributes. |
+| `listXAttrs` | `listXAttrs` | Lists extended attributes. |
+| `removeXAttr` | `removeXAttr` | Removes an extended attribute. |
+| `setAcl` | `setAcl` | Sets an ACL. |
+| `getAclStatus` | `getAclStatus` | Gets an ACL status. |
+| `modifyAclEntries` | `modifyAclEntries` | Modifies ACL entries. |
+| `removeAclEntries` | `removeAclEntries` | Removes ACL entries. |
+| `removeDefaultAcl` | `removeDefaultAcl` | Removes the default ACL. |
+| `removeAcl` | `removeAcl` | Removes an ACL. |
+| `truncate` | `truncate` | Truncates a file. |
+| `concat` | `concat` | Concatenates files. |
+| `listCorruptFileBlocks` | `listCorruptFileBlocks` | List corrupted file blocks |
+| `msync` | N/A | Does not have a corresponding HDFS audit log. |
+
+### Unsupported HDFS-Specific APIs
+
+The following APIs are specific to HDFS's `DistributedFileSystem` implementation and are not part of the generic `org.apache.hadoop.fs.FileSystem` API. Therefore, they are not supported by ofs. However, see the footnotes below for equivalent APIs.
+
+| Operation | NameNode audit log | Description | Support |
+|--------------------------------|------------------------------|-----------------------------------------------------|----------------|
+| `getErasureCodingPolicy` | `getErasureCodingPolicy` | Gets the erasure coding policy of a file/dir. | Unsupported [[6]](#footnote-6)|
+| `setErasureCodingPolicy` | `setErasureCodingPolicy` | Sets an erasure coding policy on a directory. | Unsupported [[6]](#footnote-6)|
+| `unsetErasureCodingPolicy` | `unsetErasureCodingPolicy` | Unsets an erasure coding policy on a directory. | Unsupported [[6]](#footnote-6)|
+| `addErasureCodingPolicies` | `addErasureCodingPolicies` | Adds erasure coding policies. | Unsupported [[6]](#footnote-6)|
+| `getErasureCodingPolicies` | `getErasureCodingPolicies` | Gets the available erasure coding policies. | Unsupported [[6]](#footnote-6)|
+| `removeErasureCodingPolicy` | `removeErasureCodingPolicy` | Removes an erasure coding policy. | Unsupported [[6]](#footnote-6)|
+| `enableErasureCodingPolicy` | `enableErasureCodingPolicy` | Enables an erasure coding policy. | Unsupported [[6]](#footnote-6)|
+| `disableErasureCodingPolicy` | `disableErasureCodingPolicy` | Disables an erasure coding policy. | Unsupported [[6]](#footnote-6)|
+| `getErasureCodingCodecs` | `getErasureCodingCodecs` | Lists all erasure coding codecs. | Unsupported [[6]](#footnote-6)|
+| `getECTopologyResultForPolicies` | `getECTopologyResultForPolicies` | Get erasure coding topology result for policies. | Unsupported [[6]](#footnote-6)|
+| `getSnapshotListing` | `ListSnapshot` | List all snapshots of a snapshottable directory. | Unsupported [[6]](#footnote-6)|
+| `allowSnapshot` | `allowSnapshot` | Allows snapshots to be taken on a directory. | Unsupported [[6]](#footnote-6)|
+| `disallowSnapshot` | `disallowSnapshot` | Disallows snapshots to be taken on a directory. | Unsupported [[6]](#footnote-6)|
+| `provisionSnapshotTrash` | `getfileinfo`, `mkdirs`, `setPermission` | Provision trash for a snapshottable directory. | Unsupported [[6]](#footnote-6)|
+| `createEncryptionZone` | `createEncryptionZone` | Creates an encryption zone. | Unsupported [[6]](#footnote-6)|
+| `getEZForPath` | `getEZForPath` | Gets the encryption zone for a path. | Unsupported [[6]](#footnote-6)|
+| `listEncryptionZones` | `listEncryptionZones` | Lists all encryption zones. | Unsupported [[6]](#footnote-6)|
+| `reencryptEncryptionZone` | `reencryptEncryptionZone` | Reencrypt an encryption zone. | Unsupported [[6]](#footnote-6)|
+| `listReencryptionStatus` | `listReencryptionStatus` | List reencryption status. | Unsupported [[6]](#footnote-6)|
+| `getFileEncryptionInfo` | `getfileinfo` | Get file encryption info. | Unsupported [[6]](#footnote-6)|
+| `provisionEZTrash` | `getEZForPath`, `getfileinfo`, `mkdirs`, `setPermission` | Provision trash for an encryption zone. | Unsupported [[6]](#footnote-6)|
+| `setQuota` | `clearQuota` or `clearSpaceQuota` or `setQuota` or `setSpaceQuota` | Sets the quota usage for a path. | Unsupported [[6]](#footnote-6)|
+| `getQuotaUsage` | `quotaUsage` | Gets the quota usage for a path. | Unsupported [[6]](#footnote-6)|
+| `setQuotaByStorageType` | `setSpaceQuota` | Sets quota by storage type for a path. | Unsupported [[6]](#footnote-6)|
+| `unsetStoragePolicy` | `unsetStoragePolicy` | Unsets a storage policy on a file or directory. | Unsupported |
+| `setStoragePolicy` | `setStoragePolicy` | Sets a storage policy on a file or directory. | Unsupported |
+| `getStoragePolicy` | `getStoragePolicy` | Gets the storage policy of a file or directory. | Unsupported |
+| `satisfyStoragePolicy` | `satisfyStoragePolicy` | Satisfies the storage policy of a file. | Unsupported |
+| `addCachePool` | `addCachePool` | Adds a cache pool. | Unsupported |
+| `modifyCachePool` | `modifyCachePool` | Modifies a cache pool. | Unsupported |
+| `removeCachePool` | `removeCachePool` | Removes a cache pool. | Unsupported |
+| `listCachePools` | `listCachePools` | Lists all cache pools. | Unsupported |
+| `addCacheDirective` | `addCacheDirective` | Adds a cache directive. | Unsupported |
+| `modifyCacheDirective` | `modifyCacheDirective` | Modifies a cache directive. | Unsupported |
+| `removeCacheDirective` | `removeCacheDirective` | Removes a cache directive. | Unsupported |
+| `listCacheDirectives` | `listCacheDirectives` | Lists cache directives. | Unsupported |
+| `getSlowDatanodeStats` | `datanodeReport` | Get slow Datanode stats. | Unsupported |
+| `saveNamespace` | `saveNamespace` | Save the namespace. | Unsupported |
+| `restoreFailedStorage` | `checkRestoreFailedStorage`, `enableRestoreFailedStorage`, `disableRestoreFailedStorage` | Restore failed storage. | Unsupported |
+| `refreshNodes` | `refreshNodes` | Refresh nodes. | Unsupported |
+| `setBalancerBandwidth` | `setBalancerBandwidth` | Set balancer bandwidth. | Unsupported |
+| `metaSave` | `metaSave` | Meta save. | Unsupported |
+| `rollingUpgrade` | `queryRollingUpgrade`, `startRollingUpgrade`, `finalizeRollingUpgrade` | Rolling upgrade. | Unsupported |
+| `finalizeUpgrade` | `finalizeUpgrade` | Finalize upgrade. | Unsupported [[7]](#footnote-7) |
+| `listOpenFiles` | `listOpenFiles` | List open files. | Unsupported [[7]](#footnote-7) |
+
+**Footnotes:**
+
+#### [1] {#footnote-1}
+
+Renaming files or directories across different buckets is not supported. Within a File System Optimized (FSO) bucket, rename is an atomic metadata operation. For legacy buckets, renaming a directory is a non-atomic operation that renames each file and subdirectory individually.
+
+#### [2] {#footnote-2}
+
+Deleting the filesystem root is not allowed. Recursively deleting a volume is also not supported.
+
+#### [3] {#footnote-3}
+
+Recursive listing is not supported at the root or volume level.
+
+#### [4] {#footnote-4}
+
+ofs supports "linked buckets," where one bucket serves as a reference to another. However, general-purpose symbolic links for files or directories are not supported.
+
+#### [5] {#footnote-5}
+
+Snapshots are supported at the bucket level only.
+
+#### [6] {#footnote-6}
+
+For operations related to encryption zones, erasure coding, snapshots, and quotas, use the corresponding Ozone bucket-level APIs instead.
+
+#### [7] {#footnote-7}
+
+Replace with `OzoneManagerProtocol.finalizeUpgrade()` and `OzoneManagerProtocol.listOpenFiles()`.
+
+*The following audit logs are typically produced by HDFS internal services and are not relevant for application migration: `slowDataNodesReport`, `getDatanodeStorageReport`, `rollEditLog`, `renewDelegationToken`, `cancelDelegationToken`, `gcDeletedSnapshot`.*
+
+*The following audit logs are produced by the HDFS output stream: `getAdditionalBlock`, `getAdditionalDatanode`, `abandonBlock`, `completeFile`, `fsync`.*
+
+*The `getPreferredBlockSize` audit log is used in testing only.*
diff --git a/versioned_docs/version-2.2.1/04-user-guide/01-client-interfaces/03-s3/01-s3-api.md b/versioned_docs/version-2.2.1/04-user-guide/01-client-interfaces/03-s3/01-s3-api.md
new file mode 100644
index 0000000000..d442e3d870
--- /dev/null
+++ b/versioned_docs/version-2.2.1/04-user-guide/01-client-interfaces/03-s3/01-s3-api.md
@@ -0,0 +1,194 @@
+---
+sidebar_label: Overview
+---
+
+# Overview
+
+Ozone provides S3 compatible REST interface to use the object store data with any S3 compatible tools.
+S3 buckets are stored under the `/s3v` volume.
+
+## Getting started
+
+S3 Gateway is a separated component which provides the S3 compatible APIs. It should be started additional to the regular Ozone components.
+You can start a Docker based cluster, including the S3 Gateway from the release package.
+
+Go to the `compose/ozone` directory, and start the server:
+
+```bash
+docker-compose up -d --scale datanode=3
+```
+
+You can access the S3 Gateway at `http://localhost:9878`
+
+## URL Schema
+
+Ozone S3 Gateway supports both the virtual-host-style URL S3 bucket addresses (eg. http://bucketname.host:9878) and the path-style addresses (eg. http://host:9878/bucketname)
+By default it uses the path-style addressing. To use virtual host style URLs set your main domain name in your `ozone-site.xml`:
+
+```xml
+<property>
+ <name>ozone.s3g.domain.name</name>
+ <value>s3g.internal</value>
+</property>
+```
+
+## Implemented REST Endpoints
+
+The Ozone S3 Gateway implements a substantial subset of the Amazon S3 REST API. The tables below summarize each API’s support status, its feature, and any relevant notes, including known deviations from AWS S3 behavior.
+
+### Bucket Operations
+
+| **API Name** | **Feature** | **Note** |
+| --------------------------------------------------------------------------------------------------- | ------------- | ---------- |
+| ✅ [ListBuckets](https://docs.aws.amazon.com/AmazonS3/latest/API/API_ListBuckets.html) | Lists all buckets owned by the authenticated user. | Returns the full bucket list. |
+| ✅ [CreateBucket](https://docs.aws.amazon.com/AmazonS3/latest/API/API_CreateBucket.html) | Creates a new bucket. | **Non-compliant behavior:** The default bucket ACL may include extra group permissions instead of being strictly private. Bucket names must adhere to S3 naming conventions. |
+| ✅ [HeadBucket](https://docs.aws.amazon.com/AmazonS3/latest/API/API_HeadBucket.html) | Checks for the existence of a bucket. | Returns a 200 status if the bucket exists. |
+| ✅ [DeleteBucket](https://docs.aws.amazon.com/AmazonS3/latest/API/API_DeleteBucket.html) | Deletes a bucket. | Bucket must be empty before deletion. |
+
+### Object Operations
+
+| **API Name** | **Feature** | **Note** |
+| ------------------------------------------------------------------------------------------- | ------------- | ---------- |
+| ✅ [GetObject](https://docs.aws.amazon.com/AmazonS3/latest/API/API_GetObject.html) | Retrieves the contents of an object. | **Non-compliant behavior:** For non-existent objects, Ozone may return a generic 404 without the structured XML error body defined by AWS S3. |
+| ✅ [HeadObject](https://docs.aws.amazon.com/AmazonS3/latest/API/API_HeadObject.html) | Retrieves metadata for an object. | Similar to GET Object, error responses for missing objects might lack detailed AWS-style error XML. |
+| ✅ [PutObject](https://docs.aws.amazon.com/AmazonS3/latest/API/API_PutObject.html) | Uploads a new object. | Supports both single PUT and multipart uploads. **Non-compliant behavior:** Any ACL headers provided in the request are ignored. |
+| ✅ [DeleteObject](https://docs.aws.amazon.com/AmazonS3/latest/API/API_DeleteObject.html) | Deletes a single object. | Returns standard error codes for missing objects. |
+| ✅ [DeleteObjects](https://docs.aws.amazon.com/AmazonS3/latest/API/API_DeleteObjects.html) | Deletes multiple objects in one request. | Bulk delete operation with aggregated error reporting. |
+| ✅ [CopyObject](https://docs.aws.amazon.com/AmazonS3/latest/API/API_CopyObject.html) | Copies an object (intra- or inter-bucket). | Supports metadata directives (COPY/REPLACE). **Non-compliant behavior:** Self-copying for metadata updates may differ slightly from AWS S3. |
+| ✅ [ListObjectsV2](https://docs.aws.amazon.com/AmazonS3/latest/API/API_ListObjectsV2.html) | Lists objects in a bucket with filtering and pagination. | Supports prefix, delimiter, and continuation tokens. |
+
+### Object Tagging Operations
+
+| **API Name** | **Feature** | **Note** |
+| ------------ | ----------- | -------- |
+| ✅ [PutObjectTagging](https://docs.aws.amazon.com/AmazonS3/latest/API/API_PutObjectTagging.html) | Adds or updates tags on an object. | Fully supported; updates replace any existing tag set. |
+| ✅ [GetObjectTagging](https://docs.aws.amazon.com/AmazonS3/latest/API/API_GetObjectTagging.html) | Retrieves the tag set of an object. | Returns the tag set as defined by the S3 API. |
+| ✅ [DeleteObjectTagging](https://docs.aws.amazon.com/AmazonS3/latest/API/API_DeleteObjectTagging.html) | Removes the tag set from an object. | Clears all tags associated with the object. |
+
+### Multipart Upload Operations
+
+| **API Name** | **Feature** | **Note** |
+| ------------ | ----------- | -------- |
+| ✅ [CreateMultipartUpload](https://docs.aws.amazon.com/AmazonS3/latest/API/API_CreateMultipartUpload.html) | Starts a multipart upload session. | Returns an UploadId for subsequent parts. |
+| ✅ [UploadPart](https://docs.aws.amazon.com/AmazonS3/latest/API/API_UploadPart.html) | Uploads an individual part for a multipart upload. | Part numbering and ETag computation follow AWS semantics. |
+| ✅ [ListMultipartUploads](https://docs.aws.amazon.com/AmazonS3/latest/API/API_ListMultipartUploads.html) | Lists in-progress multipart uploads in a bucket. | Up to 1000 multipart uploads are returned in a batch by default. |
+| ✅ [ListParts](https://docs.aws.amazon.com/AmazonS3/latest/API/API_ListParts.html) | Lists uploaded parts for an in-progress multipart upload. | Supports pagination if many parts exist. |
+| ✅ [CompleteMultipartUpload](https://docs.aws.amazon.com/AmazonS3/latest/API/API_CompleteMultipartUpload.html) | Assembles all uploaded parts into a final object. | Returns an ETag that follows AWS multipart rules. |
+| ✅ [AbortMultipartUpload](https://docs.aws.amazon.com/AmazonS3/latest/API/API_AbortMultipartUpload.html) | Aborts an in-progress multipart upload. | Frees up storage used by uploaded parts. Incomplete multipart uploads older than 7 days are automatically aborted by Ozone. |
+
+### Additional Operations
+
+| **API Name** | **Feature** | **Note** |
+| -------------------------- | ------------- | ---------- |
+| ✅ Generate Presigned URL | Generates a temporary URL for accessing an object. | Uses AWS Signature V4. **Non-compliant behavior:** The generated URL may include a fixed default region rather than dynamically reflecting the bucket’s location. Ozone now supports generating presigned URLs for all major S3 operations, including `GetObject`, `PutObject`, `DeleteObject`, `HeadObject`, `HeadBucket`, `MultipartUpload`. |
+
+:::note Additional Notes
+
+- **Advanced Features Not Supported:**
+ - **ACLs, Bucket Policies, CORS Configuration, and Website Hosting:** These are not fully implemented; Ozone uses an internal permission model that deviates from AWS S3.
+ - **Bucket Versioning, Object Locking, Server-Side Encryption, and S3 Select:** These features are currently not supported.
+ - **Conditional Requests:** Support for conditional requests (e.g., `If-Match`, `If-None-Match`) is planned and tracked in [HDDS-13117](https://issues.apache.org/jira/browse/HDDS-13117).
+ - **Lifecycle configuration, cross region replication, S3 event notifications** are being implemented and in the roadmap.
+- While Ozone S3 Gateway provides extensive support for common S3 operations, users should be aware of the above non-compliant behaviors and limitations when integrating with applications expecting full AWS S3 functionality.
+- While Ozone S3 Gateway does not support S3 Server-Side Encryption, it does support encrypted buckets using Apache Ranger KMS. For more information, see the [Transparent Data Encryption](../../../administrator-guide/configuration/security/encryption/transparent-data-encryption) documentation.
+:::
+
+## Security
+
+If security is not enabled, you can *use* **any** AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY
+
+If security is enabled, you can get the key and the secret with the `ozone s3 getsecret` command (*Kerberos based authentication is required).
+
+```bash
+kinit -kt /etc/security/keytabs/testuser.keytab testuser/scm@EXAMPLE.COM
+ozone s3 getsecret
+awsAccessKey=testuser/scm@EXAMPLE.COM
+awsSecret=c261b6ecabf7d37d5f9ded654b1c724adac9bd9f13e247a235e567e8296d2999
+```
+
+:::note
+Starting in Ozone 1.4.0, the secret will be **shown only once** when generated with `getsecret`. If the secret is lost, the user would have to `revokesecret` first before regenerating a new secret with `getsecret`.
+:::
+
+Now, you can use the key and the secret to access the S3 endpoint:
+
+```bash
+export AWS_ACCESS_KEY_ID=testuser/scm@EXAMPLE.COM
+export AWS_SECRET_ACCESS_KEY=c261b6ecabf7d37d5f9ded654b1c724adac9bd9f13e247a235e567e8296d2999
+aws s3api --endpoint http://localhost:9878 create-bucket --bucket bucket1
+```
+
+To invalidate/revoke the secret, use `ozone s3 revokesecret` command. Parameter '-y' can be appended to skip the interactive confirmation.
+
+```bash
+ozone s3 revokesecret
+Enter 'y' to confirm S3 secret revocation for 'testuser/scm@EXAMPLE.COM': y
+S3 secret revoked.
+```
+
+Ozone Manager administrators can run `ozone s3 getsecret` and `ozone s3 revokesecret` command with `-u` parameter to specify another users.
+
+```bash
+# Obtained Kerberos TGT for testuser/scm@EXAMPLE.COM with kinit,
+# testuser/scm@EXAMPLE.COM is an OM admin.
+ozone s3 getsecret -u om/om@EXAMPLE.COM
+awsAccessKey=om/om@EXAMPLE.COM
+awsSecret=1e9379d0424cce6669b1a501ff14834e46dee004ee868b41a313b49eabcfb68f
+
+ozone s3 revokesecret -u om/om@EXAMPLE.COM -y
+S3 secret revoked.
+```
+
+## Expose any volume
+
+Ozone has one more element in the name-space hierarchy compared to S3: the volumes. By default, all the buckets of the `/s3v` volume can be accessed with S3 interface but only the (Ozone) buckets of the `/s3v` volumes are exposed.
+
+To make any other buckets available with the S3 interface a "symbolic linked" bucket can be created:
+
+```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 expose the `/vol1/bucket1` Ozone bucket as an S3 compatible `common-bucket` via the S3 interface.
+
+:::note
+The implementation details of the bucket-linking feature can be found in the [design doc](https://ozone.apache.org/docs/edge/design/volume-management.html).
+:::
+
+## Clients
+
+### AWS CLI
+
+`aws` CLI could be used by specifying the custom REST endpoint.
+
+```bash
+aws s3api --endpoint http://localhost:9878 create-bucket --bucket buckettest
+```
+
+Or
+
+```bash
+aws s3 ls --endpoint http://localhost:9878 s3://buckettest
+```
+
+#### Supported AWS CLI Versions
+
+- AWS CLI v1 (1.37.0 and above) and AWS CLI v2 (2.23.0 and above) are supported. These are the versions in which AWS enabled [default data integrity protections](https://github.com/aws/aws-cli/issues/9214) that automatically calculate a `CRC32` checksum for S3 uploads; Ozone added handling for that flow in 2.1 and later.
+- [AWS has announced AWS CLI v1 enters maintenance mode on July 15, 2026](https://aws.amazon.com/blogs/developer/cli-v1-maintenance-mode-announcement/); users are encouraged to upgrade to AWS CLI v2. Ozone may drop support for AWS CLI v1 at some point in the future.
+
+## Compatible third-party applications
+
+Ozone's S3 Gateway enables integration with a wide range of cloud-native and analytics applications. Here are some examples of tools and platforms known to work with Ozone (in alphabetical order):
+
+- [Clickhouse](https://clickhouse.com/docs/en/integrations/s3)
+- [Fluentd](https://docs.fluentd.org/output/s3) can send logs directly to Ozone via the S3 Gateway.
+- [JuiceFS](https://juicefs.com/docs/community/s3_gateway/)
+- [Starburst](https://docs.starburst.io/latest/connector/starburst-ozone.html) (Starburst also supports Ozone `ofs://`)
+- [Teradata NOS](https://docs.teradata.com/r/Enterprise_IntelliFlex_VMware/Teradata-VantageTM-Native-Object-Store-Getting-Started-Guide-17.20)
+- [CyberDuck](https://cyberduck.io/) See the [tutorial page](https://ozone.apache.org/docs/edge/interface/cyberduckozones3.html)
+
+This list is not exhaustive—any application that supports the S3 protocol can potentially connect to Ozone, making it easy to adopt Ozone in modern data pipelines and cloud-native workflows.
diff --git a/versioned_docs/version-2.2.1/04-user-guide/01-client-interfaces/03-s3/02-securing-s3.md b/versioned_docs/version-2.2.1/04-user-guide/01-client-interfaces/03-s3/02-securing-s3.md
new file mode 100644
index 0000000000..af321f5255
--- /dev/null
+++ b/versioned_docs/version-2.2.1/04-user-guide/01-client-interfaces/03-s3/02-securing-s3.md
@@ -0,0 +1,114 @@
+---
+sidebar_label: Securing S3
+---
+
+# Securing S3
+
+To access an S3 bucket, users need AWS access key ID and AWS secret. Both of
+these are generated by going to AWS website. When you use Ozone's S3
+protocol, you need the same AWS access key and secret.
+
+Under Ozone, the clients can download the access key directly from Ozone.
+The user needs to `kinit` first and once they have authenticated via Kerberos
+they can download the S3 access key ID and AWS secret. Just like AWS S3,
+both of these are secrets that need to be protected by the client since it
+gives full access to the S3 buckets.
+
+## Obtain Secrets
+
+S3 clients can get the secret access ID and user secret from OzoneManager.
+
+### Using the command line
+
+For a regular user to get their own secret:
+
+```bash
+ozone s3 getsecret
+```
+
+An Ozone administrator can get a secret for a specific user by using the `-u` flag:
+
+```bash
+ozone s3 getsecret -u <username>
+```
+
+### Using the REST API
+
+A user can get their own secret by making a `PUT` request to the `/secret` endpoint:
+
+```bash
+curl -X PUT --negotiate -u : https://localhost:9879/secret
+```
+
+An Ozone administrator can get a secret for a specific user by appending the username to the path:
+
+```bash
+curl -X PUT --negotiate -u : https://localhost:9879/secret/<username>
+```
+
+This command will talk to Ozone, validate the user via Kerberos and generate
+the AWS credentials. The values will be printed out on the screen. You can
+set these values up in your *.aws* file for automatic access while working
+against Ozone S3 buckets.
+
+:::caution
+Please note: These S3 credentials are like your Kerberos passwords
+that give complete access to your buckets.
+:::
+
+- Now you can proceed to setup these secrets in aws configs:
+
+```bash
+aws configure set default.s3.signature_version s3v4
+aws configure set aws_access_key_id ${accessId}
+aws configure set aws_secret_access_key ${secret}
+aws configure set region us-west-1
+```
+
+Please refer to AWS S3 documentation on how to use S3 via command line or via
+S3 API.
+
+## Revoking Secrets via REST API
+
+To invalidate/revoke the secret, use `ozone s3 revokesecret` command.
+Alternatively, you can use the REST API endpoint to revoke the secret.
+Ozone now provides a REST API endpoint that allows administrators to revoke S3 access secrets. This operation invalidates a secret, ensuring it can no longer be used for authentication.
+
+### Endpoint Details
+
+- **URL:** `http://localhost:9879/secret`
+- **HTTP Method:** `DELETE`
+
+### Authentication
+
+The API leverages SPNEGO (Kerberos) authentication. The following curl options are used:
+
+- `--negotiate` enables SPNEGO.
+- `-u :` uses the current Kerberos ticket (an empty username is provided).
+
+### Example 1: Revoke Secret for the Current User
+
+This command revokes the secret for the currently authenticated user:
+
+```bash
+curl -X DELETE --negotiate -u : -v http://localhost:9879/secret
+```
+
+### Example 2: Revoke Secret by Username
+
+This command revokes the secret for a specific user by appending the username as a query parameter. Replace `testuser` with the desired username:
+
+```bash
+curl -X DELETE --negotiate -u : -v "http://localhost:9879/secret?username=testuser"
+```
+
+### Response
+
+- **Success:** Returns HTTP `200 OK` along with a confirmation message in JSON format.
+- **Failure:** Returns an appropriate HTTP error status and message if there are issues (e.g., authentication failures).
+
+### Testing and Verification
+
+For a working example of these operations, refer to the [Secret Revoke Robot Test](https://raw.githubusercontent.com/apache/ozone/refs/heads/master/hadoop-ozone/dist/src/main/smoketest/s3/secretrevoke.robot). This test demonstrates both the default secret revocation and the revocation by username.
+
+> **Note:** Ensure your Kerberos authentication is correctly configured, as secret revocation is a privileged operation.
diff --git a/versioned_docs/version-2.2.1/04-user-guide/01-client-interfaces/03-s3/README.mdx b/versioned_docs/version-2.2.1/04-user-guide/01-client-interfaces/03-s3/README.mdx
new file mode 100644
index 0000000000..a8ce6af33f
--- /dev/null
+++ b/versioned_docs/version-2.2.1/04-user-guide/01-client-interfaces/03-s3/README.mdx
@@ -0,0 +1,7 @@
+# S3 API
+
+import DocCardList from '@theme/DocCardList';
+
+This section documents Ozone's S3 compatible API support.
+
+<DocCardList/>
diff --git a/versioned_docs/version-2.2.1/04-user-guide/01-client-interfaces/04-s3a.md b/versioned_docs/version-2.2.1/04-user-guide/01-client-interfaces/04-s3a.md
new file mode 100644
index 0000000000..c834979548
--- /dev/null
+++ b/versioned_docs/version-2.2.1/04-user-guide/01-client-interfaces/04-s3a.md
@@ -0,0 +1,189 @@
+---
+sidebar_label: s3a
+---
+
+# s3a and Ozone
+
+Ozone exposes an **S3-compatible REST interface** via the S3 Gateway. Hadoop's **S3A** filesystem (`s3a://`) is a cloud connector that translates the AWS S3 API into a Hadoop-compatible file system interface. Hadoop-style data analytics tools such as Hive, Impala, and Spark can access Ozone's S3 interface using the Hadoop S3A connector, so you can use Ozone buckets from existing Hadoop ecosystem tools without application changes.
+
+This page explains how to configure the Hadoop S3A client to use Ozone's S3 Gateway (s3g) and provides sample commands to access Ozone s3g using s3a. For details about the Ozone S3 Gateway itself (supported REST APIs, URL schemes, security), see the [S3 Protocol](./s3/s3-api) page. For more information about S3A, see the [official Hadoop S3A documentation](https://hadoop.apache.org/docs/stable/hadoop-aws/tools/hadoop-aws/index.html).
+
+## Prerequisites
+
+- A running Ozone cluster with the **S3 Gateway** enabled. You can start a Docker-based cluster (including S3 Gateway) as described in the [S3 Protocol](./s3/s3-api) documentation.
+- Ozone S3 endpoint (for example `http://localhost:9878` or a load balancer DNS name).
+- Hadoop distribution with the **`hadoop-aws`** module available. See the official Hadoop S3A documentation:
+ - [Hadoop-AWS: S3A client overview](https://hadoop.apache.org/docs/stable/hadoop-aws/tools/hadoop-aws/index.html)
+ - [Connecting via S3A](https://hadoop.apache.org/docs/stable/hadoop-aws/tools/hadoop-aws/connecting.html)
+
+## Configuring S3A for Ozone
+
+### Enable the S3A client
+
+Ensure the `hadoop-aws` module is on the client classpath. In a typical Hadoop installation:
+
+- Set `HADOOP_OPTIONAL_TOOLS` in `hadoop-env.sh` to include `hadoop-aws`, **or**
+- Add a dependency on `org.apache.hadoop:hadoop-aws` with the same version as `hadoop-common`.
+
+See the [Hadoop S3A Getting Started](https://hadoop.apache.org/docs/stable/hadoop-aws/tools/hadoop-aws/index.html#Getting_Started) section for details.
+
+### core-site.xml: point S3A to Ozone
+
+Add the following properties to the Hadoop configuration (for example `core-site.xml`) so that `s3a://` URIs use the Ozone S3 Gateway instead of AWS S3:
+
+```xml
+<property>
+ <name>fs.s3a.endpoint</name>
+ <value>http://ozone-s3g-host:9878</value>
+ <description>
+ Ozone S3 Gateway endpoint. Replace with your s3g hostname or load balancer.
+ </description>
+</property>
+
+<property>
+ <name>fs.s3a.endpoint.region</name>
+ <value>us-east-1</value>
+ <description>
+ Logical region name required by the S3A client. Ozone does not enforce regions,
+ but this must be a valid-looking value.
+ </description>
+</property>
+
+<property>
+ <name>fs.s3a.path.style.access</name>
+ <value>true</value>
+ <description>
+ Ozone S3 Gateway defaults to path-style URLs (http://host:9878/bucket),
+ so S3A should use path-style access.
+ </description>
+</property>
+```
+
+These properties follow the official S3A connection settings in [Connecting to an S3 store](https://hadoop.apache.org/docs/stable/hadoop-aws/tools/hadoop-aws/connecting.html#Connection_Settings).
+
+### Recommended settings for Ozone
+
+Ozone S3 Gateway adds ETag support for S3 Multipart Upload (MPU). Object versioning and some other S3 behaviors may still differ from AWS S3. To avoid compatibility issues with older clients or when not using MPU, you can set these options when using S3A with Ozone:
+
+```xml
+<property>
+ <name>fs.s3a.bucket.probe</name>
+ <value>0</value>
+ <description>
+ Disable the bucket existence probe at startup. This is the default in recent Hadoop
+ versions and is recommended for third-party S3-compatible stores such as Ozone.
+ </description>
+</property>
+
+<property>
+ <name>fs.s3a.change.detection.mode</name>
+ <value>none</value>
+ <description>Disable change detection; not applicable to Ozone S3.</description>
+</property>
+```
+
+### Credentials
+
+Ozone uses the same AWS-style access key and secret key model for the S3 Gateway.
+
+- If **security is disabled**, any `AWS_ACCESS_KEY_ID` / `AWS_SECRET_ACCESS_KEY` pair can be used.
+- If **security is enabled**, obtain a key and secret via `ozone s3 getsecret` (Kerberos authentication is required). See the [S3 Protocol — Security](./s3/s3-api#security) and [Securing S3](./s3/securing-s3) sections for details.
+
+Configure S3A credentials in `core-site.xml`:
+
+```xml
+<property>
+ <name>fs.s3a.access.key</name>
+ <value>your-access-key</value>
+</property>
+
+<property>
+ <name>fs.s3a.secret.key</name>
+ <value>your-secret-key</value>
+</property>
+```
+
+Alternatively, use environment variables as documented in [Authenticating via AWS environment variables](https://hadoop.apache.org/docs/stable/hadoop-aws/tools/hadoop-aws/index.html#Authenticating_via_the_AWS_Environment_Variables):
+
+```bash
+export AWS_ACCESS_KEY_ID="your-access-key"
+export AWS_SECRET_ACCESS_KEY="your-secret-key"
+```
+
+:::note
+For generating and revoking Ozone S3 secrets, see the **Security** section of the [S3 Protocol](./s3/s3-api#security) page.
+:::
+
+:::caution
+If the Ozone S3 Gateway is exposed over **HTTPS**, the JVM must trust the gateway's TLS certificate. The Hadoop AWS client (`hadoop-aws`) uses the default Java truststore; if the gateway uses a custom or internal CA, add that CA to `JAVA_HOME/lib/security/jssecacerts` or configure the JVM truststore accordingly. Otherwise S3A connections to the HTTPS endpoint may fail with certificate errors.
+:::
+
+## Example: using `hadoop fs` with Ozone via S3A
+
+The examples below assume:
+
+- Ozone S3 Gateway is reachable at `http://localhost:9878`
+- `core-site.xml` is configured as above
+- An S3 bucket (for example `bucket1`) already exists (you can create it with `aws s3api --endpoint http://localhost:9878 create-bucket --bucket bucket1`)
+
+S3A URLs use the form `s3a://<bucket>/<path>`. The bucket corresponds to an Ozone bucket under the `/s3v` volume or a bucket link.
+
+### List objects in an Ozone S3 bucket
+
+```bash
+hadoop fs -ls s3a://bucket1/
+```
+
+### Upload a local file to Ozone using S3A
+
+```bash
+hadoop fs -put /data/local-file.txt s3a://bucket1/path/local-file.txt
+```
+
+### Download from Ozone to local or HDFS
+
+```bash
+# To local filesystem
+hadoop fs -copyToLocal s3a://bucket1/path/file.txt /tmp/from-ozone.txt
+
+# Copy to HDFS
+hadoop fs -cp s3a://bucket1/path/file.txt hdfs:///user/test/from-ozone.txt
+```
+
+### Quick test with inline configuration
+
+If you cannot modify cluster-wide `core-site.xml`, you can pass S3A options on the command line. Replace the endpoint, bucket, and credentials with your values:
+
+```bash
+hadoop fs \
+ -D fs.s3a.endpoint=http://localhost:9878 \
+ -D fs.s3a.endpoint.region=us-east-1 \
+ -D fs.s3a.path.style.access=true \
+ -D fs.s3a.bucket.probe=0 \
+ -D fs.s3a.change.detection.mode=none \
+ -D fs.s3a.access.key=your-access-key \
+ -D fs.s3a.secret.key=your-secret-key \
+ -ls s3a://bucket1/
+```
+
+## Example: using distcp between HDFS and Ozone
+
+You can use S3A as a source or destination for `distcp` to move data between HDFS and Ozone. Use the same S3A configuration as above.
+
+Copy from HDFS to Ozone:
+
+```bash
+hadoop distcp hdfs:///data/source/dir s3a://bucket1/backup/dir
+```
+
+Copy from Ozone to HDFS:
+
+```bash
+hadoop distcp s3a://bucket1/backup/dir hdfs:///data/restore/dir
+```
+
+## Relation to Ozone S3 documentation
+
+This page describes using Ozone from the **Hadoop FileSystem** perspective (S3A client). For REST API details, supported S3 operations, bucket linking, and S3 security, see the [S3 Protocol](./s3/s3-api) and [Securing S3](./s3/securing-s3) pages.
+
+For advanced S3A options (performance tuning, encryption, retries), refer to the official [Hadoop S3A documentation](https://hadoop.apache.org/docs/stable/hadoop-aws/tools/hadoop-aws/index.html) and its sub-pages such as [Performance](https://hadoop.apache.org/docs/stable/hadoop-aws/tools/hadoop-aws/performance.html) and [Encryption](https://hadoop.apache.org/docs/stable/hadoop-aws/tools/hadoop-aws/encryption.html).
diff --git a/versioned_docs/version-2.2.1/04-user-guide/01-client-interfaces/05-httpfs.md b/versioned_docs/version-2.2.1/04-user-guide/01-client-interfaces/05-httpfs.md
new file mode 100644
index 0000000000..e12c19f2d7
--- /dev/null
+++ b/versioned_docs/version-2.2.1/04-user-guide/01-client-interfaces/05-httpfs.md
@@ -0,0 +1,233 @@
+---
+sidebar_label: HttpFS Gateway
+---
+
+# HttpFS Gateway
+
+Ozone HttpFS can be used to integrate Ozone with other tools via REST API.
+
+## Introduction
+
+HttpFS is a service that provides a REST HTTP gateway supporting File System operations (read and write).
+It is interoperable with the **WebHDFS** REST HTTP API.
+
+HttpFS can be used to access data on an Ozone cluster behind of a firewall.
+For example, the HttpFS service acts as a gateway and is the only system that is allowed to cross the firewall into the cluster.
+
+HttpFS can be used to access data in Ozone using HTTP utilities (such as curl and wget) and HTTP libraries Perl from other languages than Java.
+
+The **WebHDFS** client FileSystem implementation can be used to access HttpFS using the Ozone filesystem command line tool (`ozone fs`) as well as from Java applications using the Hadoop FileSystem Java API.
+
+:::note
+If HttpFS is fronted by a **load balancer** and you use Kerberos (SPNEGO), clients obtain tickets for the load balancer’s hostname. Configure the HttpFS HTTP principal and keytab accordingly; see [HttpFS behind a load balancer (Kerberos)](../../administrator-guide/configuration/performance/httpfs-load-balancer).
+:::
+
+## Getting started
+
+To try it out, follow the [instructions](../../quick-start/installation/docker) to start the Ozone cluster with Docker Compose.
+
+```bash
+docker compose up -d --scale datanode=3
+```
+
+You can/should find now the HttpFS gateway in Docker with the name like `ozone_httpfs`,
+and it can be accessed through `localhost:14000`.
+HttpFS HTTP web-service API calls are HTTP REST calls that map to an Ozone file system operation.
+
+Here's some example usage:
+
+### Create a volume
+
+```bash
+# creates a volume called `volume1`.
+curl -i -X PUT "http://localhost:14000/webhdfs/v1/volume1?op=MKDIRS&user.name=hdfs"
+```
+
+Example Output:
+
+```bash
+HTTP/1.1 200 OK
+Date: Sat, 18 Oct 2025 07:51:21 GMT
+Cache-Control: no-cache
+Expires: Sat, 18 Oct 2025 07:51:21 GMT
+Pragma: no-cache
+Content-Type: application/json
+X-Content-Type-Options: nosniff
+X-XSS-Protection: 1; mode=block
+Set-Cookie: hadoop.auth="u=hdfs&p=hdfs&t=simple-dt&e=1760809881100&s=OCdVOi8eyMguFySkmEJxm5EkRfj6NbAM9agi5Gue1Iw="; Path=/; HttpOnly
+Content-Length: 17
+
+{"boolean":true}
+```
+
+### Create a bucket
+
+```bash
+# creates a bucket called `bucket1`.
+curl -i -X PUT "http://localhost:14000/webhdfs/v1/volume1/bucket1?op=MKDIRS&user.name=hdfs"
+```
+
+Example Output:
+
+```bash
+HTTP/1.1 200 OK
+Date: Sat, 18 Oct 2025 07:52:06 GMT
+Cache-Control: no-cache
+Expires: Sat, 18 Oct 2025 07:52:06 GMT
+Pragma: no-cache
+Content-Type: application/json
+X-Content-Type-Options: nosniff
+X-XSS-Protection: 1; mode=block
+Set-Cookie: hadoop.auth="u=hdfs&p=hdfs&t=simple-dt&e=1760809926682&s=yvOaeaRCVJZ+z+nZQ/rM/Y01pzEmS9Pe2mE9f0b+TWw="; Path=/; HttpOnly
+Content-Length: 17
+
+{"boolean":true}
+```
+
+### Upload a file
+
+```bash
+echo "hello" >> ./README.txt
+curl -i -X PUT "http://localhost:14000/webhdfs/v1/volume1/bucket1/user/foo/README.txt?op=CREATE&data=true&user.name=hdfs" -T ./README.txt -H "Content-Type: application/octet-stream"
+```
+
+Example Output:
+
+```bash
+HTTP/1.1 100 Continue
+
+HTTP/1.1 201 Created
+Date: Sat, 18 Oct 2025 08:33:33 GMT
+Cache-Control: no-cache
+Expires: Sat, 18 Oct 2025 08:33:33 GMT
+Pragma: no-cache
+X-Content-Type-Options: nosniff
+X-XSS-Protection: 1; mode=block
+Set-Cookie: hadoop.auth="u=hdfs&p=hdfs&t=simple-dt&e=1760812413286&s=09t7xKu/p/fjCJiQNL3bvW/Q7mTw28IbeNqDGlslZ6w="; Path=/; HttpOnly
+Location: http://localhost:14000/webhdfs/v1/volume1/bucket1/user/foo/README.txt
+Content-Type: application/json
+Content-Length: 84
+
+{"Location":"http://localhost:14000/webhdfs/v1/volume1/bucket1/user/foo/README.txt"}
+```
+
+### Read the file content
+
+```bash
+# returns the content of the key `/user/foo/README.txt`.
+curl 'http://localhost:14000/webhdfs/v1/volume1/bucket1/user/foo/README.txt?op=OPEN&user.name=foo'
+hello
+```
+
+## Supported operations
+
+Here are the tables of WebHDFS REST APIs and their state of support in Ozone.
+
+### File and Directory Operations
+
+| Operation | Support |
+|-------------------------------- | --------------------------- |
+| Create and Write to a File | supported |
+| Append to a File | not implemented in Ozone |
+| Concat File(s) | not implemented in Ozone |
+| Open and Read a File | supported |
+| Make a Directory | supported |
+| Create a Symbolic Link | not implemented in Ozone |
+| Rename a File/Directory | supported (with limitations) |
+| Delete a File/Directory | supported |
+| Truncate a File | not implemented in Ozone. |
+| Status of a File/Directory | supported |
+| List a Directory | supported |
+| List a File | supported |
+| Iteratively List a Directory | unsupported |
+
+### Other File System Operations
+
+| Operation | Support |
+| ------------------------------------- | --------------------------------------- |
+| Get Content Summary of a Directory | supported |
+| Get Quota Usage of a Directory | supported |
+| Set Quota | not implemented in Ozone FileSystem API |
+| Set Quota By Storage Type | not implemented in Ozone |
+| Get File Checksum | unsupported (to be fixed) |
+| Get Home Directory | unsupported (to be fixed) |
+| Get Trash Root | unsupported |
+| Set Permission | not implemented in Ozone FileSystem API |
+| Set Owner | not implemented in Ozone FileSystem API |
+| Set Replication Factor | not implemented in Ozone FileSystem API |
+| Set Access or Modification Time | not implemented in Ozone FileSystem API |
+| Modify ACL Entries | not implemented in Ozone FileSystem API |
+| Remove ACL Entries | not implemented in Ozone FileSystem API |
+| Remove Default ACL | not implemented in Ozone FileSystem API |
+| Remove ACL | not implemented in Ozone FileSystem API |
+| Set ACL | not implemented in Ozone FileSystem API |
+| Get ACL Status | not implemented in Ozone FileSystem API |
+| Check access | not implemented in Ozone FileSystem API |
+
+## Proxy User Configuration
+
+HttpFS supports proxy user (user impersonation) functionality, which allows a user to perform operations on behalf of another user. This is useful when HttpFS is used as a gateway and you want to allow certain users to impersonate other users.
+
+To configure proxy users, you need to add the following properties to `httpfs-site.xml`.
+
+### Configuration Properties
+
+For each user that should be allowed to perform impersonation, you need to configure two properties:
+
+1. **`httpfs.proxyuser.#USER#.hosts`**: List of hosts from which the user is allowed to perform impersonation operations.
+2. **`httpfs.proxyuser.#USER#.groups`**: List of groups whose users can be impersonated by the specified user.
+
+Replace `#USER#` with the actual username of the user who should be allowed to perform impersonation.
+
+### Example Configuration
+
+```xml
+<property>
+ <name>httpfs.proxyuser.knoxuser.hosts</name>
+ <value>*</value>
+ <description>
+ List of hosts the 'knoxuser' user is allowed to perform 'doAs'
+ operations.
+
+ The value can be the '*' wildcard or a comma-separated list of hostnames.
+
+ For multiple users, copy this property and replace the user name
+ in the property name.
+ </description>
+</property>
+
+<property>
+ <name>httpfs.proxyuser.knoxuser.groups</name>
+ <value>*</value>
+ <description>
+ List of groups the 'knoxuser' user is allowed to impersonate users
+ from to perform 'doAs' operations.
+
+ The value can be the '*' wildcard or a comma-separated list of group names.
+
+ For multiple users, copy this property and replace the user name
+ in the property name.
+ </description>
+</property>
+```
+
+In this example, the user `knoxuser` is allowed to impersonate any user from any host. For production environments, it's recommended to restrict these values to specific hosts and groups instead of using the wildcard `*`.
+
+### Troubleshooting
+
+If you encounter an error like:
+
+```bash
+User: user/host @REALM is not allowed to impersonate user01
+```
+
+This indicates that the proxy user configuration is missing or incorrect. Ensure that:
+
+1. The `httpfs.proxyuser.#USER#.hosts` property is set with appropriate host values
+2. The `httpfs.proxyuser.#USER#.groups` property is set with appropriate group values
+3. The HttpFS service has been restarted after configuration changes
+
+## Hadoop user and developer documentation about HttpFS
+
+- [HttpFS Server Setup](https://hadoop.apache.org/docs/stable/hadoop-hdfs-httpfs/ServerSetup.html)
+- [Using HTTP Tools](https://hadoop.apache.org/docs/stable/hadoop-hdfs-httpfs/ServerSetup.html)
diff --git a/versioned_docs/version-2.2.1/04-user-guide/01-client-interfaces/06-java-client-api.md b/versioned_docs/version-2.2.1/04-user-guide/01-client-interfaces/06-java-client-api.md
new file mode 100644
index 0000000000..7929950d48
--- /dev/null
+++ b/versioned_docs/version-2.2.1/04-user-guide/01-client-interfaces/06-java-client-api.md
@@ -0,0 +1,141 @@
+---
+sidebar_label: Java Client API
+---
+
+# Java Client API
+
+The Apache Ozone Java Client API provides programmatic access to Ozone storage.
+
+For detailed API documentation, refer to the [OzoneClient Javadoc](https://javadoc.io/doc/org.apache.ozone/ozone-client/latest/org/apache/hadoop/ozone/client/OzoneClient.html).
+Ozone ships with its own client library that supports RPC. For generic use cases the S3
+compatible REST interface also can be used instead of the Ozone client.
+
+## Creating an Ozone client
+
+The Ozone client factory creates the Ozone client. To get a RPC client we can call
+
+```java
+OzoneClient ozClient = OzoneClientFactory.getRpcClient();
+```
+
+If the user want to create a client based on the configuration, then they can
+call
+
+```java
+OzoneClient ozClient = OzoneClientFactory.getClient();
+```
+
+and an appropriate client based on configuration will be returned.
+
+## Writing data using Ozone Client
+
+The hierarchy of data inside Ozone is a volume, bucket and a key.
+A volume is a collection of buckets.
+A bucket is a collection of keys.
+To write data to the Ozone, you need a volume, bucket and a key.
+
+### Creating a Volume
+
+Once we have a client, we need to get a reference to the ObjectStore. This
+is done via
+
+```java
+ObjectStore objectStore = ozClient.getObjectStore();
+```
+
+An object store represents an active cluster against which the client is working.
+
+```java
+// Let us create a volume to store our game assets.
+// This uses default arguments for creating that volume.
+objectStore.createVolume("assets");
+
+// Let us verify that the volume got created.
+OzoneVolume assets = objectStore.getVolume("assets");
+```
+
+It is possible to pass an array of arguments to the createVolume by creating volume arguments.
+
+### Creating a Bucket
+
+Once you have a volume, you can create buckets inside the volume.
+
+```java
+// Let us create a bucket called videos.
+assets.createBucket("videos");
+OzoneBucket video = assets.getBucket("videos");
+```
+
+At this point we have a usable volume and a bucket. Our volume is called *assets* and bucket is called *videos*.
+
+Now we can create a Key.
+
+### Reading and Writing a Key
+
+With a bucket object the users can now read and write keys. The following code reads a video called intro.mp4 from the local disk and stores in the *video* bucket that we just created.
+
+```java
+// read data from the file, this is a user provided function.
+byte [] videoData = readFile("intro.mp4");
+
+// Create an output stream and write data.
+OzoneOutputStream videoStream = video.createKey("intro.mp4", 1048576);
+videoStream.write(videoData);
+
+// Close the stream when it is done.
+videoStream.close();
+
+
+// We can use the same bucket to read the file that we just wrote, by creating an input Stream.
+// Let us allocate a byte array to hold the video first.
+byte[] data = new byte[(int)1048576];
+OzoneInputStream introStream = video.readKey("intro.mp4");
+// read intro.mp4 into the data buffer
+introStream.read(data);
+introStream.close();
+```
+
+Here is a complete example of the code that we just wrote. Please note the close functions being called in this program.
+
+```java
+// Let us create a client
+OzoneClient ozClient = OzoneClientFactory.getClient();
+
+// Get a reference to the ObjectStore using the client
+ObjectStore objectStore = ozClient.getObjectStore();
+
+// Let us create a volume to store our game assets.
+// This default arguments for creating that volume.
+objectStore.createVolume("assets");
+
+// Let us verify that the volume got created.
+OzoneVolume assets = objectStore.getVolume("assets");
+
+// Let us create a bucket called videos.
+assets.createBucket("videos");
+OzoneBucket video = assets.getBucket("videos");
+
+// read data from the file, this is assumed to be a user provided function.
+byte [] videoData = readFile("intro.mp4");
+
+// Create an output stream and write data.
+OzoneOutputStream videoStream = video.createKey("intro.mp4", 1048576);
+videoStream.write(videoData);
+
+// Close the stream when it is done.
+videoStream.close();
+
+
+// We can use the same bucket to read the file that we just wrote, by creating an input Stream.
+// Let us allocate a byte array to hold the video first.
+
+byte[] data = new byte[(int)1048576];
+OzoneInputStream introStream = video.readKey("intro.mp4");
+introStream.read(data);
+
+// Close the stream when it is done.
+introStream.close();
+
+// Close the client.
+ozClient.close();
+```
diff --git a/versioned_docs/version-2.2.1/04-user-guide/01-client-interfaces/07-python.md b/versioned_docs/version-2.2.1/04-user-guide/01-client-interfaces/07-python.md
new file mode 100644
index 0000000000..eab7be4bb5
--- /dev/null
+++ b/versioned_docs/version-2.2.1/04-user-guide/01-client-interfaces/07-python.md
@@ -0,0 +1,235 @@
+---
+sidebar_label: Accessing Apache Ozone from Python
+---
+
+# Accessing Apache Ozone from Python
+
+Apache Ozone project itself does not provide Python client libraries.
+However, several third-party open source libraries can be used to build applications to access an Ozone cluster via
+different interfaces: ofs file system, Ozone HttpFS REST API and Ozone S3.
+
+This document outlines these approaches, providing concise setup instructions and validated code examples.
+
+## Setup and Prerequisites
+
+Before starting, ensure the following:
+
+- Python installed (3.x recommended)
+- Apache Ozone configured and accessible
+- For PyArrow with libhdfs:
+ - PyArrow library (`pip install pyarrow`)
+ - Hadoop native libraries configured and Ozone classpath specified (see below for details)
+- For S3 access:
+ - Boto3 (`pip install boto3`)
+ - Ozone S3 Gateway endpoint and bucket names
+ - Access credentials (AWS-like key and secret)
+- For HttpFS access:
+ - Requests (`pip install requests`) or fsspec (`pip install fsspec`)
+
+## Method 1: Access Ozone via PyArrow and libhdfs
+
+This approach leverages PyArrow's HadoopFileSystem API, which requires *libhdfs.so* native library.
+The *libhdfs.so* is not packaged within PyArrow and you must download it separately from Hadoop.
+
+### Configuration
+
+Ensure Ozone configuration files (core-site.xml and `ozone-site.xml`) are available and `OZONE_CONF_DIR` is set.
+Also ensure `ARROW_LIBHDFS_DIR` and `CLASSPATH` are set properly.
+
+For example,
+
+```shell
+export ARROW_LIBHDFS_DIR=hadoop-3.4.0/lib/native/
+export CLASSPATH=$(ozone classpath ozone-tools)
+```
+
+### Code Example
+
+```python
+import pyarrow.fs as pafs
+
+# Connect to Ozone using HadoopFileSystem
+# "default" tells PyArrow to use the fs.defaultFS property from core-site.xml
+fs = pafs.HadoopFileSystem("default")
+
+# Create a directory inside the bucket
+fs.create_dir("volume/bucket/aaa")
+
+# Write data to a file
+path = "volume/bucket/file1"
+with fs.open_output_stream(path) as stream:
+ stream.write(b'data')
+```
+
+:::note
+Configure fs.defaultFS in the core-site.xml to point to the Ozone cluster. For example,
+
+```xml
+<configuration>
+ <property>
+ <name>fs.defaultFS</name>
+ <value>ofs://om:9862</value>
+ <description>Ozone Manager endpoint</description>
+ </property>
+</configuration>
+```
+
+:::
+
+Try it yourself! Check out [PyArrow Tutorial](https://ozone.apache.org/docs/edge/recipe/pyarrowtutorial.html) for a quick start using Ozone's Docker image.
+
+## Method 2: Access Ozone via Boto3 and S3 Gateway
+
+### Configuration
+
+- Identify your Ozone S3 Gateway endpoint (e.g., `http://s3g:9878`).
+- Use AWS-compatible credentials (from Ozone).
+
+### Code Example
+
+```python
+import boto3
+
+# Create a local file to upload
+with open("localfile.txt", "w") as f:
+ f.write("Hello from Ozone via Boto3!\n")
+
+# Configure Boto3 client
+s3 = boto3.client(
+ 's3',
+ endpoint_url='http://s3g:9878',
+ aws_access_key_id='ozone-access-key',
+ aws_secret_access_key='ozone-secret-key'
+)
+
+# List buckets
+response = s3.list_buckets()
+print("Buckets:", response['Buckets'])
+
+# Upload the file
+s3.upload_file('localfile.txt', 'bucket', 'file.txt')
+print("Uploaded 'localfile.txt' to 'bucket/file.txt'")
+
+# Download the file back
+s3.download_file('bucket', 'file.txt', 'downloaded.txt')
+print("Downloaded 'file.txt' as 'downloaded.txt'")
+```
+
+:::note
+Replace endpoint URL, credentials, and bucket names with your setup.
+:::
+
+Try it yourself! Check out [Boto3 Tutorial](https://ozone.apache.org/docs/edge/recipe/boto3tutorial.html) for a quick start using Ozone's Docker image.
+
+## Method 3: Access Ozone via HttpFS REST API
+
+First, install requests Python module:
+
+```shell
+pip install requests
+```
+
+### Configuration
+
+- Use Ozone’s HttpFS endpoint (e.g., `http://httpfs:14000`).
+
+### Code Example (requests)
+
+```python
+#!/usr/bin/python
+import requests
+
+# Ozone HTTPFS endpoint and file path
+host = "http://httpfs:14000"
+volume = "vol1"
+bucket = "bucket1"
+filename = "hello.txt"
+path = f"/webhdfs/v1/{volume}/{bucket}/{filename}"
+user = "ozone" # can be any value in simple auth mode
+
+# Step 1: Initiate file creation (responds with 307 redirect)
+params_create = {
+ "op": "CREATE",
+ "overwrite": "true",
+ "user.name": user
+}
+
+print("Creating file...")
+resp_create = requests.put(host + path, params=params_create, allow_redirects=False)
+
+if resp_create.status_code != 307:
+ print(f"Unexpected response: {resp_create.status_code}")
+ print(resp_create.text)
+ exit(1)
+
+redirect_url = resp_create.headers['Location']
+print(f"Redirected to: {redirect_url}")
+
+# Step 2: Write data to the redirected location with correct headers
+headers = {"Content-Type": "application/octet-stream"}
+content = b"Hello from Ozone HTTPFS!\n"
+
+resp_upload = requests.put(redirect_url, data=content, headers=headers)
+if resp_upload.status_code != 201:
+ print(f"Upload failed: {resp_upload.status_code}")
+ print(resp_upload.text)
+ exit(1)
+print("File created successfully.")
+
+# Step 3: Read the file back
+params_open = {
+ "op": "OPEN",
+ "user.name": user
+}
+
+print("Reading file...")
+resp_read = requests.get(host + path, params=params_open, allow_redirects=True)
+if resp_read.ok:
+ print("File contents:")
+ print(resp_read.text)
+else:
+ print(f"Read failed: {resp_read.status_code}")
+ print(resp_read.text)
+```
+
+Try it yourself! Check out [Access Ozone using HttpFS REST API Tutorial](https://ozone.apache.org/docs/edge/recipe/pythonrequestsozonehttpfs.html) for a quick start using Ozone's Docker image.
+
+### Code Example (webhdfs)
+
+First, install fsspec Python module:
+
+```shell
+pip install fsspec
+```
+
+```python
+from fsspec.implementations.webhdfs import WebHDFS
+
+fs = WebHDFS(host='httpfs', port=14000, user='ozone')
+
+# Read a file from /vol1/bucket1/hello.txt
+file_path = "/vol1/bucket1/hello.txt"
+
+with fs.open(file_path, mode='rb') as f:
+ content = f.read()
+ print("File contents:")
+ print(content.decode('utf-8'))
+```
+
+:::note
+Replace host, port, and path as per your setup.
+:::
+
+## Troubleshooting Tips
+
+- **Authentication Errors**: Verify credentials and Kerberos tokens (if used).
+- **Connection Issues**: Check endpoint URLs, ports, and firewall rules.
+- **FileSystem Errors**: Ensure correct Ozone configuration and appropriate permissions.
+- **Missing Dependencies**: Install required Python packages (`pip install pyarrow boto3 requests fsspec`).
+
+## References and Further Resources
+
+- [Apache Ozone Documentation](https://ozone.apache.org/docs/)
+- [PyArrow Documentation](https://arrow.apache.org/docs/python/)
+- [Boto3 Documentation](https://boto3.amazonaws.com/v1/documentation/api/latest/index.html)
+- [fsspec WebHDFS Python API](https://filesystem-spec.readthedocs.io/en/latest/api.html#fsspec.implementations.webhdfs.WebHDFS)
diff --git a/versioned_docs/version-2.2.1/04-user-guide/01-client-interfaces/08-csi-protocol.md b/versioned_docs/version-2.2.1/04-user-guide/01-client-interfaces/08-csi-protocol.md
new file mode 100644
index 0000000000..38da095865
--- /dev/null
+++ b/versioned_docs/version-2.2.1/04-user-guide/01-client-interfaces/08-csi-protocol.md
@@ -0,0 +1,73 @@
+---
+sidebar_label: CSI Protocol
+---
+
+# CSI Protocol
+
+:::warning
+Ozone CSI support is still in alpha phase and buckets can be mounted only via 3rd party S3 compatible Fuse implementation (like Goofys).
+Fuse over S3 can provide only limited performance compared to a native Fuse file system.
+Long-term Ozone may support a custom solution to mount buckets which provides better user experience (with fuse or NFS or any other solution).
+Until that CSI is recommended to use only if you can live with this limitation and your use case is tested carefully.
+:::
+
+`Container Storage Interface` (CSI) will enable storage vendors (SP) to develop a plugin once and have it work across a number of container orchestration (CO) systems like Kubernetes or Yarn.
+
+To get more information about CSI at [SCI spec](https://github.com/container-storage-interface/spec/blob/master/spec.md)
+
+CSI defined a simple gRPC interface with 3 interfaces (Identity, Controller, Node). It defined how the Container Orchestrator can request the creation of a new storage space or the mount of the newly created storage but doesn't define how the storage can be mounted.
+
+
+
+By default Ozone CSI service uses a S3 fuse driver ([goofys](https://github.com/kahing/goofys)) to mount the created Ozone bucket. Implementation of other mounting options such as a dedicated NFS server or native Fuse driver is work in progress.
+
+Ozone CSI is an implementation of CSI, it can make possible of using Ozone as a storage volume for a container.
+
+## Getting started
+
+First of all, we need an Ozone cluster with s3gateway, and its OM RPC port and s3gateway port must be visible to CSI pod,
+because CSIServer will access OM to create or delete a bucket, also, CSIServer will publish volume by creating a mount point to s3g
+through goofys.
+
+If you don't have an Ozone cluster on Kubernetes, you can reference [Kubernetes](../../quick-start/installation/kubernetes) to create one. Use the resources from `kubernetes/examples/ozone` where you can find all the required Kubernetes resources to run cluster together with the dedicated Ozone CSI daemon (check `kubernetes/examples/ozone/csi`)
+
+Now, create the CSI related resources by execute the follow command.
+
+```bash
+kubectl create -f /ozone/kubernetes/examples/ozone/csi
+```
+
+## Create pv-test and visit the result
+
+Create pv-test related resources by execute the follow command.
+
+```bash
+kubectl create -f /ozone/kubernetes/examples/ozone/pv-test
+```
+
+Attach the pod `scm-0` and put a key into the `/s3v/pvc*` bucket.
+
+```bash
+kubectl exec -it scm-0 bash
+[hadoop@scm-0 ~]$ ozone sh bucket list s3v
+[ {
+ "metadata" : { },
+ "volumeName" : "s3v",
+ "name" : "pvc-861e2d8b-2232-4cd1-b43c-c0c26697ab6b",
+ "storageType" : "DISK",
+ "versioning" : false,
+ "creationTime" : "2020-06-11T08:19:47.469Z",
+ "encryptionKeyName" : null
+} ]
+[hadoop@scm-0 ~]$ ozone sh key put /s3v/pvc-861e2d8b-2232-4cd1-b43c-c0c26697ab6b/A LICENSE.txt
+```
+
+Now, let's forward port of the `ozone-csi-test-webserver-7cbdc5d65c-h5mnn` to see the UI through the web browser.
+
+```bash
+kubectl port-forward ozone-csi-test-webserver-7cbdc5d65c-h5mnn 8000:8000
+```
+
+Eventually, we can see the result from `http://localhost:8000/`
+
+
diff --git a/versioned_docs/version-2.2.1/04-user-guide/01-client-interfaces/08-native-cpp.md b/versioned_docs/version-2.2.1/04-user-guide/01-client-interfaces/08-native-cpp.md
new file mode 100644
index 0000000000..c8ab42ed86
--- /dev/null
+++ b/versioned_docs/version-2.2.1/04-user-guide/01-client-interfaces/08-native-cpp.md
@@ -0,0 +1,121 @@
+---
+sidebar_label: Native C/C++ Client Access to Ozone
+---
+
+# Native C/C++ Client Access to Ozone
+
+## Components Summary
+
+- **libhdfs**: The standard Hadoop C API. It is a JNI bridge between C/C++ and Java FileSystem implementations.
+- **libo3fs**: Lightweight wrapper exposing a simplified API for Ozone clients. It is built on top of `libhdfs`.
+- **OFS (Ozone FileSystem)**: Java-based filesystem client used internally by `libhdfs` to interact with Ozone.
+
+## Overview
+
+Native C/C++ applications can access Ozone volumes and buckets using Hadoop HDFS's `libhdfs` JNI library.
+As an example, Apache Impala uses this library to access Ozone.
+
+To demonstrate, we built a simple wrapper [`libo3fs`](https://github.com/apache/hadoop-ozone/tree/master/hadoop-ozone/native-client/libo3fs) around `libhdfs`.
+Applications can choose to use either `libo3fs` or directly use the low level `libhdfs` library for basic file operations.
+
+## Architecture and Design Notes
+
+The native client leverages the Hadoop `libhdfs` C API for low-level JNI bindings, and implements additional wrappers in `libo3fs` to support Ozone semantics. Internally:
+
+- `libo3fs` wraps Ozone FileSystem APIs for basic file operations (read/write).
+- `libhdfs` implements JNI interface.
+- JNI calls link back to a JVM-based Ozone client to execute operations.
+
+## Building the C/C++ Client Library
+
+### Prerequisites
+
+- Apache Ozone built from source (`ozone-dist/`)
+- Hadoop with compiled `libhdfs.so`
+- Java 8 or later
+- Linux (kernel > 2.6.9)
+
+The following steps assume you have Ozone built from source code, the Hadoop binary distribution downloaded and extracted,
+and the environment variables `OZONE_HOME` and `HADOOP_HOME` set to their respective directories.
+
+### 0. Download Hadoop binary distribution (optional)
+
+```bash
+wget https://archive.apache.org/dist/hadoop/common/hadoop-3.4.0/hadoop-3.4.0.tar.gz
+tar -xzf hadoop-3.4.0.tar.gz
+```
+
+### 1. Compile the Core Library & Shared Library
+
+```bash
+export JAVA_HOME=/path/to/java
+export HADOOP_HOME=/path/to/hadoop
+export OZONE_HOME=/path/to/ozone
+
+cd $OZONE_HOME/hadoop-ozone/native-client/libo3fs
+gcc -fPIC -pthread \
+ -I$HADOOP_HOME/include \
+ -g -c o3fs.c
+
+gcc -shared -o libo3fs.so o3fs.o \
+ $HADOOP_HOME/lib/native/libhdfs.so
+```
+
+### 2. Compile Sample Applications
+
+```bash
+cd $OZONE_HOME/hadoop-ozone/native-client/libo3fs-examples
+gcc -fPIC -pthread -I$OZONE_HOME/hadoop-ozone/native-client/libo3fs \
+ -I$HADOOP_HOME/include -g -c libo3fs_read.c
+gcc -fPIC -pthread -I$OZONE_HOME/hadoop-ozone/native-client/libo3fs \
+ -I$HADOOP_HOME/include -g -c libo3fs_write.c
+```
+
+### 3. Link Executables
+
+```bash
+# o3fs_read
+gcc -o o3fs_read libo3fs_read.o -L$HADOOP_HOME/lib/native -lhdfs \
+ -L$JAVA_HOME/lib/server -ljvm \
+ -L$OZONE_HOME/hadoop-ozone/native-client/libo3fs -lo3fs -pthread
+
+# o3fs_write
+gcc -o o3fs_write libo3fs_write.o -L$HADOOP_HOME/lib/native -lhdfs \
+ -L$JAVA_HOME/lib/server -ljvm \
+ -L$OZONE_HOME/hadoop-ozone/native-client/libo3fs -lo3fs -pthread
+```
+
+### 4. Environment Variables
+
+```bash
+export CLASSPATH=$($OZONE_HOME/bin/ozone classpath ozone-tools)
+export LD_LIBRARY_PATH=\
+$HADOOP_HOME/lib/native:\
+$JAVA_HOME/lib/server:\
+$OZONE_HOME/hadoop-ozone/native-client/libo3fs
+```
+
+### 5. Run Sample Applications
+
+```shell
+ozone sh volume create my-volume
+ozone sh bucket create /my-volume/my-bucket
+```
+
+```shell
+// o3fs_write writes a 100-byte file named 'file1' using a 100-byte buffer to the 'my-bucket' bucket in the 'my-volume' volume,
+// connecting to an Ozone Manager (om) on port 9862.
+./o3fs_write file1 100 100 om 9862 my-bucket my-volume
+```
+
+## Limitations
+
+- Only basic file I/O operations are supported (no directory listing, ACLs, etc.); use `libhdfs` directly for advanced features.
+- JNI dependency requires compatible JVM and shared libraries
+- Testing has been limited to Linux; No Windows nor Mac supported
+
+## References
+
+- [Ozone FileSystem Java Interface](https://ozone.apache.org/docs/edge/interface/ofs.html)
+- [Hadoop libhdfs Docs](https://hadoop.apache.org/docs/stable/hadoop-project-dist/hadoop-hdfs/LibHdfs.html)
+- [JNI and Native Libraries in Hadoop](https://hadoop.apache.org/docs/stable/hadoop-project-dist/hadoop-common/NativeLibraries.html)
diff --git a/versioned_docs/version-2.2.1/04-user-guide/01-client-interfaces/CSI.png b/versioned_docs/version-2.2.1/04-user-guide/01-client-interfaces/CSI.png
new file mode 100644
index 0000000000..38720c3019
Binary files /dev/null and b/versioned_docs/version-2.2.1/04-user-guide/01-client-interfaces/CSI.png differ
diff --git a/versioned_docs/version-2.2.1/04-user-guide/01-client-interfaces/README.mdx b/versioned_docs/version-2.2.1/04-user-guide/01-client-interfaces/README.mdx
new file mode 100644
index 0000000000..c7697e5e23
--- /dev/null
+++ b/versioned_docs/version-2.2.1/04-user-guide/01-client-interfaces/README.mdx
@@ -0,0 +1,7 @@
+# Client Interfaces
+
+import DocCardList from '@theme/DocCardList';
+
+This section documents the interfaces that clients can use to communicate with Ozone.
+
+<DocCardList/>
diff --git a/versioned_docs/version-2.2.1/04-user-guide/01-client-interfaces/persistent-volume-test-web-ui.png b/versioned_docs/version-2.2.1/04-user-guide/01-client-interfaces/persistent-volume-test-web-ui.png
new file mode 100644
index 0000000000..69e0aa121b
Binary files /dev/null and b/versioned_docs/version-2.2.1/04-user-guide/01-client-interfaces/persistent-volume-test-web-ui.png differ
diff --git a/versioned_docs/version-2.2.1/04-user-guide/02-clients/01-ozone.md b/versioned_docs/version-2.2.1/04-user-guide/02-clients/01-ozone.md
new file mode 100644
index 0000000000..8ad169b925
--- /dev/null
+++ b/versioned_docs/version-2.2.1/04-user-guide/02-clients/01-ozone.md
@@ -0,0 +1,13 @@
+---
+sidebar_label: Ozone
+---
+
+# The Ozone Client
+
+Document how to install, configure and run Ozone's client. This should also include
+
+- Which interfaces it supports (ofs, o3, Java).
+- Information about configuration files it reads (core-site.xml, client log4j).
+- Environment variables and common JVM flags (`-D`) that can be used at the CLI.
+
+**TODO:** File a subtask under [HDDS-9858](https://issues.apache.org/jira/browse/HDDS-9858) and complete this page or section.
diff --git a/versioned_docs/version-2.2.1/04-user-guide/02-clients/02-hdfs.md b/versioned_docs/version-2.2.1/04-user-guide/02-clients/02-hdfs.md
new file mode 100644
index 0000000000..03100864e8
--- /dev/null
+++ b/versioned_docs/version-2.2.1/04-user-guide/02-clients/02-hdfs.md
@@ -0,0 +1,9 @@
+---
+sidebar_label: HDFS
+---
+
+# Using an HDFS Client With Ozone
+
+Link to HDFS documentation to install and configure an HDFS client. Document how to configure it to work against Ozone. This should also include which interfaces it supports (ofs, s3a).
+
+**TODO:** File a subtask under [HDDS-9858](https://issues.apache.org/jira/browse/HDDS-9858) and complete this page or section.
diff --git a/versioned_docs/version-2.2.1/04-user-guide/02-clients/03-s3.md b/versioned_docs/version-2.2.1/04-user-guide/02-clients/03-s3.md
new file mode 100644
index 0000000000..25c4328db5
--- /dev/null
+++ b/versioned_docs/version-2.2.1/04-user-guide/02-clients/03-s3.md
@@ -0,0 +1,13 @@
+---
+sidebar_label: S3
+---
+
+# Using an S3 Client With Ozone
+
+Document how to set it up an S3 client to run against Ozone (access key and secret key).
+
+- Any S3 compatible client should work against Ozone's S3 interface.
+- The Ozone Java client is not required to be present, but can be used to generate secrets.
+- A kerberos principal is required to initially generate a secret.
+
+**TODO:** File a subtask under [HDDS-9858](https://issues.apache.org/jira/browse/HDDS-9858) and complete this page or section.
diff --git a/versioned_docs/version-2.2.1/04-user-guide/02-clients/README.mdx b/versioned_docs/version-2.2.1/04-user-guide/02-clients/README.mdx
new file mode 100644
index 0000000000..4d8a31e397
--- /dev/null
+++ b/versioned_docs/version-2.2.1/04-user-guide/02-clients/README.mdx
@@ -0,0 +1,11 @@
+---
+sidebar_label: Clients
+---
+
+# Ozone Clients
+
+import DocCardList from '@theme/DocCardList';
+
+This section provides instructions to install, configure, and run various clients to read and write data to Ozone.
+
+<DocCardList/>
diff --git a/versioned_docs/version-2.2.1/04-user-guide/03-integrations/01-hive.md b/versioned_docs/version-2.2.1/04-user-guide/03-integrations/01-hive.md
new file mode 100644
index 0000000000..9ff996fc11
--- /dev/null
+++ b/versioned_docs/version-2.2.1/04-user-guide/03-integrations/01-hive.md
@@ -0,0 +1,164 @@
+---
+sidebar_label: Hive
+---
+
+# Hive
+
+Apache Hive has supported Apache Ozone since Hive 4.0. To enable Hive to work with Ozone paths, ensure that the `ozone-filesystem-hadoop3` JAR is added to the Hive classpath.
+
+## Supported Access Protocols
+
+Hive supports the following protocols for accessing Ozone data:
+
+- ofs
+- o3fs
+- s3a
+
+## Supported Replication Types
+
+Hive is compatible with Ozone buckets configured with either:
+
+- RATIS (Replication)
+- Erasure Coding
+
+## Accessing Ozone Data in Hive
+
+Hive provides two methods to interact with data in Ozone:
+
+- Managed Tables
+- External Tables
+
+### Managed Tables
+
+#### Configuring the Hive Warehouse Directory in Ozone
+
+To store managed tables in Ozone, update the following properties in the `hive-site.xml` configuration file:
+
+```xml
+<property>
+ <name>hive.metastore.warehouse.dir</name>
+ <value>ofs://ozone1/vol1/bucket1/warehouse/</value>
+</property>
+```
+
+#### Creating a Managed Table
+
+You can create a managed table with a standard `CREATE TABLE` statement:
+
+```sql
+CREATE TABLE myTable (
+ id INT,
+ name STRING
+);
+```
+
+#### Loading Data into a Managed Table
+
+Data can be loaded into a Hive table from an Ozone location:
+
+```sql
+LOAD DATA INPATH 'ofs://ozone1/vol1/bucket1/table.csv' INTO TABLE myTable;
+```
+
+#### Specifying a Custom Ozone Path
+
+You can define a custom Ozone path for a database using the `MANAGEDLOCATION` clause:
+
+```sql
+CREATE DATABASE d1 MANAGEDLOCATION 'ofs://ozone1/vol1/bucket1/data';
+```
+
+Tables created in the database d1 will be stored under the specified path:
+
+`ofs://ozone1/vol1/bucket1/data`
+
+#### Verifying the Ozone Path
+
+You can confirm that Hive references the correct Ozone path using:
+
+```sql
+SHOW CREATE DATABASE d1;
+```
+
+Output Example:
+
+```text
++----------------------------------------------------+
+| createdb_stmt |
++----------------------------------------------------+
+| CREATE DATABASE `d1` |
+| LOCATION |
+| 'ofs://ozone1/vol1/bucket1/external/d1.db' |
+| MANAGEDLOCATION |
+| 'ofs://ozone1/vol1/bucket1/data' |
++----------------------------------------------------+
+```
+
+### External Tables
+
+Hive allows the creation of external tables to query existing data stored in Ozone.
+
+#### Creating an External Table
+
+```sql
+CREATE EXTERNAL TABLE external_table (
+ id INT,
+ name STRING
+)
+LOCATION 'ofs://ozone1/vol1/bucket1/table1';
+```
+
+- With external tables, the data is expected to be created and managed by another tool.
+- Hive queries the data as-is.
+- Note: Dropping an external table in Hive does not delete the associated data.
+
+To set a default path for external tables, configure the following property in the `hive-site.xml` file:
+
+```xml
+<property>
+ <name>hive.metastore.warehouse.external.dir</name>
+ <value>ofs://ozone1/vol1/bucket1/external/</value>
+</property>
+```
+
+This property specifies the base directory for external tables when no explicit LOCATION is provided.
+
+#### Verifying the External Table Path
+
+To confirm the table's metadata and location, use:
+
+```sql
+SHOW CREATE TABLE external_table;
+```
+
+Output Example:
+
+```text
++----------------------------------------------------+
+| createtab_stmt |
++----------------------------------------------------+
+| CREATE EXTERNAL TABLE `external_table`( |
+| `id` int, |
+| `name` string) |
+| ROW FORMAT SERDE |
+| 'org.apache.hadoop.hive.serde2.lazy.LazySimpleSerDe' |
+| STORED AS INPUTFORMAT |
+| 'org.apache.hadoop.mapred.TextInputFormat' |
+| OUTPUTFORMAT |
+| 'org.apache.hadoop.hive.ql.io.HiveIgnoreKeyTextOutputFormat' |
+| LOCATION |
+| 'ofs://ozone1/vol1/bucket1/table1' |
+| TBLPROPERTIES ( |
+| 'bucketing_version'='2', |
+| 'transient_lastDdlTime'='1734725573') |
++----------------------------------------------------+
+```
+
+## Using the S3A Protocol
+
+In addition to ofs, Hive can access Ozone using the S3 Gateway via the S3A file system.
+
+For more information, consult:
+
+- The [S3 Protocol](../client-interfaces/s3/s3-api)
+- The [Hadoop S3A](https://hadoop.apache.org/docs/current/hadoop-aws/tools/hadoop-aws/index.html) documentation.
diff --git a/versioned_docs/version-2.2.1/04-user-guide/03-integrations/02-hue.md b/versioned_docs/version-2.2.1/04-user-guide/03-integrations/02-hue.md
new file mode 100644
index 0000000000..06bb22e295
--- /dev/null
+++ b/versioned_docs/version-2.2.1/04-user-guide/03-integrations/02-hue.md
@@ -0,0 +1,3 @@
+# Hue
+
+**TODO:** File a subtask under [HDDS-9858](https://issues.apache.org/jira/browse/HDDS-9858) and complete this page or section.
diff --git a/versioned_docs/version-2.2.1/04-user-guide/03-integrations/03-iceberg.md b/versioned_docs/version-2.2.1/04-user-guide/03-integrations/03-iceberg.md
new file mode 100644
index 0000000000..e870983d87
--- /dev/null
+++ b/versioned_docs/version-2.2.1/04-user-guide/03-integrations/03-iceberg.md
@@ -0,0 +1,262 @@
+---
+sidebar_label: Iceberg
+---
+
+# Apache Iceberg
+
+[Apache Iceberg](https://iceberg.apache.org/) is an open table format for huge analytic datasets. It is designed to improve on the limitations of traditional table formats like Hive and provides features such as schema evolution, hidden partitioning, and time travel.
+
+Iceberg uses Ozone storage layer to build scalable data lakehouses, acting as the durable system of record for table data and metadata. Ozone’s native atomic rename capability supports Iceberg’s atomic commit requirements, providing strong consistency for data management without external locking services. Ozone's ability to handle high object counts and its strong consistency model (via Ratis) make it a suitable, reliable backend for Iceberg's transactional, snapshot-based structure.
+
+## Key Integration Details
+
+- **Storage and Metadata Management:** Iceberg stores data files and metadata files (manifests, snapshots) directly on Ozone.
+- **Atomic Operations:** Ozone supports necessary atomic operations for Iceberg’s commit process, ensuring data consistency during concurrent writes.
+- **Performance:** The combination allows for petabyte-scale analytics and fast query planning, overcoming the scalability bottlenecks of traditional HDFS Namenodes.
+- **Compatibility:** Iceberg interacts with Ozone using S3-compatible APIs or Hadoop FileSystem interfaces, allowing for seamless integration.
+
+## Quickstart
+
+This tutorial shows how to get started with Apache Iceberg to Apache Ozone using the S3 Gateway, with Docker Compose.
+
+### Quickstart environment
+
+- Unsecure Ozone and Iceberg clusters.
+- Ozone S3G enables virtual-host style addressing with a subdomain `s3.ozone`.
+ - The subdomain and the subdomain with the bucket name `warehouse.s3.ozone` are mapped to the S3 Gateway.
+- Iceberg accesses Ozone via S3 Gateway.
+
+### Step 1 — Create `docker-compose.yaml` for Ozone services
+
+Create a `docker-compose.yaml` file with the following content to
+
+- Spin up a single Datanode Ozone cluster
+- Start the S3 Gateway with the required configurations for Iceberg
+ - Wait for OM to be ready before starting
+ - Create the bucket `warehouse` on startup
+ - Mark the S3 Gateway as healthy only after the bucket is created because this is a pre-requisite for Iceberg containers.
+ - Define and map the bucket subdomain to the S3 Gateway.
+
+```yaml
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+x-image:
+ &image
+ image: ${OZONE_IMAGE:-apache/ozone}:${OZONE_IMAGE_VERSION:-2.1.0}${OZONE_IMAGE_FLAVOR:-}
+
+x-common-config:
+ &common-config
+ OZONE-SITE.XML_hdds.datanode.dir: "/data/hdds"
+ OZONE-SITE.XML_ozone.metadata.dirs: "/data/metadata"
+ OZONE-SITE.XML_ozone.om.address: "om"
+ OZONE-SITE.XML_ozone.om.http-address: "om:9874"
+ OZONE-SITE.XML_ozone.recon.address: "recon:9891"
+ OZONE-SITE.XML_ozone.recon.db.dir: "/data/metadata/recon"
+ OZONE-SITE.XML_ozone.replication: "1"
+ OZONE-SITE.XML_ozone.scm.block.client.address: "scm"
+ OZONE-SITE.XML_ozone.scm.client.address: "scm"
+ OZONE-SITE.XML_ozone.scm.datanode.id.dir: "/data/metadata"
+ OZONE-SITE.XML_ozone.scm.names: "scm"
+ no_proxy: "om,recon,scm,s3g,localhost,127.0.0.1"
+ OZONE-SITE.XML_hdds.scm.safemode.min.datanode: "1"
+ OZONE-SITE.XML_hdds.scm.safemode.healthy.pipeline.pct: "0"
+ OZONE-SITE.XML_ozone.s3g.domain.name: "s3.ozone"
+
+version: "3"
+services:
+ datanode:
+ <<: *image
+ ports:
+ - 9864
+ command: ["ozone","datanode"]
+ environment:
+ <<: *common-config
+ networks:
+ iceberg_net:
+ om:
+ <<: *image
+ ports:
+ - 9874:9874
+ environment:
+ <<: *common-config
+ CORE-SITE.XML_hadoop.proxyuser.hadoop.hosts: "*"
+ CORE-SITE.XML_hadoop.proxyuser.hadoop.groups: "*"
+ ENSURE_OM_INITIALIZED: /data/metadata/om/current/VERSION
+ WAITFOR: scm:9876
+ command: ["ozone","om"]
+ networks:
+ iceberg_net:
+ scm:
+ <<: *image
+ ports:
+ - 9876:9876
+ environment:
+ <<: *common-config
+ ENSURE_SCM_INITIALIZED: /data/metadata/scm/current/VERSION
+ command: ["ozone","scm"]
+ networks:
+ iceberg_net:
+ recon:
+ <<: *image
+ ports:
+ - 9888:9888
+ environment:
+ <<: *common-config
+ command: ["ozone","recon"]
+ networks:
+ iceberg_net:
+ s3g:
+ <<: *image
+ ports:
+ - 9878:9878
+ environment:
+ <<: *common-config
+ WAITFOR: om:9874
+ command:
+ - sh
+ - -c
+ - |
+ set -e
+ ozone s3g &
+ s3g_pid=$$!
+ until ozone sh volume list >/dev/null 2>&1; do echo '...waiting...' && sleep 1; done;
+ ozone sh bucket delete /s3v/warehouse || true
+ ozone sh bucket create /s3v/warehouse
+ wait "$$s3g_pid"
+ healthcheck:
+ test: [ "CMD", "ozone", "sh", "bucket", "info", "/s3v/warehouse" ]
+ interval: 5s
+ timeout: 3s
+ retries: 10
+ start_period: 30s
+ networks:
+ iceberg_net:
+ aliases:
+ - s3.ozone
+ - warehouse.s3.ozone
+```
+
+### Step 2 — Create `iceberg-spark.yml` for Iceberg services
+
+```yaml
+services:
+ spark-iceberg:
+ image: tabulario/spark-iceberg
+ container_name: spark-iceberg
+ build: spark/
+ networks:
+ iceberg_net:
+ depends_on:
+ rest:
+ condition: service_started
+ s3g:
+ condition: service_healthy
+ volumes:
+ - ./warehouse:/home/iceberg/warehouse
+ environment:
+ - AWS_ACCESS_KEY_ID=admin
+ - AWS_SECRET_ACCESS_KEY=password
+ - AWS_REGION=us-east-1
+ ports:
+ - 8888:8888
+ - 8080:8080
+ - 10000:10000
+ - 10001:10001
+ rest:
+ image: apache/iceberg-rest-fixture
+ container_name: iceberg-rest
+ networks:
+ iceberg_net:
+ ports:
+ - 8181:8181
+ environment:
+ - AWS_ACCESS_KEY_ID=admin
+ - AWS_SECRET_ACCESS_KEY=password
+ - AWS_REGION=us-east-1
+ - CATALOG_WAREHOUSE=s3://warehouse/
+ - CATALOG_IO__IMPL=org.apache.iceberg.aws.s3.S3FileIO
+ - CATALOG_S3_ENDPOINT=http://s3.ozone:9878
+
+networks:
+ iceberg_net:
+```
+
+### Step 3 — Start Iceberg and Ozone together
+
+With both `docker-compose.yaml` (for Ozone) and `docker-compose-flink.yml` (for Flink) in the same directory,
+you can start both services together, sharing the same network, using:
+
+```bash
+export COMPOSE_FILE=docker-compose.yaml:iceberg-spark.yml
+docker compose up -d
+```
+
+Verify containers are running:
+
+```bash
+docker ps
+```
+
+### Step 4 — Start a Spark SQL client
+
+```bash
+docker exec -it spark-iceberg spark-sql
+```
+
+You should now be in:
+
+```text
+spark-sql ()>
+```
+
+### Step 5 — Create and Query a table backed by Ozone S3
+
+Create an Iceberg table stored in Ozone S3:
+
+```sql
+ CREATE NAMESPACE IF NOT EXISTS demo.nyc;
+ CREATE TABLE demo.nyc.taxis
+ (
+ vendor_id bigint,
+ trip_id bigint,
+ trip_distance float,
+ fare_amount double,
+ store_and_fwd_flag string
+ )
+ PARTITIONED BY (vendor_id);
+```
+
+Insert data into the table:
+
+```sql
+ INSERT INTO demo.nyc.taxis
+ VALUES (1, 1000371, 1.8, 15.32, 'N'), (2, 1000372, 2.5, 22.15, 'N'), (2, 1000373, 0.9, 9.01, 'N'), (1, 1000374, 8.4, 42.13, 'Y');
+```
+
+Query the table:
+
+```sql
+ SELECT * FROM demo.nyc.taxis;
+```
+
+Verify data files are stored in Ozone S3:
+
+```bash
+docker compose exec -it s3g ozone fs -ls -R ofs://om/s3v/warehouse
+```
+
+Spark UI is available at `http://localhost:8080`. You can monitor the Spark jobs here.
diff --git a/versioned_docs/version-2.2.1/04-user-guide/03-integrations/04-impala.md b/versioned_docs/version-2.2.1/04-user-guide/03-integrations/04-impala.md
new file mode 100644
index 0000000000..f8d6b3b561
--- /dev/null
+++ b/versioned_docs/version-2.2.1/04-user-guide/03-integrations/04-impala.md
@@ -0,0 +1,83 @@
+---
+sidebar_label: Impala
+---
+
+# Impala
+
+Starting with version 4.2.0, Apache Impala provides full support for querying data stored in Apache Ozone. To utilize this functionality, ensure that your Ozone version is 1.4.0 or later.
+
+## Supported Access Protocols
+
+Impala supports the following protocols for accessing Ozone data:
+
+- ofs
+- s3a
+
+Note: The o3fs protocol is **NOT** supported by Impala.
+
+## Supported Replication Types
+
+Impala is compatible with Ozone buckets configured with either:
+
+- **RATIS** (Replication)
+- **Erasure Coding**
+
+## Querying Ozone Data with Impala
+
+Impala provides two approaches to interact with Ozone:
+
+- Managed Tables
+- External Tables
+
+### Managed Tables
+
+If the Hive Warehouse Directory is located in Ozone, you can execute Impala queries without any changes, treating the Ozone file system like HDFS. For example:
+
+```sql
+CREATE DATABASE d1;
+```
+
+```sql
+CREATE TABLE t1 (x INT, s STRING);
+```
+
+The data will be stored under the Hive Warehouse Directory path in Ozone.
+
+#### Specifying a Custom Ozone Path
+
+You can create managed databases, tables, or partitions at a specific Ozone path using the `LOCATION` clause. Example:
+
+```sql
+CREATE DATABASE d1 LOCATION 'ofs://ozone1/vol1/bucket1/d1.db';
+```
+
+```sql
+CREATE TABLE t1 LOCATION 'ofs://ozone1/vol1/bucket1/table1';
+```
+
+### External Tables
+
+You can create an external table in Impala to query Ozone data. For example:
+
+```sql
+CREATE EXTERNAL TABLE external_table (
+ id INT,
+ name STRING
+)
+LOCATION 'ofs://ozone1/vol1/bucket1/table1';
+```
+
+- With external tables, the data is expected to be created and managed by another tool.
+- Impala queries the data as-is.
+- The metadata is stored under the external warehouse directory.
+- Note: Dropping an external table in Impala does not delete the associated data.
+
+## Using the S3A Protocol
+
+In addition to ofs, Impala can access Ozone via the S3 Gateway using the S3A file system. For more details, refer to
+
+- The [S3 Protocol](../client-interfaces/s3/s3-api)
+- The [Hadoop S3A](https://hadoop.apache.org/docs/current/hadoop-aws/tools/hadoop-aws/index.html) documentation.
+
+For additional information, consult the Apache Impala User Documentation
+[Using Impala with Apache Ozone Storage](https://impala.apache.org/docs/build/html/topics/impala_ozone.html).
diff --git a/versioned_docs/version-2.2.1/04-user-guide/03-integrations/05-oozie.md b/versioned_docs/version-2.2.1/04-user-guide/03-integrations/05-oozie.md
new file mode 100644
index 0000000000..b4c4de4d9a
--- /dev/null
+++ b/versioned_docs/version-2.2.1/04-user-guide/03-integrations/05-oozie.md
@@ -0,0 +1,3 @@
+# Oozie
+
+**TODO:** File a subtask under [HDDS-9858](https://issues.apache.org/jira/browse/HDDS-9858) and complete this page or section.
diff --git a/versioned_docs/version-2.2.1/04-user-guide/03-integrations/06-spark.md b/versioned_docs/version-2.2.1/04-user-guide/03-integrations/06-spark.md
new file mode 100644
index 0000000000..94e4459da0
--- /dev/null
+++ b/versioned_docs/version-2.2.1/04-user-guide/03-integrations/06-spark.md
@@ -0,0 +1,195 @@
+---
+sidebar_label: Spark
+---
+
+# Using Apache Spark with Ozone
+
+[Apache Spark](https://spark.apache.org/) is a widely used unified analytics engine for large-scale data processing. Ozone can serve as a scalable storage layer for Spark applications, allowing you to read and write data directly from/to Ozone clusters using familiar Spark APIs.
+
+:::note
+This guide covers Apache Spark 3.x. Examples were tested with Spark 3.5.x and Apache Ozone 2.1.0.
+:::
+
+## Overview
+
+Spark interacts with Ozone primarily through the OzoneFileSystem connector, which allows access using the `ofs://` URI scheme.
+Spark can also access Ozone through the S3 Gateway using the `s3a://` protocol, which is useful for porting existing cloud-native Spark applications to Ozone without changing application code.
+
+The older `o3fs://` scheme is supported for legacy compatibility but is not recommended for new deployments.
+
+Key benefits include:
+
+- Storing large datasets generated or consumed by Spark jobs directly in Ozone.
+- Leveraging Ozone's scalability and object storage features for Spark workloads.
+- Using standard Spark DataFrame and `RDD` APIs to interact with Ozone data.
+
+## Prerequisites
+
+1. **Ozone Cluster:** A running Ozone cluster.
+2. **Ozone Client JARs:** The `ozone-filesystem-hadoop3-client-*.jar` must be available on the Spark driver and executor classpath.
+3. **Hadoop 3.4.x runtime (Ozone 2.1.0+):** Ozone 2.1.0 removed bundled copies of several Hadoop classes (`LeaseRecoverable`, `SafeMode`, `SafeModeAction`) and now requires them from the runtime classpath ([HDDS-13574](https://issues.apache.org/jira/browse/HDDS-13574)). Since Spark 3.5.x ships with Hadoop 3.3.4, you must add `hadoop-common-3.4.x.jar` to the Spark classpath alongside the existing Hadoop JARs.
+4. **Configuration:** Spark needs access to Ozone configuration (`core-site.xml` and potentially `ozone-site.xml`) to connect to the Ozone cluster.
+
+## Configuration
+
+### 1. Core Site (`core-site.xml`)
+
+For `core-site.xml` configuration, refer to the [Ozone File System (ofs) Configuration section](../client-interfaces/ofs#configuration).
+
+### 2. Spark Configuration (`spark-defaults.conf` or `--conf`)
+
+While Spark often picks up settings from `core-site.xml` on the classpath, explicitly setting the implementation can sometimes be necessary:
+
+```properties
+spark.hadoop.fs.ofs.impl=org.apache.hadoop.fs.ozone.RootedOzoneFileSystem
+```
+
+### 3. Security (Kerberos)
+
+If your Ozone and Spark clusters are Kerberos-enabled, Spark needs permission to obtain delegation tokens for Ozone.
+
+Configure the following property in `spark-defaults.conf` or via `--conf`, specifying your Ozone filesystem URI:
+
+```properties
+# For YARN deployments in spark3+
+spark.kerberos.access.hadoopFileSystems=ofs://ozone1/
+```
+
+Replace `ozone1` with your OM Service ID. Ensure the user running the Spark job has a valid Kerberos ticket (`kinit`).
+
+## Usage Examples
+
+You can read and write data using `ofs://` URIs like any other Hadoop-compatible filesystem.
+
+**URI Format:** `ofs://<om-service-id>/<volume>/<bucket>/path/to/key`
+
+### Reading Data (Scala)
+
+```scala
+import org.apache.spark.sql.SparkSession
+
+val spark = SparkSession.builder.appName("Ozone Spark Read Example").getOrCreate()
+
+// Read a CSV file from Ozone
+val df = spark.read.format("csv")
+ .option("header", "true")
+ .option("inferSchema", "true")
+ .load("ofs://ozone1/volume1/bucket1/input/data.csv")
+
+df.show()
+```
+
+### Writing Data (Scala)
+
+```scala
+import org.apache.spark.sql.SparkSession
+
+val spark = SparkSession.builder.appName("Ozone Spark Write Example").getOrCreate()
+
+// Assume 'df' is a DataFrame you want to write
+val data = Seq(("Alice", 1), ("Bob", 2), ("Charlie", 3))
+val df = spark.createDataFrame(data).toDF("name", "id")
+
+// Write DataFrame to Ozone as Parquet files
+df.write.mode("overwrite")
+ .parquet("ofs://ozone1/volume1/bucket1/output/users.parquet")
+```
+
+### Reading Data (Python)
+
+```python
+from pyspark.sql import SparkSession
+
+spark = SparkSession.builder.appName("Ozone Spark Read Example").getOrCreate()
+
+# Read a CSV file from Ozone
+df = spark.read.format("csv") \
+ .option("header", "true") \
+ .option("inferSchema", "true") \
+ .load("ofs://ozone1/volume1/bucket1/input/data.csv")
+
+df.show()
+```
+
+### Writing Data (Python)
+
+```python
+from pyspark.sql import SparkSession
+
+spark = SparkSession.builder.appName("Ozone Spark Write Example").getOrCreate()
+
+# Assume 'df' is a DataFrame you want to write
+data = [("Alice", 1), ("Bob", 2), ("Charlie", 3)]
+columns = ["name", "id"]
+df = spark.createDataFrame(data, columns)
+
+# Write DataFrame to Ozone as Parquet files
+df.write.mode("overwrite") \
+ .parquet("ofs://ozone1/volume1/bucket1/output/users.parquet")
+```
+
+## Spark on Kubernetes
+
+The recommended approach for running Spark on Kubernetes with Ozone is to bake the `ozone-filesystem-hadoop3-client-*.jar` JAR, the `hadoop-common-3.4.x.jar` JAR (if using Ozone 2.1.0+), and core-site.xml directly into a custom Spark image.
+
+### Build a Custom Spark Image
+
+Place the Ozone client JAR and Hadoop compatibility JAR in /opt/spark/jars/, which is on the default Spark classpath, and core-site.xml in /opt/spark/conf/:
+
+```dockerfile
+FROM apache/spark:3.5.8-scala2.12-java11-python3-ubuntu
+
+USER root
+
+ADD https://repo1.maven.org/maven2/org/apache/ozone/ozone-filesystem-hadoop3-client/2.1.0/ozone-filesystem-hadoop3-client-2.1.0.jar \
+ /opt/spark/jars/
+
+# Ozone 2.1.0+ requires Hadoop 3.4.x classes (HDDS-13574).
+# Add alongside (not replacing) Spark's bundled hadoop-common-3.3.4.jar.
+ADD https://repo1.maven.org/maven2/org/apache/hadoop/hadoop-common/3.4.2/hadoop-common-3.4.2.jar \
+ /opt/spark/jars/
+
+COPY core-site.xml /opt/spark/conf/core-site.xml
+COPY ozone_write.py /opt/spark/work-dir/ozone_write.py
+
+USER spark
+```
+
+Where core-site.xml contains at minimum:
+
+```xml
+<?xml version="1.0"?>
+<?xml-stylesheet type="text/xsl" href="configuration.xsl"?>
+<configuration>
+ <property>
+ <name>fs.ofs.impl</name>
+ <value>org.apache.hadoop.fs.ozone.RootedOzoneFileSystem</value>
+ </property>
+ <property>
+ <name>ozone.om.address</name>
+ <value>om-host.example.com:9862</value>
+ </property>
+</configuration>
+```
+
+### Submit a Spark Job
+
+```bash
+./bin/spark-submit \
+ --master k8s://https://YOUR_KUBERNETES_API_SERVER:6443 \
+ --deploy-mode cluster \
+ --name spark-ozone-example \
+ --conf spark.executor.instances=2 \
+ --conf spark.kubernetes.container.image=YOUR_REPO/spark-ozone:latest \
+ --conf spark.kubernetes.authenticate.driver.serviceAccountName=spark \
+ --conf spark.kubernetes.namespace=YOUR_NAMESPACE \
+ local:///opt/spark/work-dir/ozone_write.py
+```
+
+Replace `YOUR_KUBERNETES_API_SERVER`, `YOUR_REPO`, and `YOUR_NAMESPACE` with your environment values.
+
+## Using the S3A Protocol
+
+Spark can also access Ozone through the S3 Gateway using the `s3a://` protocol. This is useful for porting existing cloud-native Spark applications to Ozone without changing application code.
+
+For configuration details, refer to the [S3A documentation](../client-interfaces/s3a).
diff --git a/versioned_docs/version-2.2.1/04-user-guide/03-integrations/07-trino.md b/versioned_docs/version-2.2.1/04-user-guide/03-integrations/07-trino.md
new file mode 100644
index 0000000000..1ca7d4671f
--- /dev/null
+++ b/versioned_docs/version-2.2.1/04-user-guide/03-integrations/07-trino.md
@@ -0,0 +1,3 @@
+# Trino
+
+**TODO:** File a subtask under [HDDS-9858](https://issues.apache.org/jira/browse/HDDS-9858) and complete this page or section.
diff --git a/versioned_docs/version-2.2.1/04-user-guide/03-integrations/08-hadoop-distcp.md b/versioned_docs/version-2.2.1/04-user-guide/03-integrations/08-hadoop-distcp.md
new file mode 100644
index 0000000000..09442b5369
--- /dev/null
+++ b/versioned_docs/version-2.2.1/04-user-guide/03-integrations/08-hadoop-distcp.md
@@ -0,0 +1,159 @@
+---
+sidebar_label: DistCp
+---
+
+# Hadoop DistCp
+
+Hadoop DistCp is a command-line, MapReduce-based tool for bulk data copying.
+
+The `hadoop distcp` command can be used to copy data to and from Ozone and any Hadoop-compatible file systems, such as HDFS or S3A.
+
+## Basic Usage
+
+To copy files from a source Ozone cluster directory to a destination Ozone cluster directory, use the following command:
+
+```bash
+hadoop distcp ofs://ozone1/vol1/bucket/dir1 ofs://ozone2/vol2/bucket2/dir2
+```
+
+You must define the service IDs for both `ozone1` and `ozone2` clusters in the `ozone-site.xml` configuration file. For example:
+
+```xml
+<property>
+ <name>ozone.om.service.ids</name>
+ <value>ozone1,ozone2</value>
+</property>
+```
+
+Next, define their logical mappings. For more details, refer to the OM High Availability documentation.
+
+## Copy from HDFS to Ozone
+
+DistCp performs a file checksum check to ensure file integrity. However, since the default checksum type of HDFS (`CRC32C`) differs from that of Ozone (`CRC32`), the file checksum check will cause the DistCp job to fail.
+
+To prevent job failures, specify checksum options in the DistCp command to force Ozone to use the same checksum type as HDFS.
+
+**Example:**
+
+```bash
+hadoop distcp \
+ -Ddfs.checksum.combine.mode=COMPOSITE_CRC \
+ -Dozone.client.checksum.type=CRC32C \
+ hdfs://ns1/tmp ofs://ozone1/vol1/bucket1/dst
+```
+
+> **Note:**
+> The parameter `-Ddfs.checksum.combine.mode=COMPOSITE_CRC` is not required if the HDFS cluster is running Hadoop 3.1.1 or later.
+
+Alternatively, you can skip the file checksum check entirely:
+
+```bash
+hadoop distcp \
+ -skipcrccheck \
+ hdfs://ns1/tmp ofs://ozone1/vol1/bucket1/dst
+```
+
+## Copy from Ozone to HDFS
+
+When copying files from Ozone to HDFS, similar issues can occur due to differences in checksum types. In this case, you must configure the checksum type for HDFS, as it is the destination system.
+
+**Example:**
+
+```bash
+hadoop distcp \
+ -Ddfs.checksum.combine.mode=COMPOSITE_CRC \
+ -Ddfs.checksum.type=CRC32 \
+ ofs://ozone1/vol1/bucket1/src hdfs://ns1/tmp/dst
+```
+
+By specifying the appropriate checksum configuration or skipping the validation, you can ensure that DistCp jobs complete successfully when transferring data between HDFS and Ozone.
+
+## Encrypted Data
+
+When data resides in an HDFS encryption zone or Ozone encrypted buckets, the file checksum will not match. This is because the underlying block data differs due to the use of a new EDEK (Encryption Data Encryption Key) at the destination. In such cases, specify the `-skipcrccheck` parameter to avoid job failures.
+
+> **Note:**
+> DistCp is supported between encrypted Ozone clusters starting with Ozone 2.0.
+
+For more information about using Hadoop DistCp, consult the [Hadoop DistCp Guide](https://hadoop.apache.org/docs/current/hadoop-distcp/DistCp.html).
+
+## Troubleshooting Common Issues
+
+### Delegation Token Issues
+
+If a DistCp command fails and the error output contains “OzoneToken”, indicating an issue with retrieving a delegation token from the destination (or source) Ozone cluster, ensure that Ozone’s security is explicitly enabled in the client’s configuration.
+
+Add the following property to `ozone-site.xml` on the node where you run the DistCp command:
+
+```xml
+<property>
+ <name>ozone.security.enabled</name>
+ <value>true</value>
+</property>
+```
+
+This helps the client correctly engage in secure communication protocols with Ozone.
+
+### Cross-Realm Kerberos (Ozone 1.x)
+
+**Affected Versions:** Ozone 1.x
+
+When issuing DistCp commands (or other HDFS-compatible commands like `hdfs dfs -ls`) against an Ozone cluster in a different Kerberos realm than the client or source/destination cluster, Ozone 1.x versions may produce an error similar to:
+
+```text
+24/02/07 18:47:36 INFO retry.RetryInvocationHandler: com.google.protobuf.ServiceException: java.io.IOException: DestHost:destPort host1.dst.example.com:9862, LocalHost:localPort host1.src.example.com/10.140.99.144:0. Failed on local exception: java.io.IOException: Couldn't set up I/O streams: java.lang.IllegalArgumentException: Server has invalid Kerberos principal: om/host1.dst.example.com@DST.LOCAL, expecting: OM/host1.dst.example.com@REALM, while invoking $Proxy10.submitRequest over n [...]
+```
+
+**Cause:**
+This typically occurs because the Ozone Manager’s Kerberos principal (`ozone.om.kerberos.principal`) is not defined or interpreted in a way that accommodates cross-realm interactions. The client expects a principal from its own realm or a specifically trusted one, and a mismatch occurs. This issue is addressed in Ozone 2.0.
+
+**Workaround (for Ozone 1.x):**
+To resolve this in Ozone 1.x, add the following property to the `ozone-site.xml` on the client machine running DistCp (and potentially on the Ozone Managers if they also need to inter-communicate across realms):
+
+```xml
+<property>
+ <name>ozone.om.kerberos.principal.pattern</name>
+ <value>*</value>
+</property>
+```
+
+This configuration relaxes the principal matching, allowing the client to accept Ozone Manager principals from different realms.
+
+**Fix:**
+This bug is tracked by **HDDS-10328** and is fixed in Ozone 2.0 and later versions. Upgrading to Ozone 2.0+ is the recommended long-term solution.
+
+### Token Renewal Failures in Bidirectional Cross-Realm Trust Environments
+
+In environments with bidirectional cross-realm Kerberos trust, DistCp jobs (which run as MapReduce jobs) may fail during execution due to errors renewing delegation tokens. An example error is:
+
+```text
+24/02/08 00:35:00 ERROR tools.DistCp: Exception encountered
+java.io.IOException: org.apache.hadoop.yarn.exceptions.YarnException: Failed to submit application_1707350431298_0001 to YARN: Failed to renew token: Kind: HDFS_DELEGATION_TOKEN, Service: 10.140.99.144:8020, Ident: (token for systest: HDFS_DELEGATION_TOKEN owner=user1@SRC.EXAMPLE.COM, renewer=yarn, realUser=, issueDate=1707352474394, maxDate=1707957274394, sequenceNumber=44, masterKeyId=14)
+```
+
+This can happen when the MapReduce job attempts to renew a delegation token for a remote HDFS or Ozone filesystem, and the renewal fails due to cross-realm complexities. The `Service` field in the error (e.g., `10.140.99.144:8020`) usually indicates the filesystem whose token renewal failed.
+
+**Solution:**
+You can prevent the DistCp MapReduce job from attempting to renew delegation tokens for specific HDFS-compatible filesystems by using the `-Dmapreduce.job.hdfs-servers.token-renewal.exclude` parameter. The value should be the authority (hostname or service ID) of the cluster whose tokens are causing renewal issues.
+
+**Parameter:**
+
+```bash
+-Dmapreduce.job.hdfs-servers.token-renewal.exclude=<authority_of_filesystem_to_exclude>
+```
+
+For an HDFS cluster, `<authority_of_filesystem_to_exclude>` would be its NameNode address (e.g., `namenode.example.com:8020` or just `namenode.example.com` if the port is standard). For an Ozone cluster, it would be its service ID (e.g., `ozoneprod`).
+
+**Example:**
+If you are running the DistCp command on a YARN cluster associated with the destination Ozone cluster (`ofs://ozone1707264383/...`) and copying data from a source HDFS cluster (`hdfs://host1.src.example.com:8020/...`), and the token renewal for the source HDFS cluster is failing:
+
+```bash
+hadoop distcp \
+ -Dmapreduce.job.hdfs-servers.token-renewal.exclude=host1.src.example.com \
+ -Ddfs.checksum.combine.mode=COMPOSITE_CRC \
+ -Dozone.client.checksum.type=CRC32C \
+ hdfs://host1.src.example.com:8020/tmp/ \
+ ofs://ozone1707264383/tmp/dest
+```
+
+In this example, `host1.src.example.com` is the authority of the source HDFS cluster, and its tokens will not be renewed by the DistCp MapReduce job. Adjust the value based on which cluster’s (source or destination, HDFS or Ozone) token renewals are problematic.
diff --git a/versioned_docs/version-2.2.1/04-user-guide/03-integrations/09-flink.md b/versioned_docs/version-2.2.1/04-user-guide/03-integrations/09-flink.md
new file mode 100644
index 0000000000..76efc7fbce
--- /dev/null
+++ b/versioned_docs/version-2.2.1/04-user-guide/03-integrations/09-flink.md
@@ -0,0 +1,178 @@
+---
+sidebar_label: Flink
+---
+
+# Apache Flink
+
+[Apache Flink](https://flink.apache.org/) is a powerful, open-source distributed processing framework designed for stateful computations over both bounded and unbounded data streams at any scale. It enables high-throughput, low-latency, and fault-tolerant processing while offering elastic scaling capabilities to handle millions of events per second across thousands of cores.
+
+Apache Flink can use Apache Ozone for reading and writing data, and for storing essential operational components like application state checkpoints and savepoints.
+
+## Quickstart
+
+This tutorial shows how to get started with connecting Apache Flink to Apache Ozone using the S3 Gateway, with Docker Compose.
+
+### Quickstart environment
+
+- Unsecure Ozone and Flink clusters.
+- Ozone S3G enables path style access. To enable virtual-host style addressing see [here](../client-interfaces/s3/s3-api#url-schema).
+- Flink accesses Ozone via S3 Gateway.
+
+### Step 1 — Download Ozone's `docker-compose.yaml`
+
+First, obtain Ozone's sample Docker Compose configuration and save it as `docker-compose.yaml`:
+
+```bash
+curl -O https://raw.githubusercontent.com/apache/ozone-docker/refs/heads/latest/docker-compose.yaml
+```
+
+Edit the `docker-compose.yaml`:
+
+Append the last 2 SCM safemode configurations to the `x-common-config:` section to enable starting with a single Datanode.
+
+```bash
+x-common-config:
+ &common-config
+ ...
+ no_proxy: "om,recon,scm,s3g,localhost,127.0.0.1"
+ OZONE-SITE.XML_hdds.scm.safemode.min.datanode: "1"
+ OZONE-SITE.XML_hdds.scm.safemode.healthy.pipeline.pct: "0"
+```
+
+Refer to the [Docker quick start page](../../quick-start/installation/docker) for details.
+
+### Step 2 — Create `docker-compose-flink.yml` for Flink
+
+```yaml
+services:
+ jobmanager:
+ image: flink:scala_2.12-java17
+ command: >
+ bash -c "mkdir -p /opt/flink/plugins/s3-fs-hadoop &&
+ cp /opt/flink/opt/flink-s3-fs-hadoop-*.jar /opt/flink/plugins/s3-fs-hadoop/ &&
+ /docker-entrypoint.sh jobmanager"
+ ports:
+ - "8081:8081"
+ environment:
+ AWS_ACCESS_KEY_ID: ozone
+ AWS_SECRET_ACCESS_KEY: ozone
+ FLINK_PROPERTIES: |
+ jobmanager.rpc.address: jobmanager
+ fs.s3a.endpoint: http://s3g:9878
+ fs.s3a.path.style.access: true
+ fs.s3a.connection.ssl.enabled: false
+ fs.s3a.access.key: ozone
+ fs.s3a.secret.key: ozone
+
+ taskmanager:
+ image: flink:scala_2.12-java17
+ command: >
+ bash -c "mkdir -p /opt/flink/plugins/s3-fs-hadoop &&
+ cp /opt/flink/opt/flink-s3-fs-hadoop-*.jar /opt/flink/plugins/s3-fs-hadoop/ &&
+ /docker-entrypoint.sh taskmanager"
+ depends_on:
+ - jobmanager
+ environment:
+ AWS_ACCESS_KEY_ID: ozone
+ AWS_SECRET_ACCESS_KEY: ozone
+ FLINK_PROPERTIES: |
+ jobmanager.rpc.address: jobmanager
+ taskmanager.numberOfTaskSlots: 4
+ fs.s3a.endpoint: http://s3g:9878
+ fs.s3a.path.style.access: true
+ fs.s3a.connection.ssl.enabled: false
+ fs.s3a.access.key: ozone
+ fs.s3a.secret.key: ozone
+```
+
+### Step 3 — Start Flink and Ozone together
+
+With both `docker-compose.yaml` (for Ozone) and `docker-compose-flink.yml` (for Flink) in the same directory,
+you can start both services together, sharing the same network, using:
+
+```bash
+export COMPOSE_FILE=docker-compose.yaml:docker-compose-flink.yml
+docker compose up -d
+```
+
+Verify containers are running:
+
+```bash
+docker ps
+```
+
+### Step 4 — Create an Ozone bucket
+
+You need to connect to Ozone (for example, `s3g`) to create a OBS bucket:
+
+```bash
+docker compose exec -it s3g ozone sh bucket create s3v/bucket1 -l obs
+```
+
+### Step 5 — Start Flink SQL client
+
+```bash
+docker compose exec -it jobmanager ./bin/sql-client.sh
+```
+
+You should now be in:
+
+```text
+Flink SQL>
+```
+
+### Step 6 — Create and Query a table backed by Ozone S3
+
+Important: Must use BATCH mode otherwise multi-part upload fails.
+
+```sql
+SET 'execution.runtime-mode' = 'BATCH';
+
+CREATE TABLE ozone_sink (
+ id STRING,
+ ts TIMESTAMP(3)
+) WITH (
+ 'connector' = 'filesystem',
+ 'path' = 's3a://bucket1/ozone_sink/',
+ 'format' = 'csv'
+);
+```
+
+Insert data:
+
+```sql
+INSERT INTO ozone_sink VALUES ('hello', CURRENT_TIMESTAMP);
+```
+
+Query it:
+
+```sql
+SELECT * FROM ozone_sink;
+```
+
+If this works, Flink is successfully reading/writing Ozone via S3.
+
+### Step 7 — Check Flink job status in the Web UI
+
+Open your browser:
+
+```text
+http://localhost:8081/
+```
+
+Here you can:
+
+- See running and completed jobs
+- Inspect TaskManagers
+- Debug failures visually
+
+This is the first place to look if something goes wrong.
+
+## Key takeaways (important)
+
+- Flink Docker images do not ship with S3 enabled
+- The S3 plugin must exist in both JM and TM
+- Flink and Ozone should be started using a combined Docker Compose file (`COMPOSE_FILE`) to ensure they share the same network.
+- Always use `s3a://` with `flink-s3-fs-hadoop`
+- Check `http://localhost:8081/` to confirm jobs are running
+- **Batch mode is required** for Flink SQL to avoid multipart upload failures to Ozone. Use `SET 'execution.runtime-mode' = 'BATCH';`
diff --git a/versioned_docs/version-2.2.1/04-user-guide/03-integrations/09-hbase.md b/versioned_docs/version-2.2.1/04-user-guide/03-integrations/09-hbase.md
new file mode 100644
index 0000000000..2087d0d57c
--- /dev/null
+++ b/versioned_docs/version-2.2.1/04-user-guide/03-integrations/09-hbase.md
@@ -0,0 +1,60 @@
+---
+sidebar_label: HBase
+---
+
+# HBase
+
+Apache Ozone supports integration with Apache HBase, allowing you to use Ozone as the underlying storage layer for HBase tables. This integration leverages the `ofs://` scheme to provide a scalable and robust filesystem for HBase Region Servers.
+
+## Prerequisites
+
+- An active Apache Ozone cluster.
+- Ozone must be configured to use **Ratis replication**. HBase does not currently support Erasure Coded (EC) buckets.
+
+## Configuration Steps
+
+### 1. Ozone Setup
+
+Before configuring HBase, you must prepare the Ozone filesystem:
+
+- **Create Volume and Bucket:** Create a dedicated volume and bucket for HBase. Ensure the bucket is **File System Optimized (FSO)**.
+- **Permissions:** If using Apache Ranger, grant the `hbase` user `READ/WRITE` permissions for the specific Ozone volume and bucket.
+
+### 2. Ozone Service Configurations
+
+Update your `ozone-site.xml` (or via your cluster management tool) with the following properties to enable HBase compatibility:
+
+| Property | Value | Description |
+| :--- | :--- | :--- |
+| `ozone.fs.hsync.enabled` | `true` | Required for HBase WAL (Write Ahead Log) durability. |
+| `ozone.hbase.enhancements.allowed` | `true` | Enables Ozone-side optimizations for HBase. |
+| `ozone.client.hbase.enhancements.allowed` | `true` | Enables client-side optimizations. |
+| `ozone.client.stream.putblock.piggybacking` | `true` | Improves performance for small writes. |
+| `ozone.client.incremental.chunk.list` | `true` | Optimizes metadata handling for HBase. |
+
+### 3. HBase Service Configurations
+
+Configure HBase to point to the Ozone filesystem. Update `hbase-site.xml` with the following:
+
+- **Root Directory:** Set `hbase.rootdir` to your Ozone path using the `ofs://` scheme.
+
+ ```xml
+ <property>
+ <name>hbase.rootdir</name>
+ <value>ofs://[service-id]/[volume]/[bucket]/hbase</value>
+ </property>
+ ```
+
+- **Scheme Support:** Note that only `ofs://` is supported. The older `o3fs://` scheme is not supported for HBase integration.
+
+Now you are ready to start your HBase cluster with Ozone.
+
+## Support Matrix and Restrictions
+
+### Unsupported Features
+
+The following features are currently **not supported** when running HBase on Ozone:
+
+- **HBase Features:** Medium Object Storage (MOB), Favored Nodes, Hedged Read, Storage Policy, and Short Circuit Read.
+- **Ozone Features:** Snapshots, Erasure Coded (EC) buckets, and Object Store (OBS) buckets.
+- **Phoenix:** Phoenix User Defined Functions (UDF) are not supported on Ozone.
diff --git a/versioned_docs/version-2.2.1/04-user-guide/03-integrations/README.mdx b/versioned_docs/version-2.2.1/04-user-guide/03-integrations/README.mdx
new file mode 100644
index 0000000000..01c133a508
--- /dev/null
+++ b/versioned_docs/version-2.2.1/04-user-guide/03-integrations/README.mdx
@@ -0,0 +1,11 @@
+---
+sidebar_label: Integrations
+---
+
+# Integrating Ozone Storage With Other Systems
+
+import DocCardList from '@theme/DocCardList';
+
+This section provides instructions to configure other systems to use Ozone for storage.
+
+<DocCardList/>
diff --git a/versioned_docs/version-2.2.1/04-user-guide/README.mdx b/versioned_docs/version-2.2.1/04-user-guide/README.mdx
new file mode 100644
index 0000000000..0033a11331
--- /dev/null
+++ b/versioned_docs/version-2.2.1/04-user-guide/README.mdx
@@ -0,0 +1,7 @@
+# User Guide
+
+import DocCardList from '@theme/DocCardList';
+
+This section provides instructions for end users to read and write data to an existing Ozone system.
+
+<DocCardList/>
diff --git a/versioned_docs/version-2.2.1/05-administrator-guide/01-installation/01-deployment-architecture.md b/versioned_docs/version-2.2.1/05-administrator-guide/01-installation/01-deployment-architecture.md
new file mode 100644
index 0000000000..6c1cce63d0
--- /dev/null
+++ b/versioned_docs/version-2.2.1/05-administrator-guide/01-installation/01-deployment-architecture.md
@@ -0,0 +1,3 @@
+# Deployment Architecture
+
+**TODO:** File a subtask under [HDDS-9859](https://issues.apache.org/jira/browse/HDDS-9859) and complete this page or section.
diff --git a/versioned_docs/version-2.2.1/05-administrator-guide/01-installation/02-reference-architecture.md b/versioned_docs/version-2.2.1/05-administrator-guide/01-installation/02-reference-architecture.md
new file mode 100644
index 0000000000..14f829ec0e
--- /dev/null
+++ b/versioned_docs/version-2.2.1/05-administrator-guide/01-installation/02-reference-architecture.md
@@ -0,0 +1,15 @@
+---
+sidebar_label: Reference Architecture
+---
+
+# Reference Architecture
+
+Several hardware and software vendors publish reference architectures for Apache Ozone. The Apache Ozone project does not endorse any of the vendors but we'd like to provide the links to these reference architectures to help users build a cluster.
+
+## Vendor Reference Architectures
+
+- **Cisco:** [Cisco](https://www.cisco.com/c/en/us/td/docs/unified_computing/ucs/UCS_CVDs/cdip_ucs_cloudera_ozone.html)
+- **Cloudera:** [Cloudera](https://docs.cloudera.com/cdp-private-cloud-base/7.3.1/cdp-private-cloud-base-installation/topics/cdpdc-ozone.html)
+- **Hitachi:** [Hitachi](https://www.hitachivantara.com/content/dam/hvac/pdfs/architecture-guide/analytics-infrastructure-for-apache-ozone.pdf)
+- **Dell:** [Dell](https://infohub.delltechnologies.com/en-uk/l/design-guide-data-management-with-cloudera-data-platform-on-intel-powered-dell-emc-infrastructure/architecture-concepts-20/)
+- **Lenovo:** [Lenovo](https://lenovopress.lenovo.com/lp1458-big-data-reference-design-for-cloudera-data-platform)
diff --git a/versioned_docs/version-2.2.1/05-administrator-guide/01-installation/03-hardware-and-sizing.md b/versioned_docs/version-2.2.1/05-administrator-guide/01-installation/03-hardware-and-sizing.md
new file mode 100644
index 0000000000..b25c7729ba
--- /dev/null
+++ b/versioned_docs/version-2.2.1/05-administrator-guide/01-installation/03-hardware-and-sizing.md
@@ -0,0 +1,150 @@
+# Hardware and Sizing
+
+This guide outlines the hardware requirements and sizing recommendations for Apache Ozone clusters of different scales. Proper hardware selection is critical for achieving optimal performance, reliability, and cost-effectiveness.
+
+Note: Apache Ozone can run on a single node inside Kubernetes and serve all functionality for development, testing, and small workloads. The hardware specifications in this guide reflect common configurations for production deployments. Your choice of hardware should depend on your desired scale, performance requirements, and workload characteristics.
+
+## Principles
+
+When planning an Ozone deployment, consider these key principles:
+
+- **Separate Metadata and Data Hardware**: Metadata services (OM, SCM) have different requirements than data services (Datanodes).
+- **SSD/NVMe for Metadata**: All metadata services require fast storage for RocksDB.
+- **Scale Metadata Vertically**: Add more resources to existing metadata nodes rather than more nodes.
+- **Scale Datanodes Horizontally**: Add more Datanode machines as capacity and throughput needs grow.
+- **Plan for Failure**: Size the cluster to handle expected failures of drives and nodes. Do not exceed 400 TB raw Datanode capacity.
+
+## Guidelines
+
+### Hardware Configuration Best Practices
+
+#### Drive Configuration
+
+- Use enterprise-class drives in production environments
+- Use SAS HDD drives for data nodes
+- Use SSD/NVMe optimized for mixed workloads as system drives
+- Use NVMe or SAS SSD optimized for heavy write workloads for metadata and Ratis logs
+- Use hardware RAID1 for system drives and metadata storage
+- Leave at least 20% free space on metadata drives for RocksDB compaction
+- Factor in drive failure rates (typically 1–5% annually) for capacity planning and use SMART to monitor drive health.
+
+#### Memory Configuration
+
+- Reserve at least 4-8GB for OS and other services on each node
+- Budget memory to avoid swap usage but do not disable swap entirely; this prevents the OOM killer from terminating critical processes unpredictably.
+- For co-located services (OM+SCM), size the heap to accommodate both services plus overhead
+- Use G1GC collector for production JVMs
+
+#### Expansion Planning
+
+- Design racks with expansion capacity in mind
+- Datanodes can be added in increments of 1+ nodes
+- Plan for hardware replacement cycles (typically 3-5 years)
+
+#### Network Planning
+
+Proper network planning is essential for Ozone performance:
+
+##### Bandwidth Sizing
+
+Ensure network bandwidth matches aggregate disk throughput
+
+- For HDDs: ~150-200MB/s per drive
+- For SSDs: ~500MB/s+ per drive
+- For NVMe: ~1-3GB/s+ per drive
+
+##### Network Oversubscription
+
+- Limit oversubscription to 2:1 ratio maximum
+- Ideal: 1:1 subscription for metadata and heavy workloads
+
+### Minimum Production Deployment
+
+A minimal production-ready deployment should include:
+
+- 3 nodes for OM HA (can be co-located with SCM)
+- 3 nodes for SCM HA (can be co-located with OM)
+- At least a single Recon instance
+- Minimum 10 Datanodes for RS-6-3 encoding, 15 Datanodes for RS-10-4
+
+#### Total Hardware (Consolidated)
+
+- 3 metadata nodes (running both OM and SCM)
+- 10+ Datanodes
+
+## Reference Configurations
+
+### Small Enterprise Deployment (3 - 20PB)
+
+Consolidated architecture with 3 metadata nodes and 10+ Datanodes.
+
+#### Metadata Nodes (3x)
+
+- 2x 16-core CPUs (32 cores total)
+- 128GB RAM
+- 31GB JVM heap per service (OM and SCM)
+- 2x 480GB SSD mixed workload drives in RAID1 for OS
+- 2x 2TB write optimized NVMe in RAID1
+- 2x 25GbE network ports
+
+#### Datanodes (10+)
+
+- 2x 16-core CPUs (32 cores total)
+- 128GB RAM
+- 31GB JVM heap
+- 2x 480GB SSD mixed workload drives in RAID1 for OS
+- 6+ SAS HDDs
+- 2x 480GB write optimized NVMe in RAID1 (metadata)
+- 2x 25GbE network ports
+
+### Large Enterprise Deployment (20PB+)
+
+Dedicated service architecture.
+
+#### OM Nodes (3x)
+
+- 2x 20-core CPUs (40 cores total)
+- 256GB RAM
+- 48GB JVM heap
+- 2x 480GB SSD mixed workload drives in RAID1 for OS
+- 2x 4TB write optimized NVMe in RAID1
+- 2x 100GbE network ports
+
+#### SCM Nodes (3x)
+
+- 2x 20-core CPUs (40 cores total)
+- 256GB RAM
+- 48GB JVM heap
+- 2x 480GB SSD mixed workload drives in RAID1 for OS
+- 2x 4TB write optimized NVMe in RAID1
+- 2x 100GbE network ports
+
+#### Datanodes (80+)
+
+- 2x 16-core CPUs (32 cores total)
+- 128GB RAM
+- 48GB JVM heap
+- 2x 480GB SSD mixed workload drives in RAID1 for OS
+- 6+ SAS HDDs
+- 2x 480GB write optimized NVMe in RAID1 (metadata)
+- 2x 100GbE network ports
+
+#### Recon Node (1x)
+
+- 2x 12-core CPUs (24 cores total)
+- 128GB RAM
+- 48GB JVM heap
+- 2x 2TB NVMe in RAID1
+- 2x 100GbE network
+
+#### S3 Gateway Nodes (3+)
+
+- 2x 16-core CPUs (32 cores total)
+- 128GB RAM
+- 48 GB JVM heap
+- 2x 480GB SSD mixed workload drives in RAID1 for OS
+- 2x 100GbE network ports
+
+#### Load balancer for S3 Gateways
+
+Consider co-locating S3 Gateways with applications that use them or use dedicated hardware or software L7 load balancer for balancing traffic between S3 Gateways.
diff --git a/versioned_docs/version-2.2.1/05-administrator-guide/01-installation/04-installing-binaries.md b/versioned_docs/version-2.2.1/05-administrator-guide/01-installation/04-installing-binaries.md
new file mode 100644
index 0000000000..88bd177913
--- /dev/null
+++ b/versioned_docs/version-2.2.1/05-administrator-guide/01-installation/04-installing-binaries.md
@@ -0,0 +1,47 @@
+# Installing the Ozone Binaries
+
+This section outlines the steps to obtain and install the Apache Ozone binaries on your hosts.
+
+## Identify Hosts
+
+First, identify the hosts where Ozone will be installed. The installation steps described below should be performed on each designated host.
+
+## Obtain Binaries
+
+To obtain the Ozone binaries, you have two primary options:
+
+1. **Official Apache Ozone Releases**:
+ For official releases, navigate to the [Downloads page](/download) to get the released binary tarball. Follow the instructions to verify the integrity of the tarball.
+
+2. **Build from Source**:
+ Alternatively, you can build Ozone from its source code. Follow the detailed instructions in the [Developer Guide: Building Ozone With Maven](../../developer-guide/build/maven).
+
+### Untar the Tarball (for released binaries)
+
+If you downloaded a binary tarball, untar it to your desired installation path:
+
+```bash
+tar zxvf ozone-<version>.tar.gz -C /path/to/ozone
+```
+
+### RPM or DEB Packages
+
+To use an RPM or DEB package, execute the appropriate command:
+
+For RPM:
+
+```bash
+dnf install ozone-<version>-1.noarch.rpm
+```
+
+or
+
+```bash
+yum install ozone-<version>-1.noarch.rpm
+```
+
+For DEB:
+
+```bash
+apt install ozone_<version>-<linux_distro>_.deb
+```
diff --git a/versioned_docs/version-2.2.1/05-administrator-guide/01-installation/05-initializing-cluster.md b/versioned_docs/version-2.2.1/05-administrator-guide/01-installation/05-initializing-cluster.md
new file mode 100644
index 0000000000..f734694b14
--- /dev/null
+++ b/versioned_docs/version-2.2.1/05-administrator-guide/01-installation/05-initializing-cluster.md
@@ -0,0 +1,125 @@
+---
+title: Initializing Cluster
+---
+
+After installing the binaries, the next step is to initialize the cluster. This section provides instructions on how to initialize a new Ozone cluster.
+
+## Initialize configurations
+
+Ozone relies on a configuration file called `ozone-site.xml`. To generate a template that you can replace with proper values, please run the following command. This will generate a template called `ozone-site.xml` at the specified path (directory).
+
+```bash
+export OZONE_HOME=/path/to/ozone
+export PATH=$PATH:$OZONE_HOME/bin
+export OZONE_CONF_DIR=$OZONE_HOME/etc/ozone
+
+ozone genconf $OZONE_CONF_DIR
+```
+
+Let us look at the settings inside the generated file (`ozone-site.xml`) and how they control Ozone. Once the right values are defined, this file is ready for use.
+
+- **ozone.metadata.dirs** Allows Administrators to specify where the metadata must reside. Usually you pick your fastest disk (SSD if you have them on your nodes). OzoneManager, SCM and Datanode will write the metadata to this path. This is a required setting, if this is missing Ozone will fail to come up.
+
+ Here is an example,
+
+ ```xml
+ <property>
+ <name>ozone.metadata.dirs</name>
+ <value>/data/disk1/meta</value>
+ </property>
+ ```
+
+- **`ozone.scm.names`** Storage Container Manager (SCM) is a distributed block service which is used by Ozone. This property allows Datanodes to discover SCM's address. Datanodes send heartbeat to SCM. Until HA feature is complete, we configure `ozone.scm.names` to be a single machine.
+
+ Here is an example,
+
+ ```xml
+ <property>
+ <name>ozone.scm.names</name>
+ <value>scm.ozone.apache.org</value>
+ </property>
+ ```
+
+- **`ozone.scm.datanode.id.dir`** Datanodes generate a Unique ID called Datanode ID. This identity is written to the file `datanode.id` in a directory specified by this path. *Datanodes will create this path if it doesn't exist already.*
+
+ Here is an example,
+
+ ```xml
+ <property>
+ <name>ozone.scm.datanode.id.dir</name>
+ <value>/data/disk1/meta/node</value>
+ </property>
+ ```
+
+- **`ozone.om.address`** OM server address. This is used by OzoneClient and Ozone File System.
+
+ Here is an example,
+
+ ```xml
+ <property>
+ <name>ozone.om.address</name>
+ <value>ozonemanager.ozone.apache.org</value>
+ </property>
+ ```
+
+## Ozone Settings Summary
+
+| Setting | Value | Comment |
+| ------------------------------ | ---------------------------- | ---------------------------------------------------------------- |
+| `ozone.metadata.dirs` | file path | The metadata will be stored here. |
+| `ozone.scm.names` | SCM server name | Hostname:port or IP:port address of SCM. |
+| `ozone.scm.block.client.address` | SCM server name and port | Used by services like OM |
+| `ozone.scm.client.address` | SCM server name and port | Used by client-side |
+| `ozone.scm.datanode.address` | SCM server name and port | Used by Datanode to talk to SCM |
+| `ozone.om.address` | OM server name | Used by Ozone handler and Ozone file system. |
+| `hdds.datanode.dir` | file path | HDDS Datanodes store data in this directory. |
+
+## Initialize the cluster
+
+:::info
+For simplicity, here we show the steps for non-HA cluster (1 OM, 1 SCM). To configure OM HA or to convert from non-HA to HA, see the [OM HA documentation](../../administrator-guide/configuration/high-availability/om-ha). To configure SCM HA or to convert from non-HA to HA, see the [SCM HA documentation](../../administrator-guide/configuration/high-availability/scm-ha).
+:::
+
+:::tip For Production Deployments
+It is highly recommended to set up an HA-enabled cluster from the beginning for production environments. While it is possible to convert a non-HA cluster to an HA cluster, it is a complex procedure.
+:::
+
+Before we boot up the Ozone cluster, we need to initialize both SCM and Ozone Manager.
+
+```bash
+ozone scm --init
+```
+
+This allows SCM to create the cluster Identity and initialize its state. The `init` command initializes the metadata directory specified in `$ozone.metadata.dirs`. Init command is executed only once, that allows SCM to create all the required on-disk structures to work correctly.
+
+```bash
+ozone --daemon start scm
+```
+
+Once we know SCM is up and running, we can create an Object Store for our use. This is done by running the following command.
+
+```bash
+ozone om --init
+```
+
+Once Ozone Manager is initialized, we are ready to run the name service.
+
+```bash
+ozone --daemon start om
+```
+
+At this point Ozone's name services, the Ozone Manager, and the block service SCM are both running.
+
+:::info
+SCM start will fail if on-disk data structures are missing; If SCM is not running, `om --init` command will fail. So please make sure you have done both `scm --init` and `om --init` commands.
+:::
+
+Now we need to start the Datanodes. Please run the following command on each Datanode.
+
+```bash
+ozone --daemon start datanode
+```
+
+At this point SCM, Ozone Manager and Datanodes are up and running.
+
+***Congratulations!, You have set up a functional Ozone cluster.***
diff --git a/versioned_docs/version-2.2.1/05-administrator-guide/01-installation/README.mdx b/versioned_docs/version-2.2.1/05-administrator-guide/01-installation/README.mdx
new file mode 100644
index 0000000000..14e1b39015
--- /dev/null
+++ b/versioned_docs/version-2.2.1/05-administrator-guide/01-installation/README.mdx
@@ -0,0 +1,11 @@
+---
+sidebar_label: Installation
+---
+
+# Installing Ozone In Production
+
+import DocCardList from '@theme/DocCardList';
+
+This section documents how to install a production Ozone system.
+
+<DocCardList/>
diff --git a/versioned_docs/version-2.2.1/05-administrator-guide/02-configuration/01-basic/01-configuration-files.md b/versioned_docs/version-2.2.1/05-administrator-guide/02-configuration/01-basic/01-configuration-files.md
new file mode 100644
index 0000000000..5f18db0498
--- /dev/null
+++ b/versioned_docs/version-2.2.1/05-administrator-guide/02-configuration/01-basic/01-configuration-files.md
@@ -0,0 +1,45 @@
+# Configuration Files
+
+Apache Ozone services are configured using XML files. These configuration files define various parameters that control the behavior of Ozone Managers (OM), Storage Container Managers (SCM), Datanodes (DN), and other related services like S3 Gateway and HttpFS.
+
+The primary configuration files for an Ozone server are:
+
+- **`ozone-site.xml`**: This file contains Ozone-specific configurations. Most of the parameters you'll set for your Ozone cluster will reside here.
+- **`core-site.xml`**: This file contains core configurations that are common across various services that integrate with or run alongside Ozone. Parameters related to file system client behavior, I/O settings, and some security aspects might be defined here.
+- **`httpfs-site.xml`**: This file is specific to the HttpFS service, which provides a REST HTTP gateway to Ozone. It contains configurations related to the HttpFS server, such as its port, authentication settings, and proxy user definitions.
+
+## Basic Format
+
+All these configuration files follow a standard XML format, consisting of a `<configuration>` root element, inside which each configuration property is defined using `<property>` tags. Each `<property>` tag contains a `<name>` tag for the property key and a `<value>` tag for its value.
+
+Example:
+
+```xml
+<?xml version="1.0"?>
+<?xml-stylesheet type="text/xsl" href="configuration.xsl"?>
+<configuration>
+ <property>
+ <name>ozone.om.address</name>
+ <value>0.0.0.0:9862</value>
+ </property>
+ <property>
+ <name>ozone.scm.client.address</name>
+ <value>0.0.0.0:9850</value>
+ </property>
+</configuration>
+```
+
+## Where Configuration Files Are Read From
+
+Ozone services read their configuration from files typically located in a designated `conf` directory. When running Ozone directly, this usually means the `etc/hadoop` directory within your Ozone installation path. The `OZONE_CONF_DIR` environment variable can be used to specify a custom location for this directory.
+
+The loading order and precedence of configuration files are as follows:
+
+1. **Default Configurations**: Each service has a set of default configurations embedded within its JAR files (e.g., [`ozone-default.xml`](https://github.com/apache/ozone/blob/master/hadoop-hdds/common/src/main/resources/ozone-default.xml)). These provide baseline settings.
+2. **Site-Specific Configurations**: Files like `ozone-site.xml`, `core-site.xml`, and `httpfs-site.xml` located in the `conf` directory override the default settings. These are where administrators customize the cluster's behavior.
+
+For example, if Ozone is installed at `/opt/ozone`, the configuration files would typically be located at `/opt/ozone/etc/hadoop/`.
+
+When deploying with Docker or Kubernetes, the configuration files are usually mounted into the container's designated configuration directory (e.g., `/opt/ozone/etc/hadoop` inside a Docker container).
+
+Specific configuration keys will be documented in later sections.
diff --git a/versioned_docs/version-2.2.1/05-administrator-guide/02-configuration/01-basic/02-environment-variables.md b/versioned_docs/version-2.2.1/05-administrator-guide/02-configuration/01-basic/02-environment-variables.md
new file mode 100644
index 0000000000..a3a3fbf279
--- /dev/null
+++ b/versioned_docs/version-2.2.1/05-administrator-guide/02-configuration/01-basic/02-environment-variables.md
@@ -0,0 +1,85 @@
+---
+sidebar_label: Environment Variables
+---
+
+# Environment Variables
+
+The `ozone-env.sh` script, located at `$OZONE_HOME/etc/hadoop`, defines the environment variables used by Ozone processes.
+
+> Note: The following list is not exhaustive but includes the most commonly used environment variables.
+
+## Common Environment Variables
+
+These environment variables apply to all Ozone processes.
+
+| Variable | Default Value | Description |
+| :----------------- | :--------------------------------- | :---------------------------------------------------------------------------------------------------------------- |
+| `JAVA_HOME` | (none) | The path to the Java installation. Must be set on most platforms, but is auto-detected on macOS. |
+| `OZONE_HOME` | Auto-detected from script location | The path to the Ozone installation directory. |
+| `OZONE_CONF_DIR` | `$OZONE_HOME/etc/hadoop` | The directory containing Ozone configuration files. |
+| `OZONE_LOG_DIR` | `$OZONE_HOME/logs` | The directory where Ozone log files are stored. |
+| `OZONE_PID_DIR` | `/tmp` | The directory where daemon PID files are stored. |
+| `OZONE_OPTS` | `-Djava.net.preferIPv4Stack=true` | Universal Java options applied to all Ozone processes. |
+| `OZONE_HEAPSIZE_MAX`| (JVM default) | The maximum JVM heap size (`-Xmx`). If not set, the JVM auto-scales. |
+| `OZONE_HEAPSIZE_MIN`| (JVM default) | The minimum JVM heap size (`-Xms`). If not set, the JVM auto-scales. |
+
+## Role-Specific Environment Variables
+
+These environment variables apply only to certain Ozone services or roles.
+
+| Variable | Default Value | Description |
+| :----------------- | :--------------------------------- | :---------------------------------------------------------------------------------------------------------------- |
+| `OZONE_SERVER_OPTS`| (none) | Options for all Ozone server daemons (appended to `OZONE_OPTS`). |
+| `OZONE_CLIENT_OPTS`| (empty) | Specifies Java properties for Ozone commands and clients. |
+| `OZONE_OM_OPTS` | (empty) | Specifies Java properties for the Ozone Manager (OM). |
+| `OZONE_SCM_OPTS` | (empty) | Specifies Java properties for the Storage Container Manager (SCM). |
+| `OZONE_DATANODE_OPTS`| (empty) | Specifies Java properties for Datanodes. |
+| `OZONE_S3G_OPTS` | (empty) | Specifies Java properties for the S3 Gateway. |
+| `OZONE_RECON_OPTS` | (empty) | Specifies Java properties for the Recon server. |
+
+:::note HttpFS Gateway Configuration
+The HttpFS Gateway does not use an `OZONE_HTTPFS_OPTS` variable. Its specific JVM properties must be added to the global `OZONE_OPTS` variable.
+:::
+
+## Configuration Methods
+
+There are several ways to set these environment variables, depending on your needs.
+
+### System-Wide Configuration
+
+For multi-user environments, creating a system-wide profile file ensures that variables are set for all users. A common practice is to create a file in `/etc/profile.d/`, which is loaded by most shells on login.
+
+**Example for `/etc/profile.d/ozone.sh`:**
+
+```bash
+export JAVA_HOME="$(/usr/libexec/java_home)"
+export OZONE_HOME=/opt/ozone
+export OZONE_CONF_DIR=/etc/ozone
+```
+
+After creating this file, users must log out and log back in for the changes to take effect.
+
+### User-Specific Configuration
+
+If you only need to set variables for a single user, you can add them to their personal shell profile.
+
+- For Bash users, add to `~/.bashrc` or `~/.bash_profile`.
+- For Zsh users, add to `~/.zshrc`.
+- For other shells, consult their documentation.
+
+**Example for `~/.bashrc`:**
+
+```bash
+export OZONE_HOME=~/ozone
+export OZONE_CONF_DIR=$OZONE_HOME/etc/hadoop
+```
+
+After editing, you must reload the profile (e.g., `source ~/.bashrc`) or open a new shell session.
+
+### Per-Command Configuration
+
+For quick tests or one-off commands, you can set an environment variable for a single command's execution.
+
+```bash
+OZONE_HEAPSIZE_MAX=16G ozone sh volume create /vol1
+```
diff --git a/versioned_docs/version-2.2.1/05-administrator-guide/02-configuration/01-basic/02-network/01-ozone-manager.md b/versioned_docs/version-2.2.1/05-administrator-guide/02-configuration/01-basic/02-network/01-ozone-manager.md
new file mode 100644
index 0000000000..4d7e9b0167
--- /dev/null
+++ b/versioned_docs/version-2.2.1/05-administrator-guide/02-configuration/01-basic/02-network/01-ozone-manager.md
@@ -0,0 +1,7 @@
+---
+sidebar_label: Ozone Manager
+---
+
+# Network Configuration for Ozone Manager
+
+**TODO:** File a subtask under [HDDS-9859](https://issues.apache.org/jira/browse/HDDS-9859) and complete this page or section.
diff --git a/versioned_docs/version-2.2.1/05-administrator-guide/02-configuration/01-basic/02-network/02-storage-container-manager.md b/versioned_docs/version-2.2.1/05-administrator-guide/02-configuration/01-basic/02-network/02-storage-container-manager.md
new file mode 100644
index 0000000000..ed022ef42c
--- /dev/null
+++ b/versioned_docs/version-2.2.1/05-administrator-guide/02-configuration/01-basic/02-network/02-storage-container-manager.md
@@ -0,0 +1,7 @@
+---
+sidebar_label: Storage Container Manager
+---
+
+# Network Configuration for Storage Container Manager
+
+**TODO:** File a subtask under [HDDS-9859](https://issues.apache.org/jira/browse/HDDS-9859) and complete this page or section.
diff --git a/versioned_docs/version-2.2.1/05-administrator-guide/02-configuration/01-basic/02-network/03-datanode.md b/versioned_docs/version-2.2.1/05-administrator-guide/02-configuration/01-basic/02-network/03-datanode.md
new file mode 100644
index 0000000000..1108399134
--- /dev/null
+++ b/versioned_docs/version-2.2.1/05-administrator-guide/02-configuration/01-basic/02-network/03-datanode.md
@@ -0,0 +1,7 @@
+---
+sidebar_label: Datanodes
+---
+
+# Network Configuration for Datanodes
+
+**TODO:** File a subtask under [HDDS-9859](https://issues.apache.org/jira/browse/HDDS-9859) and complete this page or section.
diff --git a/versioned_docs/version-2.2.1/05-administrator-guide/02-configuration/01-basic/02-network/04-recon.md b/versioned_docs/version-2.2.1/05-administrator-guide/02-configuration/01-basic/02-network/04-recon.md
new file mode 100644
index 0000000000..a4db9649d3
--- /dev/null
+++ b/versioned_docs/version-2.2.1/05-administrator-guide/02-configuration/01-basic/02-network/04-recon.md
@@ -0,0 +1,7 @@
+---
+sidebar_label: Recon
+---
+
+# Network Configuration for Recon
+
+**TODO:** File a subtask under [HDDS-9859](https://issues.apache.org/jira/browse/HDDS-9859) and complete this page or section.
diff --git a/versioned_docs/version-2.2.1/05-administrator-guide/02-configuration/01-basic/02-network/05-s3-gateway.md b/versioned_docs/version-2.2.1/05-administrator-guide/02-configuration/01-basic/02-network/05-s3-gateway.md
new file mode 100644
index 0000000000..12cfc6edd6
--- /dev/null
+++ b/versioned_docs/version-2.2.1/05-administrator-guide/02-configuration/01-basic/02-network/05-s3-gateway.md
@@ -0,0 +1,7 @@
+---
+sidebar_label: S3 Gateways
+---
+
+# Network Configuration for S3 Gateways
+
+**TODO:** File a subtask under [HDDS-9859](https://issues.apache.org/jira/browse/HDDS-9859) and complete this page or section.
diff --git a/versioned_docs/version-2.2.1/05-administrator-guide/02-configuration/01-basic/02-network/07-default-ports.md b/versioned_docs/version-2.2.1/05-administrator-guide/02-configuration/01-basic/02-network/07-default-ports.md
new file mode 100644
index 0000000000..7f7dbc74a4
--- /dev/null
+++ b/versioned_docs/version-2.2.1/05-administrator-guide/02-configuration/01-basic/02-network/07-default-ports.md
@@ -0,0 +1,88 @@
+---
+sidebar_label: Default Ports
+---
+
+# Default Ports Used by Ozone
+
+This document provides a comprehensive overview of the network ports utilized by Apache Ozone.
+Due to its distributed nature and the requirement for high performance in handling data-intensive tasks, understanding and correctly configuring these network ports is essential for the successful deployment, operation, and maintenance of Apache Ozone clusters.
+
+## **Ozone Manager (OM)**
+
+| Default Port Number | Configuration Key | Endpoint Protocol | Purpose |
+| :--- | :--- | :--- | :--- |
+| 9862 | `ozone.om.address.<service_id>.<node_id>` | Hadoop RPC | Primary RPC endpoint for Ozone clients |
+| 9874 | `ozone.om.http-address.<service_id>.<node_id>` | HTTP | Web UI for monitoring OM status and metadata |
+| 9875 | `ozone.om.https-address.<service_id>.<node_id>` | HTTPS | Secure Web UI for monitoring OM status and metadata |
+| 9872 | `ozone.om.ratis.port.<service_id>.<node_id>` | HTTP/2 | RPC endpoint for OM HA instances to form a RAFT consensus ring |
+| 8981 | `ozone.om.grpc.port` | HTTP/2 | gRPC endpoint for Ozone Manager clients |
+
+:::note
+Except for `ozone.om.grpc.port`, all the above OM properties are suffixed with `service_id.node_id`.
+For example: `ozone.om.address.cluster1.om1`.
+:::
+
+## **Storage Container Manager (SCM)**
+
+| Default Port Number | Configuration Key | Endpoint Protocol | Purpose |
+| :---- | :---- | :---- | :---- |
+| 9860 | `ozone.scm.client.port.<service_id>.<node_id>` | Hadoop RPC | Communication with Ozone clients for namespace and container management. `ozone.scm.client.address` overrides it, if defined (default is empty) |
+| 9863 | `ozone.scm.block.client.port.<service_id>.<node_id>` | Hadoop RPC | Communication with Datanodes for block-level operations |
+| 9861 | `ozone.scm.datanode.port.<service_id>.<node_id>` | Hadoop RPC | Port used by Datanodes to communicate with the SCM. `ozone.scm.datanode.address` overrides it, if defined (default is empty) |
+| 9961 | `ozone.scm.security.service.port.<service_id>.<node_id>` | Hadoop RPC | SCM security server port |
+| 9876 | `ozone.scm.http-address.<service_id>.<node_id>` | HTTP | Web UI for monitoring SCM status |
+| 9877 | `ozone.scm.https-address.<service_id>.<node_id>` | HTTPS | Secure Web UI for monitoring SCM status |
+| 9894 | `ozone.scm.ratis.port.<service_id>.<node_id>` | HTTP/2 | SCM Ratis HA |
+| 9895 | `ozone.scm.grpc.port.<service_id>.<node_id>` | HTTP/2 | SCM gRPC server port |
+
+:::note
+All the above SCM properties are suffixed with `service_id.node_id`.
+For example: `ozone.scm.client.port.scmservice.scm1`.
+:::
+
+## **Recon**
+
+| Default Port Number | Configuration Key | Endpoint Protocol | Purpose |
+| :---- | :---- | :---- | :---- |
+| 9891 | `ozone.recon.address` | Hadoop RPC | RPC address for Recon to collect metadata from other Ozone services |
+| 9888 | `ozone.recon.http-address` | HTTP | Web-based management and monitoring console for the entire Ozone cluster |
+| 9889 | `ozone.recon.https-address` | HTTPS | Web-based management and monitoring console for the entire Ozone cluster |
+
+## **S3 Gateway (S3G)**
+
+| Default Port Number | Configuration Key | Endpoint Protocol | Purpose |
+| :---- | :---- | :---- | :---- |
+| 9878 | `ozone.s3g.http-address` | HTTP | S3-compatible RESTful API endpoint |
+| 9879 | `ozone.s3g.https-address` | HTTPS | Secure S3-compatible RESTful API endpoint |
+| 19878 | `ozone.s3g.webadmin.http-address` | HTTP | Ozone S3Gateway serves web content |
+| 19879 | `ozone.s3g.webadmin.https-address` | HTTPS | Ozone S3Gateway serves web content |
+
+## **HttpFS Server**
+
+| Default Port Number | Configuration Key | Endpoint Protocol | Purpose |
+| :---- | :---- | :---- | :---- |
+| 14000 | `httpfs.http.port` | HTTP or HTTPS | The HTTP port for HttpFS REST API. TLS is enabled if `httpfs.ssl.enabled` is true |
+
+## **Datanode**
+
+| Default Port Number | Configuration Key | Endpoint Protocol | Purpose |
+| :---- | :---- | :---- | :---- |
+| 9859 | `hdds.container.ipc.port` | HTTP/2 | Inter-process communication related to container operations |
+| 9855 | `hdds.container.ratis.datastream.port` | TCP | Ratis data streaming for container replication (if enabled) |
+| 9858 | `hdds.container.ratis.ipc.port` | HTTP/2 | Communication with embedded Ratis server for replication coordination |
+| 9857 | `hdds.container.ratis.admin.port` | HTTP/2 | Administrative requests to the Ratis server |
+| 9856 | `hdds.container.ratis.server.port` | HTTP/2 | Communication between Ratis peers in a replication pipeline |
+| 9882 | `hdds.datanode.http-address` | HTTP | Web UI for monitoring Datanode status and resource utilization |
+| 9883 | `hdds.datanode.https-address` | HTTPS | Secure Web UI for monitoring Datanode status and resource utilization |
+| 19864 | `hdds.datanode.client.port` | Hadoop RPC | The port number of the Ozone Datanode client service |
+
+:::note
+
+- The default port values can be overridden within the `ozone-site.xml` configuration file, with the exception of HttpFS ports, which are configurable via the `httpfs-site.xml` configuration file.
+- Hadoop RPC, a binary protocol operating over TCP, may be authenticated and encrypted using the Java SASL mechanism.
+- Authentication of the Web UI and HttpFS is achievable through Kerberos/SPNEGO, with encryption facilitated by HTTPS.
+- S3 client connections to the S3 Gateway undergo authentication utilizing S3 secrets and encryption via TLS.
+- A series of Ozone service ports are established by gRPC and Ratis, the latter employing gRPC. gRPC, a protocol based on HTTP/2, is capable of being encrypted with TLS. For how TLS and mTLS apply across gRPC/Ratis and HTTPS ports, see [Configuring gRPC With TLS](../../security/encryption/network-encryption/grpc).
+- Ratis streaming ports, initiated by Netty, can be secured through TLS encryption.
+
+:::
diff --git a/versioned_docs/version-2.2.1/05-administrator-guide/02-configuration/01-basic/02-network/README.mdx b/versioned_docs/version-2.2.1/05-administrator-guide/02-configuration/01-basic/02-network/README.mdx
new file mode 100644
index 0000000000..4ec0e1b620
--- /dev/null
+++ b/versioned_docs/version-2.2.1/05-administrator-guide/02-configuration/01-basic/02-network/README.mdx
@@ -0,0 +1,11 @@
+---
+sidebar_label: Network
+---
+
+# Network Related Configurations
+
+import DocCardList from '@theme/DocCardList';
+
+This section documents configurations for network communication between Ozone components.
+
+<DocCardList/>
diff --git a/versioned_docs/version-2.2.1/05-administrator-guide/02-configuration/01-basic/03-directories/01-ozone-manager.md b/versioned_docs/version-2.2.1/05-administrator-guide/02-configuration/01-basic/03-directories/01-ozone-manager.md
new file mode 100644
index 0000000000..ebac548eb9
--- /dev/null
+++ b/versioned_docs/version-2.2.1/05-administrator-guide/02-configuration/01-basic/03-directories/01-ozone-manager.md
@@ -0,0 +1,15 @@
+---
+sidebar_label: Ozone Manager
+---
+
+# Directory Configurations for Ozone Manager
+
+This section describes the directory-related configuration properties used by Ozone Manager (OM).
+
+| Property Name | Description | Tags | Default/Example Value | Sample Value |
+| ------------------------------- | ---------------------------------------------------------------------------------------------------------- | ------------------------------------- | ------------------------------------------------ | -------------------------- |
+| `ozone.om.db.dirs` | Directory where the OzoneManager stores its metadata. If not defined, falls back to `ozone.metadata.dirs`. | `OZONE`, `OM`, `STORAGE`, `PERFORMANCE` | Empty (creates directory if it doesn't exist) | `/var/data/ozone/om` |
+| `ozone.om.db.dirs.permissions` | Permissions for the metadata directories for Ozone Manager. Defaults to `750` if not defined. | | `750` | `750` |
+| `ozone.om.ratis.storage.dir` | Directory for storing OM's Ratis metadata like logs. Should use fast storage like SSD. | `OZONE`, `OM`, `STORAGE`, `MANAGEMENT`, `RATIS` | Falls back to `ozone.metadata.dirs` if undefined | `/var/data/ozone/ratis` |
+| `ozone.om.ratis.snapshot.dir` | Directory for storing OM's snapshot-related files like the `ratisSnapshotIndex` and DB checkpoint. | `OZONE`, `OM`, `STORAGE`, `MANAGEMENT`, `RATIS` | Falls back to `ozone.metadata.dirs` if undefined | `/var/data/ozone/snapshot` |
+| `ozone.om.snapshot.diff.db.dir` | Directory where OzoneManager stores snapshot diff-related data. | `OZONE`, `OM` | Falls back to `ozone.metadata.dirs` if undefined | `/var/data/ozone/diff` |
diff --git a/versioned_docs/version-2.2.1/05-administrator-guide/02-configuration/01-basic/03-directories/02-storage-container-manager.md b/versioned_docs/version-2.2.1/05-administrator-guide/02-configuration/01-basic/03-directories/02-storage-container-manager.md
new file mode 100644
index 0000000000..181783b821
--- /dev/null
+++ b/versioned_docs/version-2.2.1/05-administrator-guide/02-configuration/01-basic/03-directories/02-storage-container-manager.md
@@ -0,0 +1,7 @@
+---
+sidebar_label: Storage Container Manager
+---
+
+# Directory Configurations for Storage Container Manager
+
+**TODO:** File a subtask under [HDDS-9859](https://issues.apache.org/jira/browse/HDDS-9859) and complete this page or section.
diff --git a/versioned_docs/version-2.2.1/05-administrator-guide/02-configuration/01-basic/03-directories/03-datanode.md b/versioned_docs/version-2.2.1/05-administrator-guide/02-configuration/01-basic/03-directories/03-datanode.md
new file mode 100644
index 0000000000..a677821739
--- /dev/null
+++ b/versioned_docs/version-2.2.1/05-administrator-guide/02-configuration/01-basic/03-directories/03-datanode.md
@@ -0,0 +1,7 @@
+---
+sidebar_label: Datanodes
+---
+
+# Directory Configurations for Datanodes
+
+**TODO:** File a subtask under [HDDS-9859](https://issues.apache.org/jira/browse/HDDS-9859) and complete this page or section.
diff --git a/versioned_docs/version-2.2.1/05-administrator-guide/02-configuration/01-basic/03-directories/04-recon.md b/versioned_docs/version-2.2.1/05-administrator-guide/02-configuration/01-basic/03-directories/04-recon.md
new file mode 100644
index 0000000000..c408fe237d
--- /dev/null
+++ b/versioned_docs/version-2.2.1/05-administrator-guide/02-configuration/01-basic/03-directories/04-recon.md
@@ -0,0 +1,7 @@
+---
+sidebar_label: Recon
+---
+
+# Directory Configurations for Recon
+
+**TODO:** File a subtask under [HDDS-9859](https://issues.apache.org/jira/browse/HDDS-9859) and complete this page or section.
diff --git a/versioned_docs/version-2.2.1/05-administrator-guide/02-configuration/01-basic/03-directories/README.mdx b/versioned_docs/version-2.2.1/05-administrator-guide/02-configuration/01-basic/03-directories/README.mdx
new file mode 100644
index 0000000000..6492445129
--- /dev/null
+++ b/versioned_docs/version-2.2.1/05-administrator-guide/02-configuration/01-basic/03-directories/README.mdx
@@ -0,0 +1,11 @@
+---
+sidebar_label: Directories
+---
+
+# Directory Related Configurations
+
+import DocCardList from '@theme/DocCardList';
+
+This section documents configurations for directories that Ozone components will store their data in.
+
+<DocCardList/>
diff --git a/versioned_docs/version-2.2.1/05-administrator-guide/02-configuration/01-basic/README.mdx b/versioned_docs/version-2.2.1/05-administrator-guide/02-configuration/01-basic/README.mdx
new file mode 100644
index 0000000000..aaa55ae227
--- /dev/null
+++ b/versioned_docs/version-2.2.1/05-administrator-guide/02-configuration/01-basic/README.mdx
@@ -0,0 +1,11 @@
+---
+sidebar_label: Basic
+---
+
+# Basic Ozone Configuration
+
+import DocCardList from '@theme/DocCardList';
+
+This section documents the minimal set of configurations required for Ozone to run.
+
+<DocCardList/>
diff --git a/versioned_docs/version-2.2.1/05-administrator-guide/02-configuration/02-logging/01-application-logs.md b/versioned_docs/version-2.2.1/05-administrator-guide/02-configuration/02-logging/01-application-logs.md
new file mode 100644
index 0000000000..cd925888da
--- /dev/null
+++ b/versioned_docs/version-2.2.1/05-administrator-guide/02-configuration/02-logging/01-application-logs.md
@@ -0,0 +1,68 @@
+---
+sidebar_label: Application Logs
+---
+
+# Configuring Application Logs
+
+## Service Logs
+
+Each Ozone service (Ozone Manager, Storage Container Manager, Datanode, S3 Gateway, and Recon) generates its own log file. These logs contain detailed information about the service’s operations, including errors and warnings.
+
+By default, log files are stored in the `$OZONE_LOG_DIR` directory, which is usually set to the `logs` directory under the Ozone installation. The log file names are specific to each service, for example:
+
+- `ozone-om-....log` for Ozone Manager
+- `ozone-scm-....log` for Storage Container Manager
+- `ozone-datanode-....log` for Datanode
+
+The logging behavior for each service is controlled by its `log4j.properties` file, located in the service’s `$OZONE_CONF_DIR` directory, usually `etc/hadoop`. You can modify this file to change the log level, logging outputs, and other logging parameters.
+
+## Datanode Container Logs
+
+In addition to the main service log, Datanode also generates container-specific logs that track container replica-level events. These logs record brief messages about container state changes (open, closing, closed, unhealthy), replication events, reconstruction, reconciliation, container moves, and other container lifecycle events.
+
+Container logs are configured via `dn-container-log4j2.properties` and are stored as `dn-container-${hostName}.log` in the `$OZONE_LOG_DIR` directory.
+
+### Example
+
+```text
+2026-02-01 16:08:59,261 | INFO | ID=2 | Index=0 | BCSID=0 | State=OPEN | Volume=/hadoop-ozone/datanode/data/hdds | DataChecksum=0 |
+2026-02-03 12:49:36,139 | INFO | ID=2 | Index=0 | BCSID=1172 | State=CLOSING | Volume=/hadoop-ozone/datanode/data/hdds | DataChecksum=0 |
+2026-02-03 12:49:37,443 | INFO | ID=2 | Index=0 | BCSID=1172 | State=CLOSED | Volume=/hadoop-ozone/datanode/data/hdds | DataChecksum=4117a7a2 |
+2026-02-03 13:31:17,149 | INFO | ID=2018 | Index=0 | BCSID=159 | State=CLOSING | Volume=/mnt/dummy_disk1/hadoop-ozone/datanode/data/hdds | DataChecksum=0 |
+2026-02-03 13:31:17,205 | WARN | ID=2018 | Index=0 | BCSID=159 | State=QUASI_CLOSED | Volume=/mnt/dummy_disk1/hadoop-ozone/datanode/data/hdds | DataChecksum=2a21d155 | Ratis group removed. Group id: group-82AA09A3DA8C |
+```
+
+## Debugging
+
+You can increase the log verbosity for debugging purposes for both services and CLI tools.
+
+### Enabling Debug Logs for Services
+
+To enable debug logging for a service, you need to modify its `log4j.properties` file. Change the log level for the desired logger from `INFO` to `DEBUG`. For example, to enable debug logging for the Ozone Manager, you would edit its `log4j.properties` and change the following line:
+
+```properties
+rootLogger.level = info
+```
+
+to
+
+```properties
+rootLogger.level = debug
+```
+
+After saving the file and restarting the service, the service will start logging more detailed debug information.
+
+### Enabling Debug Logs for CLI Tools
+
+To enable debug logging for Ozone CLI tools (e.g., `ozone sh volume create`), you can set the `OZONE_ROOT_LOGGER` environment variable to `debug`:
+
+```bash
+export OZONE_ROOT_LOGGER=DEBUG,console
+ozone sh volume create /vol1
+```
+
+Alternatively, you can use the --loglevel option with the Ozone command:
+
+```bash
+ozone --loglevel debug sh volume create /vol1
+```
diff --git a/versioned_docs/version-2.2.1/05-administrator-guide/02-configuration/02-logging/02-audit-logs.md b/versioned_docs/version-2.2.1/05-administrator-guide/02-configuration/02-logging/02-audit-logs.md
new file mode 100644
index 0000000000..617e2a26ff
--- /dev/null
+++ b/versioned_docs/version-2.2.1/05-administrator-guide/02-configuration/02-logging/02-audit-logs.md
@@ -0,0 +1,53 @@
+---
+sidebar_label: Audit Logs
+---
+
+# Configuring Audit Logs
+
+Audit logs record security-sensitive operations, providing a trail of actions performed on the cluster. The following services produce audit logs:
+
+- Ozone Manager
+
+- Storage Container Manager
+
+- Datanode
+
+- S3 Gateway
+
+Audit log configurations are set in `*-audit-log4j2.properties` files. You can change the corresponding files to update the audit log policies for each component.
+
+## Sample Audit Log Entry
+
+Here is an example of an audit log entry from the Ozone Manager:
+
+```text
+INFO | OMAudit | ? | user=hdfs | ip=127.0.0.1 | op=CREATE_VOLUME | params={volume=vol1, admin=hdfs, owner=hdfs} | result=SUCCESS
+```
+
+This entry shows that the user `hdfs` successfully created a volume named `vol1`.
+
+## Deletion of Audit Logs
+
+The default log appender is a rolling appender. The following configurations can be added for the deletion of out-of-date AuditLogs.
+
+```properties
+appender.rolling.strategy.type=DefaultRolloverStrategy
+
+appender.rolling.strategy.max=3000
+
+appender.rolling.strategy.delete.type=Delete
+
+appender.rolling.strategy.delete.basePath=${sys:hadoop.log.dir}
+
+appender.rolling.strategy.delete.maxDepth=1
+
+appender.rolling.strategy.delete.ifFileName.type=IfFileName
+
+appender.rolling.strategy.delete.ifFileName.glob=om-audit-*.log.gz
+
+appender.rolling.strategy.delete.ifLastModified.type=IfLastModified
+
+appender.rolling.strategy.delete.ifLastModified.age=30d
+```
+
+For more details, please check [Log4j2 Delete on Rollover](https://logging.apache.org/log4j/2.x/manual/appenders.html#CustomDeleteOnRollover).
diff --git a/versioned_docs/version-2.2.1/05-administrator-guide/02-configuration/02-logging/README.mdx b/versioned_docs/version-2.2.1/05-administrator-guide/02-configuration/02-logging/README.mdx
new file mode 100644
index 0000000000..47230e5b15
--- /dev/null
+++ b/versioned_docs/version-2.2.1/05-administrator-guide/02-configuration/02-logging/README.mdx
@@ -0,0 +1,11 @@
+---
+sidebar_label: Logging
+---
+
+# Logging Configuration
+
+import DocCardList from '@theme/DocCardList';
+
+This section documents configurations for various server side logs in Ozone.
+
+<DocCardList/>
diff --git a/versioned_docs/version-2.2.1/05-administrator-guide/02-configuration/03-security/01-administrators.md b/versioned_docs/version-2.2.1/05-administrator-guide/02-configuration/03-security/01-administrators.md
new file mode 100644
index 0000000000..cf0841e05b
--- /dev/null
+++ b/versioned_docs/version-2.2.1/05-administrator-guide/02-configuration/03-security/01-administrators.md
@@ -0,0 +1,45 @@
+---
+sidebar_label: Administrators
+---
+
+# Configuring Ozone Administrators
+
+Ozone identifies administrators through specific configuration properties, allowing for fine-grained control over administrative access. These properties define users and groups with elevated privileges, or read-only administrative access.
+
+## Core Ozone Administrators
+
+These properties define the primary administrators for the Ozone cluster.
+
+| Property Name | Description | Default Value |
+|---|---|---|
+| `ozone.administrators` | Comma-separated list of user names who are considered Ozone administrators. If this property is not explicitly set, the user who launches an Ozone service will be automatically designated as the initial administrator. | (empty) |
+| `ozone.administrators.groups` | Comma-separated list of group names whose members are considered Ozone administrators. Users belonging to any of these groups will have administrative access. | (empty) |
+
+## Read-Only Ozone Administrators
+
+These properties define users and groups with read-only administrative access, allowing them to perform read operations without standard access checks.
+
+| Property Name | Description | Default Value |
+|---|---|---|
+| `ozone.readonly.administrators` | Comma-separated list of user names who have read-only administrative access. These users can perform read operations without undergoing regular access checks. | (empty) |
+| `ozone.readonly.administrators.groups` | Comma-separated list of group names whose members have read-only administrative access. Users in these groups can perform read operations bypassing normal access controls. | (empty) |
+
+## S3-Specific Administrators
+
+These properties define administrators with privileges specific to the S3 Gateway interface.
+
+| Property Name | Description | Default Value |
+|---|---|---|
+| `ozone.s3.administrators` | Comma-separated list of user names who have S3-specific administrative access. These users can access admin-only information from the S3 Gateway. If this property is empty, users defined in `ozone.administrators` will automatically have S3 administrative privileges. | (empty) |
+| `ozone.s3.administrators.groups` | Comma-separated list of group names whose members have S3-specific administrative access. Members of these groups can access admin-only information from the S3 Gateway. | (empty) |
+
+## Recon Administrators
+
+These properties define administrators for the Recon service, which provides monitoring and management capabilities for the Ozone cluster.
+
+| Property Name | Description | Default Value |
+|---|---|---|
+| `ozone.recon.administrators` | Comma-separated list of user names who are Recon administrators. These users can access admin-only information from Recon. Note that users defined in `ozone.administrators` will always have access to all Recon information regardless of this setting. | (empty) |
+| `ozone.recon.administrators.groups` | Comma-separated list of group names whose members are Recon administrators. Users in these groups can access admin-only information from Recon. | (empty) |
+
+It is enough for a user to be defined in `ozone.administrators` or be directly or indirectly in a group defined in `ozone.administrators.groups` to have full administrative access across Ozone services.
diff --git a/versioned_docs/version-2.2.1/05-administrator-guide/02-configuration/03-security/02-kerberos.md b/versioned_docs/version-2.2.1/05-administrator-guide/02-configuration/03-security/02-kerberos.md
new file mode 100644
index 0000000000..38a40ee9f9
--- /dev/null
+++ b/versioned_docs/version-2.2.1/05-administrator-guide/02-configuration/03-security/02-kerberos.md
@@ -0,0 +1,93 @@
+---
+sidebar_label: Kerberos
+---
+
+# Configuring Kerberos
+
+Ozone depends on [Kerberos](https://web.mit.edu/kerberos/) to make the clusters secure. Historically, HDFS has supported running in an isolated secure networks where it is possible to deploy without securing the cluster.
+
+This release of Ozone follows that model, but soon will move to *secure by default.* Today to enable security in Ozone cluster, we need to set the configuration `ozone.security.enabled` to `true` and `hadoop.security.authentication` to `kerberos`.
+
+| Property | Value |
+| -------------------------------- | ---------- |
+| `ozone.security.enabled` | `true` |
+| `hadoop.security.authentication` | `kerberos` |
+
+## Storage Container Manager
+
+SCM requires two Kerberos principals, and the corresponding key tab files for both of these principals.
+
+| Property | Description |
+| --------------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
+| `hdds.scm.kerberos.principal` | The SCM service principal. e.g. `scm/_HOST@REALM.COM` |
+| `hdds.scm.kerberos.keytab.file` | The keytab file used by SCM daemon to login as its service principal. |
+| `hdds.scm.http.auth.kerberos.principal` | SCM HTTP server service principal if SPNEGO is enabled for SCM HTTP server. |
+| `hdds.scm.http.auth.kerberos.keytab` | The keytab file used by SCM HTTP server to login as its service principal if SPNEGO is enabled for SCM HTTP server. |
+
+:::note
+For general configuration on enabling Kerberos based SPNEGO authentication for HTTP web-consoles, refer to [Configuring HTTP authentication using Kerberos SPNEGO](../../../administrator-guide/configuration/security/https).
+:::
+
+## Ozone Manager
+
+Like SCM, OM also requires two Kerberos principals, and the corresponding key tab files for both of these principals.
+
+| Property | Description |
+| --------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
+| `ozone.om.kerberos.principal` | The OzoneManager service principal. e.g. `om/_HOST@REALM.COM` |
+| `ozone.om.kerberos.keytab.file` | The keytab file used by OM daemon to login as its service principal. |
+| `ozone.om.http.auth.kerberos.principal` | Ozone Manager HTTP server service principal if SPNEGO is enabled for OM HTTP server. |
+| `ozone.om.http.auth.kerberos.keytab` | The keytab file used by OM HTTP server to login as its service principal if SPNEGO is enabled for OM HTTP server. |
+
+## S3 Gateway
+
+S3 Gateway requires one service principal and here the configuration values needed in the `ozone-site.xml`.
+
+| Property | Description |
+| ---------------------------------------- | --------------------------------------------------------------------------------------------------- |
+| `ozone.s3g.kerberos.principal` | S3 Gateway principal. e.g. `s3g/_HOST@REALM` |
+| `ozone.s3g.kerberos.keytab.file` | The keytab file used by S3 Gateway. e.g. `/etc/security/keytabs/s3g.keytab` |
+| `ozone.s3g.http.auth.kerberos.principal` | S3 Gateway principal if SPNEGO is enabled for S3 Gateway HTTP server. e.g. `HTTP/_HOST@EXAMPLE.COM` |
+| `ozone.s3g.http.auth.kerberos.keytab` | The keytab file used by S3 Gateway if SPNEGO is enabled for S3 Gateway HTTP server. |
+
+## HttpFS Gateway
+
+The HttpFS gateway offers an HDFS-compatible REST API (`webhdfs`). It requires Kerberos for its client-facing HTTP endpoint and for its internal connection to the Ozone Manager (which acts as an HDFS NameNode proxy).
+
+| Property | Description |
+|---|---|
+| `hadoop.http.authentication.type` | Defines the authentication mechanism used by HttpFS for its HTTP clients. Valid values are `simple` or `kerberos`. Set to `kerberos` for SPNEGO. |
+| `hadoop.http.authentication.kerberos.principal` | The HTTP Kerberos principal used by HttpFS for its client-facing HTTP endpoint. This MUST start with `HTTP/` (e.g., `HTTP/${httpfs.hostname}@${kerberos.realm}`). |
+| `hadoop.http.authentication.kerberos.keytab` | The Kerberos keytab file for the client-facing HTTP principal. e.g., `${user.home}/httpfs.keytab`. |
+| `httpfs.hadoop.authentication.type` | Defines the authentication mechanism used by HttpFS to connect to the HDFS NameNode (Ozone Manager). Valid values are `simple` (default) or `kerberos`. |
+| `httpfs.hadoop.authentication.kerberos.principal` | The Kerberos principal used by HttpFS to connect to the HDFS NameNode (Ozone Manager). e.g., `${user.name}/${httpfs.hostname}@${kerberos.realm}`. |
+| `httpfs.hadoop.authentication.kerberos.keytab` | The Kerberos keytab file for the principal used to connect to the HDFS NameNode (Ozone Manager). e.g., `${user.home}/httpfs.keytab`. |
+
+:::note
+For HttpFS placed behind a **load balancer** with Kerberos (SPNEGO), the HTTP principal must match the **load balancer hostname** that clients use, not only the backend HttpFS host. See [HttpFS behind a load balancer (Kerberos)](../performance/httpfs-load-balancer).
+:::
+
+## Recon Server
+
+Recon provides monitoring and management capabilities and can be secured using Kerberos authentication for its web UI and REST endpoints.
+
+| Property | Description |
+|---|---|
+| `ozone.recon.http.auth.type` | Sets Recon's HTTP authentication type. Set to `kerberos` for SPNEGO. |
+| `ozone.recon.http.auth.kerberos.principal` | The service principal for the Recon HTTP endpoint. e.g., `HTTP/_HOST@REALM`. |
+| `ozone.recon.http.auth.kerberos.keytab` | The keytab file for the Recon HTTP principal. e.g., `/path/to/HTTP.keytab`. |
+
+Access to Recon's admin-only APIs is controlled by `ozone.administrators` or `ozone.recon.administrators` lists. Refer to [Configuring Ozone Administrators](../../configuration/security/administrators) for more details.
+
+## Securing Datanodes
+
+Datanodes under Hadoop is traditionally secured by creating a Keytab file on the Datanodes. With Ozone, we have moved away to using Datanode certificates. That is, Kerberos on Datanodes is not needed in case of a secure Ozone cluster.
+
+However, we support the legacy Kerberos based Authentication to make it easy for the current set of users. The HDFS configuration keys are the following that is setup in `hdfs-site.xml`.
+
+| Property | Description |
+| -------------------------------------------- | ------------------------------------------------------------------------------- |
+| `dfs.datanode.kerberos.principal` | The Datanode service principal. e.g. `dn/_HOST@REALM.COM` |
+| `dfs.datanode.kerberos.keytab.file` | The keytab file used by Datanode daemon to login as its service principal. |
+| `hdds.datanode.http.auth.kerberos.principal` | Datanode HTTP server service principal. |
+| `hdds.datanode.http.auth.kerberos.keytab` | The keytab file used by Datanode HTTP server to login as its service principal. |
diff --git a/versioned_docs/version-2.2.1/05-administrator-guide/02-configuration/03-security/03-https.md b/versioned_docs/version-2.2.1/05-administrator-guide/02-configuration/03-security/03-https.md
new file mode 100644
index 0000000000..6090cc4cbb
--- /dev/null
+++ b/versioned_docs/version-2.2.1/05-administrator-guide/02-configuration/03-security/03-https.md
@@ -0,0 +1,119 @@
+---
+sidebar_label: HTTPS
+---
+
+# Configuring HTTP authentication using Kerberos SPNEGO
+
+This document describes how to configure Ozone HTTP web-consoles to require user authentication.
+
+## Default authentication
+
+By default Ozone HTTP web-consoles (OM, SCM, S3G, Recon, Datanode) allow access without authentication based on the following default configurations.
+
+| Property | Value |
+|----------|-------|
+| `ozone.security.http.kerberos.enabled` | `false` |
+| `ozone.http.filter.initializers` | |
+
+If you have an SPNEGO enabled Ozone cluster and want to disable it for all Ozone services, just make sure the two key mentioned are configured as above.
+
+## Kerberos based SPNEGO authentication
+
+However, they can be configured to require Kerberos authentication using HTTP SPNEGO protocol (supported by browsers like Firefox and Chrome). To achieve that, the following keys must be configured first.
+
+| Property | Value |
+|----------|-------|
+| `hadoop.security.authentication` | `kerberos` |
+| `ozone.security.http.kerberos.enabled` | `true` |
+| `ozone.http.filter.initializers` | `org.apache.hadoop.security.AuthenticationFilterInitializer` |
+
+After that, individual component needs to configure properly to completely enable SPNEGO or SIMPLE authentication.
+
+## Enable SPNEGO authentication for OM HTTP
+
+| Property | Value |
+|----------|-------|
+| `ozone.om.http.auth.type` | `kerberos` |
+| `ozone.om.http.auth.kerberos.principal` | `HTTP/_HOST@REALM` |
+| `ozone.om.http.auth.kerberos.keytab` | `/path/to/HTTP.keytab` |
+
+## Enable SPNEGO authentication for S3G HTTP
+
+| Property | Value |
+|----------|-------|
+| `ozone.s3g.http.auth.type` | `kerberos` |
+| `ozone.s3g.http.auth.kerberos.principal` | `HTTP/_HOST@REALM` |
+| `ozone.s3g.http.auth.kerberos.keytab` | `/path/to/HTTP.keytab` |
+
+## Enable SPNEGO authentication for Recon HTTP
+
+| Property | Value |
+|----------|-------|
+| `ozone.recon.http.auth.type` | `kerberos` |
+| `ozone.recon.http.auth.kerberos.principal` | `HTTP/_HOST@REALM` |
+| `ozone.recon.http.auth.kerberos.keytab` | `/path/to/HTTP.keytab` |
+
+## Enable SPNEGO authentication for SCM HTTP
+
+| Property | Value |
+|----------|-------|
+| `ozone.scm.http.auth.type` | `kerberos` |
+| `ozone.scm.http.auth.kerberos.principal` | `HTTP/_HOST@REALM` |
+| `ozone.scm.http.auth.kerberos.keytab` | `/path/to/HTTP.keytab` |
+
+## Enable SPNEGO authentication for Datanode HTTP
+
+| Property | Value |
+|----------|-------|
+| `ozone.datanode.http.auth.type` | `kerberos` |
+| `ozone.datanode.http.auth.kerberos.principal` | `HTTP/_HOST@REALM` |
+| `ozone.datanode.http.auth.kerberos.keytab` | `/path/to/HTTP.keytab` |
+
+Note: Ozone Datanode does not have a default webpage, which prevents you from accessing “/” or “/index.html”. But it does provide standard servlet like `jmx/conf/jstack` via HTTP.
+
+In addition, Ozone HTTP web-console support the equivalent of Hadoop’s Pseudo/Simple authentication. If this option is enabled, the user name must be specified in the first browser interaction using the user.name query string parameter. e.g., http://scm:9876/?user.name=scmadmin.
+
+## Enable SIMPLE authentication for OM HTTP
+
+| Property | Value |
+|----------|-------|
+| `ozone.om.http.auth.type` | `simple` |
+| `ozone.om.http.auth.simple.anonymous.allowed` | `false` |
+
+If you don’t want to specify the user.name in the query string parameter, change `ozone.om.http.auth.simple.anonymous.allowed` to true.
+
+## Enable SIMPLE authentication for S3G HTTP
+
+| Property | Value |
+|----------|-------|
+| `ozone.s3g.http.auth.type` | `simple` |
+| `ozone.s3g.http.auth.simple.anonymous.allowed` | `false` |
+
+If you don’t want to specify the user.name in the query string parameter, change `ozone.s3g.http.auth.simple.anonymous.allowed` to true.
+
+## Enable SIMPLE authentication for Recon HTTP
+
+| Property | Value |
+|----------|-------|
+| `ozone.recon.http.auth.type` | `simple` |
+| `ozone.recon.http.auth.simple.anonymous.allowed` | `false` |
+
+If you don’t want to specify the user.name in the query string parameter, change `ozone.recon.http.auth.simple.anonymous.allowed` to true.
+
+## Enable SIMPLE authentication for SCM HTTP
+
+| Property | Value |
+|----------|-------|
+| `ozone.scm.http.auth.type` | `simple` |
+| `ozone.scm.http.auth.simple.anonymous.allowed` | `false` |
+
+If you don’t want to specify the user.name in the query string parameter, change `hdds.scm.http.auth.simple.anonymous.allowed` to true.
+
+## Enable SIMPLE authentication for Datanode HTTP
+
+| Property | Value |
+|----------|-------|
+| `ozone.datanode.http.auth.type` | `simple` |
+| `ozone.datanode.http.auth.simple.anonymous.allowed` | `false` |
+
+If you don’t want to specify the user.name in the query string parameter, change `hdds.datanode.http.auth.simple.anonymous.allowed` to true.
diff --git a/versioned_docs/version-2.2.1/05-administrator-guide/02-configuration/03-security/04-knox.md b/versioned_docs/version-2.2.1/05-administrator-guide/02-configuration/03-security/04-knox.md
new file mode 100644
index 0000000000..7ccb2f12e8
--- /dev/null
+++ b/versioned_docs/version-2.2.1/05-administrator-guide/02-configuration/03-security/04-knox.md
@@ -0,0 +1,7 @@
+---
+sidebar_label: Apache Knox
+---
+
+# Configuring Apache Knox
+
+**TODO:** File a subtask under [HDDS-9859](https://issues.apache.org/jira/browse/HDDS-9859) and complete this page or section.
diff --git a/versioned_docs/version-2.2.1/05-administrator-guide/02-configuration/03-security/05-encryption/01-network-encryption/01-hadoop-rpc.md b/versioned_docs/version-2.2.1/05-administrator-guide/02-configuration/03-security/05-encryption/01-network-encryption/01-hadoop-rpc.md
new file mode 100644
index 0000000000..daf2e751f5
--- /dev/null
+++ b/versioned_docs/version-2.2.1/05-administrator-guide/02-configuration/03-security/05-encryption/01-network-encryption/01-hadoop-rpc.md
@@ -0,0 +1,24 @@
+---
+sidebar_label: Hadoop RPC
+---
+
+# Configuring Hadoop RPC With SASL
+
+Ozone traffic may be transferred via Hadoop RPC for client-to-OM (Ozone Manager) communication. To encrypt client-OM communication, configure `hadoop.rpc.protection` to `privacy` in your `core-site.xml`. This ensures that all data exchanged over Hadoop RPC is encrypted.
+
+Hadoop RPC is encrypted using the algorithm selected by the Java SASL, which is typically 3DES or RC4. Note that the Hadoop RPC throughput may drop due to encryption overhead.
+
+For more information, check out [Hadoop in Secure Mode](https://hadoop.apache.org/docs/current/hadoop-project-dist/hadoop-common/SecureMode.html).
+
+```xml
+<property>
+ <name>hadoop.rpc.protection</name>
+ <value>privacy</value>
+</property>
+```
+
+## OM Transport Class
+
+The default transport class for communication with the Ozone Manager (OM) is `org.apache.hadoop.ozone.om.protocolPB.Hadoop3OmTransportFactory`. However, users can configure the system to use a gRPC-based transport class for client-to-OM communication by setting the `ozone.om.transport.class` configuration property to `org.apache.hadoop.ozone.om.protocolPB.GrpcOmTransportFactory`.
+
+In this case, the Hadoop RPC encryption configuration is not applicable. Refer to the [Configuring gRPC With TLS](./grpc) page to encrypt gRPC-based communication.
diff --git a/versioned_docs/version-2.2.1/05-administrator-guide/02-configuration/03-security/05-encryption/01-network-encryption/02-grpc.md b/versioned_docs/version-2.2.1/05-administrator-guide/02-configuration/03-security/05-encryption/01-network-encryption/02-grpc.md
new file mode 100644
index 0000000000..00c05c6ec4
--- /dev/null
+++ b/versioned_docs/version-2.2.1/05-administrator-guide/02-configuration/03-security/05-encryption/01-network-encryption/02-grpc.md
@@ -0,0 +1,39 @@
+---
+sidebar_label: gRPC TLS
+---
+
+# Configuring gRPC With TLS
+
+Ozone traffic may be transferred via gRPC (e.g., Ratis write pipeline or client reading blocks from Datanode). To enable TLS for gRPC traffic, set `hdds.grpc.tls.enabled` to **true**. This encrypts communication between Ozone services that use gRPC.
+
+## mTLS in Apache Ozone
+
+In Apache Ozone, mTLS requirements are split across two distinct communication layers:
+
+| Communication Layer | Protocol | mTLS Requirement | Configuration Key(s) |
+| --- | --- | --- | --- |
+| Peer-to-Peer (Core) | gRPC / Ratis | Required (Hardcoded) | `ozone.security.enabled` & `hdds.grpc.tls.enabled` |
+| Management / Web | HTTPS | Optional | `ozone.https.client.need-auth` (default: **false**) |
+
+For the primary peer-to-peer communication (consensus, replication, heartbeats), Ozone effectively mandates mTLS by default whenever TLS is enabled in a secure cluster, using the SCM's internal Certificate Authority to issue and verify peer identities. For the HTTPS layer, mTLS is an optional extra security measure.
+
+Clients (including the S3 Gateway) are often treated as "external" entities. While the S3 Gateway is part of the Ozone distribution, it utilizes the standard client libraries which are designed to work from machines that do not have SCM-issued certificates, relying instead on Kerberos for identity and tokens for data access.
+
+## Configuration
+
+Add the following property to your `ozone-site.xml` configuration file:
+
+```xml
+<property>
+ <name>hdds.grpc.tls.enabled</name>
+ <value>true</value>
+ <description>Enable TLS for gRPC traffic</description>
+</property>
+```
+
+## Related Configuration
+
+For information on protecting other types of in-transit traffic in Ozone, see:
+
+- [Hadoop RPC Encryption](./hadoop-rpc) - For client-to-Ozone Manager communication
+- [Default Ports](../../../basic/network/default-ports) - For details on network ports and transport types
diff --git a/versioned_docs/version-2.2.1/05-administrator-guide/02-configuration/03-security/05-encryption/01-network-encryption/03-web-ui-https.md b/versioned_docs/version-2.2.1/05-administrator-guide/02-configuration/03-security/05-encryption/01-network-encryption/03-web-ui-https.md
new file mode 100644
index 0000000000..40035f16d0
--- /dev/null
+++ b/versioned_docs/version-2.2.1/05-administrator-guide/02-configuration/03-security/05-encryption/01-network-encryption/03-web-ui-https.md
@@ -0,0 +1,268 @@
+---
+sidebar_label: Web UI HTTPS
+---
+
+# Configuring HTTPS for Web UI
+
+Ozone exposes multiple Web UIs (OM, SCM, Datanode, HttpFS, Recon, S3 Gateway). This page describes how to enable HTTPS for these Web UIs and how to configure optional mutual TLS (mTLS) using server and client certificates.
+
+For authentication (Kerberos/SIMPLE) of the HTTP endpoints, see the **Securing HTTP** documentation. This page focuses on transport encryption only.
+
+## 1. Enabling HTTPS endpoints
+
+HTTPS for Web UIs is controlled globally by the `ozone.http.policy` property.
+
+### Configuration key
+
+| Property | Default | Description |
+|----------|---------|--------------|
+| `ozone.http.policy` | `HTTP_ONLY` | Controls whether HTTPS is enabled for Ozone daemons' HTTP endpoints. |
+
+**Supported values** (from [`ozone-default.xml`](https://github.com/apache/ozone/blob/master/hadoop-hdds/common/src/main/resources/ozone-default.xml)):
+
+- `HTTP_ONLY`: Service is provided only over HTTP.
+- `HTTPS_ONLY`: Service is provided only over HTTPS.
+- `HTTP_AND_HTTPS`: Both HTTP and HTTPS ports are enabled.
+
+To enable HTTPS for Web UIs, set the policy in `ozone-site.xml`, for example:
+
+```xml
+<property>
+ <name>ozone.http.policy</name>
+ <value>HTTPS_ONLY</value>
+</property>
+```
+
+Or, to keep both HTTP and HTTPS available:
+
+```xml
+<property>
+ <name>ozone.http.policy</name>
+ <value>HTTP_AND_HTTPS</value>
+</property>
+```
+
+## 2. HTTP vs HTTPS ports for Web UIs
+
+Each service has separate configuration keys for its HTTP and HTTPS Web UI endpoints. HTTPS uses different ports than HTTP.
+
+### Example: Ozone Manager (OM)
+
+From `ozone-default.xml` and the Network Ports reference:
+
+- `ozone.om.http-address` – default `0.0.0.0:9874` (HTTP Web UI)
+- `ozone.om.https-address` – default `0.0.0.0:9875` (HTTPS Web UI)
+
+Example in `ozone-site.xml`:
+
+```xml
+<property>
+ <name>ozone.om.http-address</name>
+ <value>0.0.0.0:9874</value>
+</property>
+
+<property>
+ <name>ozone.om.https-address</name>
+ <value>0.0.0.0:9875</value>
+</property>
+```
+
+When HA is enabled, append the service ID and node ID to each property, for example: `ozone.om.https-address.service1.om1`.
+
+### Other services
+
+The same pattern is used for other Web UIs:
+
+- **SCM**: `ozone.scm.http-address`, `ozone.scm.https-address` (defaults 0.0.0.0:9876, 0.0.0.0:9877)
+- **Recon**: `ozone.recon.http-address`, `ozone.recon.https-address` (defaults 0.0.0.0:9888, 0.0.0.0:9889)
+- **S3 Gateway (S3G)**: `ozone.s3g.http-address`, `ozone.s3g.https-address` (defaults 0.0.0.0:9878, 0.0.0.0:9879)
+- **Datanode**: `hdds.datanode.http-address`, `hdds.datanode.https-address` (defaults 0.0.0.0:9882, 0.0.0.0:9883)
+- **HttpFS**: use `httpfs.http.port` and corresponding SSL settings (see HttpFS documentation)
+
+See the [Default Ports](../../../basic/network/default-ports) reference for the full list of default ports and keys.
+
+## 3. Server keystore and truststore configuration
+
+Ozone uses standard Hadoop SSL configuration. The main entry point is the server keystore resource.
+
+### Configuration keys
+
+From [`ozone-default.xml`](https://github.com/apache/ozone/blob/master/hadoop-hdds/common/src/main/resources/ozone-default.xml):
+
+| Property | Default | Description |
+|----------|---------|--------------|
+| `ozone.https.server.keystore.resource` | `ssl-server.xml` | Resource file from which server keystore information is read |
+| `ssl.server.keystore.location` | *(empty)* | Filesystem path to the server keystore file |
+| `ssl.server.keystore.password` | *(empty)* | Password for the server keystore |
+| `ssl.server.keystore.keypassword` | *(empty)* | Password for the private key in the keystore |
+| `ssl.server.truststore.location` | *(empty)* | Filesystem path to the server truststore file |
+| `ssl.server.truststore.password` | *(empty)* | Password for the server truststore |
+
+### Step 1 – Point Ozone to the server SSL resource
+
+In `ozone-site.xml`, you can override the server SSL resource file name:
+
+```xml
+<property>
+ <name>ozone.https.server.keystore.resource</name>
+ <value>ssl-server.xml</value>
+</property>
+```
+
+This resource is usually found on the classpath and contains the keystore/truststore definitions.
+
+### Step 2 – Define keystore and truststore in the SSL resource
+
+In the referenced `ssl-server.xml` (or the file named by `ozone.https.server.keystore.resource`), configure the keystore and truststore locations and passwords:
+
+```xml
+<configuration>
+ <property>
+ <name>ssl.server.keystore.location</name>
+ <value>/etc/security/keystores/ozone-server.jks</value>
+ </property>
+
+ <property>
+ <name>ssl.server.keystore.password</name>
+ <value>changeit</value>
+ </property>
+
+ <property>
+ <name>ssl.server.keystore.keypassword</name>
+ <value>changeit</value>
+ </property>
+
+ <property>
+ <name>ssl.server.truststore.location</name>
+ <value>/etc/security/keystores/ozone-truststore.jks</value>
+ </property>
+
+ <property>
+ <name>ssl.server.truststore.password</name>
+ <value>changeit</value>
+ </property>
+</configuration>
+```
+
+### Requirements
+
+- The keystore must contain a certificate whose hostname matches the Web UI URL.
+- All hosts running Ozone Web UI roles must be able to read the keystore and truststore files.
+- Use strong passwords and protect these files carefully.
+
+## 4. Enabling mutual TLS (mTLS)
+
+By default, the server does **not** require a client certificate.
+
+### Configuration keys
+
+From [`ozone-default.xml`](https://github.com/apache/ozone/blob/master/hadoop-hdds/common/src/main/resources/ozone-default.xml):
+
+| Property | Default | Description |
+|----------|---------|--------------|
+| `ozone.https.client.need-auth` | `false` | Whether SSL client certificate authentication is required (mTLS). |
+| `ozone.https.client.keystore.resource` | `ssl-client.xml` | Resource file describing the client keystore/truststore. |
+
+To require client certificates (mTLS) for HTTPS Web UIs:
+
+```xml
+<property>
+ <name>ozone.https.client.need-auth</name>
+ <value>true</value>
+</property>
+```
+
+Then configure the client SSL resource:
+
+```xml
+<property>
+ <name>ozone.https.client.keystore.resource</name>
+ <value>ssl-client.xml</value>
+</property>
+```
+
+In `ssl-client.xml`, define the client keystore and truststore, for example:
+
+```xml
+<configuration>
+ <property>
+ <name>ssl.client.keystore.location</name>
+ <value>/etc/security/keystores/ozone-client.jks</value>
+ </property>
+
+ <property>
+ <name>ssl.client.keystore.password</name>
+ <value>changeit</value>
+ </property>
+
+ <property>
+ <name>ssl.client.truststore.location</name>
+ <value>/etc/security/keystores/ozone-client-truststore.jks</value>
+ </property>
+
+ <property>
+ <name>ssl.client.truststore.password</name>
+ <value>changeit</value>
+ </property>
+</configuration>
+```
+
+### mTLS considerations
+
+- The server truststore (`ssl.server.truststore.location`) must trust the CA that signed client certificates.
+- The client truststore must trust the server certificate's CA.
+- For browser access, client certificates must be available in the browser's key store or the underlying OS keychain.
+
+## 5. Example minimal configuration
+
+Below is a minimal example that enables HTTPS-only access to the OM Web UI with server-side TLS.
+
+In `ozone-site.xml`:
+
+```xml
+<configuration>
+ <property>
+ <name>ozone.http.policy</name>
+ <value>HTTPS_ONLY</value>
+ </property>
+
+ <property>
+ <name>ozone.om.https-address</name>
+ <value>0.0.0.0:9875</value>
+ </property>
+
+ <property>
+ <name>ozone.https.server.keystore.resource</name>
+ <value>ssl-server.xml</value>
+ </property>
+</configuration>
+```
+
+In the referenced `ssl-server.xml`:
+
+```xml
+<configuration>
+ <property>
+ <name>ssl.server.keystore.location</name>
+ <value>/etc/security/keystores/ozone-server.jks</value>
+ </property>
+ <property>
+ <name>ssl.server.keystore.password</name>
+ <value>changeit</value>
+ </property>
+ <property>
+ <name>ssl.server.keystore.keypassword</name>
+ <value>changeit</value>
+ </property>
+ <property>
+ <name>ssl.server.truststore.location</name>
+ <value>/etc/security/keystores/ozone-truststore.jks</value>
+ </property>
+ <property>
+ <name>ssl.server.truststore.password</name>
+ <value>changeit</value>
+ </property>
+</configuration>
+```
+
+After configuring the server (and optionally client) keystores, restart Ozone services so the HTTPS and mTLS settings take effect.
diff --git a/versioned_docs/version-2.2.1/05-administrator-guide/02-configuration/03-security/05-encryption/01-network-encryption/README.mdx b/versioned_docs/version-2.2.1/05-administrator-guide/02-configuration/03-security/05-encryption/01-network-encryption/README.mdx
new file mode 100644
index 0000000000..ce88651403
--- /dev/null
+++ b/versioned_docs/version-2.2.1/05-administrator-guide/02-configuration/03-security/05-encryption/01-network-encryption/README.mdx
@@ -0,0 +1,11 @@
+---
+sidebar_label: Network Encryption
+---
+
+# Network Encryption Configuration
+
+import DocCardList from '@theme/DocCardList';
+
+This section documents encryption configurations for each type of network communication in Ozone.
+
+<DocCardList/>
diff --git a/versioned_docs/version-2.2.1/05-administrator-guide/02-configuration/03-security/05-encryption/02-transparent-data-encryption.md b/versioned_docs/version-2.2.1/05-administrator-guide/02-configuration/03-security/05-encryption/02-transparent-data-encryption.md
new file mode 100644
index 0000000000..401e5c1107
--- /dev/null
+++ b/versioned_docs/version-2.2.1/05-administrator-guide/02-configuration/03-security/05-encryption/02-transparent-data-encryption.md
@@ -0,0 +1,209 @@
+# Transparent Data Encryption (TDE)
+
+Ozone Transparent Data Encryption (TDE) enables you to encrypt data at rest. TDE is enabled at the bucket level when a bucket is created. To use TDE, an administrator must first configure a Key Management Server (KMS). Ozone can work with **Hadoop KMS** and **Ranger KMS**. The KMS URI needs to be provided to Ozone via the `core-site.xml` configuration file.
+
+Once the KMS is configured, users can create an encryption key and then create an encrypted bucket using that key. All data written to an encrypted bucket will be transparently encrypted on the server-side, and data read from the bucket will be transparently decrypted.
+
+## Configuring TDE
+
+1. **Set up a Key Management Server (KMS):**
+ - **Hadoop KMS:** Follow the instructions in the [Hadoop KMS documentation](https://hadoop.apache.org/docs/r3.4.1/hadoop-kms/index.html).
+ - **Ranger KMS:** Ranger KMS can also be used. For Ranger KMS, encryption keys can be managed via the Ranger KMS management console or its [REST API](https://ranger.apache.org/kms/apidocs/index.html), in addition to the `hadoop key` command line interface.
+
+2. **Configure Ozone:**
+ Add the following property to Ozone’s `core-site.xml`:
+
+ ```xml
+ <property>
+ <name>hadoop.security.key.provider.path</name>
+ <value>kms://http@kms-host:9600/kms</value>
+ </property>
+ ```
+
+ Replace `kms://http@kms-host:9600/kms` with the actual URI of your KMS. For example, `kms://http@kms1.example.com:9600/kms`
+
+## Creating an Encryption Key
+
+Use the `hadoop key create` command to create an encryption key in the configured KMS:
+
+```shell
+hadoop key create <key_name> [-size <key_bit_length>] [-cipher <cipher_suite>] [-description <description>]
+```
+
+- `<key_name>`: The name of the encryption key.
+- **`-size <key_bit_length>` (Optional):** Specifies the key bit length. The default is 128 bits (defined by `hadoop.security.key.default.bitlength`).
+Ranger KMS supports both 128 and 256 bits. Hadoop KMS is also commonly used with 128 and 256 bit keys; for specific version capabilities, consult the Hadoop KMS documentation. Valid AES key lengths are 128, 192, and 256 bits.
+- **`-cipher <cipher_suite>` (Optional):** Specifies the cipher suite. Currently, only **`AES/CTR/NoPadding`** (the default) is supported.
+- `-description <description>` (Optional): A description for the key.
+
+For example:
+
+```shell
+hadoop key create enckey -size 256 -cipher AES/CTR/NoPadding -description "Encryption key for my_bucket"
+```
+
+### Creating an Encrypted Bucket
+
+Use the Ozone shell `ozone sh bucket create` command with the `-k` (or `--bucketkey`) option to specify the encryption key:
+
+```shell
+ozone sh bucket create --bucketkey <key_name> /<volume_name>/<bucket_name>
+```
+
+For example:
+
+```shell
+ozone sh bucket create --bucketkey enckey /vol1/encrypted_bucket
+```
+
+Now, all data written to `/vol1/encrypted_bucket` will be encrypted at rest. As long as the client is configured correctly to use the key, such encryption is completely transparent to the end users.
+
+## Performance Optimization for TDE
+
+Since Ozone leverages Hadoop's encryption library, performance optimization strategies similar to HDFS encryption apply:
+
+:::warning Hardware Acceleration: Architecture Support
+The OpenSSL-based hardware acceleration discussed below is currently only supported on x86 architectures. ARM64 architectures are not supported at this time.
+:::
+
+1. **Enable AES-NI Hardware Acceleration:**
+ - Install OpenSSL development libraries: On most Linux distributions, install `openssl-devel` (or `libssl-dev` on Debian/Ubuntu) to provide `libcrypto.so`, which is utilized by the Hadoop native library for hardware-accelerated encryption.
+ - Use servers with CPUs that support the AES-NI instruction set and RDRAND instruction (most modern Intel and AMD CPUs do)
+
+2. **Install and Configure Native Libraries:**
+ - Ensure that the native `libhadoop.so` library is properly installed
+
+ ```shell
+ ozone debug checknative
+ ```
+
+ - The output should show "true" for the Hadoop library
+ - To troubleshoot native library loading issues on Ozone Datanode and applications, configure their log level to DEBUG. The log messages below are examples, and actual paths may vary. The following log message indicates that the libhadoop native library fails to load:
+
+ ```bash
+ 25/06/14 01:25:21 DEBUG util.NativeCodeLoader: Trying to load the custom-built native-hadoop library...
+ 25/06/14 01:25:21 DEBUG util.NativeCodeLoader: Failed to load native-hadoop with error: java.lang.UnsatisfiedLinkError: no hadoop in java.library.path
+ 25/06/14 01:25:21 DEBUG util.NativeCodeLoader: java.library.path=/opt/hadoop/lib/native:/usr/java/packages/lib/amd64:/usr/lib64:/lib64:/lib:/usr/lib
+ 25/06/14 01:25:21 WARN util.NativeCodeLoader: Unable to load native-hadoop library for your platform... using builtin-java classes where applicable
+ ```
+
+ - And the following log message indicates OpenSSL library fails to load:
+
+ ```bash
+ 25/06/14 01:18:53 DEBUG crypto.OpensslCipher: Failed to load OpenSSL Cipher.
+ java.lang.UnsatisfiedLinkError: Cannot load libcrypto.so (libcrypto.so: cannot open shared object file: No such file or directory)!
+ at org.apache.hadoop.crypto.OpensslCipher.initIDs(Native Method)
+ at org.apache.hadoop.crypto.OpensslCipher.<clinit>(OpensslCipher.java:89)
+ at org.apache.hadoop.crypto.OpensslAesCtrCryptoCodec.<init>(OpensslAesCtrCryptoCodec.java:50)
+ ```
+
+3. **Validate Hardware Acceleration:**
+ - To verify if AES-NI is being utilized, check OpenSSL acceleration:
+
+ ```shell
+ openssl speed -evp aes-256-ctr
+ ```
+
+## Using Transparent Data Encryption from S3G
+
+Ozone’s S3 Gateway (S3G) allows you to access encrypted buckets. However, it's important to note that **Ozone does not support S3-SSE (Server-Side Encryption) or S3-CSE (Client-Side Encryption) in the way AWS S3 does.** That said, Ozone S3 buckets can be encrypted using Ranger KMS or Hadoop KMS to provide a guarantee similar to S3-SSE with client-supplied keys (SSE-C).
+
+When creating an encrypted bucket that will be accessed via S3G:
+
+1. **Create the bucket under the `/s3v` volume:**
+ The `/s3v` volume is the default volume for S3 buckets.
+
+ ```shell
+ ozone sh bucket create --bucketkey <key_name> /s3v/<bucket_name> --layout=OBJECT_STORE
+ ```
+
+2. **Alternatively, create an encrypted bucket elsewhere and link it:**
+
+ ```shell
+ ozone sh bucket create --bucketkey <key_name> /<volume_name>/<bucket_name> --layout=OBJECT_STORE
+ ozone sh bucket link /<volume_name>/<bucket_name> /s3v/<link_name>
+ ```
+
+Note 1: An encrypted bucket cannot be created via S3 APIs. It must be done using Ozone shell commands as shown above.
+After creating an encrypted bucket, all the keys added to this bucket using s3g will be encrypted.
+
+Note 2: `--layout=OBJECT_STORE` is specified in the above examples
+for full compatibility with S3 (which is the default value for the `--layout`
+argument, but explicitly added here to make a point).
+
+Bucket created with the `OBJECT_STORE` type will NOT be accessible via
+HCFS (ofs or o3fs) at all. And such access will be rejected. For instance:
+
+```bash
+$ ozone fs -ls ofs://ozone1/s3v/encryptedbucket/
+-ls: Bucket: encryptedbucket has layout: OBJECT_STORE, which does not support file system semantics. Bucket Layout must be FILE_SYSTEM_OPTIMIZED or LEGACY.
+```
+
+```bash
+$ ozone fs -ls o3fs://encryptedbucket.s3v.ozone1/
+22/02/07 00:00:00 WARN fs.FileSystem: Failed to initialize fileystem o3fs://encryptedbucket.s3v.ozone1/: java.lang.IllegalArgumentException: Bucket: encryptedbucket has layout: OBJECT_STORE, which does not support file system semantics. Bucket Layout must be FILE_SYSTEM_OPTIMIZED or LEGACY.
+-ls: Bucket: encryptedbucket has layout: OBJECT_STORE, which does not support file system semantics. Bucket Layout must be FILE_SYSTEM_OPTIMIZED or LEGACY.
+```
+
+If one wants the bucket to be accessible from both S3G and HCFS (ofs and o3fs)
+at the same time, use `--layout=FILE_SYSTEM_OPTIMIZED` instead.
+
+However, in buckets with `FILE_SYSTEM_OPTIMIZED` layout, some irregular S3 key
+names may be rejected or normalized, which can be undesired.
+
+<!--
+See [Prefix based File System Optimization](../../../../system-internals/features/filesystem-optimization) for more information.
+-->
+
+When accessing an S3G-enabled encrypted bucket:
+
+The below three configurations must be added to the kms-site.xml to allow the S3Gateway principal to act as a proxy for other users. In this example,
+`ozone.s3g.kerberos.principal` is assumed to be `s3g`
+
+```xml
+<property>
+ <name>hadoop.kms.proxyuser.s3g.users</name>
+ <value>user1,user2,user3</value>
+ <description>
+ Specifies the list of users that the S3 Gateway (`s3g`) is allowed to impersonate when interacting with the KMS. Use `*` to allow all users.
+ </description>
+</property>
+<property>
+ <name>hadoop.kms.proxyuser.s3g.groups</name>
+ <value>group1,group2,group3</value>
+ <description>
+ Specifies the list of groups whose members `s3g` is allowed to impersonate when making requests to the KMS. Use `*` to allow all groups.
+ </description>
+</property>
+<property>
+ <name>hadoop.kms.proxyuser.s3g.hosts</name>
+ <value>s3g-host1.com</value>
+ <description>
+ Specifies the hostnames or IPs from which `s3g` is permitted to send proxy requests to the KMS. Use `*` to allow all hosts.
+ </description>
+</property>
+```
+
+## KMS Authorization
+
+Key Management Servers (KMS) may enforce key access authorization. **Hadoop KMS supports ACLs (Access Control Lists) for fine-grained permission control, while Ranger KMS supports Ranger policies for encryption keys.** Ensure that the appropriate users have the necessary permissions based on the KMS type in use.
+
+For example, when using Ranger KMS for authorization, to allow the user `om` (the Ozone Manager user) to access the key `enckey` and the user `hdfs` (a typical HDFS service user) to manage keys, you might have policies in Ranger KMS like:
+
+- **Policy for `om` user (or the user running the Ozone Manager):**
+ - Resource: `keyname=enckey`
+ - Permissions: `DECRYPT_EEK` (Decrypt Encrypted Encryption Key)
+- **Policy for S3 Gateway proxy user (e.g., the user specified in `ozone.s3g.kerberos.principal`, typically `s3g`):**
+ - Resource: `keyname=enckey` (or specific keys for S3 buckets)
+ - Permissions: `DECRYPT_EEK`
+- **Policy for administrative users (e.g., `hdfs` or a key admin group):**
+ - Resource: `keyname=*` (or specific keys)
+ - Permissions: `CREATE_KEY`, `DELETE_KEY`, `GET_KEYS`, `ROLL_NEW_VERSION`
+
+Refer to the Ranger documentation for detailed instructions on configuring KMS policies if you are using Ranger KMS. For Hadoop KMS, consult its [Hadoop KMS documentation](https://hadoop.apache.org/docs/r3.4.1/hadoop-kms/index.html#ACLs_.28Access_Control_Lists.29) for managing ACLs.
+
+## Additional References
+
+- For more background on Transparent Data Encryption concepts, you can refer to the [Transparent Encryption in HDFS documentation](https://hadoop.apache.org/docs/current/hadoop-project-dist/hadoop-hdfs/TransparentEncryption.html).
+- For detailed information on Hadoop KMS, see the [Hadoop KMS documentation](https://hadoop.apache.org/docs/r3.4.1/hadoop-kms/index.html).
+- For OpenSSL crypto performance tuning, refer to [Intel's AES-NI optimization guide](https://software.intel.com/content/www/us/en/develop/articles/intel-advanced-encryption-standard-aes-instructions-set.html).
diff --git a/versioned_docs/version-2.2.1/05-administrator-guide/02-configuration/03-security/05-encryption/README.mdx b/versioned_docs/version-2.2.1/05-administrator-guide/02-configuration/03-security/05-encryption/README.mdx
new file mode 100644
index 0000000000..9ca98d1118
--- /dev/null
+++ b/versioned_docs/version-2.2.1/05-administrator-guide/02-configuration/03-security/05-encryption/README.mdx
@@ -0,0 +1,11 @@
+---
+sidebar_label: Encryption
+---
+
+# Encryption Configuration
+
+import DocCardList from '@theme/DocCardList';
+
+This section documents the different types of encryption supported by Ozone and how to configure them.
+
+<DocCardList/>
diff --git a/versioned_docs/version-2.2.1/05-administrator-guide/02-configuration/03-security/05-ranger.md b/versioned_docs/version-2.2.1/05-administrator-guide/02-configuration/03-security/05-ranger.md
new file mode 100644
index 0000000000..2302f49852
--- /dev/null
+++ b/versioned_docs/version-2.2.1/05-administrator-guide/02-configuration/03-security/05-ranger.md
@@ -0,0 +1,36 @@
+---
+sidebar_label: Apache Ranger
+---
+
+# Configuring Apache Ranger
+
+Apache Ranger™ is a framework to enable, monitor and manage comprehensive data security across the Hadoop platform and beyond. Apache Ranger has supported authorization for Ozone since version 2.0. However, due to improvements and bug fixes, using the [latest release](https://ranger.apache.org/download.html) is recommended.
+
+To use Apache Ranger, you must have Apache Ranger installed in your Hadoop Cluster. For installation instructions of Apache Ranger, please take a look at the [Apache Ranger website](https://ranger.apache.org/index.html).
+
+If you have a working Apache Ranger installation that is aware of Ozone, then configuring Ozone to work with Apache Ranger is trivial. You have to enable the ACLs support and set the acl authorizer class inside Ozone to be Ranger authorizer. Please add the following properties to the `ozone-site.xml`.
+
+| Property | Value |
+|----------|-------|
+| `ozone.acl.enabled` | `true` |
+| `ozone.acl.authorizer.class` | `org.apache.ranger.authorization.ozone.authorizer.RangerOzoneAuthorizer` |
+
+To use the `RangerOzoneAuthorizer`, you also need to add the following environment variables to `ozone-env.sh`:
+
+```bash
+export OZONE_MANAGER_CLASSPATH="${OZONE_HOME}/share/ozone/lib/libext/*"
+```
+
+## About the ranger-ozone-plugin JARs
+
+The *ranger-ozone-plugin JARs* are the Java libraries that come with the **Apache Ranger Ozone plugin**. They contain the implementation classes (for example `RangerOzoneAuthorizer`) that allow Ozone Manager to delegate authorization checks to Ranger.
+
+You obtain these JARs when you install Apache Ranger and enable the Ozone plugin; see the [Apache Ranger documentation](https://ranger.apache.org/) for installation steps. To make the plugin available to Ozone Manager, ensure that these JARs are on the Ozone Manager classpath. In the example above, the JARs are copied into `${OZONE_HOME}/share/ozone/lib/libext/` and that directory is added to `OZONE_MANAGER_CLASSPATH`.
+
+If your distribution installs the Ranger Ozone plugin into another directory, point `OZONE_MANAGER_CLASSPATH` to that location instead, for example:
+
+```bash
+export OZONE_MANAGER_CLASSPATH=/opt/ranger/ozone-plugin/lib/*
+```
+
+If Ranger is installed on a different host, copy the Ranger Ozone plugin JARs from that installation to a directory on the Ozone Manager host (such as `share/ozone/lib/libext/`) and reference that directory from `OZONE_MANAGER_CLASSPATH` so that Ozone Manager can load the plugin at startup.
diff --git a/versioned_docs/version-2.2.1/05-administrator-guide/02-configuration/03-security/06-securing-s3-secrets.md b/versioned_docs/version-2.2.1/05-administrator-guide/02-configuration/03-security/06-securing-s3-secrets.md
new file mode 100644
index 0000000000..01c2bdfd37
--- /dev/null
+++ b/versioned_docs/version-2.2.1/05-administrator-guide/02-configuration/03-security/06-securing-s3-secrets.md
@@ -0,0 +1,112 @@
+---
+sidebar_label: Securing S3 Secrets
+---
+
+# External S3 Secret Storage with HashiCorp Vault
+
+By default, S3 secrets are stored in the Ozone Manager’s RocksDB. For enhanced security, Ozone can be configured to use HashiCorp Vault as an external secret storage backend.
+
+## Configuration
+
+To enable Vault integration, you need to configure the following properties in `ozone-site.xml`:
+
+| Property | Description |
+| --------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
+| `ozone.secret.s3.store.provider` | The S3 secret storage provider to use. Set this to `org.apache.hadoop.ozone.s3.remote.vault.VaultS3SecretStorageProvider` to enable Vault. |
+| `ozone.secret.s3.store.remote.vault.address` | The address of the Vault server (e.g., `http://vault:8200`). |
+| `ozone.secret.s3.store.remote.vault.namespace` | The Vault namespace to use. |
+| `ozone.secret.s3.store.remote.vault.enginever` | The version of the Vault secrets engine (e.g., `2`). |
+| `ozone.secret.s3.store.remote.vault.secretpath` | The path where the secrets are stored in Vault. |
+| `ozone.secret.s3.store.remote.vault.auth` | The authentication method to use with Vault. Supported values are `TOKEN` and `APPROLE`. |
+| `ozone.secret.s3.store.remote.vault.auth.token` | The Vault authentication token. Required if `ozone.secret.s3.store.remote.vault.auth` is set to `TOKEN`. |
+| `ozone.secret.s3.store.remote.vault.auth.approle.id` | The AppRole RoleID. Required if `ozone.secret.s3.store.remote.vault.auth` is set to `APPROLE`. |
+| `ozone.secret.s3.store.remote.vault.auth.approle.secret` | The AppRole SecretID. Required if `ozone.secret.s3.store.remote.vault.auth` is set to `APPROLE`. |
+| `ozone.secret.s3.store.remote.vault.auth.approle.path` | The AppRole path. Required if `ozone.secret.s3.store.remote.vault.auth` is set to `APPROLE`. |
+| `ozone.secret.s3.store.remote.vault.trust.store.type` | The type of the trust store (e.g., `JKS`). |
+| `ozone.secret.s3.store.remote.vault.trust.store.path` | The path to the trust store file. |
+| `ozone.secret.s3.store.remote.vault.trust.store.password` | The password for the trust store. |
+| `ozone.secret.s3.store.remote.vault.key.store.type` | The type of the key store (e.g., `JKS`). |
+| `ozone.secret.s3.store.remote.vault.key.store.path` | The path to the key store file. |
+| `ozone.secret.s3.store.remote.vault.key.store.password` | The password for the key store. |
+
+## Example
+
+Here is an example of how to configure Ozone to use Vault for S3 secret storage with token authentication:
+
+```xml
+<property>
+ <name>ozone.secret.s3.store.provider</name>
+ <value>org.apache.hadoop.ozone.s3.remote.vault.VaultS3SecretStorageProvider</value>
+</property>
+<property>
+ <name>ozone.secret.s3.store.remote.vault.address</name>
+ <value>http://localhost:8200</value>
+</property>
+<property>
+ <name>ozone.secret.s3.store.remote.vault.enginever</name>
+ <value>2</value>
+</property>
+<property>
+ <name>ozone.secret.s3.store.remote.vault.secretpath</name>
+ <value>secret</value>
+</property>
+<property>
+ <name>ozone.secret.s3.store.remote.vault.auth</name>
+ <value>TOKEN</value>
+</property>
+<property>
+ <name>ozone.secret.s3.store.remote.vault.auth.token</name>
+ <value>your-vault-token</value>
+</property>
+```
+
+## Example with SSL
+
+Here is an example of how to configure Ozone to use Vault for S3 secret storage with SSL:
+
+```xml
+<property>
+ <name>ozone.secret.s3.store.provider</name>
+ <value>org.apache.hadoop.ozone.s3.remote.vault.VaultS3SecretStorageProvider</value>
+</property>
+<property>
+ <name>ozone.secret.s3.store.remote.vault.address</name>
+ <value>https://localhost:8200</value>
+</property>
+<property>
+ <name>ozone.secret.s3.store.remote.vault.enginever</name>
+ <value>2</value>
+</property>
+<property>
+ <name>ozone.secret.s3.store.remote.vault.secretpath</name>
+ <value>secret</value>
+</property>
+<property>
+ <name>ozone.secret.s3.store.remote.vault.auth</name>
+ <value>TOKEN</value>
+</property>
+<property>
+ <name>ozone.secret.s3.store.remote.vault.auth.token</name>
+ <value>your-vault-token</value>
+</property>
+<property>
+ <name>ozone.secret.s3.store.remote.vault.trust.store.path</name>
+ <value>/path/to/truststore.jks</value>
+</property>
+<property>
+ <name>ozone.secret.s3.store.remote.vault.trust.store.password</name>
+ <value>truststore-password</value>
+</property>
+<property>
+ <name>ozone.secret.s3.store.remote.vault.key.store.path</name>
+ <value>/path/to/keystore.jks</value>
+</property>
+<property>
+ <name>ozone.secret.s3.store.remote.vault.key.store.password</name>
+ <value>keystore-password</value>
+</property>
+```
+
+## References
+
+- [HashiCorp Vault Documentation](https://developer.hashicorp.com/vault/docs)
diff --git a/versioned_docs/version-2.2.1/05-administrator-guide/02-configuration/03-security/README.mdx b/versioned_docs/version-2.2.1/05-administrator-guide/02-configuration/03-security/README.mdx
new file mode 100644
index 0000000000..b91f8f6945
--- /dev/null
+++ b/versioned_docs/version-2.2.1/05-administrator-guide/02-configuration/03-security/README.mdx
@@ -0,0 +1,11 @@
+---
+sidebar_label: Security
+---
+
+# Security Configuration
+
+import DocCardList from '@theme/DocCardList';
+
+This section documents how to configure a secure Ozone cluster in a production environment.
+
+<DocCardList/>
diff --git a/versioned_docs/version-2.2.1/05-administrator-guide/02-configuration/04-performance/01-placeholder.md b/versioned_docs/version-2.2.1/05-administrator-guide/02-configuration/04-performance/01-placeholder.md
new file mode 100644
index 0000000000..6f2c1e3d87
--- /dev/null
+++ b/versioned_docs/version-2.2.1/05-administrator-guide/02-configuration/04-performance/01-placeholder.md
@@ -0,0 +1,71 @@
+---
+sidebar_label: Production Deployment
+---
+
+# Production Deployment
+
+This document provides guidance on the requirements and best practices for a production deployment of Apache Ozone.
+
+## Ozone Components
+
+A typical production Ozone cluster includes the following services:
+
+- **Ozone Manager (OM)**: Manages the namespace and metadata of the Ozone cluster. A production cluster requires 3 OM instances for high availability.
+- **Storage Container Manager (SCM)**: Manages the data nodes and pipelines. A production cluster requires 3 SCM instances for high availability.
+- **Datanode**: Stores the actual data in containers. A production cluster requires at least 3 Datanodes.
+- **Recon**: A web-based UI for monitoring and managing the Ozone cluster. A Recon server is strongly recommended, though not required.
+- **S3 Gateway (S3G)**: An S3-compatible gateway for accessing Ozone. Multiple S3 Gateway instances are strongly recommended to load balance S3 traffic.
+- **HttpFS**: An WebHDFS-compatible API for accessing Ozone. This is an optional component.
+
+## Requirements
+
+### System Requirements
+
+- **Hardware**: Bare metal machines are recommended for optimal performance. Virtual machines or containers are not recommended for production deployments.
+- **Operating System**: Linux (recommended distributions: Red Hat 8/Rocky 8+, Ubuntu, SUSE; supported architectures: x86/ARM).
+- **Java Development Kit (JDK)**: Version 8 or higher.
+- **Time Synchronization**: A time synchronization service such as Chrony or ntpd must be enabled to prevent time drift.
+
+### Memory Requirements
+
+- **Ozone Manager (OM), Storage Container Manager (SCM), and Recon**: Recommended heap size in large production clusters is 64GB.
+- **Datanode, S3 Gateway, and HttpFS**: Recommended heap size is 31GB.
+
+### Storage Requirements
+
+- **Ozone Manager (OM), Storage Container Manager (SCM), and Recon Metadata Storage**: Use SAS SSD or NVMe SSD for metadata (RocksDB and Ratis) to ensure optimal performance. It is recommended to use RAID 1 (disk mirroring) for the metadata disks to protect against disk failures.
+- **Datanode Storage**:
+ - **Ratis Log**: Use SAS SSD or NVMe SSD for the Ratis log directory for low latency writes.
+ - **Container Data**: Hard disks are acceptable for container data storage.
+ - **Disk Configuration**: It is recommended to use a JBOD (Just a Bunch Of Disks) configuration instead of RAID. Ozone is a replicated distributed storage system and handles data redundancy. Using RAID can decrease performance without providing additional data protection benefits.
+- **Storage Type**: Use direct-attached storage. Do not use Network Attached Storage (NAS) or Storage Area Network (SAN).
+
+### Network Requirements
+
+- **Network Bandwidth**: A minimum of 25Gbps network card bandwidth is recommended.
+- **Network Topology**: A leaf-spine network topology with an oversubscription ratio below 3:1 is recommended for predictable performance.
+
+### Security Requirements (Optional but Recommended)
+
+- **Kerberos**: A Kerberos environment, including a Key Distribution Center (KDC), is recommended for enhanced security.
+
+## Recommended Configurations
+
+### Linux Kernel
+
+- **CPU Governor**: Set the CPU scaling driver to `performance` mode to maximize performance.
+- **Transparent Hugepage**: Disable Transparent Hugepage to avoid performance issues.
+- **SELinux**: Disable SELinux.
+- **Swappiness**: Set `vm.swappiness=1` to minimize swapping.
+
+### Local File System
+
+- **LVM**: Disable Logical Volume Manager (LVM) for data drives.
+- **File System**: Use `ext4` or `xfs` file systems.
+- **Mount Options**: Mount drives with the `noatime` option to reduce unnecessary disk writes. For SSDs, also add the `discard` option.
+
+### Ozone Configuration
+
+- **Monitoring**: Install [Prometheus](../../operations/observability/prometheus) and [Grafana](../../operations/observability/grafana) for monitoring the Ozone cluster. For audit logs, consider using a log ingestion framework such as the ELK Stack (Elasticsearch, Logstash, and Kibana) with FileBeat, or other similar frameworks. Alternatively, you can use Apache Ranger to manage audit logs.
+- **Pipeline Limits**: Increase the number of allowed write pipelines to better suit your workload by adjusting `ozone.scm.datanode.pipeline.limit`. See the [Multi-Raft](./multi-raft) documentation for the formula to calculate appropriate pipeline limits based on your metadata disk configuration.
+- **Heap Sizes**: Configure sufficient heap sizes for Ozone Manager (OM), Storage Container Manager (SCM), Recon, Datanode, S3 Gateway (S3G), and HttpFS services to ensure stability.
diff --git a/versioned_docs/version-2.2.1/05-administrator-guide/02-configuration/04-performance/02-topology.md b/versioned_docs/version-2.2.1/05-administrator-guide/02-configuration/04-performance/02-topology.md
new file mode 100644
index 0000000000..4111053d06
--- /dev/null
+++ b/versioned_docs/version-2.2.1/05-administrator-guide/02-configuration/04-performance/02-topology.md
@@ -0,0 +1,207 @@
+---
+sidebar_label: Topology
+---
+
+# Configuring Network Topology
+
+Apache Ozone uses topology information (e.g., rack placement) to optimize data access and improve resilience. A fully rack-aware cluster needs:
+
+1. Configured network topology.
+2. Topology-aware Datanode selection for container replica placement (write path).
+3. Pipeline choosing policy to load balance write traffic.
+4. Prioritized reads from topologically closest Datanodes (read path).
+
+## Applicability to Container Types
+
+Ozone's topology-aware strategies apply differently depending on the operation:
+
+- **Write Path (Open Containers):** When a client writes data, topology awareness is used during **pipeline creation** to ensure the set of Datanodes forming the pipeline are on different racks. This provides fault tolerance for the initial write.
+- **Re-replication Path (Closed Containers):** When a replica of a **closed** container is needed (due to node failure, decommissioning, or balancing), a topology-aware policy is used to select the best Datanode for the new replica.
+
+See the [page about Containers](../../../core-concepts/replication/storage-containers) for more information related to Open vs Closed containers.
+
+## Configuring Topology Hierarchy
+
+Ozone determines Datanode network locations (e.g., racks) using Hadoop's rack awareness, configured via `net.topology.node.switch.mapping.impl` in `ozone-site.xml`. This key specifies a `org.apache.hadoop.net.CachedDNSToSwitchMapping` implementation. [1]
+
+:::note
+Both Ozone Manager (OM) and Storage Container Manager (SCM) use network topology information. It is critical to maintain a consistent topology assignment across all OM and SCM instances in the cluster.
+:::
+
+Two primary methods exist:
+
+### 1. Static List: `TableMapping`
+
+This is the non-default implementation for static mapping. It maps IPs/hostnames to racks using a predefined file. If no mapping file is specified, or if a Datanode is not found in the file, it is assigned to `/default-rack`.
+
+- **Configuration:** Set `net.topology.node.switch.mapping.impl` to `org.apache.hadoop.net.TableMapping` and `net.topology.table.file.name` to the mapping file's path. [1]
+
+ ```xml
+ <property>
+ <name>net.topology.node.switch.mapping.impl</name>
+ <value>org.apache.hadoop.net.TableMapping</value>
+ </property>
+ <property>
+ <name>net.topology.table.file.name</name>
+ <value>/etc/ozone/topology.map</value>
+ </property>
+ ```
+
+- **File Format:** A two-column text file (IP/hostname, rack path per line). [1]
+ Example `topology.map`:
+
+ ```text
+ 192.168.1.100 /rack1
+ datanode101.example.com /rack1
+ 192.168.1.102 /rack2
+ datanode103.example.com /rack2
+ ```
+
+### 2. Dynamic List: `ScriptBasedMapping` (Default)
+
+This is the default implementation. It uses an external script to resolve rack locations for IPs.
+
+- **Configuration:** Set `net.topology.node.switch.mapping.impl` to `org.apache.hadoop.net.ScriptBasedMapping` and `net.topology.script.file.name` to the script's path. [1]
+
+ ```xml
+ <property>
+ <name>net.topology.node.switch.mapping.impl</name>
+ <value>org.apache.hadoop.net.ScriptBasedMapping</value>
+ </property>
+ <property>
+ <name>net.topology.script.file.name</name>
+ <value>/etc/ozone/determine_rack.sh</value>
+ </property>
+ ```
+
+- **Script:** Admin-provided, executable script. Ozone passes IPs (up to `net.topology.script.number.args`, default 100) as arguments; script outputs rack paths (one per line).
+ Example `determine_rack.sh`:
+
+ ```bash
+ #!/bin/bash
+ # This is a simplified example. A real script might query a CMDB or use other logic.
+ while [ $# -gt 0 ] ; do
+ nodeAddress=$1
+ if [[ "$nodeAddress" == "192.168.1.100" || "$nodeAddress" == "datanode101.example.com" ]]; then
+ echo "/rack1"
+ elif [[ "$nodeAddress" == "192.168.1.102" || "$nodeAddress" == "datanode103.example.com" ]]; then
+ echo "/rack2"
+ else
+ echo "/default-rack"
+ fi
+ shift
+ done
+ ```
+
+Ensure the script is executable (`chmod +x /etc/ozone/determine_rack.sh`).
+
+**Note:** For production environments, implement robust error handling and validation in your script. This should include handling network timeouts, invalid inputs, CMDB query failures, and logging errors appropriately. The example above is simplified for illustration purposes only.
+
+**Topology Mapping Best Practices:**
+
+- **Accuracy:** Mappings must be accurate and current.
+- **Static Mapping:** Simpler for small, stable clusters; requires manual updates.
+- **Dynamic Mapping:** Flexible for large/dynamic clusters. Script performance, correctness, and reliability are vital; ensure it's idempotent and handles batch lookups efficiently.
+
+## Placement and Selection Policies
+
+Ozone uses three distinct types of policies to manage how and where data is written.
+
+### 1. Pipeline Creation Policy
+
+This policy selects a set of Datanodes to form a new pipeline. Its purpose is to ensure new pipelines are internally fault-tolerant by spreading their nodes across racks, while also balancing the number of pipelines across the Datanodes. This is the primary mechanism for topology awareness on the write path for open containers.
+
+The policy is configured by the `ozone.scm.pipeline.placement.impl` property in `ozone-site.xml`.
+
+- **`PipelinePlacementPolicy` (Default)**
+
+ - **Function:** This is the default and only supported policy for pipeline creation. It chooses Datanodes based on load balancing (pipeline count per node) and network topology. It filters out nodes that are too heavily engaged in other pipelines and then selects nodes to ensure rack diversity. This policy is recommended for most production environments.
+ - **Use Cases:** General purpose pipeline creation in a rack-aware cluster.
+
+### 2. Pipeline Selection (Load Balancing) Policy
+
+After a pool of healthy, open, and rack-aware pipelines has been created, this policy is used to **select one** of them to handle a client's write request. Its purpose is **load balancing**, not topology awareness, as the topology has already been handled during pipeline creation.
+
+The policy is configured by `hdds.scm.pipeline.choose.policy.impl` in `ozone-site.xml` for Ratis containers, and `hdds.scm.ec.pipeline.choose.policy.impl` for EC containers. All of the following policies are supported by both Ratis and EC containers.
+
+- **`RandomPipelineChoosePolicy` (Default):** Selects a pipeline at random from the available list. This policy is simple and distributes load without considering other metrics.
+- **`CapacityPipelineChoosePolicy`:** Picks two random pipelines and selects the one with lower utilization, favoring pipelines with more available capacity.
+- **`RoundRobinPipelineChoosePolicy`:** Selects pipelines in a round-robin order. This is mainly for debugging and testing.
+- **`HealthyPipelineChoosePolicy`:** Randomly selects pipelines but only returns a healthy one.
+
+Note: When configuring these values, include the full class name prefix: for example, `org.apache.hadoop.hdds.scm.pipeline.choose.algorithms.CapacityPipelineChoosePolicy`
+
+### 3. Closed Container Replication Policy
+
+#### Ratis containers
+
+This is configured using the `ozone.scm.container.placement.impl` property in `ozone-site.xml` for Ratis containers. The available policies are:
+
+- **`SCMContainerPlacementRackAware` (Default)**
+
... 11369 lines suppressed ...
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@ozone.apache.org
For additional commands, e-mail: commits-help@ozone.apache.org