自訂Terway配置參數 - Container Service for Kubernetes

Terway的預設配置已經能夠滿足絕大多數情境的需求。對Terway進行配置修改是高危操作，可能會導致Terway運行中止等錯誤。如果您對Terway配置有特殊需求，例如增加Terway預留IP資源集區以最佳化Pod IP分配速度等，您可參照本文對Terway進行自訂配置。

背景資訊

Terway支援通過控制台、OpenAPI、Terraform和ConfigMap進行自訂參數配置。

通過控制台配置、通過OpenAPI配置、通過Terraform配置三種方式提供的配置參數完全相同，並且都會對使用者輸入進行校正，攔截格式和數值範圍不正確的參數值。
以上三種方式僅支援修改部分Terway配置參數。
ConfigMap支援修改Terway所有配置參數。但修改ConfigMap是高危操作，可能導致Terway運行中止等錯誤，請謹慎操作。

重要

Terway配置參數較多，本文僅對配置參數功能進行說明。請結合使用情境選擇合適的參數並進行充分的驗證。

通過控制台配置

登入Container Service管理主控台，在左側導覽列選擇叢集列表。
在叢集列表頁面，單擊目的地組群名稱，然後在左側導覽列，單擊組件管理。
單擊網路頁簽，然後terway-eniip、terway-controlplane右側的配置，分別配置兩個組件的參數。
Ratelimit部分的參數請參見RateLimit 預設數值。

通過OpenAPI配置

通過建立叢集API中的addons欄位或修改叢集組件執行個體配置API，都可以對Terway參數進行配置，參數具體說明如下：

terway-eniip參數表

參數名	類型	預設值	參數限制	說明
`TerwayMemoryRequest`	string	`100Mi`	記憶體單位	terway 容器記憶體 request
`TerwayCpuRequest`	string	`100m`	正數/`m`	terway 容器 CPU request
`TerwayMemoryLimit`	string	`256Mi`	可空+記憶體單位	terway 容器記憶體 limit
`TerwayCpuLimit`	string	`100m`	可空/`m`	terway 容器 CPU limit
`PolicyMemoryRequest`	string	`100Mi`	記憶體單位	policy 容器記憶體 request
`PolicyCpuRequest`	string	`250m`	正數/`m`	policy 容器 CPU request
`PolicyMemoryLimit`	string	`""`（不限制）	可空+記憶體單位	policy 容器記憶體 limit
`PolicyCpuLimit`	string	`1`	可空/`m`	policy 容器 CPU limit
`NetworkPolicy`	string	無	`true`/`false`	是否啟用網路原則
`PodVswitchId`	object	無	按可用性區域映射	為 Pod 指定 vSwitch
`SecurityGroupIDs`	array[string]	無	1–10 個，≤128 字元	Pod ENI 使用的安全性群組
`MaxPoolSize`	integer	`5`	0–9999	IP 資源集區最大緩衝數
`MinPoolSize`	integer	`0`	0–9999	IP 資源集區最小緩衝數
`CiliumArgs`	string\|null	無	長度小於或等於 256 字元	cilium 額外啟動參數
`VSwitchSelectionPolicy`	string	`ordered`	`ordered`/`random`	vSwitch 選擇策略
`KubeClientQPS`	number	`5`	0–9999	訪問 apiserver QPS
`KubeClientBurst`	integer	`10`	0–9999	訪問 apiserver Burst
`ResourceGroupID`	string	無	≤128 字元	資源群組 ID

terway-controlplane 參數表

參數名	類型	預設值	參數限制	含義
`CustomStatefulWorkloadKinds`	array[string]	無	—	自訂有狀態工作負載 Kind 列表
`ciliumClientQPS`	number	`20`	取值範圍：[0, 10000]	cilium-operator 訪問 apiserver QPS
`ciliumClientBurst`	integer	`30`	取值範圍：；1–10000	cilium-operator 訪問 apiserver Burst
`kubeClientQPS`	number	`500`	0–10000	控制面 kube client QPS。
`kubeClientBurst`	integer	`700`	1–10000	控制面 kube client Burst。
`RateLimit`	object	請參見RateLimit 預設數值	每項 1–999999。各 API 的預設值請參見“RateLimit 預設數值”（未列出的 API 預設為 500）。	terway-controlplane組件發起阿里雲 OpenAPI 請求的速率限制，按不同 API 進行區分，單位：次數/分鐘。

RateLimit 預設數值

