Kubernetes Without kube-proxy

This guide explains how to provision a Kubernetes cluster without kube-proxy, and to use Cilium to fully replace it. For simplicity, we will use kubeadm to bootstrap the cluster.

For help with installing kubeadm and for more provisioning options please refer to the official Kubeadm documentation.

Note

Cilium’s kube-proxy replacement depends on the socket-LB feature, which requires a v4.19.57, v5.1.16, v5.2.0 or more recent Linux kernel. Linux kernels v5.3 and v5.8 add additional features that Cilium can use to further optimize the kube-proxy replacement implementation.

Note that v5.0.y kernels do not have the fix required to run the kube-proxy replacement since at this point in time the v5.0.y stable kernel is end-of-life (EOL) and not maintained anymore on kernel.org. For individual distribution maintained kernels, the situation could differ. Therefore, please check with your distribution.

Quick-Start

Initialize the control-plane node via kubeadm init and skip the installation of the kube-proxy add-on:

Note

Depending on what CRI implementation you are using, you may need to use the --cri-socket flag with your kubeadm init ... command. For example: if you’re using Docker CRI you would use --cri-socket unix:///var/run/cri-dockerd.sock.

  1. $ kubeadm init --skip-phases=addon/kube-proxy

Afterwards, join worker nodes by specifying the control-plane node IP address and the token returned by kubeadm init (for this tutorial, you will want to add at least one worker node to the cluster):

  1. $ kubeadm join <..>

Note

Please ensure that kubelet’s --node-ip is set correctly on each worker if you have multiple interfaces. Cilium’s kube-proxy replacement may not work correctly otherwise. You can validate this by running kubectl get nodes -o wide to see whether each node has an InternalIP which is assigned to a device with the same name on each node.

For existing installations with kube-proxy running as a DaemonSet, remove it by using the following commands below. Careful: Be aware that this will break existing service connections. It will also stop service related traffic until the Cilium replacement has been installed:

  1. $ kubectl -n kube-system delete ds kube-proxy
  2. $ # Delete the configmap as well to avoid kube-proxy being reinstalled during a Kubeadm upgrade (works only for K8s 1.19 and newer)
  3. $ kubectl -n kube-system delete cm kube-proxy
  4. $ # Run on each node with root permissions:
  5. $ iptables-save | grep -v KUBE | iptables-restore

Note

Make sure you have Helm 3 installed. Helm 2 is no longer supported.

Setup Helm repository:

  1. helm repo add cilium https://helm.cilium.io/

Next, generate the required YAML files and deploy them. Important: Make sure you correctly set your API_SERVER_IP and API_SERVER_PORT below with the control-plane node IP address and the kube-apiserver port number reported by kubeadm init (Kubeadm will use port 6443 by default).

Specifying this is necessary as kubeadm init is run explicitly without setting up kube-proxy and as a consequence, although it exports KUBERNETES_SERVICE_HOST and KUBERNETES_SERVICE_PORT with a ClusterIP of the kube-apiserver service to the environment, there is no kube-proxy in our setup provisioning that service. Therefore, the Cilium agent needs to be made aware of this information with the following configuration:

  1. API_SERVER_IP=<your_api_server_ip>
  2. # Kubeadm default is 6443
  3. API_SERVER_PORT=<your_api_server_port>
  4. helm install cilium cilium/cilium --version 1.12.0 \
  5.     --namespace kube-system \
  6.     --set kubeProxyReplacement=strict \
  7.     --set k8sServiceHost=${API_SERVER_IP} \
  8.     --set k8sServicePort=${API_SERVER_PORT}

Note

Cilium will automatically mount cgroup v2 filesystem required to attach BPF cgroup programs by default at the path /run/cilium/cgroupv2. To do that, it needs to mount the host /proc inside an init container launched by the DaemonSet temporarily. If you need to disable the auto-mount, specify --set cgroup.autoMount.enabled=false, and set the host mount point where cgroup v2 filesystem is already mounted by using --set cgroup.hostRoot. For example, if not already mounted, you can mount cgroup v2 filesystem by running the below command on the host, and specify --set cgroup.hostRoot=/sys/fs/cgroup.

  1. mount -t cgroup2 none /sys/fs/cgroup

This will install Cilium as a CNI plugin with the eBPF kube-proxy replacement to implement handling of Kubernetes services of type ClusterIP, NodePort, LoadBalancer and services with externalIPs. As well, the eBPF kube-proxy replacement also supports hostPort for containers such that using portmap is not necessary anymore.

Finally, as a last step, verify that Cilium has come up correctly on all nodes and is ready to operate:

  1. $ kubectl -n kube-system get pods -l k8s-app=cilium
  2. NAME                READY     STATUS    RESTARTS   AGE
  3. cilium-fmh8d        1/1       Running   0          10m
  4. cilium-mkcmb        1/1       Running   0          10m

Note, in above Helm configuration, the kubeProxyReplacement has been set to strict mode. This means that the Cilium agent will bail out in case the underlying Linux kernel support is missing.

By default, Helm sets kubeProxyReplacement=disabled, which only enables per-packet in-cluster load-balancing of ClusterIP services.

Cilium’s eBPF kube-proxy replacement is supported in direct routing as well as in tunneling mode.

Validate the Setup

After deploying Cilium with above Quick-Start guide, we can first validate that the Cilium agent is running in the desired mode:

  1. $ kubectl -n kube-system exec ds/cilium -- cilium status | grep KubeProxyReplacement
  2. KubeProxyReplacement:   Strict      [eth0 (Direct Routing), eth1]

Use --verbose for full details:

  1. $ kubectl -n kube-system exec ds/cilium -- cilium status --verbose
  2. [...]
  3. KubeProxyReplacement Details:
  4.   Status:                Strict
  5.   Socket LB:             Enabled
  6.   Protocols:             TCP, UDP
  7.   Devices:               eth0 (Direct Routing), eth1
  8.   Mode:                  SNAT
  9.   Backend Selection:     Random
  10.   Session Affinity:      Enabled
  11.   Graceful Termination:  Enabled
  12.   NAT46/64 Support:      Enabled
  13.   XDP Acceleration:      Disabled
  14.   Services:
  15.   - ClusterIP:      Enabled
  16.   - NodePort:       Enabled (Range: 30000-32767)
  17.   - LoadBalancer:   Enabled
  18.   - externalIPs:    Enabled
  19.   - HostPort:       Enabled
  20. [...]

As an optional next step, we will create an Nginx Deployment. Then we’ll create a new NodePort service and validate that Cilium installed the service correctly.

The following yaml is used for the backend pods:

  1. apiVersion: apps/v1
  2. kind: Deployment
  3. metadata:
  4.   name: my-nginx
  5. spec:
  6.   selector:
  7.     matchLabels:
  8.       run: my-nginx
  9.   replicas: 2
  10.   template:
  11.     metadata:
  12.       labels:
  13.         run: my-nginx
  14.     spec:
  15.       containers:
  16.       - name: my-nginx
  17.         image: nginx
  18.         ports:
  19.         - containerPort: 80

