jojochuang commented on code in PR #178:
URL: https://github.com/apache/ozone-site/pull/178#discussion_r2655752858


##########
docs/05-administrator-guide/02-configuration/04-performance/02-topology.md:
##########
@@ -4,4 +4,197 @@ sidebar_label: Topology
 
 # Configuring Network Topology
 
-**TODO:** File a subtask under 
[HDDS-9859](https://issues.apache.org/jira/browse/HDDS-9859) and complete this 
page or section.
+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. 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]
+
+Two primary methods exist:
+
+### 1. Static List: `TableMapping`

Review Comment:
   Looks like TableMapping is the default value. If an assignment is not 
specified, all nodes are assigned to /default-rack.
   
   The description in ozone-default.xml is not correct: 
https://github.com/apache/ozone/blob/8eaca4c3bf2972a7e9f84062ff4c1d49fa2ea6db/hadoop-hdds/common/src/main/resources/ozone-default.xml#L4858-L4868
   
   We should also make it clear that the topology assignment is used by OM and 
SCM and it's crucial to ensure the assignments are consistent between the two 
roles (and on all instances)



##########
docs/05-administrator-guide/02-configuration/04-performance/02-topology.md:
##########
@@ -4,4 +4,197 @@ sidebar_label: Topology
 
 # Configuring Network Topology
 
