[docs] add rate simulatation to network chaos (#411)

* [docs] add rate simulatation to network chaos Signed-off-by: Balaji Arun <balaji@aptoslabs.com> * fix: reorganize some paragraphs Signed-off-by: Yue Yang <g1enyy0ung@gmail.com> --------- Signed-off-by: Balaji Arun <balaji@aptoslabs.com> Signed-off-by: Yue Yang <g1enyy0ung@gmail.com> Co-authored-by: Yue Yang <g1enyy0ung@gmail.com>
2024-01-26 16:30:01 -08:00 · 2024-01-26 16:30:01 -08:00 · 6dbead50b0
parent dfd17eae0d
commit 6dbead50b0
8 changed files with 61 additions and 14 deletions
--- a/docs/simulate-network-chaos-on-kubernetes.md
+++ b/docs/simulate-network-chaos-on-kubernetes.md
@ -39,7 +39,7 @@ Before creating NetworkChaos experiments, ensure the following:

 ## Create experiments using the YAML files

-### Net emulation example
+### Delay example

 1. Write the experiment configuration to the `network-delay.yaml` file, as shown below:

@ -136,24 +136,57 @@ Before creating NetworkChaos experiments, ensure the following:
   kubectl apply -f ./network-bandwidth.yaml
   ```

+### Network Emulation example
+
+1. Write the experiment configuration to the `netem.yaml` file, as shown below:
+
+   ```yaml
+   apiVersion: chaos-mesh.org/v1alpha1
+   kind: NetworkChaos
+   metadata:
+     name: network-emulation
+   spec:
+     action: netem
+     mode: all
+     selector:
+       namespaces:
+         - default
+       labelSelectors:
+         'app': 'web-show'
+     delay:
+       latency: '10ms'
+       correlation: '100'
+       jitter: '0ms'
+     rate:
+       rate: '10mbps'
+   ```
+
+   This configuration causes a latency of 10 milliseconds and a bandwidth limit of 10mbps in the network connections of the target Pods. In addition to latency and rate, the `netem` action also supports packet loss, reorder and corruption.
+
+2. After the configuration file is prepared, use `kubectl` to create an experiment:
+
+   ```bash
+   kubectl apply -f ./netem.yaml
+   ```
+
 ## Field description

 | Parameter | Type | Description | Default value | Required | Example |
 | --- | --- | --- | --- | --- | --- |
-| action | string | Indicates the specific fault type. Available types include: `netem`, `delay` (network delay), `loss` (packet loss), `duplicate` (packet duplicating), `corrupt` (packet corrupt), `partition` (network partition), and `bandwidth` (network bandwidth limit).After you specify `action` field, refer to [Description for `action`-related fields](#description-for-action-related-fields) for other necessary field configuration. | None | Yes | Partition |
+| action | string | Indicates the specific fault type. Available types include: `netem`, `delay` (network delay), `loss` (packet loss), `duplicate` (packet duplicating), `corrupt` (packet corrupt), `partition` (network partition), and `bandwidth` (network bandwidth limit). After you specify `action` field, refer to [Description for `action`-related fields](#description-for-action-related-fields) for other necessary field configuration. | None | Yes | Partition |
 | target | Selector | Used in combination with direction, making Chaos only effective for some packets. | None | No |  |
 | direction | enum | Indicates the direction of `target` packets. Available vaules include `from` (the packets from `target`), `to` (the packets to `target`), and `both` ( the packets from or to `target`). This parameter makes Chaos only take effect for a specific direction of packets. | to | No | both |
 | mode | string | Specifies the mode of the experiment. The mode options include `one` (selecting a random Pod), `all` (selecting all eligible Pods), `fixed` (selecting a specified number of eligible Pods), `fixed-percent` (selecting a specified percentage of Pods from the eligible Pods), and `random-max-percent` (selecting the maximum percentage of Pods from the eligible Pods). | None | Yes | `one` |
 | value | string | Provides a parameter for the `mode` configuration, depending on `mode`. For example, when `mode` is set to `fixed-percent`, `value` specifies the percentage of Pods. | None | No | 1 |
 | selector | struct | Specifies the target Pod. For details, refer to [Define the experiment scope](./define-chaos-experiment-scope.md). | None | Yes |  |
-| externalTargets | []string | Indicates the network targets except for Kubernetes, which can be IPv4 addresses or domains. This parameter only works with `direction: to`. | None | No | 1.1.1.1, www.google.com |
+| externalTargets | []string | Indicates the network targets except for Kubernetes, which can be IPv4 addresses or domains. This parameter only works with `direction: to`. | None | No | 1.1.1.1, google.com |
 | device | string | Specifies the affected network interface | None | No | "eth0" |

 ### Description for `action`-related fields

 For the Net Emulation and Bandwidth fault types, you can further configure the `action` related parameters according to the following description.

- Net Emulation type: `delay`, `loss`, `duplicated`, `corrupt`
+- Net Emulation type: `delay`, `loss`, `duplicated`, `corrupt`, `rate`
 - Bandwidth type: `bandwidth`

 #### delay
@ -224,10 +257,24 @@ Setting `action` to `corrupt` means simulating package corruption fault. You can

 For occasional events such as `reorder`, `loss`, `duplicate`, and `corrupt`, the `correlation` is more complicated. For specific model description, refer to [NetemCLG](http://web.archive.org/web/20200120162102/http://netgroup.uniroma2.it/twiki/bin/view.cgi/Main/NetemCLG).

+#### rate
+
+Setting `action` to `rate` means simulating bandwidth rate fault. This action is similar to [bandwidth/rate](#bandwidth) below, however, **the key distinction is that this action can combine with other `netem` actions listed above**. However, if you require more control over the bandwidth simulation such as limiting the buffer size, check the [bandwidth](#bandwidth) action.
+
+| Parameter | Type | Description | Default value | Required | Example |
+| --- | --- | --- | --- | --- | --- |
+| rate | string | Indicates the rate of bandwidth limit. Allows bit, kbit, mbit, gbit, tbit, bps, kbps, mbps, gbps, tbps unit. bps means bytes per second |  | Yes | 1mbps |
+
 #### bandwidth

 Setting `action` to `bandwidth` means simulating bandwidth limit fault. You also need to configure the following parameters.

+:::info
+
+This action is mutually exclusive with any `netem` action defined above. If you need to inject bandwidth rate along with other network failures such as corruption, use the [rate](#rate) action instead.
+
+:::
+
 | Parameter | Type | Description | Default value | Required | Example |
 | --- | --- | --- | --- | --- | --- |
 | rate | string | Indicates the rate of bandwidth limit. Allows bit, kbit, mbit, gbit, tbit, bps, kbps, mbps, gbps, tbps unit. bps means bytes per second |  | Yes | 1mbps |
--- a/i18n/zh/docusaurus-plugin-content-docs/current/simulate-network-chaos-on-kubernetes.md
+++ b/i18n/zh/docusaurus-plugin-content-docs/current/simulate-network-chaos-on-kubernetes.md
@ -144,7 +144,7 @@ NetworkChaos 用于模拟集群中网络故障的场景，目前支持以下几
 | mode | string | 指定实验的运行方式，可选择的方式包括：`one`（表示随机选出一个符合条件的 Pod）、`all`（表示选出所有符合条件的 Pod）、`fixed`（表示选出指定数量且符合条件的 Pod）、`fixed-percent`（表示选出占符合条件的 Pod 中指定百分比的 Pod）、`random-max-percent`（表示选出占符合条件的 Pod 中不超过指定百分比的 Pod） | 无 | 是 | `one` |
 | value | string | 取决与 `mode` 的配置，为 `mode` 提供对应的参数。例如，当你将 `mode` 配置为 `fixed-percent` 时，`value` 用于指定 Pod 的百分比 | 无 | 否 | 1 |
 | selector | struct | 指定注入故障的目标 Pod，详情请参考[定义实验范围](./define-chaos-experiment-scope.md) | 无 | 是 |  |
-| externalTargets | []string | 表示 Kubernetes 之外的网络目标, 可以是 IPv4 地址或者域名。只能与 `direction: to` 一起工作。 | 无 | 否 | 1.1.1.1, www.google.com |
+| externalTargets | []string | 表示 Kubernetes 之外的网络目标, 可以是 IPv4 地址或者域名。只能与 `direction: to` 一起工作。 | 无 | 否 | 1.1.1.1, google.com |
 | device | string | 指定影响的网络设备 | 无 | 否 | "eth0" |

 针对不同的 `action`，还有不同的配置项可以填写。
--- a/i18n/zh/docusaurus-plugin-content-docs/version-2.4.3/simulate-network-chaos-on-kubernetes.md
+++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.4.3/simulate-network-chaos-on-kubernetes.md
@ -144,7 +144,7 @@ NetworkChaos 用于模拟集群中网络故障的场景，目前支持以下几
 | mode | string | 指定实验的运行方式，可选择的方式包括：`one`（表示随机选出一个符合条件的 Pod）、`all`（表示选出所有符合条件的 Pod）、`fixed`（表示选出指定数量且符合条件的 Pod）、`fixed-percent`（表示选出占符合条件的 Pod 中指定百分比的 Pod）、`random-max-percent`（表示选出占符合条件的 Pod 中不超过指定百分比的 Pod） | 无 | 是 | `one` |
 | value | string | 取决与 `mode` 的配置，为 `mode` 提供对应的参数。例如，当你将 `mode` 配置为 `fixed-percent` 时，`value` 用于指定 Pod 的百分比 | 无 | 否 | 1 |
 | selector | struct | 指定注入故障的目标 Pod，详情请参考[定义实验范围](./define-chaos-experiment-scope.md) | 无 | 是 |  |
-| externalTargets | []string | 表示 Kubernetes 之外的网络目标, 可以是 IPv4 地址或者域名。只能与 `direction: to` 一起工作。 | 无 | 否 | 1.1.1.1, www.google.com |
+| externalTargets | []string | 表示 Kubernetes 之外的网络目标, 可以是 IPv4 地址或者域名。只能与 `direction: to` 一起工作。 | 无 | 否 | 1.1.1.1, google.com |
 | device | string | 指定影响的网络设备 | 无 | 否 | "eth0" |

 针对不同的 `action`，还有不同的配置项可以填写。
--- a/i18n/zh/docusaurus-plugin-content-docs/version-2.5.2/simulate-network-chaos-on-kubernetes.md
+++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.5.2/simulate-network-chaos-on-kubernetes.md
@ -144,7 +144,7 @@ NetworkChaos 用于模拟集群中网络故障的场景，目前支持以下几
 | mode | string | 指定实验的运行方式，可选择的方式包括：`one`（表示随机选出一个符合条件的 Pod）、`all`（表示选出所有符合条件的 Pod）、`fixed`（表示选出指定数量且符合条件的 Pod）、`fixed-percent`（表示选出占符合条件的 Pod 中指定百分比的 Pod）、`random-max-percent`（表示选出占符合条件的 Pod 中不超过指定百分比的 Pod） | 无 | 是 | `one` |
 | value | string | 取决与 `mode` 的配置，为 `mode` 提供对应的参数。例如，当你将 `mode` 配置为 `fixed-percent` 时，`value` 用于指定 Pod 的百分比 | 无 | 否 | 1 |
 | selector | struct | 指定注入故障的目标 Pod，详情请参考[定义实验范围](./define-chaos-experiment-scope.md) | 无 | 是 |  |
-| externalTargets | []string | 表示 Kubernetes 之外的网络目标, 可以是 IPv4 地址或者域名。只能与 `direction: to` 一起工作。 | 无 | 否 | 1.1.1.1, www.google.com |
+| externalTargets | []string | 表示 Kubernetes 之外的网络目标, 可以是 IPv4 地址或者域名。只能与 `direction: to` 一起工作。 | 无 | 否 | 1.1.1.1, google.com |
 | device | string | 指定影响的网络设备 | 无 | 否 | "eth0" |

 针对不同的 `action`，还有不同的配置项可以填写。
--- a/i18n/zh/docusaurus-plugin-content-docs/version-2.6.2/simulate-network-chaos-on-kubernetes.md
+++ b/i18n/zh/docusaurus-plugin-content-docs/version-2.6.2/simulate-network-chaos-on-kubernetes.md
@ -144,7 +144,7 @@ NetworkChaos 用于模拟集群中网络故障的场景，目前支持以下几
 | mode | string | 指定实验的运行方式，可选择的方式包括：`one`（表示随机选出一个符合条件的 Pod）、`all`（表示选出所有符合条件的 Pod）、`fixed`（表示选出指定数量且符合条件的 Pod）、`fixed-percent`（表示选出占符合条件的 Pod 中指定百分比的 Pod）、`random-max-percent`（表示选出占符合条件的 Pod 中不超过指定百分比的 Pod） | 无 | 是 | `one` |
 | value | string | 取决与 `mode` 的配置，为 `mode` 提供对应的参数。例如，当你将 `mode` 配置为 `fixed-percent` 时，`value` 用于指定 Pod 的百分比 | 无 | 否 | 1 |
 | selector | struct | 指定注入故障的目标 Pod，详情请参考[定义实验范围](./define-chaos-experiment-scope.md) | 无 | 是 |  |
-| externalTargets | []string | 表示 Kubernetes 之外的网络目标, 可以是 IPv4 地址或者域名。只能与 `direction: to` 一起工作。 | 无 | 否 | 1.1.1.1, www.google.com |
+| externalTargets | []string | 表示 Kubernetes 之外的网络目标, 可以是 IPv4 地址或者域名。只能与 `direction: to` 一起工作。 | 无 | 否 | 1.1.1.1, google.com |
 | device | string | 指定影响的网络设备 | 无 | 否 | "eth0" |

 针对不同的 `action`，还有不同的配置项可以填写。
--- a/versioned_docs/version-2.4.3/simulate-network-chaos-on-kubernetes.md
+++ b/versioned_docs/version-2.4.3/simulate-network-chaos-on-kubernetes.md
@ -140,13 +140,13 @@ Before creating NetworkChaos experiments, ensure the following:

 | Parameter | Type | Description | Default value | Required | Example |
 | --- | --- | --- | --- | --- | --- |
-| action | string | Indicates the specific fault type. Available types include: `netem`, `delay` (network delay), `loss` (packet loss), `duplicate` (packet duplicating), `corrupt` (packet corrupt), `partition` (network partition), and `bandwidth` (network bandwidth limit).After you specify `action` field, refer to [Description for `action`-related fields](#description-for-action-related-fields) for other necessary field configuration. | None | Yes | Partition |
+| action | string | Indicates the specific fault type. Available types include: `netem`, `delay` (network delay), `loss` (packet loss), `duplicate` (packet duplicating), `corrupt` (packet corrupt), `partition` (network partition), and `bandwidth` (network bandwidth limit). After you specify `action` field, refer to [Description for `action`-related fields](#description-for-action-related-fields) for other necessary field configuration. | None | Yes | Partition |
 | target | Selector | Used in combination with direction, making Chaos only effective for some packets. | None | No |  |
 | direction | enum | Indicates the direction of `target` packets. Available vaules include `from` (the packets from `target`), `to` (the packets to `target`), and `both` ( the packets from or to `target`). This parameter makes Chaos only take effect for a specific direction of packets. | to | No | both |
 | mode | string | Specifies the mode of the experiment. The mode options include `one` (selecting a random Pod), `all` (selecting all eligible Pods), `fixed` (selecting a specified number of eligible Pods), `fixed-percent` (selecting a specified percentage of Pods from the eligible Pods), and `random-max-percent` (selecting the maximum percentage of Pods from the eligible Pods). | None | Yes | `one` |
 | value | string | Provides a parameter for the `mode` configuration, depending on `mode`. For example, when `mode` is set to `fixed-percent`, `value` specifies the percentage of Pods. | None | No | 1 |
 | selector | struct | Specifies the target Pod. For details, refer to [Define the experiment scope](./define-chaos-experiment-scope.md). | None | Yes |  |
-| externalTargets | []string | Indicates the network targets except for Kubernetes, which can be IPv4 addresses or domains. This parameter only works with `direction: to`. | None | No | 1.1.1.1, www.google.com |
+| externalTargets | []string | Indicates the network targets except for Kubernetes, which can be IPv4 addresses or domains. This parameter only works with `direction: to`. | None | No | 1.1.1.1, google.com |
 | device | string | Specifies the affected network interface | None | No | "eth0" |

 ### Description for `action`-related fields
--- a/versioned_docs/version-2.5.2/simulate-network-chaos-on-kubernetes.md
+++ b/versioned_docs/version-2.5.2/simulate-network-chaos-on-kubernetes.md
@ -140,13 +140,13 @@ Before creating NetworkChaos experiments, ensure the following:

 | Parameter | Type | Description | Default value | Required | Example |
 | --- | --- | --- | --- | --- | --- |
-| action | string | Indicates the specific fault type. Available types include: `netem`, `delay` (network delay), `loss` (packet loss), `duplicate` (packet duplicating), `corrupt` (packet corrupt), `partition` (network partition), and `bandwidth` (network bandwidth limit).After you specify `action` field, refer to [Description for `action`-related fields](#description-for-action-related-fields) for other necessary field configuration. | None | Yes | Partition |
+| action | string | Indicates the specific fault type. Available types include: `netem`, `delay` (network delay), `loss` (packet loss), `duplicate` (packet duplicating), `corrupt` (packet corrupt), `partition` (network partition), and `bandwidth` (network bandwidth limit). After you specify `action` field, refer to [Description for `action`-related fields](#description-for-action-related-fields) for other necessary field configuration. | None | Yes | Partition |
 | target | Selector | Used in combination with direction, making Chaos only effective for some packets. | None | No |  |
 | direction | enum | Indicates the direction of `target` packets. Available vaules include `from` (the packets from `target`), `to` (the packets to `target`), and `both` ( the packets from or to `target`). This parameter makes Chaos only take effect for a specific direction of packets. | to | No | both |
 | mode | string | Specifies the mode of the experiment. The mode options include `one` (selecting a random Pod), `all` (selecting all eligible Pods), `fixed` (selecting a specified number of eligible Pods), `fixed-percent` (selecting a specified percentage of Pods from the eligible Pods), and `random-max-percent` (selecting the maximum percentage of Pods from the eligible Pods). | None | Yes | `one` |
 | value | string | Provides a parameter for the `mode` configuration, depending on `mode`. For example, when `mode` is set to `fixed-percent`, `value` specifies the percentage of Pods. | None | No | 1 |
 | selector | struct | Specifies the target Pod. For details, refer to [Define the experiment scope](./define-chaos-experiment-scope.md). | None | Yes |  |
-| externalTargets | []string | Indicates the network targets except for Kubernetes, which can be IPv4 addresses or domains. This parameter only works with `direction: to`. | None | No | 1.1.1.1, www.google.com |
+| externalTargets | []string | Indicates the network targets except for Kubernetes, which can be IPv4 addresses or domains. This parameter only works with `direction: to`. | None | No | 1.1.1.1, google.com |
 | device | string | Specifies the affected network interface | None | No | "eth0" |

 ### Description for `action`-related fields
--- a/versioned_docs/version-2.6.2/simulate-network-chaos-on-kubernetes.md
+++ b/versioned_docs/version-2.6.2/simulate-network-chaos-on-kubernetes.md
@ -140,13 +140,13 @@ Before creating NetworkChaos experiments, ensure the following:

 | Parameter | Type | Description | Default value | Required | Example |
 | --- | --- | --- | --- | --- | --- |
-| action | string | Indicates the specific fault type. Available types include: `netem`, `delay` (network delay), `loss` (packet loss), `duplicate` (packet duplicating), `corrupt` (packet corrupt), `partition` (network partition), and `bandwidth` (network bandwidth limit).After you specify `action` field, refer to [Description for `action`-related fields](#description-for-action-related-fields) for other necessary field configuration. | None | Yes | Partition |
+| action | string | Indicates the specific fault type. Available types include: `netem`, `delay` (network delay), `loss` (packet loss), `duplicate` (packet duplicating), `corrupt` (packet corrupt), `partition` (network partition), and `bandwidth` (network bandwidth limit). After you specify `action` field, refer to [Description for `action`-related fields](#description-for-action-related-fields) for other necessary field configuration. | None | Yes | Partition |
 | target | Selector | Used in combination with direction, making Chaos only effective for some packets. | None | No |  |
 | direction | enum | Indicates the direction of `target` packets. Available vaules include `from` (the packets from `target`), `to` (the packets to `target`), and `both` ( the packets from or to `target`). This parameter makes Chaos only take effect for a specific direction of packets. | to | No | both |
 | mode | string | Specifies the mode of the experiment. The mode options include `one` (selecting a random Pod), `all` (selecting all eligible Pods), `fixed` (selecting a specified number of eligible Pods), `fixed-percent` (selecting a specified percentage of Pods from the eligible Pods), and `random-max-percent` (selecting the maximum percentage of Pods from the eligible Pods). | None | Yes | `one` |
 | value | string | Provides a parameter for the `mode` configuration, depending on `mode`. For example, when `mode` is set to `fixed-percent`, `value` specifies the percentage of Pods. | None | No | 1 |
 | selector | struct | Specifies the target Pod. For details, refer to [Define the experiment scope](./define-chaos-experiment-scope.md). | None | Yes |  |
-| externalTargets | []string | Indicates the network targets except for Kubernetes, which can be IPv4 addresses or domains. This parameter only works with `direction: to`. | None | No | 1.1.1.1, www.google.com |
+| externalTargets | []string | Indicates the network targets except for Kubernetes, which can be IPv4 addresses or domains. This parameter only works with `direction: to`. | None | No | 1.1.1.1, google.com |
 | device | string | Specifies the affected network interface | None | No | "eth0" |

 ### Description for `action`-related fields