Verify that the Nginx pods are up and running:

  1. $ kubectl get pods -l run=my-nginx -o wide
  2. NAME                        READY   STATUS    RESTARTS   AGE   IP             NODE   NOMINATED NODE   READINESS GATES
  3. my-nginx-756fb87568-gmp8c   1/1     Running   0          62m   10.217.0.149   apoc   <none>           <none>
  4. my-nginx-756fb87568-n5scv   1/1     Running   0          62m   10.217.0.107   apoc   <none>           <none>

In the next step, we create a NodePort service for the two instances:

  1. $ kubectl expose deployment my-nginx --type=NodePort --port=80
  2. service/my-nginx exposed

Verify that the NodePort service has been created:

  1. $ kubectl get svc my-nginx
  2. NAME       TYPE       CLUSTER-IP       EXTERNAL-IP   PORT(S)        AGE
  3. my-nginx   NodePort   10.104.239.135   <none>        80:31940/TCP   24m

With the help of the cilium service list command, we can validate that Cilium’s eBPF kube-proxy replacement created the new NodePort service. In this example, services with port 31940 were created (one for each of devices eth0 and eth1):

  1. $ kubectl -n kube-system exec ds/cilium -- cilium service list
  2. ID   Frontend               Service Type   Backend
  3. [...]
  4. 4    10.104.239.135:80      ClusterIP      1 => 10.217.0.107:80
  5.                                            2 => 10.217.0.149:80
  6. 5    0.0.0.0:31940          NodePort       1 => 10.217.0.107:80
  7.                                            2 => 10.217.0.149:80
  8. 6    192.168.178.29:31940   NodePort       1 => 10.217.0.107:80
  9.                                            2 => 10.217.0.149:80
  10. 7    172.16.0.29:31940      NodePort       1 => 10.217.0.107:80
  11.                                            2 => 10.217.0.149:80

Create a variable with the node port for testing:

  1. $ node_port=$(kubectl get svc my-nginx -o=jsonpath='{@.spec.ports[0].nodePort}')

At the same time we can verify, using iptables in the host namespace, that no iptables rule for the service is present:

  1. $ iptables-save | grep KUBE-SVC
  2. [ empty line ]

Last but not least, a simple curl test shows connectivity for the exposed NodePort as well as for the ClusterIP:

  1. $ curl 127.0.0.1:$node_port
  2. <!DOCTYPE html>
  3. <html>
  4. <head>
  5. <title>Welcome to nginx!</title>
  6. [....]
  1. $ curl 192.168.178.29:$node_port
  2. <!doctype html>
  3. <html>
  4. <head>
  5. <title>welcome to nginx!</title>
  6. [....]
  1. $ curl 172.16.0.29:$node_port
  2. <!doctype html>
  3. <html>
  4. <head>
  5. <title>welcome to nginx!</title>
  6. [....]
  1. $ curl 10.104.239.135:80
  2. <!DOCTYPE html>
  3. <html>
  4. <head>
  5. <title>Welcome to nginx!</title>
  6. [....]

As can be seen, Cilium’s eBPF kube-proxy replacement is set up correctly.

Advanced Configuration

This section covers a few advanced configuration modes for the kube-proxy replacement that go beyond the above Quick-Start guide and are entirely optional.

Client Source IP Preservation

Cilium’s eBPF kube-proxy replacement implements various options to avoid performing SNAT on NodePort requests where the client source IP address would otherwise be lost on its path to the service endpoint.

  • externalTrafficPolicy=Local: The Local policy is generally supported through the eBPF implementation. In-cluster connectivity for services with externalTrafficPolicy=Local is possible and can also be reached from nodes which have no local backends, meaning, given SNAT does not need to be performed, all service endpoints are available for load balancing from in-cluster side.

  • externalTrafficPolicy=Cluster: For the Cluster policy which is the default upon service creation, multiple options exist for achieving client source IP preservation for external traffic, that is, operating the kube-proxy replacement in DSR or Hybrid mode if only TCP-based services are exposed to the outside world for the latter.

Maglev Consistent Hashing (Beta)

Cilium’s eBPF kube-proxy replacement supports consistent hashing by implementing a variant of The Maglev paper hashing in its load balancer for backend selection. This improves resiliency in case of failures. As well, it provides better load balancing properties since Nodes added to the cluster will make consistent backend selection throughout the cluster for a given 5-tuple without having to synchronize state with the other Nodes. Similarly, upon backend removal the backend lookup tables are reprogrammed with minimal disruption for unrelated backends (at most 1% difference in the reassignments) for the given service.

Maglev hashing for services load balancing can be enabled by setting loadBalancer.algorithm=maglev:

  1. helm install cilium cilium/cilium --version 1.12.0 \
  2.     --namespace kube-system \
  3.     --set kubeProxyReplacement=strict \
  4.     --set loadBalancer.algorithm=maglev \
  5.     --set k8sServiceHost=${API_SERVER_IP} \
  6.     --set k8sServicePort=${API_SERVER_PORT}

Note that Maglev hashing is applied only to external (N-S) traffic. For in-cluster service connections (E-W), sockets are assigned to service backends directly, e.g. at TCP connect time, without any intermediate hop and thus are not subject to Maglev. Maglev hashing is also supported for Cilium’s XDP acceleration.

There are two more Maglev-specific configuration settings: maglev.tableSize and maglev.hashSeed.

maglev.tableSize specifies the size of the Maglev lookup table for each single service. Maglev recommends the table size (M) to be significantly larger than the number of maximum expected backends (N). In practice that means that M should be larger than 100 * N in order to guarantee the property of at most 1% difference in the reassignments on backend changes. M must be a prime number. Cilium uses a default size of 16381 for M. The following sizes for M are supported as maglev.tableSize Helm option:

maglev.tableSize value

251

509

1021

2039

4093

8191

16381

32749

65521

131071

For example, a maglev.tableSize of 16381 is suitable for a maximum of ~160 backends per service. If a higher number of backends are provisioned under this setting, then the difference in reassignments on backend changes will increase.

The maglev.hashSeed option is recommended to be set in order for Cilium to not rely on the fixed built-in seed. The seed is a base64-encoded 12 byte-random number, and can be generated once through head -c12 /dev/urandom | base64 -w0, for example. Every Cilium agent in the cluster must use the same hash seed for Maglev to work.

The below deployment example is generating and passing such seed to Helm as well as setting the Maglev table size to 65521 to allow for ~650 maximum backends for a given service (with the property of at most 1% difference on backend reassignments):

  1. SEED=$(head -c12 /dev/urandom | base64 -w0)
  2. helm install cilium cilium/cilium --version 1.12.0 \
  3.     --namespace kube-system \
  4.     --set kubeProxyReplacement=strict \
  5.     --set loadBalancer.algorithm=maglev \
  6.     --set maglev.tableSize=65521 \
  7.     --set maglev.hashSeed=$SEED \
  8.     --set k8sServiceHost=${API_SERVER_IP} \
  9.     --set k8sServicePort=${API_SERVER_PORT}

