From 0f012dfb52fb43f3fdc1789bed6a4b6a4820a72f Mon Sep 17 00:00:00 2001 From: Tomas Hruby Date: Sat, 7 Mar 2026 16:24:53 -0800 Subject: [PATCH 1/2] Document bpfKubeProxyHealthzPort conflict with Kubernetes kube-proxy When kube-proxy cannot be disabled (e.g. AKS), the BPF kube-proxy replacement's health check server conflicts with Kubernetes kube-proxy on port 10256. For released versions (calico 3.30/3.31, CE 3.23-1): change the port to an unused value (e.g. 10258). For unreleased versions (calico/next, CE/next): set the port to 0 to disable the health check server entirely (requires projectcalico/calico#12033). Co-Authored-By: Claude Opus 4.6 --- calico-enterprise/operations/ebpf/enabling-ebpf.mdx | 6 ++++++ .../version-3.23-1/operations/ebpf/enabling-ebpf.mdx | 6 ++++++ calico/operations/ebpf/enabling-ebpf.mdx | 6 ++++++ .../version-3.30/operations/ebpf/enabling-ebpf.mdx | 6 ++++++ .../version-3.31/operations/ebpf/enabling-ebpf.mdx | 6 ++++++ 5 files changed, 30 insertions(+) diff --git a/calico-enterprise/operations/ebpf/enabling-ebpf.mdx b/calico-enterprise/operations/ebpf/enabling-ebpf.mdx index f2490850ff..92823146df 100644 --- a/calico-enterprise/operations/ebpf/enabling-ebpf.mdx +++ b/calico-enterprise/operations/ebpf/enabling-ebpf.mdx @@ -185,6 +185,12 @@ kubectl patch felixconfiguration default --patch='{"spec": {"bpfKubeProxyIptable If both `kube-proxy` and `BPFKubeProxyIptablesCleanupEnabled` is enabled then `kube-proxy` will write its iptables rules and Felix will try to clean them up resulting in iptables flapping between the two. +You should also set `bpfKubeProxyHealthzPort` to `0` to disable the health check server in $[prodname]'s BPF kube-proxy replacement, which by default binds to port 10256 and would conflict with the Kubernetes `kube-proxy` already running on the node. The Kubernetes `kube-proxy` can serve the health check equally well, so there is no degradation. + +```bash +kubectl patch felixconfiguration default --patch='{"spec": {"bpfKubeProxyHealthzPort": 0}}' +``` + ### MKE: Change the VXLAN port before enabling eBPF :::caution diff --git a/calico-enterprise_versioned_docs/version-3.23-1/operations/ebpf/enabling-ebpf.mdx b/calico-enterprise_versioned_docs/version-3.23-1/operations/ebpf/enabling-ebpf.mdx index 000a8f3fff..52e5b1dd2a 100644 --- a/calico-enterprise_versioned_docs/version-3.23-1/operations/ebpf/enabling-ebpf.mdx +++ b/calico-enterprise_versioned_docs/version-3.23-1/operations/ebpf/enabling-ebpf.mdx @@ -185,6 +185,12 @@ kubectl patch felixconfiguration default --patch='{"spec": {"bpfKubeProxyIptable If both `kube-proxy` and `BPFKubeProxyIptablesCleanupEnabled` is enabled then `kube-proxy` will write its iptables rules and Felix will try to clean them up resulting in iptables flapping between the two. +You should also change `bpfKubeProxyHealthzPort` to an unused port to avoid conflicting with the Kubernetes `kube-proxy`'s default health check port (10256). The Kubernetes `kube-proxy` can serve the health check equally well, so there is no degradation. Changing the health check port of the Kubernetes `kube-proxy` is typically not possible on managed platforms such as AKS. Choose a port that is not already in use on your nodes (for example, 10258; note that 10257 may be used by containerd). + +```bash +kubectl patch felixconfiguration default --patch='{"spec": {"bpfKubeProxyHealthzPort": 10258}}' +``` + ### MKE: Change the VXLAN port before enabling eBPF :::caution diff --git a/calico/operations/ebpf/enabling-ebpf.mdx b/calico/operations/ebpf/enabling-ebpf.mdx index 59f9f50193..2c7940243e 100644 --- a/calico/operations/ebpf/enabling-ebpf.mdx +++ b/calico/operations/ebpf/enabling-ebpf.mdx @@ -326,6 +326,12 @@ kubectl patch felixconfiguration default --patch='{"spec": {"bpfKubeProxyIptable If both `kube-proxy` and `BPFKubeProxyIptablesCleanupEnabled` is enabled then `kube-proxy` will write its iptables rules and Felix will try to clean them up resulting in iptables flapping between the two. +You should also set `bpfKubeProxyHealthzPort` to `0` to disable the health check server in $[prodname]'s BPF kube-proxy replacement, which by default binds to port 10256 and would conflict with the Kubernetes `kube-proxy` already running on the node. The Kubernetes `kube-proxy` can serve the health check equally well, so there is no degradation. + +``` +kubectl patch felixconfiguration default --patch='{"spec": {"bpfKubeProxyHealthzPort": 0}}' +``` + ### MKE: Change the VXLAN port before enabling eBPF :::caution diff --git a/calico_versioned_docs/version-3.30/operations/ebpf/enabling-ebpf.mdx b/calico_versioned_docs/version-3.30/operations/ebpf/enabling-ebpf.mdx index d46be6109b..6dcbfe615b 100644 --- a/calico_versioned_docs/version-3.30/operations/ebpf/enabling-ebpf.mdx +++ b/calico_versioned_docs/version-3.30/operations/ebpf/enabling-ebpf.mdx @@ -318,6 +318,12 @@ kubectl patch felixconfiguration default --patch='{"spec": {"bpfKubeProxyIptable If both `kube-proxy` and `BPFKubeProxyIptablesCleanupEnabled` is enabled then `kube-proxy` will write its iptables rules and Felix will try to clean them up resulting in iptables flapping between the two. +You should also change `bpfKubeProxyHealthzPort` to an unused port to avoid conflicting with the Kubernetes `kube-proxy`'s default health check port (10256). The Kubernetes `kube-proxy` can serve the health check equally well, so there is no degradation. Changing the health check port of the Kubernetes `kube-proxy` is typically not possible on managed platforms such as AKS. Choose a port that is not already in use on your nodes (for example, 10258; note that 10257 may be used by containerd). + +``` +kubectl patch felixconfiguration default --patch='{"spec": {"bpfKubeProxyHealthzPort": 10258}}' +``` + ### Enable eBPF mode **The next step depends on whether you installed $[prodname] using the operator, or a manifest:** diff --git a/calico_versioned_docs/version-3.31/operations/ebpf/enabling-ebpf.mdx b/calico_versioned_docs/version-3.31/operations/ebpf/enabling-ebpf.mdx index ace49fdd49..534d9d8838 100644 --- a/calico_versioned_docs/version-3.31/operations/ebpf/enabling-ebpf.mdx +++ b/calico_versioned_docs/version-3.31/operations/ebpf/enabling-ebpf.mdx @@ -326,6 +326,12 @@ kubectl patch felixconfiguration default --patch='{"spec": {"bpfKubeProxyIptable If both `kube-proxy` and `BPFKubeProxyIptablesCleanupEnabled` is enabled then `kube-proxy` will write its iptables rules and Felix will try to clean them up resulting in iptables flapping between the two. +You should also change `bpfKubeProxyHealthzPort` to an unused port to avoid conflicting with the Kubernetes `kube-proxy`'s default health check port (10256). The Kubernetes `kube-proxy` can serve the health check equally well, so there is no degradation. Changing the health check port of the Kubernetes `kube-proxy` is typically not possible on managed platforms such as AKS. Choose a port that is not already in use on your nodes (for example, 10258; note that 10257 may be used by containerd). + +``` +kubectl patch felixconfiguration default --patch='{"spec": {"bpfKubeProxyHealthzPort": 10258}}' +``` + ### MKE: Change the VXLAN port before enabling eBPF :::caution From 702f99b77b2825211cfb82e9862c2f7510a979ee Mon Sep 17 00:00:00 2001 From: Tomas Hruby Date: Fri, 27 Mar 2026 11:54:13 -0700 Subject: [PATCH 2/2] =?UTF-8?q?Fix=20incorrect=20port=2010257=20attributio?= =?UTF-8?q?n=20(containerd=20=E2=86=92=20kube-controller-manager)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Port 10257 is used by kube-controller-manager, not containerd. Reword to note that 10257/10259 are used by control plane components and advise verifying port availability with ss/netstat. Co-Authored-By: Claude Opus 4.6 (1M context) --- .../version-3.23-1/operations/ebpf/enabling-ebpf.mdx | 2 +- .../version-3.30/operations/ebpf/enabling-ebpf.mdx | 2 +- .../version-3.31/operations/ebpf/enabling-ebpf.mdx | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/calico-enterprise_versioned_docs/version-3.23-1/operations/ebpf/enabling-ebpf.mdx b/calico-enterprise_versioned_docs/version-3.23-1/operations/ebpf/enabling-ebpf.mdx index 52e5b1dd2a..2f57a131d3 100644 --- a/calico-enterprise_versioned_docs/version-3.23-1/operations/ebpf/enabling-ebpf.mdx +++ b/calico-enterprise_versioned_docs/version-3.23-1/operations/ebpf/enabling-ebpf.mdx @@ -185,7 +185,7 @@ kubectl patch felixconfiguration default --patch='{"spec": {"bpfKubeProxyIptable If both `kube-proxy` and `BPFKubeProxyIptablesCleanupEnabled` is enabled then `kube-proxy` will write its iptables rules and Felix will try to clean them up resulting in iptables flapping between the two. -You should also change `bpfKubeProxyHealthzPort` to an unused port to avoid conflicting with the Kubernetes `kube-proxy`'s default health check port (10256). The Kubernetes `kube-proxy` can serve the health check equally well, so there is no degradation. Changing the health check port of the Kubernetes `kube-proxy` is typically not possible on managed platforms such as AKS. Choose a port that is not already in use on your nodes (for example, 10258; note that 10257 may be used by containerd). +You should also change `bpfKubeProxyHealthzPort` to an unused port to avoid conflicting with the Kubernetes `kube-proxy`'s default health check port (10256). The Kubernetes `kube-proxy` can serve the health check equally well, so there is no degradation. Changing the health check port of the Kubernetes `kube-proxy` is typically not possible on managed platforms such as AKS. Choose a port that is not already in use on your nodes (for example, 10258; note that other Kubernetes control plane components commonly use ports such as 10257 and 10259, so verify an unused port on your nodes with tools like `ss` or `netstat` before selecting one. ```bash kubectl patch felixconfiguration default --patch='{"spec": {"bpfKubeProxyHealthzPort": 10258}}' diff --git a/calico_versioned_docs/version-3.30/operations/ebpf/enabling-ebpf.mdx b/calico_versioned_docs/version-3.30/operations/ebpf/enabling-ebpf.mdx index 6dcbfe615b..ac10f6af9c 100644 --- a/calico_versioned_docs/version-3.30/operations/ebpf/enabling-ebpf.mdx +++ b/calico_versioned_docs/version-3.30/operations/ebpf/enabling-ebpf.mdx @@ -318,7 +318,7 @@ kubectl patch felixconfiguration default --patch='{"spec": {"bpfKubeProxyIptable If both `kube-proxy` and `BPFKubeProxyIptablesCleanupEnabled` is enabled then `kube-proxy` will write its iptables rules and Felix will try to clean them up resulting in iptables flapping between the two. -You should also change `bpfKubeProxyHealthzPort` to an unused port to avoid conflicting with the Kubernetes `kube-proxy`'s default health check port (10256). The Kubernetes `kube-proxy` can serve the health check equally well, so there is no degradation. Changing the health check port of the Kubernetes `kube-proxy` is typically not possible on managed platforms such as AKS. Choose a port that is not already in use on your nodes (for example, 10258; note that 10257 may be used by containerd). +You should also change `bpfKubeProxyHealthzPort` to an unused port to avoid conflicting with the Kubernetes `kube-proxy`'s default health check port (10256). The Kubernetes `kube-proxy` can serve the health check equally well, so there is no degradation. Changing the health check port of the Kubernetes `kube-proxy` is typically not possible on managed platforms such as AKS. Choose a port that is not already in use on your nodes (for example, 10258; note that other Kubernetes control plane components commonly use ports such as 10257 and 10259, so verify an unused port on your nodes with tools like `ss` or `netstat` before selecting one. ``` kubectl patch felixconfiguration default --patch='{"spec": {"bpfKubeProxyHealthzPort": 10258}}' diff --git a/calico_versioned_docs/version-3.31/operations/ebpf/enabling-ebpf.mdx b/calico_versioned_docs/version-3.31/operations/ebpf/enabling-ebpf.mdx index 534d9d8838..e970c38a19 100644 --- a/calico_versioned_docs/version-3.31/operations/ebpf/enabling-ebpf.mdx +++ b/calico_versioned_docs/version-3.31/operations/ebpf/enabling-ebpf.mdx @@ -326,7 +326,7 @@ kubectl patch felixconfiguration default --patch='{"spec": {"bpfKubeProxyIptable If both `kube-proxy` and `BPFKubeProxyIptablesCleanupEnabled` is enabled then `kube-proxy` will write its iptables rules and Felix will try to clean them up resulting in iptables flapping between the two. -You should also change `bpfKubeProxyHealthzPort` to an unused port to avoid conflicting with the Kubernetes `kube-proxy`'s default health check port (10256). The Kubernetes `kube-proxy` can serve the health check equally well, so there is no degradation. Changing the health check port of the Kubernetes `kube-proxy` is typically not possible on managed platforms such as AKS. Choose a port that is not already in use on your nodes (for example, 10258; note that 10257 may be used by containerd). +You should also change `bpfKubeProxyHealthzPort` to an unused port to avoid conflicting with the Kubernetes `kube-proxy`'s default health check port (10256). The Kubernetes `kube-proxy` can serve the health check equally well, so there is no degradation. Changing the health check port of the Kubernetes `kube-proxy` is typically not possible on managed platforms such as AKS. Choose a port that is not already in use on your nodes (for example, 10258; note that other Kubernetes control plane components commonly use ports such as 10257 and 10259, so verify an unused port on your nodes with tools like `ss` or `netstat` before selecting one. ``` kubectl patch felixconfiguration default --patch='{"spec": {"bpfKubeProxyHealthzPort": 10258}}'