自定义Terway配置参数-容器服务 Kubernetes 版 ACK(ACK)-阿里云帮助中心

Terway的默认配置已经能够满足绝大多数场景的需求。对Terway进行配置修改是高危操作，可能会导致Terway运行中止等错误。如果您对Terway配置有特殊需求，例如增加Terway预留IP资源池以优化Pod IP分配速度等，您可参照本文对Terway进行自定义配置。

背景信息

Terway支持通过控制台、OpenAPI、Terraform和ConfigMap进行自定义参数配置。

通过控制台配置、通过OpenAPI配置、通过Terraform配置三种方式提供的配置参数完全相同，并且都会对用户输入进行校验，拦截格式和数值范围不正确的参数值。
以上三种方式仅支持修改部分Terway配置参数。
ConfigMap支持修改Terway所有配置参数。但修改ConfigMap是高危操作，可能导致Terway运行中止等错误，请谨慎操作。

重要

Terway配置参数较多，本文仅对配置参数功能进行说明。请结合使用场景选择合适的参数并进行充分的验证。

通过控制台配置

登录容器服务管理控制台，在左侧导航栏选择集群列表。
在集群列表页面，单击目标集群名称，然后在左侧导航栏，单击组件管理。
单击网络页签，然后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
```

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`	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集群开启集群内负载均衡？	是	是

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]。	是	否