Note that enabling Maglev will have a higher memory consumption on each Cilium-managed Node compared to the default of loadBalancer.algorithm=random given random does not need the extra lookup tables. However, random won’t have consistent backend selection.

Direct Server Return (DSR)

By default, Cilium’s eBPF NodePort implementation operates in SNAT mode. That is, when node-external traffic arrives and the node determines that the backend for the LoadBalancer, NodePort, or services with externalIPs is at a remote node, then the node is redirecting the request to the remote backend on its behalf by performing SNAT. This does not require any additional MTU changes. The cost is that replies from the backend need to make the extra hop back to that node to perform the reverse SNAT translation there before returning the packet directly to the external client.

This setting can be changed through the loadBalancer.mode Helm option to dsr in order to let Cilium’s eBPF NodePort implementation operate in DSR mode. In this mode, the backends reply directly to the external client without taking the extra hop, meaning, backends reply by using the service IP/port as a source. DSR currently requires Cilium to be deployed in Native-Routing, i.e. it will not work in either tunneling mode.

Another advantage in DSR mode is that the client’s source IP is preserved, so policy can match on it at the backend node. In the SNAT mode this is not possible. Given a specific backend can be used by multiple services, the backends need to be made aware of the service IP/port which they need to reply with. Therefore, Cilium encodes this information in a Cilium-specific IPv4 option or IPv6 Destination Option extension header at the cost of advertising a lower MTU. For TCP services, Cilium only encodes the service IP/port for the SYN packet, but not subsequent ones. The latter also allows to operate Cilium in a hybrid mode as detailed in the next subsection where DSR is used for TCP and SNAT for UDP in order to avoid an otherwise needed MTU reduction.

Note that usage of DSR mode might not work in some public cloud provider environments due to the Cilium-specific IP options that could be dropped by an underlying network fabric. In case of connectivity issues to services where backends are located on a remote node from the node that is processing the given NodePort request, first check whether the NodePort request actually arrived on the node containing the backend. If this was not the case, then switching back to the default SNAT mode would be advised as a workaround.

Also, in some public cloud provider environments, which implement a source / destination IP address checking (e.g. AWS), the checking has to be disabled in order for the DSR mode to work.

The above Helm example configuration in a kube-proxy-free environment with DSR-only mode enabled would look as follows:

  1. helm install cilium cilium/cilium --version 1.12.0 \
  2.     --namespace kube-system \
  3.     --set tunnel=disabled \
  4.     --set autoDirectNodeRoutes=true \
  5.     --set kubeProxyReplacement=strict \
  6.     --set loadBalancer.mode=dsr \
  7.     --set k8sServiceHost=${API_SERVER_IP} \
  8.     --set k8sServicePort=${API_SERVER_PORT}

Hybrid DSR and SNAT Mode

Cilium also supports a hybrid DSR and SNAT mode, that is, DSR is performed for TCP and SNAT for UDP connections. This removes the need for manual MTU changes in the network while still benefiting from the latency improvements through the removed extra hop for replies, in particular, when TCP is the main transport for workloads.

The mode setting loadBalancer.mode allows to control the behavior through the options dsr, snat and hybrid. By default the snat mode is used in the agent.

A Helm example configuration in a kube-proxy-free environment with DSR enabled in hybrid mode would look as follows:

  1. helm install cilium cilium/cilium --version 1.12.0 \
  2.     --namespace kube-system \
  3.     --set tunnel=disabled \
  4.     --set autoDirectNodeRoutes=true \
  5.     --set kubeProxyReplacement=strict \
  6.     --set loadBalancer.mode=hybrid \
  7.     --set k8sServiceHost=${API_SERVER_IP} \
  8.     --set k8sServicePort=${API_SERVER_PORT}

Socket LoadBalancer Bypass in Pod Namespace

The socket-level loadbalancer acts transparent to Cilium’s lower layer datapath in that upon connect (TCP, connected UDP), sendmsg (UDP), or recvmsg (UDP) system calls, the destination IP is checked for an existing service IP and one of the service backends is selected as a target. This means that although the application assumes it is connected to the service address, the corresponding kernel socket is actually connected to the backend address and therefore no additional lower layer NAT is required.

Cilium has built-in support for bypassing the socket-level loadbalancer and falling back to the tc loadbalancer at the veth interface when a custom redirection/operation relies on the original ClusterIP within pod namespace (e.g., Istio side-car) or due to the Pod’s nature the socket-level loadbalancer is ineffective (e.g., KubeVirt, Kata Containers).

Setting socketLB.hostNamespaceOnly=true enables this bypassing mode. When enabled, this circumvents socket rewrite in the connect() and sendmsg() syscall bpf hook and will pass the original packet to next stage of operation (e.g., stack in per-endpoint-routing mode) and re-enables service lookup in the tc bpf program.

A Helm example configuration in a kube-proxy-free environment with socket LB bypass looks as follows:

  1. helm install cilium cilium/cilium --version 1.12.0 \
  2.     --namespace kube-system \
  3.     --set tunnel=disabled \
  4.     --set autoDirectNodeRoutes=true \
  5.     --set kubeProxyReplacement=strict \
  6.     --set socketLB.hostNamespaceOnly=true

LoadBalancer & NodePort XDP Acceleration

Cilium has built-in support for accelerating NodePort, LoadBalancer services and services with externalIPs for the case where the arriving request needs to be forwarded and the backend is located on a remote node. This feature was introduced in Cilium version 1.8 at the XDP (eXpress Data Path) layer where eBPF is operating directly in the networking driver instead of a higher layer.

The mode setting loadBalancer.acceleration allows to enable this acceleration through the option native. The option disabled is the default and disables the acceleration. The majority of drivers supporting 10G or higher rates also support native XDP on a recent kernel. For cloud based deployments most of these drivers have SR-IOV variants that support native XDP as well. For on-prem deployments the Cilium XDP acceleration can be used in combination with LoadBalancer service implementations for Kubernetes such as MetalLB. The acceleration can be enabled only on a single device which is used for direct routing.

For high-scale environments, also consider tweaking the default map sizes to a larger number of entries e.g. through setting a higher config.bpfMapDynamicSizeRatio. See eBPF Maps for further details.

The loadBalancer.acceleration setting is supported for DSR, SNAT and hybrid modes and can be enabled as follows for loadBalancer.mode=hybrid in this example:

  1. helm install cilium cilium/cilium --version 1.12.0 \
  2.     --namespace kube-system \
  3.     --set tunnel=disabled \
  4.     --set autoDirectNodeRoutes=true \
  5.     --set kubeProxyReplacement=strict \
  6.     --set loadBalancer.acceleration=native \
  7.     --set loadBalancer.mode=hybrid \
  8.     --set k8sServiceHost=${API_SERVER_IP} \
  9.     --set k8sServicePort=${API_SERVER_PORT}

