Configure Terway parameters - Container Service for Kubernetes

The default Terway configurations work for most clusters. If you have specific requirements—such as increasing the IP address resource pool size to speed up pod IP allocation—customize the settings described here.

Warning

Modifying Terway configurations is a high-risk operation. Incorrect parameters can cause errors, including stopping the Terway component. Thoroughly test all configurations before applying them to production.

Limits

This topic describes the function of each parameter. Not every parameter combination works in every scenario. Test your configurations before applying them.
If a parameter is unavailable in the console, the current component version does not support it. Upgrade the Terway component first.

ConfigMap structure

The Terway component uses a ConfigMap named eni-config in the kube-system namespace. The following example shows the full structure:

apiVersion: v1
data:
  10-terway.conf: |     # Terway Container Network Interface (CNI) configuration file. Delivered to /etc/cni/net.d/. Do not modify.
    {
      "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"    # Whether to disable NetworkPolicy.
  eni_conf: |                        # Main Terway configuration: vSwitches, security groups, and more.
    {
      "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"   # In-cluster load balancing. Takes effect only in DataPathV2 or IPvlan mode.
kind: ConfigMap
metadata:
  name: eni-config
  namespace: kube-system

Parameter reference

Top-level parameters

Parameter	Description	Modifiable	Console
`10-terway.conf`	Terway CNI configuration file. Delivered to `/etc/cni/net.d/`. Do not modify.	No	No
`10-terway.conflist`	Custom Terway CNI configuration file. For details, see Configure a custom CNI chain.	Yes	No
`disable_network_policy`	Whether to disable NetworkPolicy. `false`: enabled. `true`: disabled.	Yes	Yes
`eni_conf`	Main Terway configuration parameters, including vSwitches and security groups.	Yes	Partially
`in_cluster_loadbalance`	Whether to enable in-cluster load balancing. Takes effect only in DataPathV2 or IPvlan mode. For details, see How do I enable load balancing within a cluster in Terway IPVLAN mode?	Yes	Yes

10-terway.conf parameters

Parameter	Type	Description	Modifiable	Console
`cniVersion`	string	CNI configuration version.	No	No
`name`	string	CNI plugin name.	No	No
`type`	string	CNI plugin type.	No	No
`capabilities`	string	CNI capabilities.	Yes	No
`eniip_virtual_type`	string	ENI virtualization method.	No	No
`cilium_args`	string	Cilium configuration parameters. Example: `--bpf-map-dynamic-size-ratio=0.003`. See note below.	Yes	Yes
`symmetric_routing`	bool	Requires terway-eniip 1.15.0+. Whether to enable symmetric routing. When enabled, policy-based routing rules ensure traffic egresses from the same interface it ingresses. `true`: enabled. `false`: disabled.	Yes	No
`symmetric_routing_config`	map\[string\]any	Requires terway-eniip 1.15.0+. Symmetric routing configuration. In most cases, the defaults are sufficient. See details below.	Yes	No

Important

cilium_args support varies by community version and backward compatibility is not guaranteed. If the Terway pod fails to start after an upgrade, remove these parameters and retry.

`symmetric_routing_config` defaults:

{
  "symmetric_routing_config": {
    "interface": "eth0",
    "mark": 16,
    "mask": 16,
    "table_id": 100,
    "rule_priority": 600,
    "comment": "terway-symmetric"
  }
}

Important

Incorrect symmetric_routing_config values can affect existing network configurations. Test thoroughly in a non-production environment before applying.

eni_conf parameters

IP address resource pool

These parameters control how Terway pre-allocates and reclaims IP addresses for pods.

Parameter	Type	Default	Description	Modifiable	Console
`max_pool_size`	int	`5`	Maximum number of idle IP addresses to keep in the pool.	Yes	Yes
`min_pool_size`	int	`0`	Minimum number of idle IP addresses to keep in the pool.	Yes	Yes
`ip_pool_sync_period`	string	`120s`	Requires terway-eniip 1.15.0+. How often the IP address pool syncs. Examples: `2m`, `120s`.	Yes	No
`idle_ip_reclaim_after`	string	—	Requires terway-eniip 1.16.0+. How long an IP address must be idle before reclaim. Example: `60m`. The timer resets if a pod is created or deleted before reclaim completes.	Yes	No
`idle_ip_reclaim_interval`	string	—	Requires terway-eniip 1.16.0+. Time between reclaim checks. Example: `30m`.	Yes	No
`idle_ip_reclaim_batch_size`	int	—	Requires terway-eniip 1.16.0+. Maximum IPs reclaimed per batch. Valid range: 1–10. Example: `5`.	Yes	No
`idle_ip_reclaim_jitter_factor`	string	—	Requires terway-eniip 1.16.0+. Jitter factor to randomize reclaim timing. Valid range: 0.0–1.0. Example: `0.1`.	Yes	No

vSwitch and security group

These parameters determine which vSwitches and security groups Terway uses when creating elastic network interfaces (ENIs).

Changes to eni_tags, security_group, security_groups, and resource_group_id do not affect existing ENIs—only newly created ones.

Parameter	Type	Description	Modifiable	Console
`vswitches`	map\[string\]\[\]string	vSwitches for ENIs, keyed by zone.	Yes	Yes
`vswitch_selection_policy`	string	How Terway selects a vSwitch when creating an ENI. `ordered` (default): selects the vSwitch with the most remaining IP addresses. `random`: randomly selects a vSwitch.	Yes	Yes
`security_group`	string	Security group for new ENIs.	Yes	No
`security_groups`	\[\]string	Security groups for new ENIs. Up to 10 groups, all of the same type. If both `security_group` and `security_groups` are set, Terway uses the union of both values.	Yes	Yes
`eni_tags`	map\[string\]string	Tags added to ENIs at creation time.	No	No
`eni_tag_filter`	map\[string\]string	Filters which ENIs Terway manages. For details, see Configure a whitelist for ENIs.	Yes	No
`resource_group_id`	string	Resource group for new ENIs.	Yes	Yes

Kubernetes client

These parameters tune the Kubernetes API client used by Terway. kube_client_qps and kube_client_burst must be configured together, and kube_client_burst must be greater than kube_client_qps.

Parameter	Type	Description	Modifiable	Console
`kube_client_qps`	float32	Queries per second (QPS) limit for the Kubernetes client.	Yes	Yes
`kube_client_burst`	int	Burst limit for the Kubernetes client. Must be greater than `kube_client_qps`.	Yes	Yes

Feature flags and cluster metadata

These parameters include cluster-level read-only values set by ACK and feature flags for optional Terway capabilities.

Parameter	Type	Description	Modifiable	Console
`credential_path`	string	Path to the Security Token Service (STS) token used to access OpenAPI. Applies only to ACK managed clusters.	No	No
`service_cidr`	string	Service CIDR block of the cluster.	No	No
`ip_stack`	string	IP family mode of the cluster.	No	No
`enable_eni_trunking`	bool	Enables the Trunk feature. For details, see Configure fixed IP addresses, independent vSwitches, and security groups for pods.	Yes	No
`enable_eip_migrate`	bool	Enables elastic IP address (EIP) migration. For details, see Migrate EIPs from Terway to ack-extend-network-controller.	Yes	No

Configure Terway

Use the console

The console validates parameter format and rejects malformed input.

Log on to the ACK console. In the left navigation pane, click Clusters.
On the Clusters page, click the name of the cluster to manage. In the left navigation pane, click Add-ons.
Click the Networking tab, then click Configuration in the terway-eniip card.
Configure the parameters, then click OK.

Use kubectl

Warning

kubectl does not validate input. Incorrect parameters can cause errors, including stopping the Terway component. Make sure you fully understand a configuration before applying it.

Connect to the cluster using kubectl, then edit the ConfigMap:
```
kubectl edit cm -n kube-system eni-config
```

Save and exit, then restart the DaemonSet to apply the changes:

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

What's next

To upgrade Terway, see Components.
To manage ConfigMaps, see Manage ConfigMaps.