kubeovn · zhangzujian · Aug 4, 2026 · Aug 4, 2026 · Aug 4, 2026
diff --git a/docs/reference/kube-ovn-api.en.md b/docs/reference/kube-ovn-api.en.md
@@ -740,7 +740,7 @@ In each CRD definition, the Condition field in Status follows the above format,
 | nodeSelector | []VpcEgressGatewayNodeSelector | Optional. Node selector for the workload |
 | tolerations | []Toleration | Optional. Standard Kubernetes tolerations |
 | resources | ResourceRequirements | Optional. Container resource limits; the controller uses defaults when unspecified |
-| bandwidth | BandwidthLimit | Optional. Per-replica ingress/egress bandwidth limit (in Mbps) |
+| bandwidth | BandwidthLimit | Optional. Per-replica ingress/egress bandwidth limit, expressed as integer Mbps or a supported bit-rate quantity |
 
 ##### VpcEgressGatewaySelector
 
@@ -778,8 +778,8 @@ In each CRD definition, the Condition field in Status follows the above format,
 
 | Property Name | Type | Description |
 | --- | --- | --- |
-| ingress | Int64 | Ingress bandwidth limit, in Mbps |
-| egress | Int64 | Egress bandwidth limit, in Mbps |
+| ingress | Int64 or String | Limit for traffic entering the VPC from the external network. Integers and numeric strings are Mbps; quantities use `M`, `Mi`, `G`, or `Gi` bits per second |
+| egress | Int64 or String | Limit for traffic leaving the VPC for the external network. Integers and numeric strings are Mbps; quantities use `M`, `Mi`, `G`, or `Gi` bits per second |
 
 #### VpcEgressGatewayStatus
 

diff --git a/docs/reference/kube-ovn-api.md b/docs/reference/kube-ovn-api.md
@@ -740,7 +740,7 @@
 | nodeSelector | []VpcEgressGatewayNodeSelector | 可选，工作负载节点选择器 |
 | tolerations | []Toleration | 可选，标准 Kubernetes 容忍配置 |
 | resources | ResourceRequirements | 可选，容器资源限制；未指定时控制器使用默认值 |
-| bandwidth | BandwidthLimit | 可选，每个网关实例的入向/出向带宽限速（Mbps） |
+| bandwidth | BandwidthLimit | 可选，每个网关副本的入向/出向带宽限制，可使用整数 Mbps 或支持的 bit-rate quantity |
 
 ##### VpcEgressGatewaySelector
 
@@ -778,8 +778,8 @@
 
 | 属性名称 | 类型 | 描述 |
 | --- | --- | --- |
-| ingress | Int64 | 入向带宽限速，单位 Mbps |
-| egress | Int64 | 出向带宽限速，单位 Mbps |
+| ingress | Int64 或 String | 从外部网络进入 VPC 的流量限制；整数和纯数字字符串的单位为 Mbps，quantity 使用 `M`、`Mi`、`G` 或 `Gi` bit/s |
+| egress | Int64 或 String | 从 VPC 发往外部网络的流量限制；整数和纯数字字符串的单位为 Mbps，quantity 使用 `M`、`Mi`、`G` 或 `Gi` bit/s |
 
 #### VpcEgressGatewayStatus
 