In case of a multi-device environment, where Cilium’s device auto-detection selects more than a single device to expose NodePort or a user specifies multiple devices with devices, the XDP acceleration is enabled on all devices. This means that each underlying device’s driver must have native XDP support on all Cilium managed nodes. In addition, for the performance reasons we recommend kernel >= 5.5 for the multi-device XDP acceleration.

A list of drivers supporting native XDP can be found in the table below. The corresponding network driver name of an interface can be determined as follows:

  1. # ethtool -i eth0
  2. driver: nfp
  3. [...]

Vendor

Driver

XDP Support

Amazon

ena

>= 5.6

Broadcom

bnxt_en

>= 4.11

Cavium

thunderx

>= 4.12

Freescale

dpaa2

>= 5.0

Intel

ixgbe

>= 4.12

ixgbevf

>= 4.17

i40e

>= 4.13

ice

>= 5.5

Marvell

mvneta

>= 5.5

Mellanox

mlx4

>= 4.8

mlx5

>= 4.9

Microsoft

hv_netvsc

>= 5.6

Netronome

nfp

>= 4.10

Others

virtio_net

>= 4.10

tun/tap

>= 4.14

Qlogic

qede

>= 4.10

Socionext

netsec

>= 5.3

Solarflare

sfc

>= 5.5

Texas Instruments

cpsw

>= 5.3

The current Cilium kube-proxy XDP acceleration mode can also be introspected through the cilium status CLI command. If it has been enabled successfully, Native is shown:

  1. $ kubectl -n kube-system exec ds/cilium -- cilium status --verbose | grep XDP
  2.   XDP Acceleration:    Native

Note that packets which have been pushed back out of the device for NodePort handling right at the XDP layer are not visible in tcpdump since packet taps come at a much later stage in the networking stack. Cilium’s monitor command or metric counters can be used instead for gaining visibility.

NodePort XDP on AWS

In order to run with NodePort XDP on AWS, follow the instructions in the Quick Installation guide to set up an EKS cluster or use any other method of your preference to set up a Kubernetes cluster.

If you are following the EKS guide, make sure to create a node group with SSH access, since we need few additional setup steps as well as create a larger instance type which supports the Elastic Network Adapter (ena). As an instance example, m5n.xlarge is used in the config nodegroup-config.yaml:

  1. apiVersion: eksctl.io/v1alpha5
  2. kind: ClusterConfig
  4. metadata:
  5.   name: test-cluster
  6.   region: us-west-2
  8. nodeGroups:
  9.   - name: ng-1
  10.     instanceType: m5n.xlarge
  11.     desiredCapacity: 2
  12.     ssh:
  13.       allow: true
  14.     ## taint nodes so that application pods are
  15.     ## not scheduled/executed until Cilium is deployed.
  16.     ## Alternatively, see the note below.
  17.     taints:
  18.       - key: "node.cilium.io/agent-not-ready"
  19.         value: "true"
  20.         effect: "NoExecute"

Note

Please make sure to read and understand the documentation page on taint effects and unmanaged pods.

The nodegroup is created with:

  1. $ eksctl create nodegroup -f nodegroup-config.yaml

Each of the nodes need the kernel-ng and ethtool package installed. The former is needed in order to run a sufficiently recent kernel for eBPF in general and native XDP support on the ena driver. The latter is needed to configure channel parameters for the NIC.

  1. $ IPS=$(kubectl get no -o jsonpath='{$.items[*].status.addresses[?(@.type=="ExternalIP")].address }{"\\n"}' | tr ' ' '\\n')
  3. $ for ip in $IPS ; do ssh ec2-user@$ip "sudo amazon-linux-extras install -y kernel-ng && sudo yum install -y ethtool && sudo reboot"; done

Once the nodes come back up their kernel version should say 5.4.58-27.104.amzn2.x86_64 or similar through uname -r. In order to run XDP on ena, make sure the driver version is at least 2.2.8. The driver version can be inspected through ethtool -i eth0. For the given kernel version the driver version should be reported as 2.2.10g.

Before Cilium’s XDP acceleration can be deployed, there are two settings needed on the network adapter side, that is, MTU needs to be lowered in order to be able to operate with XDP, and number of combined channels need to be adapted.

The default MTU is set to 9001 on the ena driver. Given XDP buffers are linear, they operate on a single page. A driver typically reserves some headroom for XDP as well (e.g. for encapsulation purpose), therefore, the highest possible MTU for XDP would be 3498.

In terms of ena channels, the settings can be gathered via ethtool -l eth0. For the m5n.xlarge instance, the default output should look like:

  1. Channel parameters for eth0:
  2. Pre-set maximums:
  3. RX:             0
  4. TX:             0
  5. Other:          0
  6. Combined:       4
  7. Current hardware settings:
  8. RX:             0
  9. TX:             0
  10. Other:          0
  11. Combined:       4

In order to use XDP the channels must be set to at most 1/2 of the value from Combined above. Both, MTU and channel changes are applied as follows:

  1. $ for ip in $IPS ; do ssh ec2-user@$ip "sudo ip link set dev eth0 mtu 3498"; done
  2. $ for ip in $IPS ; do ssh ec2-user@$ip "sudo ethtool -L eth0 combined 2"; done

In order to deploy Cilium, the Kubernetes API server IP and port is needed:

  1. $ export API_SERVER_IP=$(kubectl get ep kubernetes -o jsonpath='{$.subsets[0].addresses[0].ip}')
  2. $ export API_SERVER_PORT=443

Finally, the deployment can be upgraded and later rolled-out with the loadBalancer.acceleration=native setting to enable XDP in Cilium:

  1. helm upgrade cilium cilium/cilium --version 1.12.0 \
  2.       --namespace kube-system \
  3.       --reuse-values \
  4.       --set autoDirectNodeRoutes=true \
  5.       --set kubeProxyReplacement=strict \
  6.       --set loadBalancer.acceleration=native \
  7.       --set loadBalancer.mode=snat \
  8.       --set k8sServiceHost=${API_SERVER_IP} \
  9.       --set k8sServicePort=${API_SERVER_PORT}

NodePort XDP on Azure

To enable NodePort XDP on Azure AKS or a self-managed Kubernetes running on Azure, the virtual machines running Kubernetes must have Accelerated Networking enabled. In addition, the Linux kernel on the nodes must also have support for native XDP in the hv_netvsc driver, which is available in kernel >= 5.6 and was backported to the Azure Linux kernel in 5.4.0-1022.

On AKS, make sure to use the AKS Ubuntu 18.04 node image with Kubernetes version v1.18 which will provide a Linux kernel with the necessary backports to the hv_netvsc driver. Please refer to the documentation on how to configure an AKS cluster for more details.

To enable accelerated networking when creating a virtual machine or virtual machine scale set, pass the --accelerated-networking option to the Azure CLI. Please refer to the guide on how to create a Linux virtual machine with Accelerated Networking using Azure CLI for more details.