API	預設值
AttachNetworkInterface	500
DetachNetworkInterface	400
UnassignPrivateIpAddresses	400
UnassignIpv6Addresses	400
DescribeVSwitches	300
AttachElasticNetworkInterface	300
ListElasticNetworkInterfaces	6000
DeleteElasticNetworkInterface	1200
DeleteHighDensityElasticNetworkInterface	300
DetachHighDensityElasticNetworkInterface	300
GetNodeInfoForPod	6000
CreateNetworkInterface	500
AssignPrivateIpAddresses	400
AssignIpv6Addresses	400
DescribeInstanceTypes	400
AssignLeniPrivateIpAddress	300
DetachElasticNetworkInterface	300
CreateElasticNetworkInterface	1200
CreateHighDensityElasticNetworkInterface	900
AttachHighDensityElasticNetworkInterface	300
ListHighDensityElasticNetworkInterfaces	6000
其他未列出的API	500

通過Terraform配置

ACK 組件參數通過 addon 的 config 欄位（JSON 字串）傳入，參數名與OpenAPI中的參數完全一致。配置樣本請參見下方

建立叢集時啟用 terway-eniip（alicloud_cs_managed_kubernetes）

resource "alicloud_cs_managed_kubernetes" "terway" {
  name               = "terway-demo"
  cluster_spec       = "ack.pro.small"
  worker_vswitch_ids = [alicloud_vswitch.node.id]
  pod_vswitch_ids    = [alicloud_vswitch.pod.id]   # terway 需要獨立 pod vSwitch
  service_cidr       = "172.21.0.0/20"

  addons {
    name = "terway-eniip"
    config = jsonencode({
      NetworkPolicy          = "true"
      MaxPoolSize            = 5
      MinPoolSize            = 0
      VSwitchSelectionPolicy = "ordered"
      TerwayMemoryLimit      = "256Mi"
      SecurityGroupIDs       = [alicloud_security_group.pod.id]
    })
  } 
}

單獨管理 terway-controlplane 參數（alicloud_cs_kubernetes_addon）

resource "alicloud_cs_kubernetes_addon" "terway_controlplane" {
  cluster_id = alicloud_cs_managed_kubernetes.terway.id
  name       = "terway-controlplane"
  version    = "v1.18.0"

  config = jsonencode({
    kubeClientQPS     = 500
    kubeClientBurst   = 700
    ciliumClientQPS   = 20
    ciliumClientBurst = 30
    RateLimit = {
      CreateNetworkInterface = 600
      DescribeNetworkInterfaces = 1000
    }
  })
}

修改 config 後 terraform apply 即觸發組件 Modify/Upgrade。SecurityGroupIDs、PodVswitchId 等留空時由叢集預設值填充。

通過Terway ConfigMap配置

Terway部分參數不會顯示在控制台上，您可通過kubectl對這些參數進行配置。參數列表參考Terway設定檔樣本。

警告

使用kubectl對Terway進行配置是高危操作，kubectl無法對輸入內容進行校正，輸入不正確的參數可能會導致Terway運行中止等錯誤。請您確保對配置有充分理解後再進行修改。

通過擷取叢集KubeConfig並通過kubectl工具串連叢集，執行如下命令配置進階參數。
```
kubectl edit cm -n kube-system  eni-config 
```

完成配置後，請儲存並退出。然後，執行如下命令更新配置。

 kubectl rollout restart -n kube-system daemonset.apps/terway-eniip

主要參數

參數	說明	是否允許修改	是否支援通過控制台進行配置
`10-terway.conf`	Terway CNI設定檔參數，其中配置會轉換並下發到 `/etc/cni/net.d/`。	否	否
`10-terway.conflist`	Terway CNI配置自訂檔案參數。更多資訊，請參見配置自訂CNI Chain。	是	否
`disable_network_policy`	是否關閉NetworkPolicy功能。 `false`：開啟NetworkPolicy功能。 `true`：關閉NetworkPolicy功能。	是	是
`eni_conf`	Terway主要配置參數，例如使用的交換器、安全性群組配置等。	是	部分允許
`in_cluster_loadbalance`	是否啟用叢集內負載平衡，只在DataPathV2或IPvlan模式下生效。更多資訊，請參見如何為Terway IPvlan叢集開啟叢集內負載平衡？	是	是

Terway 設定檔參數列表

Terway設定檔樣本

叢集中Terway組件的配置項ConfigMap檔案格式如下。