diff --git a/docs/reference/next.md b/docs/reference/next.md
@@ -5,6 +5,7 @@ This document lists the features merged into the master branch for the next mino
 ## Post-v1.16.0
 
 - QoS: support configurable ingress/egress burst limits via per-NIC annotations (`ovn.kubernetes.io/ingress_burst`). [#6628](https://github.com/kubeovn/kube-ovn/pull/6628)
+- VPC Egress Gateway: accept integer Mbps values and `M`, `Mi`, `G`, or `Gi` bit-rate quantities for per-replica bandwidth limits. [#7115](https://github.com/kubeovn/kube-ovn/pull/7115)
 - VPC NAT Gateway: allow placing the NAT gateway StatefulSet and its iptables-EIP custom resources in a user-specified namespace. [#6595](https://github.com/kubeovn/kube-ovn/pull/6595)
 - iptables-EIP: surface the bound external subnet in the `kubectl get iptables-eip` printer. [#6672](https://github.com/kubeovn/kube-ovn/pull/6672)
 - Helm Chart (kube-ovn-v2): ship PrometheusRule and Grafana dashboards out of the box. [#6630](https://github.com/kubeovn/kube-ovn/pull/6630)

diff --git a/docs/vpc/vpc-egress-gateway.en.md b/docs/vpc/vpc-egress-gateway.en.md
@@ -404,6 +404,34 @@ Spec:
 | `selectors` | `object array` | Yes | - | Configure Egress policies by namespace selectors and Pod selectors. SNAT/MASQUERADE will be applied to the matched Pods. Configurable when `policies` is configured. | - |
 | `nodeSelector` | `object array` | Yes | - | Node selector applied to the workload. The workload (Deployment/Pod) will run on the selected nodes. | - |
 | `trafficPolicy` | `string` | Yes | `Cluster` | Available values: `Cluster`/`Local`. **Effective only when BFD is enabled**. When set to `Local`, Egress traffic will be redirected to the VPC Egress Gateway instance running on the same node if available. If the instance is down, Egress traffic will be redirected to other instances. | `Local` |
+| `bandwidth` | `object` | Yes | - | Per-replica ingress and egress bandwidth limits. | - |
+| `bandwidth.ingress` | `integer or string` | Yes | - | Limit for traffic entering the VPC from the external network. | `1024` / `1Gi` |
+| `bandwidth.egress` | `integer or string` | Yes | - | Limit for traffic leaving the VPC for the external network. | `1024` / `1Gi` |
+
+##### Bandwidth Limits
+
+An integer or a numeric string specifies an integer Mbps value. A quantity string with an `M`, `Mi`, `G`, or `Gi` suffix specifies bits per second and is rounded up to a whole Mbps value. For example, `100M`, `100Mi`, `1G`, and `1Gi` become 100, 105, 1000, and 1074 Mbps, respectively.
+
+Values must be non-negative and must not exceed 9223372036854 Mbps. Empty strings, other suffixes, exponent notation, negative values, whitespace-padded values, and decimals without a suffix are rejected. Omit `ingress` or `egress` to leave that direction unlimited; an empty string is not equivalent to an omitted field.
+
+```yaml
+spec:
+  bandwidth:
+    ingress: 1024
+    egress: 1Gi
+```
+
+!!! warning "Upgrade and downgrade compatibility"
+
+    Existing integer values from 0 through 9223372036854 retain their Mbps meaning after an upgrade. Keep using integer values until every Kube-OVN component has been upgraded and the `vpc-egress-gateways.kubeovn.io` CRD contains `x-kubernetes-int-or-string: true` for both bandwidth fields.
+
+    Helm does not update CRDs stored in a chart's `crds/` directory. When upgrading with the `kube-ovn-v2` chart, set `KUBE_OVN_VERSION` to the exact Kube-OVN release tag being installed and explicitly apply its matching CRD bundle before using string values:
+
+    ```shell
+    kubectl apply -f "https://raw.githubusercontent.com/kubeovn/kube-ovn/${KUBE_OVN_VERSION}/charts/kube-ovn-v2/crds/kube-ovn-crd.yaml"
+    ```
+
+    Before downgrading to a version that only accepts integer bandwidth fields, convert every numeric or quantity string back to its integer Mbps value.
 
 BFD Configuration:
 

diff --git a/docs/vpc/vpc-egress-gateway.md b/docs/vpc/vpc-egress-gateway.md
@@ -404,6 +404,34 @@ Spec：
 | `selectors` | `object array` | 是 | - | 通过 Namespace Selector 以及 Pod Selector 配置 Egress 策略。匹配到的 Pod 将开启 SNAT/MASQUERADE。可与 `policies` 同时配置。 | - |
 | `nodeSelector` | `object array` | 是 | - | 工作负载的节点选择器，工作负载（Deployment/Pod）将运行在被选择的节点上。 | - |
 | `trafficPolicy` | `string` | 是 | `Cluster` | 可选值：`Cluster`/`Local`。**仅开启 BFD 时生效**。 设置为 `Local` 时，Egress 流量将优先导向同节点上的 VPC Egress Gateway 实例。若同节点上的 VPC Egress Gateway 实例出现故障，Egress 流量将导向其它实例。 | `Local` |
+| `bandwidth` | `object` | 是 | - | 每个网关副本的入向和出向带宽限制。 | - |
+| `bandwidth.ingress` | `integer 或 string` | 是 | - | 从外部网络进入 VPC 的流量限制。 | `1024` / `1Gi` |
+| `bandwidth.egress` | `integer 或 string` | 是 | - | 从 VPC 发往外部网络的流量限制。 | `1024` / `1Gi` |
+
+##### 带宽限制
+
+整数或纯数字字符串表示整数 Mbps 值。带有 `M`、`Mi`、`G` 或 `Gi` 后缀的 quantity 字符串表示 bit/s，并向上取整为整数 Mbps。例如，`100M`、`100Mi`、`1G` 和 `1Gi` 分别转换为 100、105、1000 和 1074 Mbps。
+
+带宽值必须为非负数，且不得超过 9223372036854 Mbps。空字符串、其它单位后缀、指数格式、负数、首尾含空白的值，以及没有单位后缀的小数均会被拒绝。省略 `ingress` 或 `egress` 表示对应方向不限速；空字符串不等同于省略字段。
+
+```yaml
+spec:
+  bandwidth:
+    ingress: 1024
+    egress: 1Gi
+```
+
+!!! warning "升级与降级兼容性"
+
+    升级后，0 到 9223372036854 范围内的现有整数值仍保持原有 Mbps 语义。在所有 Kube-OVN 组件完成升级，并确认 `vpc-egress-gateways.kubeovn.io` CRD 的两个带宽字段均包含 `x-kubernetes-int-or-string: true` 之前，请继续使用整数值。
+
+    Helm 不会更新 Chart 的 `crds/` 目录中的 CRD。使用 `kube-ovn-v2` Chart 升级时，请将 `KUBE_OVN_VERSION` 设置为待安装的准确 Kube-OVN 版本标签，并在使用字符串值之前显式应用匹配的 CRD bundle：
+
+    ```shell
+    kubectl apply -f "https://raw.githubusercontent.com/kubeovn/kube-ovn/${KUBE_OVN_VERSION}/charts/kube-ovn-v2/crds/kube-ovn-crd.yaml"
+    ```
+
+    降级到仅接受整数带宽字段的版本前，请将所有纯数字字符串或 quantity 字符串转换回对应的整数 Mbps 值。
 
 BFD 配置：