When Accelerated Networking is enabled, lspci will show a Mellanox ConnectX-3 or ConnectX-4 Lx NIC:

  1. $ lspci | grep Ethernet
  2. 2846:00:02.0 Ethernet controller: Mellanox Technologies MT27710 Family [ConnectX-4 Lx Virtual Function] (rev 80)

In order to run XDP, large receive offload (LRO) needs to be disabled on the hv_netvsc device. If not the case already, this can be achieved by:

  1. $ ethtool -K eth0 lro off

NodePort XDP requires Cilium to run in direct routing mode (tunnel=disabled). It is recommended to use Azure IPAM for the pod IP address allocation, which will automatically configure your virtual network to route pod traffic correctly:

  1. helm install cilium cilium/cilium --version 1.12.0 \
  2.   --namespace kube-system \
  3.   --set ipam.mode=azure \
  4.   --set azure.enabled=true \
  5.   --set azure.resourceGroup=$AZURE_NODE_RESOURCE_GROUP \
  6.   --set azure.subscriptionID=$AZURE_SUBSCRIPTION_ID \
  7.   --set azure.tenantID=$AZURE_TENANT_ID \
  8.   --set azure.clientID=$AZURE_CLIENT_ID \
  9.   --set azure.clientSecret=$AZURE_CLIENT_SECRET \
  10.   --set tunnel=disabled \
  11.   --set enableIPv4Masquerade=false \
  12.   --set devices=eth0 \
  13.   --set kubeProxyReplacement=strict \
  14.   --set loadBalancer.acceleration=native \
  15.   --set loadBalancer.mode=hybrid \
  16.   --set k8sServiceHost=${API_SERVER_IP} \
  17.   --set k8sServicePort=${API_SERVER_PORT}

When running Azure IPAM on a self-managed Kubernetes cluster, each v1.Node must have the resource ID of its VM in the spec.providerID field. Refer to the Azure IPAM reference for more information.

NodePort XDP on GCP

NodePort XDP on the Google Cloud Platform is currently not supported. Both virtual network interfaces available on Google Compute Engine (the older virtIO-based interface and the newer gVNIC) are currently lacking support for native XDP.

NodePort Devices, Port and Bind settings

When running Cilium’s eBPF kube-proxy replacement, by default, a NodePort or LoadBalancer service or a service with externalIPs will be accessible through the IP addresses of native devices which have the default route on the host or have Kubernetes InternalIP or ExternalIP assigned. InternalIP is preferred over ExternalIP if both exist. To change the devices, set their names in the devices Helm option, e.g. devices='{eth0,eth1,eth2}'. Each listed device has to be named the same on all Cilium managed nodes. Alternatively if the devices do not match across different nodes, the wildcard option can be used, e.g. devices=eth+, which would match any device starting with prefix eth. If no device can be matched the Cilium agent will try to perform auto detection.

When multiple devices are used, only one device can be used for direct routing between Cilium nodes. By default, if a single device was detected or specified via devices then Cilium will use that device for direct routing. Otherwise, Cilium will use a device with Kubernetes InternalIP or ExternalIP being set. InternalIP is preferred over ExternalIP if both exist. To change the direct routing device, set the nodePort.directRoutingDevice Helm option, e.g. nodePort.directRoutingDevice=eth1. The wildcard option can be used as well as the devices option, e.g. directRoutingDevice=eth+. If more than one devices match the wildcard option, Cilium will sort them in increasing alphanumerical order and pick the first one. If the direct routing device does not exist within devices, Cilium will add the device to the latter list. The direct routing device is used for the NodePort XDP acceleration as well (if enabled).

In addition, thanks to the socket-LB feature, the NodePort service can be accessed by default from a host or a pod within a cluster via its public, any local (except for docker* prefixed names) or loopback address, e.g. 127.0.0.1:NODE_PORT.

If kube-apiserver was configured to use a non-default NodePort port range, then the same range must be passed to Cilium via the nodePort.range option, for example, as nodePort.range="10000\,32767" for a range of 10000-32767. The default Kubernetes NodePort range is 30000-32767.

If the NodePort port range overlaps with the ephemeral port range (net.ipv4.ip_local_port_range), Cilium will append the NodePort range to the reserved ports (net.ipv4.ip_local_reserved_ports). This is needed to prevent a NodePort service from hijacking traffic of a host local application which source port matches the service port. To disable the modification of the reserved ports, set nodePort.autoProtectPortRanges to false.

By default, the NodePort implementation prevents application bind(2) requests to NodePort service ports. In such case, the application will typically see a bind: Operation not permitted error. This happens either globally for older kernels or starting from v5.7 kernels only for the host namespace by default and therefore not affecting any application pod bind(2) requests anymore. In order to opt-out from this behavior in general, this setting can be changed for expert users by switching nodePort.bindProtection to false.

NodePort with FHRP & VPC

When using Cilium’s kube-proxy replacement in conjunction with a FHRP such as VRRP or Cisco’s HSRP and VPC (also known as multi-chassis EtherChannel), the default configuration can cause issues or unwanted traffic flows. This is due to an optimization that causes the source IP of ingress packets destined for a NodePort to be associated with the corresponding MAC address, and later in the reply, the MAC address is used as the destination when forwarding the L2 frame, bypassing the FIB lookup.

In such an environment, it may be preferred to instruct Cilium not to attempt this optimization. This will ensure the response is always forwarded to the MAC address of the currently active FHRP peer, no matter the origin of the incoming packet.

To disable the optimization set bpf.lbBypassFIBLookup to false.

  1. helm install cilium cilium/cilium --version 1.12.0 \
  2.     --namespace kube-system \
  3.     --set kubeProxyReplacement=strict \
  4.     --set bpf.lbBypassFIBLookup=false

Configuring BPF Map Sizes

For high-scale environments, Cilium’s BPF maps can be configured to have higher limits on the number of entries. Overriding Helm options can be used to tweak these limits.

To increase the number of entries in Cilium’s BPF LB service, backend and affinity maps consider overriding bpf.lbMapMax Helm option. The default value of this LB map size is 65536.

  1. helm install cilium cilium/cilium --version 1.12.0 \
  2.     --namespace kube-system \
  3.     --set kubeProxyReplacement=strict \
  4.     --set bpf.lbMapMax=131072

Container HostPort Support

Although not part of kube-proxy, Cilium’s eBPF kube-proxy replacement also natively supports hostPort service mapping without having to use the Helm CNI chaining option of cni.chainingMode=portmap.

By specifying kubeProxyReplacement=strict the native hostPort support is automatically enabled and therefore no further action is required. Otherwise hostPort.enabled=true can be used to enable the setting.

If the hostPort is specified without an additional hostIP, then the Pod will be exposed to the outside world with the same local addresses from the node that were detected and used for exposing NodePort services, e.g. the Kubernetes InternalIP or ExternalIP if set. Additionally, the Pod is also accessible through the loopback address on the node such as 127.0.0.1:hostPort. If in addition to hostPort also a hostIP has been specified for the Pod, then the Pod will only be exposed on the given hostIP instead. A hostIP of 0.0.0.0 will have the same behavior as if a hostIP was not specified. The hostPort must not reside in the configured NodePort port range to avoid collisions.

