Skip to content

Document bpfKubeProxyHealthzPort conflict when kube-proxy cannot be disabled #2575

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
tomastigera wants to merge 2 commits into
base: main
Choose a base branch
from
+30 −0
Open

Document bpfKubeProxyHealthzPort conflict when kube-proxy cannot be disabled #2575

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
0f012df
Document bpfKubeProxyHealthzPort conflict with Kubernetes kube-proxy
tomastigera Mar 8, 2026
702f99b
Fix incorrect port 10257 attribution (containerd → kube-controller-ma…
tomastigera Mar 27, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 6 additions & 0 deletions calico-enterprise/operations/ebpf/enabling-ebpf.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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}}'
Comment on lines +188 to +191
Copy link

Copilot AI Mar 8, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This states that bpfKubeProxyHealthzPort: 0 disables the embedded health check server, but the generated Felix config reference (calico-enterprise/_includes/components/FelixConfig/config-params.json) currently documents this parameter only as an integer port and does not mention 0 as a disable value. Please add a version/feature gate note (and link) for when 0 is supported, or change the guidance to selecting an unused port (as in the versioned docs).

Suggested change
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}}'
You should also set `bpfKubeProxyHealthzPort` to an unused port to avoid conflicts with 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; the new port value is only to avoid the conflict. For example:
```bash
kubectl patch felixconfiguration default --patch='{"spec": {"bpfKubeProxyHealthzPort": 11256}}'

Copilot uses AI. Check for mistakes.
Copy link
Copy Markdown
Collaborator

@ctauchen ctauchen Mar 9, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@tomastigera Is this valid?

Copy link
Copy Markdown
Contributor Author

@tomastigera tomastigera Mar 27, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

i think not anymore, there was some lag to merge the os pr to ee

```

### MKE: Change the VXLAN port before enabling eBPF
Copy link
Copy Markdown
Collaborator

@ctauchen ctauchen Mar 9, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think this PR includes changes from the other PR #2574 . Can you separate them?


:::caution
Expand Down
6 changes: 6 additions & 0 deletions calico-enterprise_versioned_docs/version-3.23-1/operations/ebpf/enabling-ebpf.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 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}}'
```

### MKE: Change the VXLAN port before enabling eBPF

:::caution
Expand Down
6 changes: 6 additions & 0 deletions calico/operations/ebpf/enabling-ebpf.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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}}'
```
Comment on lines +329 to +333
Copy link

Copilot AI Mar 8, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This claims that setting bpfKubeProxyHealthzPort to 0 disables Felix's embedded health check server. However, the generated Felix configuration reference (calico/_includes/components/FelixConfig/config-params.json) documents this field only as an integer port (default 10256) and does not mention 0 having special meaning. Please either (a) add a version/feature availability note and link to the release that implements 0=disabled, or (b) keep the guidance consistent with released docs by choosing an unused port instead of 0.

Copilot uses AI. Check for mistakes.

### MKE: Change the VXLAN port before enabling eBPF

:::caution
Expand Down
6 changes: 6 additions & 0 deletions calico_versioned_docs/version-3.30/operations/ebpf/enabling-ebpf.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 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}}'
```

### Enable eBPF mode

**The next step depends on whether you installed $[prodname] using the operator, or a manifest:**
Expand Down
6 changes: 6 additions & 0 deletions calico_versioned_docs/version-3.31/operations/ebpf/enabling-ebpf.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 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}}'
```

### MKE: Change the VXLAN port before enabling eBPF

:::caution
Expand Down
Loading