apiVersion: v1
data:
  10-terway.conf: |     # Terway CNI設定檔參數，其中配置會轉換並下發到 /etc/cni/net.d/。請勿修改。
    {
      "cniVersion": "0.4.0",
      "name": "terway",
      "capabilities": {"bandwidth": true},
      "eniip_virtual_type": "datapathv2",
      "host_stack_cidrs": ["169.254.20.10/32"],
      "cilium_args": "",
      "type": "terway"
    }
  disable_network_policy: "false"    # 是否關閉NetworkPolicy功能開關。
  eni_conf: |                        # Terway主要配置參數，例如使用的交換器、安全性群組配置等。
    {
      "version": "1",
      "max_pool_size": 5,
      "min_pool_size": 0,
      "credential_path": "/var/addon/token-config",
      "enable_eni_trunking": true,
      "vswitches": {"cn-hangzhou-j":["vsw-foo"],"cn-hangzhou-k":["vsw-foo"]},
      "eni_tags": {"ack.aliyun.com":"c7c3cfoo"},
      "service_cidr": "192.168.0.0/16",
      "security_group": "sg-foo",
      "ip_stack": "ipv4",
      "vswitch_selection_policy": "ordered"
    }
  in_cluster_loadbalance: "true"   # 叢集內負載平衡，DataPathV2或IPvlan模式下生效，
kind: ConfigMap
metadata:
  name: eni-config
  namespace: kube-system

Terway設定檔參數說明

10-terway.conf參數

參數	類型	說明	是否允許修改	是否支援通過控制台進行配置
`cniVersion`	string	CNI配置版本。	否	否
`name`	string	CNI外掛程式名稱。	否	否
`type`	string	CNI外掛程式類型。	否	否
`capabilities`	string	CNI capabilities。	是	否
`eniip_virtual_type`	string	網卡虛擬化方式。	否	否
`cilium_args`	string	Cilium配置參數。例如`--bpf-map-dynamic-size-ratio=0.003`。重要參數支援情況隨社區版本變化，不支援向後相容能力。如需在實際環境中使用這些參數，請確保充分驗證後再使用。如升級時Terway Pod無法啟動，請刪除配置後重試。組件升級時會校正參數列表，允許設定的參數列表如下，如果升級Terway時提示`cilium_args validation`失敗，請刪除配置後重試。 `bpf-map-dynamic-size-ratio bpf-ct-timeout-regular-any bpf-ct-timeout-regular-tcp bpf-ct-timeout-regular-tcp-fin bpf-ct-timeout-regular-tcp-syn bpf-ct-timeout-service-any bpf-ct-timeout-service-tcp bpf-ct-timeout-service-tcp-grace bpf-lb-map-max bpf-node-map-max bpf-policy-map-max conntrack-gc-interval bpf-ct-global-any-max bpf-ct-global-tcp-max bpf-nat-global-max prometheus-serve-addr api-rate-limit k8s-client-qps k8s-client-burst labels`	是	是
`symmetric_routing`	bool	terway-eniip版本需為1.15.0及以上。是否開啟對稱路由配置功能。開啟後將設定策略路由規則，用於控制網卡流量的源進源出。 `true`：開啟。 `false`：關閉。	是	否
`symmetric_routing_config`	map[string]any	terway-eniip版本需為1.15.0及以上。對稱路由配置參數，以下為預設值和參數樣本，一般情況下無需配置。 `{ "symmetric_routing_config": { "interface": "eth0", "mark": 16, "mask": 16, "table_id": 100, "rule_priority": 600, "comment": "terway-symmetric" } }` 重要配置錯誤可能影響存量網路設定，請在測試環境充分驗證後使用。	是	否

eni_conf參數