An example deployment in a kube-proxy-free environment therefore is the same as in the earlier getting started deployment:

  1. helm install cilium cilium/cilium --version 1.12.0 \
  2.     --namespace kube-system \
  3.     --set kubeProxyReplacement=strict \
  4.     --set k8sServiceHost=${API_SERVER_IP} \
  5.     --set k8sServicePort=${API_SERVER_PORT}

Also, ensure that each node IP is known via INTERNAL-IP or EXTERNAL-IP, for example:

  1. $ kubectl get nodes -o wide
  2. NAME   STATUS   ROLES    AGE     VERSION   INTERNAL-IP      EXTERNAL-IP   [...]
  3. apoc   Ready    master   6h15m   v1.17.3   192.168.178.29   <none>        [...]
  4. tank   Ready    <none>   6h13m   v1.17.3   192.168.178.28   <none>        [...]

If this is not the case, then kubelet needs to be made aware of it through specifying --node-ip through KUBELET_EXTRA_ARGS. Assuming eth0 is the public facing interface, this can be achieved by:

  1. $ echo KUBELET_EXTRA_ARGS=\"--node-ip=$(ip -4 -o a show eth0 | awk '{print $4}' | cut -d/ -f1)\" | tee -a /etc/default/kubelet

After updating /etc/default/kubelet, kubelet needs to be restarted.

In order to verify whether the HostPort feature has been enabled in Cilium, the cilium status CLI command provides visibility through the KubeProxyReplacement info line. If it has been enabled successfully, HostPort is shown as Enabled, for example:

  1. $ kubectl -n kube-system exec ds/cilium -- cilium status --verbose | grep HostPort
  2.   - HostPort:       Enabled

The following modified example yaml from the setup validation with an additional hostPort: 8080 parameter can be used to verify the mapping:

  1. apiVersion: apps/v1
  2. kind: Deployment
  3. metadata:
  4.   name: my-nginx
  5. spec:
  6.   selector:
  7.     matchLabels:
  8.       run: my-nginx
  9.   replicas: 1
  10.   template:
  11.     metadata:
  12.       labels:
  13.         run: my-nginx
  14.     spec:
  15.       containers:
  16.       - name: my-nginx
  17.         image: nginx
  18.         ports:
  19.         - containerPort: 80
  20.           hostPort: 8080

After deployment, we can validate that Cilium’s eBPF kube-proxy replacement exposed the container as HostPort under the specified port 8080:

  1. $ kubectl exec -it -n kube-system cilium-fmh8d -- cilium service list
  2. ID   Frontend               Service Type   Backend
  3. [...]
  4. 5    192.168.178.29:8080    HostPort       1 => 10.29.207.199:80

Similarly, we can inspect through iptables in the host namespace that no iptables rule for the HostPort service is present:

  1. $ iptables-save | grep HOSTPORT
  2. [ empty line ]

Last but not least, a simple curl test shows connectivity for the exposed HostPort container under the node’s IP:

  1. $ curl 192.168.178.29:8080
  2. <!DOCTYPE html>
  3. <html>
  4. <head>
  5. <title>Welcome to nginx!</title>
  6. [....]

Removing the deployment also removes the corresponding HostPort from the cilium service list dump:

  1. $ kubectl delete deployment my-nginx

kube-proxy Hybrid Modes

Cilium’s eBPF kube-proxy replacement can be configured in several modes, i.e. it can replace kube-proxy entirely or it can co-exist with kube-proxy on the system if the underlying Linux kernel requirements do not support a full kube-proxy replacement.

Careful: When deploying the eBPF kube-proxy replacement under co-existence with kube-proxy on the system, be aware that both mechanisms operate independent of each other. Meaning, if the eBPF kube-proxy replacement is added or removed on an already running cluster in order to delegate operation from respectively back to kube-proxy, then it must be expected that existing connections will break since, for example, both NAT tables are not aware of each other. If deployed in co-existence on a newly spawned up node/cluster which does not yet serve user traffic, then this is not an issue.

This section elaborates on the various kubeProxyReplacement options:

  • kubeProxyReplacement=strict: This option expects a kube-proxy-free Kubernetes setup where Cilium is expected to fully replace all kube-proxy functionality. Once the Cilium agent is up and running, it takes care of handling Kubernetes services of type ClusterIP, NodePort, LoadBalancer, services with externalIPs as well as HostPort. If the underlying kernel version requirements are not met (see Kubernetes Without kube-proxy note), then the Cilium agent will bail out on start-up with an error message.

  • kubeProxyReplacement=partial: This option is intended for a hybrid setup, that is, kube-proxy is running in the Kubernetes cluster where Cilium partially replaces and optimizes kube-proxy functionality. The partial option requires the user to manually specify which components for the eBPF kube-proxy replacement should be used. When kubeProxyReplacement is set to partial make sure to also set enableHealthCheckNodeport to false, so that the Cilium agent does not start the NodePort health check server. Similarly to strict mode, the Cilium agent will bail out on start-up with an error message if the underlying kernel requirements are not met. For fine-grained configuration, socketLB.enabled, nodePort.enabled, externalIPs.enabled and hostPort.enabled can be set to true. By default all four options are set to false. A few example configurations for the partial option are provided below.

    The following Helm setup below would be equivalent to kubeProxyReplacement=strict in a kube-proxy-free environment:

    1. helm install cilium cilium/cilium --version 1.12.0 \
    2.     --namespace kube-system \
    3.     --set kubeProxyReplacement=partial \
    4.     --set socketLB.enabled=true \
    5.     --set nodePort.enabled=true \
    6.     --set externalIPs.enabled=true \
    7.     --set hostPort.enabled=true \
    8.     --set k8sServiceHost=${API_SERVER_IP} \
    9.     --set k8sServicePort=${API_SERVER_PORT}

    The following Helm setup below would be equivalent to the default Cilium service handling in v1.6 or earlier in a kube-proxy environment, that is, serving ClusterIP for pods:

    1. helm install cilium cilium/cilium --version 1.12.0 \
    2.     --namespace kube-system \
    3.     --set kubeProxyReplacement=partial

    The following Helm setup below would optimize Cilium’s NodePort, LoadBalancer and services with externalIPs handling for external traffic ingressing into the Cilium managed node in a kube-proxy environment:

    1. helm install cilium cilium/cilium --version 1.12.0 \
    2.     --namespace kube-system \
    3.     --set kubeProxyReplacement=partial \
    4.     --set nodePort.enabled=true \
    5.     --set externalIPs.enabled=true

  • kubeProxyReplacement=disabled: This option disables any Kubernetes service handling by fully relying on kube-proxy instead, except for ClusterIP services accessed from pods (pre-v1.6 behavior).

