Configure a custom CNI chain with Terway - Container Service for Kubernetes

By default, ACK clusters use a single CNI plug-in (Terway) to handle all pod networking. A custom CNI chain lets you link additional CNI plug-ins after Terway so each plug-in handles one specific networking task—port mapping, IPv6 tuning, and so on. When ACK creates a pod, it calls the plug-ins in sequence: the output of each plug-in becomes the input for the next.

Warning

ACK does not guarantee that CNI plug-ins work together. A custom CNI chain is a high-risk operation that can cause business interruptions if misconfigured. Make sure you understand how a CNI chain works before proceeding.

Prerequisites

Before you begin, ensure that you have:

An ACK managed cluster that uses Terway as the CNI plug-in. For details, see Create an ACK managed cluster.
Terway plug-in version 1.5.6 or later. To update the plug-in, see Manage components.

Configure a CNI chain

To add CNI plug-ins to the chain, edit the eni-config ConfigMap to populate the 10-terway.conflist field.

Edit the eni-config ConfigMap.

kubectl edit cm -nkube-system eni-config

The ConfigMap contains two fields:

Field	Description
`10-terway.conf`	The Terway CNI configuration. Do not modify this field.
`10-terway.conflist`	The custom CNI chain configuration. The first entry in `plugins` must match the content of `10-terway.conf`. All content must be valid JSON.

Important

The example below is for reference only. Do not copy it directly—using it without modification may cause configuration errors. Verify each parameter against your cluster setup.

kind: ConfigMap
apiVersion: v1
metadata:
  name: eni-config
  namespace: kube-system
data:
  10-terway.conflist: |
      {
        "plugins": [
          {
            "cniVersion": "0.4.0",
            "name": "terway",
            "type": "terway",
            "capabilities": {"bandwidth": true}
          },
          {
            "type": "portmap",
            "capabilities": {"portMappings": true},
            "externalSetMarkChain":"KUBE-MARK-MASQ"
          }
        ]
      }
  10-terway.conf: |
    {
      "cniVersion": "0.4.0",
      "name": "terway",
      "type": "terway",
      "capabilities": {"bandwidth": true}
    }

Restart the Terway DaemonSet to apply the configuration.

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

Verify the configuration on a node.
```
cat /etc/cni/net.d/10-terway.conflist
```
If the output contains your custom plug-in configuration, the CNI chain is active.

Use cases

The following examples show common CNI chain configurations. Use them as a starting point and adapt them to your environment.

Map pod ports to host ports (portmap)

The portmap plug-in maps a pod's internal ports to ports on the host, letting you expose pod services through the node's IP address and port. Use this approach when you need direct host port access for a specific pod. If you need flexible external access at scale, consider a LoadBalancer or NodePort Service instead.

Note

If pods need to be reachable from the Internet, open the corresponding ports for inbound traffic in the node's security group.

Access via private IP address

Use this configuration when pods only need to be reachable within the VPC.

kind: ConfigMap
apiVersion: v1
metadata:
  name: eni-config
  namespace: kube-system
data:
  10-terway.conflist: |
      {
        "plugins": [
          {
            "cniVersion": "0.4.0",
            "name": "terway",
            "type": "terway",
            "capabilities": {"bandwidth": true}
          },
          {
            "type": "portmap",
            "capabilities": {"portMappings": true},
            "externalSetMarkChain":"KUBE-MARK-MASQ"
          }
        ]
      }

  10-terway.conf: |
    {
      "cniVersion": "0.4.0",
      "name": "terway",
      "type": "terway",
      "capabilities": {"bandwidth": true}
    }

Access via public IP address

For Internet access, two additional parameters are required. Requirements differ by Terway mode:

Parameter	Plug-in	Minimum version	Non-Datapath V2	Datapath V2
`masqAll`	portmap	portmap v1.7.1	Not required	Required
`symmetric_routing`	Terway	Terway v1.15.0	Required	Required

Parameter details:

masqAll: A parameter for the portmap plug-in. Requires portmap v1.7.1 or later.
symmetric_routing: A parameter for the Terway plug-in. Requires Terway v1.15.0 or later.

kind: ConfigMap
apiVersion: v1
metadata:
  name: eni-config
  namespace: kube-system
data:
  10-terway.conflist: |
      {
        "plugins": [
          {
            "cniVersion": "0.4.0",
            "name": "terway",
            "type": "terway",
            "symmetric_routing": true,
            "capabilities": {"bandwidth": true}
          },
          {
            "type": "portmap",
            "capabilities": {"portMappings": true},
            "masqAll": false
          }
        ]
      }

  10-terway.conf: |
    {
      "cniVersion": "0.4.0",
      "name": "terway",
      "type": "terway",
      "capabilities": {"bandwidth": true}
    }

Disable IPv6 link-local addresses in containers

Even when IPv6 dual-stack is not enabled for the cluster, the OS kernel automatically assigns an IPv6 link-local address from the fe80::/64 range to each container's network interface. This is default kernel behavior and is generally harmless.

However, if your application misidentifies link-local addresses as pod IP addresses and tries to use them for cross-network communication, it will fail—link-local addresses are only valid for communication between devices on the same network link. If you can fix the application code, do that first. If you cannot, use the tuning plug-in to disable IPv6 link-local addresses in containers.

kind: ConfigMap
apiVersion: v1
metadata:
  name: eni-config
  namespace: kube-system
data:
  10-terway.conflist: |
      {
        "plugins": [
          {
            "cniVersion": "0.4.0",
            "name": "terway",
            "type": "terway",
            "capabilities": {"bandwidth": true}
          },
          {
            "type": "tuning",
            "sysctl": {
              "net.ipv6.conf.all.disable_ipv6": "1",
              "net.ipv6.conf.default.disable_ipv6": "1",
              "net.ipv6.conf.lo.disable_ipv6": "1"
            }
          }
        ]
      }
  10-terway.conf: |
    {
      "cniVersion": "0.4.0",
      "name": "terway",
      "type": "terway",
      "capabilities": {"bandwidth": true}
    }