參數	類型	說明	是否允許修改	是否支援通過控制台進行配置
`credential_path`	string	用於訪問OpenAPI的STS Token，僅適用於ACK託管叢集。	否	否
`service_cidr`	string	叢集Service網段。	否	否
`vswitches`	map[string][]string	彈性網卡使用的交換器列表。	是	是
`eni_tags`	map[string]string	設定建立彈性網卡時配置的標籤。修改配置對存量網卡不生效。	否	否
`eni_tag_filter`	map[string]string	僅共用ENI模式支援。過濾Terway管理的彈性網卡。更多詳情，請參見為彈性網卡（ENI）配置白名單。	是	否
`max_pool_size`	int	僅共用ENI模式支援。 IP資源集區，最大保留空閑IP數量。預設值為5。	是	是
`min_pool_size`	int	僅共用ENI模式支援。 IP資源集區，最少保留空閑IP數量。預設值為0。	是	是
`security_group`	string	設定建立彈性網卡時使用的安全性群組。修改配置對存量網卡不生效。	是	否
`security_groups`	[]string	設定建立彈性網卡時使用的安全性群組。最多10個，且安全性群組類型需一致。若配置則取和`security_group`的並集。修改配置對存量網卡不生效。	是	是
`vswitch_selection_policy`	string	建立彈性網卡時選擇交換器的策略。 `ordered`：選擇剩餘IP多的交換器。預設值。 `random`：隨機播放交換器。	是	是
`enable_eip_migrate`	bool	啟用EIP遷移功能。更多詳情，請參見將EIP從Terway遷移至ack-extend-network-controller。	是	否
`ip_stack`	string	叢集IP Family模式。不可修改。	否	否
`ipam_type`	string	叢集IPAM方式。不可修改。	否	否
`enable_eni_trunking`	bool	啟用`Trunk`功能。更多詳情，請參見為Pod配置固定IP及獨立虛擬交換器、安全性群組。	是	否
`kube_client_qps`	float32	Kubernetes client QPS配置。需要與`kube_client_burst`同時配置。	是	是
`kube_client_burst`	int	Kubernetes client Burst配置。需要與`kube_client_qps`同時配置，且需要大於`kube_client_qps`。	是	是
`resource_group_id`	string	建立彈性網卡時設定的資源群組。修改配置對存量網卡不生效。	是	是
`ip_pool_sync_period`	string	terway-eniip版本需為1.15.0及以上。僅共用ENI模式支援。 IP 資源集區同步周期。預設 120 秒。樣本`2m`、`120s`。	是	否
`idle_ip_reclaim_after`	string	terway-eniip版本需為1.16.0及以上。僅共用ENI模式支援。 IP 位址在被回收前，必須保持閒置時間長度。樣本：`60m`。說明在回收前，如果有Pod建立或者刪除，時間將重新計算。	是	否
`idle_ip_reclaim_interval`	string	terway-eniip版本需為1.16.0及以上。僅共用ENI模式支援。兩次回收檢查之間的時間間隔。樣本：`30m`。	是	否
`idle_ip_reclaim_batch_size`	int	terway-eniip版本需為1.16.0及以上。僅共用ENI模式支援。單次批量回收的最大 IP 數量。取值範圍[1, 10]。樣本：`5`。	是	否
`idle_ip_reclaim_jitter_factor`	string	terway-eniip版本需為1.16.0及以上。僅共用ENI模式支援。用於隨機化回收時間的抖動因子。取值範圍[0.0, 1.0]。樣本：`0.1`。	是	否
`ip_warm_up_size`	int	terway-eniip版本需為1.16.4及以上且叢集`ipam_type`配置為`crd`。僅共用ENI模式支援。一次性預熱IP個數。僅對新加入節點生效，預熱任務將在節點分配IP數量達到預期後停止。樣本：`5`。	是	否
`enable_patch_pod_ips`	bool	terway-eniip版本需為1.13.7及以上。僅共用ENI模式支援。預設`true`。開啟後為Pod設定Annotation `k8s.aliyun.com/pod-ips`。	是	否
`enable_ip_prefix`	bool	terway-eniip版本需為1.17.0及以上。僅共用ENI模式支援。預設`false`。開啟將為ENI分配IP Prefix。	是	否
`ipv4_prefix_count`	int	terway-eniip版本需為1.17.0及以上。僅共用ENI模式支援。在 IPv4 單棧和雙棧模式下有效。（在雙棧模式下，IPv6 首碼由系統自動管理，每個 ENI 1 個）。節點配置的IP Prefix數量。在叢集網路類型為 `ipv4`、`dual`有效。取值範圍 >=0，上限隨機型規格自動限制。	是	否
`ipv6_prefix_count`	int	terway-eniip版本需為1.17.0及以上。僅共用ENI模式支援。節點 IPv6 首碼總數。僅在 IPv6 單棧模式下有效，取值範圍 0 或 1。雙棧模式下忽略此欄位（IPv6 首碼由系統自動管理，每個 ENI 1 個）。節點配置的IP Prefix數量。在叢集網路類型為 `ipv6`有效。取值範圍 [0,1]。	是	否

Container Service for Kubernetes：自訂Terway配置參數