In Cilium’s Helm chart, the default mode is kubeProxyReplacement=disabled for new deployments.

The current Cilium kube-proxy replacement mode can also be introspected through the cilium status CLI command:

  1. $ kubectl -n kube-system exec ds/cilium -- cilium status | grep KubeProxyReplacement
  2. KubeProxyReplacement:   Strict      [eth0 (DR)]

Graceful Termination

Cilium’s eBPF kube-proxy replacement supports graceful termination of service endpoint pods. The feature requires at least Kubernetes version 1.20, and the feature gate EndpointSliceTerminatingCondition needs to be enabled. By default, the Cilium agent then detects such terminating Pod state. If needed, the feature can be disabled with the configuration option enable-k8s-terminating-endpoint.

The cilium agent feature flag can be probed by running cilium status command:

  1. $ kubectl -n kube-system exec ds/cilium -- cilium status --verbose
  2. [...]
  3. KubeProxyReplacement Details:
  4.  [...]
  5.  Graceful Termination:  Enabled
  6. [...]

When Cilium agent receives a Kubernetes update event for a terminating endpoint, the datapath state for the endpoint is removed such that it won’t service new connections, but the endpoint’s active connections are able to terminate gracefully. The endpoint state is fully removed when the agent receives a Kubernetes delete event for the endpoint. The Kubernetes pod termination documentation contains more background on the behavior and configuration using terminationGracePeriodSeconds.

Session Affinity

Cilium’s eBPF kube-proxy replacement supports Kubernetes service session affinity. Each connection from the same pod or host to a service configured with sessionAffinity: ClientIP will always select the same service endpoint. The default timeout for the affinity is three hours (updated by each request to the service), but it can be configured through Kubernetes’ sessionAffinityConfig if needed.

The source for the affinity depends on the origin of a request. If a request is sent from outside the cluster to the service, the request’s source IP address is used for determining the endpoint affinity. If a request is sent from inside the cluster, then the source depends on whether the socket-LB feature is used to load balance ClusterIP services. If yes, then the client’s network namespace cookie is used as the source. The latter was introduced in the 5.7 Linux kernel to implement the affinity at the socket layer at which the socket-LB operates (a source IP is not available there, as the endpoint selection happens before a network packet has been built by the kernel). If the socket-LB is not used (i.e. the loadbalancing is done at the pod network interface, on a per-packet basis), then the request’s source IP address is used as the source.

The session affinity support is enabled by default for Cilium’s kube-proxy replacement. For users who run on older kernels which do not support the network namespace cookies, a fallback in-cluster mode is implemented, which is based on a fixed cookie value as a trade-off. This makes all applications on the host to select the same service endpoint for a given service with session affinity configured. To disable the feature, set config.sessionAffinity=false.

When the fixed cookie value is not used, the session affinity of a service with multiple ports is per service IP and port. Meaning that all requests for a given service sent from the same source and to the same service port will be routed to the same service endpoints; but two requests for the same service, sent from the same source but to different service ports may be routed to distinct service endpoints.