-**TODO:** File a subtask under 
[HDDS-9859](https://issues.apache.org/jira/browse/HDDS-9859) and complete this 
page or section.
+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. 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]
+
+Two primary methods exist:
+
+### 1. Static List: `TableMapping`
+
+Maps IPs/hostnames to racks using a predefined file.
+
+- **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). 
Unlisted nodes go to `/default-rack`. [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`
+
+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`.
+
+- **`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
+
+This is configured using the `ozone.scm.container.placement.impl` property in 
`ozone-site.xml`. The available policies are:
+
+- **`SCMContainerPlacementRackAware` (Default)**
+
+  - **Function:** Distributes the Datanodes of a pipeline across racks for 
fault tolerance (e.g., for a 3-node pipeline, it aims for at least two racks). 
Similar to HDFS placement. [1]
+  - **Use Cases:** Production clusters needing rack-level fault tolerance.
+  - **Limitations:** Designed for single-layer rack topologies (e.g., 
`/rack/node`). Not recommended for multi-layer hierarchies (e.g., 
`/dc/row/rack/node`) as it may not interpret deeper levels correctly. [1]
+
+- **`SCMContainerPlacementRandom`**
+
+  - **Function:** Randomly selects healthy, available Datanodes, ignoring rack 
topology. [3]
+  - **Use Cases:** Small/dev/test clusters where rack fault tolerance is not 
critical.
+
+- **`SCMContainerPlacementCapacity`**
+  
+  - **Function:** Selects Datanodes by available capacity (favors lower disk 
utilization) to balance disk usage across the cluster. [4]
+  - **Use Cases:** Heterogeneous storage clusters or where even disk 
utilization is key.
+
+Note: When configuring these values, include the full class name prefix: for 
example, 
`org.apache.hadoop.hdds.scm.container.placement.algorithms.SCMContainerPlacementCapacity`
+
+## Container Placement for Erasure Coded (EC) Containers
+
+For Erasure Coded (EC) containers, SCM employs a specialized placement policy 
to ensure data resilience and availability by distributing data and parity 
blocks across multiple racks. This is configured using the 
`ozone.scm.container.placement.ec.impl.key` property in `ozone-site.xml`.
+
+### 1. `SCMContainerPlacementRackScatter` (Default)
+
+- **Function:** This is the default policy for EC containers. It attempts to 
place each block (both data and parity) of an EC container on a different rack. 
For example, for an RS-6-3-1024k container (6 data blocks + 3 parity blocks), 
this policy will try to place the 9 blocks on 9 different racks. This "scatter" 
approach maximizes the fault tolerance, as the loss of a single rack will not 
impact more than one block of the container. [5]
+- **Use Cases:** This policy is highly recommended for production clusters 
using Erasure Coding to protect against rack-level failures.
+- **Configuration:**
+
+    ```xml
+    <property>
+      <name>ozone.scm.container.placement.ec.impl.key</name>
+      
<value>org.apache.hadoop.hdds.scm.container.placement.algorithms.SCMContainerPlacementRackScatter</value>
+    </property>
+    ```
+
+- **Behavior:** If the number of available racks is less than the number of 
blocks in the EC group, the policy will start placing more than one block on 
the same rack, while trying to keep the distribution as even as possible.
+- **Limitations:** Similar to `SCMContainerPlacementRackAware`, this policy is 
designed for single-layer rack topologies (e.g., `/rack/node`) and is not 
recommended for multi-layer hierarchies.
+
+## Optimizing Read Paths
+
+Enable by setting `ozone.network.topology.aware.read` to `true` in 
`ozone-site.xml`. [1]

Review Comment:
   This is enabled by default since Ozone 1.4.0: 
[HDDS-8300](https://issues.apache.org/jira/browse/HDDS-8300)



##########
docs/05-administrator-guide/02-configuration/04-performance/02-topology.md:
##########
@@ -4,4 +4,197 @@ sidebar_label: Topology
 
 # Configuring Network Topology
 
-**TODO:** File a subtask under 
[HDDS-9859](https://issues.apache.org/jira/browse/HDDS-9859) and complete this 
page or section.
+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. 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]
+
+Two primary methods exist:
+
+### 1. Static List: `TableMapping`
+
+Maps IPs/hostnames to racks using a predefined file.
+
+- **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). 
Unlisted nodes go to `/default-rack`. [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`
+
+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`.
+
+- **`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
+
+This is configured using the `ozone.scm.container.placement.impl` property in 
`ozone-site.xml`. The available policies are:
+
+- **`SCMContainerPlacementRackAware` (Default)**
+
+  - **Function:** Distributes the Datanodes of a pipeline across racks for 
fault tolerance (e.g., for a 3-node pipeline, it aims for at least two racks). 
Similar to HDFS placement. [1]
+  - **Use Cases:** Production clusters needing rack-level fault tolerance.
+  - **Limitations:** Designed for single-layer rack topologies (e.g., 
`/rack/node`). Not recommended for multi-layer hierarchies (e.g., 
`/dc/row/rack/node`) as it may not interpret deeper levels correctly. [1]
+
+- **`SCMContainerPlacementRandom`**
+
+  - **Function:** Randomly selects healthy, available Datanodes, ignoring rack 
topology. [3]
+  - **Use Cases:** Small/dev/test clusters where rack fault tolerance is not 
critical.
+
+- **`SCMContainerPlacementCapacity`**
+  
+  - **Function:** Selects Datanodes by available capacity (favors lower disk 
utilization) to balance disk usage across the cluster. [4]
+  - **Use Cases:** Heterogeneous storage clusters or where even disk 
utilization is key.
+
+Note: When configuring these values, include the full class name prefix: for 
example, 
`org.apache.hadoop.hdds.scm.container.placement.algorithms.SCMContainerPlacementCapacity`
+
+## Container Placement for Erasure Coded (EC) Containers

Review Comment:
   The EC pipeline choosing policy hdds.scm.ec.pipeline.choose.policy.impl is 
not mentioned.



##########
docs/05-administrator-guide/02-configuration/04-performance/02-topology.md:
##########
@@ -4,4 +4,197 @@ sidebar_label: Topology
 
 # Configuring Network Topology
 
-**TODO:** File a subtask under 
[HDDS-9859](https://issues.apache.org/jira/browse/HDDS-9859) and complete this 
page or section.
+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. 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]
+
+Two primary methods exist:
+
+### 1. Static List: `TableMapping`
+
+Maps IPs/hostnames to racks using a predefined file.
+
+- **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). 
Unlisted nodes go to `/default-rack`. [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`
+
+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

Review Comment:
   We should make it clear that the section 2 and section 3 are for Ratis 
(replicated) containers. Perhaps even refactor them into a sub-page.



##########
docs/05-administrator-guide/02-configuration/04-performance/02-topology.md:
##########
@@ -4,4 +4,197 @@ sidebar_label: Topology
 
 # Configuring Network Topology
 
-**TODO:** File a subtask under 
[HDDS-9859](https://issues.apache.org/jira/browse/HDDS-9859) and complete this 
page or section.
+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).

Review Comment:
   also: pipeline choosing policy.



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: [email protected]

For queries about this service, please contact Infrastructure at:
[email protected]


---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]

Reply via email to