diff --git a/keps/sig-network/4962-network-topology-standard/README.md b/keps/sig-network/4962-network-topology-standard/README.md index e2dee5592c4..6130a130c69 100644 --- a/keps/sig-network/4962-network-topology-standard/README.md +++ b/keps/sig-network/4962-network-topology-standard/README.md @@ -236,8 +236,6 @@ Consider including folks who also work outside the SIG or subproject. ## Design Details - - ### Reserved Network Types We have introduced reserved network types to better accommodate common network hierarchies. These reserved network types include the following predefined names and characteristics: @@ -252,7 +250,7 @@ The scheduler will prioritize switches according to the order outlined above, pr If provided, Network QoS Annotations can be used to refine and enhance the details of link performance, enabling more precise scheduling decisions. -#### Example of network topology representation with reserved network types: +#### Example 1: network topology representation with reserved network types: Consider the following network topology: @@ -260,7 +258,7 @@ Consider the following network topology: Let's examine node `vm12` as an example. This node is connected to NVSwitch `nvl10` and network switch `sw11`, which in turn is connected to switches `sw21` and `sw31`. In this case, the node labels would be: -``` +```yaml network.topology.kubernetes.io/accelerator: nvl10 network.topology.kubernetes.io/block: sw11 network.topology.kubernetes.io/datacenter: sw21 @@ -268,7 +266,7 @@ network.topology.kubernetes.io/zone: sw31 ``` If we have additional information such as latency and/or bandwidth between the node and the switches, it can be provided in an annotation: -``` +```yaml network.qos.kubernetes.io/switches: { "nvl10": { "latency": "2us", @@ -289,37 +287,91 @@ network.qos.kubernetes.io/switches: { } ``` +#### Example 2: network topology representation with reserved network types: + +Consider the following network topology: + +![Netwotk topology with reserved network types](./img/topo-reserved-labels2.png) + +Let's examine node `vm31` as an example. This node is connected to the top-of-rack switch `sw13`, which in turn is connected to switches `sw22` and `sw31`. + +In this case, the node labels would be: + +```yaml +network.topology.kubernetes.io/block: sw13 +network.topology.kubernetes.io/datacenter: sw22 +network.topology.kubernetes.io/zone: sw31 +``` + +Similar to the previous example, the optional QoS metrics can be provided in an annotation: + +```yaml +network.qos.kubernetes.io/switches: { + "sw13": { + "latency": "50us", + "bandwidth": "40Gbps" + }, + "sw22": { + "latency": "500us", + "bandwidth": "20Gbps" + }, + "sw31": { + "latency": "1ms", + "bandwidth": "10Gbps" + } +} +``` + ### Extensibility and Future-Proofing This proposal is designed with extensibility in mind, enabling the use of custom network types. This ensures that the standard can adapt to future advancements in cluster networking without requiring significant overhauls. For custom network types, Network QoS Annotations are required, with distance being the minimum mandatory metric. Specifying latency and bandwidth is optional, but including them can offer a more detailed view of link performance, enabling more efficient scheduling decisions. -#### Example of network topology with custom network types +#### Example 3: network topology representation with custom network types -##### Node Labels: -``` -network.topology.kubernetes.io/area: sw-a -network.topology.kubernetes.io/sector: block-b -network.topology.kubernetes.io/center: center-c +The same network topology depicted in Example 2 can be represented using custom network types. + +Let's use `tor` for top-of-rack switches, `area` for the second level of switches, and `center` for the third level. + +In this case, the node labels for node `vm31` would be: + +```yaml +network.topology.kubernetes.io/tor: sw13 +network.topology.kubernetes.io/area: sw22 +network.topology.kubernetes.io/center: sw31 ``` -##### Node Annotations: +The minimally required annotation would be: + +```yaml +network.qos.kubernetes.io/switches: { + "sw13": { + "distance": 1 + }, + "sw22": { + "distance": 2 + }, + "sw31": { + "distance": 3 + } +} ``` + +Optionally, the annotations might include additional QoS metrics: + +```yaml network.qos.kubernetes.io/switches: { - "sw-a": { + "sw13": { "distance": 1, - "latency": "100ns", "bandwidth": "40Gbps" }, - "block-b": { + "sw22": { "distance": 2, - "latency": "500ns", "bandwidth": "20Gbps" }, - "center-c": { + "sw31": { "distance": 3, - "latency": "1ms", "bandwidth": "10Gbps" } } diff --git a/keps/sig-network/4962-network-topology-standard/img/topo-reserved-labels2.png b/keps/sig-network/4962-network-topology-standard/img/topo-reserved-labels2.png new file mode 100644 index 00000000000..3a002087960 Binary files /dev/null and b/keps/sig-network/4962-network-topology-standard/img/topo-reserved-labels2.png differ