For users who run with kube-proxy (i.e. with Cilium’s kube-proxy replacement disabled), the ClusterIP service loadbalancing when a request is sent from a pod running in a non-host network namespace is still performed at the pod network interface (until GH#16197 is fixed). For this case the session affinity support is disabled by default. To enable the feature, set config.sessionAffinity=true.

kube-proxy Replacement Health Check server

To enable health check server for the kube-proxy replacement, the kubeProxyReplacementHealthzBindAddr option has to be set (disabled by default). The option accepts the IP address with port for the health check server to serve on. E.g. to enable for IPv4 interfaces set kubeProxyReplacementHealthzBindAddr='0.0.0.0:10256', for IPv6 - kubeProxyReplacementHealthzBindAddr='[::]:10256'. The health check server is accessible via the HTTP /healthz endpoint.

LoadBalancer Source Ranges Checks

When a LoadBalancer service is configured with spec.loadBalancerSourceRanges, Cilium’s eBPF kube-proxy replacement restricts access from outside (e.g. external world traffic) to the service to the white-listed CIDRs specified in the field. If the field is empty, no restrictions for the access will be applied.

When accessing the service from inside a cluster, the kube-proxy replacement will ignore the field regardless whether it is set. This means that any pod or any host process in the cluster will be able to access the LoadBalancer service internally.

The load balancer source range check feature is enabled by default, and it can be disabled by setting config.svcSourceRangeCheck=false. It makes sense to disable the check when running on some cloud providers. E.g. Amazon NLB natively implements the check, so the kube-proxy replacement’s feature can be disabled. Meanwhile GKE internal TCP/UDP load balancer does not, so the feature must be kept enabled in order to restrict the access.

Service Proxy Name Configuration

Like kube-proxy, Cilium also honors the service.kubernetes.io/service-proxy-name service annotation and only manages services that contain a matching service-proxy-name label. This name can be configured by setting k8s.serviceProxyName option and the behavior is identical to that of kube-proxy. The service proxy name defaults to an empty string which instructs Cilium to only manage services not having service.kubernetes.io/service-proxy-name label.

For more details on the usage of service.kubernetes.io/service-proxy-name label and its working, take a look at this KEP.

Note

If Cilium with a non-empty service proxy name is meant to manage all services in kube-proxy free mode, make sure that default Kubernetes services like kube-dns and kubernetes have the required label value.

Topology Aware Hints

The kube-proxy replacement implements the K8s service Topology Aware Hints. This allows Cilium nodes to prefer service endpoints residing in the same zone. To enable the feature, set loadBalancer.serviceTopology=true.

Neighbor Discovery

When kube-proxy replacement is enabled, Cilium does L2 neighbor discovery of nodes in the cluster. This is required for the service load-balancing to populate L2 addresses for backends since it is not possible to dynamically resolve neighbors on demand in the fast-path.

In Cilium 1.10 or earlier, the agent itself contained an ARP resolution library where it triggered discovery and periodic refresh of new nodes joining the cluster. The resolved neighbor entries were pushed into the kernel and refreshed as PERMANENT entries. In some rare cases, Cilium 1.10 or earlier might have left stale entries behind in the neighbor table causing packets between some nodes to be dropped. To skip the neighbor discovery and instead rely on the Linux kernel to discover neighbors, you can pass the --enable-l2-neigh-discovery=false flag to the cilium-agent. However, note that relying on the Linux Kernel might also cause some packets to be dropped. For example, a NodePort request can be dropped on an intermediate node (i.e., the one which received a service packet and is going to forward it to a destination node which runs the selected service endpoint). This could happen if there is no L2 neighbor entry in the kernel (due to the entry being garbage collected or given that the neighbor resolution has not been done by the kernel). This is because it is not possible to drive the neighbor resolution from BPF programs in the fast-path e.g. at the XDP layer.

From Cilium 1.11 onwards, the neighbor discovery has been fully reworked and the Cilium internal ARP resolution library has been removed from the agent. The agent now fully relies on the Linux kernel to discover gateways or hosts on the same L2 network. Both IPv4 and IPv6 neighbor discovery is supported in the Cilium agent. As per our recent kernel work presented at Plumbers, “managed” neighbor entries have been upstreamed and will be available in Linux kernel v5.16 or later which the Cilium agent will detect and transparently use. In this case, the agent pushes down L3 addresses of new nodes joining the cluster as externally learned “managed” neighbor entries. For introspection, iproute2 displays them as “managed extern_learn”. The “extern_learn” attribute prevents garbage collection of the entries by the kernel’s neighboring subsystem. Such “managed” neighbor entries are dynamically resolved and periodically refreshed by the Linux kernel itself in case there is no active traffic for a certain period of time. That is, the kernel attempts to always keep them in REACHABLE state. For Linux kernels v5.15 or earlier where “managed” neighbor entries are not present, the Cilium agent similarly pushes L3 addresses of new nodes into the kernel for dynamic resolution, but with an agent triggered periodic refresh. For introspection, iproute2 displays them only as “extern_learn” in this case. If there is no active traffic for a certain period of time, then a Cilium agent controller triggers the Linux kernel-based re-resolution for attempting to keep them in REACHABLE state. The refresh interval can be changed if needed through a --arping-refresh-period=30s flag passed to the cilium-agent. The default period is 30s which corresponds to the kernel’s base reachable time.

The neighbor discovery supports multi-device environments where each node has multiple devices and multiple next-hops to another node. The Cilium agent pushes neighbor entries for all target devices, including the direct routing device. Currently, it supports one next-hop per device. The following example illustrates how the neighbor discovery works in a multi-device environment. Each node has two devices connected to different L3 networks (10.69.0.64/26 and 10.69.0.128/26), and global scope addresses each (10.69.0.1/26 and 10.69.0.2/26). A next-hop from node1 to node2 is either 10.69.0.66 dev eno1 or 10.69.0.130 dev eno2. The Cilium agent pushes neighbor entries for both 10.69.0.66 dev eno1 and 10.69.0.130 dev eno2 in this case.

  1. +---------------+     +---------------+
  2. |    node1      |     |    node2      |
  3. | 10.69.0.1/26  |     | 10.69.0.2/26  |
  4. |           eno1+-----+eno1           |
  5. |           |   |     |   |           |
  6. | 10.69.0.65/26 |     |10.69.0.66/26  |
  7. |               |     |               |
  8. |           eno2+-----+eno2           |
  9. |           |   |     | |             |
  10. | 10.69.0.129/26|     | 10.69.0.130/26|
  11. +---------------+     +---------------+

With, on node1:

  1. $ ip route show
  2. 10.69.0.2
  3.         nexthop via 10.69.0.66 dev eno1 weight 1
  4.         nexthop via 10.69.0.130 dev eno2 weight 1
  6. $ ip neigh show
  7. 10.69.0.66 dev eno1 lladdr 96:eb:75:fd:89:fd extern_learn  REACHABLE
  8. 10.69.0.130 dev eno2 lladdr 52:54:00:a6:62:56 extern_learn  REACHABLE

External Access To ClusterIP Services

As per k8s Service, Cilium’s eBPF kube-proxy replacement by default disallows access to a ClusterIP service from outside the cluster. This can be allowed by setting bpf.lbExternalClusterIP=true.

Troubleshooting

Validate BPF cgroup programs attachment

Cilium attaches BPF cgroup programs to enable socket-based load-balancing (aka host-reachable services). If you see connectivity issues for clusterIP services, check if the programs are attached to the host cgroup root. The default cgroup root is set to /run/cilium/cgroupv2. Run the following commands from a Cilium agent pod as well as the underlying kubernetes node where the pod is running. If the container runtime in your cluster is running in the cgroup namespace mode, Cilium agent pod can attach BPF cgroup programs to the virtualized cgroup root. In such cases, Cilium kube-proxy replacement based load-balancing may not be effective leading to connectivity issues. For more information, ensure that you have the fix Pull Request.

  1. $ mount | grep cgroup2
  2. none on /run/cilium/cgroupv2 type cgroup2 (rw,relatime)
  4. $ bpftool cgroup tree /run/cilium/cgroupv2/
  5. CgroupPath
  6. ID       AttachType      AttachFlags     Name
  7. /run/cilium/cgroupv2
  8. 10613    device          multi
  9. 48497    connect4
  10. 48493    connect6
  11. 48499    sendmsg4
  12. 48495    sendmsg6
  13. 48500    recvmsg4
  14. 48496    recvmsg6
  15. 48498    getpeername4
  16. 48494    getpeername6

Limitations

  • Cilium’s eBPF kube-proxy replacement currently cannot be used with Transparent Encryption.

  • Cilium’s eBPF kube-proxy replacement relies upon the socket-LB feature which uses eBPF cgroup hooks to implement the service translation. Using it with libceph deployments currently requires support for the getpeername(2) hook address translation in eBPF, which is only available for kernels v5.8 and higher.

  • Cilium’s DSR NodePort mode currently does not operate well in environments with TCP Fast Open (TFO) enabled. It is recommended to switch to snat mode in this situation.

  • Cilium’s eBPF kube-proxy replacement does not support the SCTP transport protocol. Only TCP and UDP is supported as a transport for services at this point.

  • Cilium’s eBPF kube-proxy replacement does not allow hostPort port configurations for Pods that overlap with the configured NodePort range. In such case, the hostPort setting will be ignored and a warning emitted to the Cilium agent log. Similarly, explicitly binding the hostIP to the loopback address in the host namespace is currently not supported and will log a warning to the Cilium agent log.

  • When Cilium’s kube-proxy replacement is used with Kubernetes versions(< 1.19) that have support for EndpointSlices, Services without selectors and backing Endpoints don’t work. The reason is that Cilium only monitors changes made to EndpointSlices objects if support is available and ignores Endpoints in those cases. Kubernetes 1.19 release introduces EndpointSliceMirroring controller that mirrors custom Endpoints resources to corresponding EndpointSlices and thus allowing backing Endpoints to work. For a more detailed discussion see GitHub issue 12438.

  • When deployed on kernels older than 5.7, Cilium is unable to distinguish between host and pod namespaces due to the lack of kernel support for network namespace cookies. As a result, Kubernetes services are reachable from all pods via the loopback address.

  • The neighbor discovery in a multi-device environment doesn’t work with the runtime device detection which means that the target devices for the neighbor discovery doesn’t follow the device changes.

Further Readings

The following presentations describe inner-workings of the kube-proxy replacement in eBPF in great details:

  • “Liberating Kubernetes from kube-proxy and iptables” (KubeCon North America 2019, slides, video)

  • “Kubernetes service load-balancing at scale with BPF & XDP” (Linux Plumbers 2020, slides, video)

  • “eBPF as a revolutionary technology for the container landscape” (Fosdem 2020, slides, video)

  • “Kernel improvements for Cilium socket LB” (LSF/MM/BPF 2020, slides)