Missing clusterCIDR Update Step in Calico IPAM Migration Documentation (VXLAN Mode)

[jfpucheu]

During an IP pool migration using Calico in VXLAN mode, we encountered unexpected network policy behavior due to a missing step in the official documentation: updating the clusterCIDR value in the kube-proxy ConfigMap to match the new Calico IP pool.

Expected Behavior

The Calico IPAM migration documentation ( https://docs.tigera.io/calico/latest/networking/ipam/migrate-pools )should clearly state that during the migration process, the clusterCIDR value in the kube-proxy ConfigMap (located in the kube-system namespace) must be updated to match the new IP pool defined in Calico.

Current Behavior

The documentation does not mention the need to update the clusterCIDR in the kube-proxy configuration. As a result, users may overlook this critical step during migration.

Possible Solution

Add a clear note in the migration guide instructing users to:

Update the clusterCIDR field in the kube-proxy ConfigMap to reflect the new Calico IP pool (e.g., 172.20.0.0/16) and restart kube-proxy
Ensure this change is applied before or during the migration to avoid network policy issues.

Context

When migrating IP pools in Calico (VXLAN mode), if the clusterCIDR in kube-proxy is not updated to match the new pool, certain network policies may block traffic. Specifically:

Pod-to-Pod communication continues to work.
Pod-to-Service communication fails when network policies are defined.
This behavior can lead to significant service disruptions and is difficult to diagnose without prior knowledge of the clusterCIDR dependency.

Your Environment

Calico Version: All
Calico Mode: VXLAN
Kubernetes Versions: All supported versions
Observed Symptoms: Network policies block traffic through Kubernetes services; direct Pod-to-Pod communication unaffected.

[caseydavenport]

@jfpucheu thanks for raising. Agree that the cluster CIDR should be mentioned, but it's also worth noting that:

• not all clusters specify a cluster CIDR to their kube-proxy
• some CIDR migrations may not require this, if their cluster CIDR value already encompasses the new IP pool CIDR.

So, the docs should just call out that if you're using the cluster-cidr argument on the kube proxy, it should include the new pool CIDR.

[caseydavenport]

@jfpucheu looking at the existing docs, I see this https://docs.tigera.io/calico/latest/networking/ipam/migrate-pools#ip-pools-and-cluster-cidrs

and this:

It is highly recommended that your Calico IP pools are within the Kubernetes cluster CIDR. If pods IPs are allocated from outside of the Kubernetes cluster CIDR, some traffic flows may have NAT applied unnecessarily causing unexpected behavior.

I'm not sure there's more we on the Calico side can / should say?

[jfpucheu]

@caseydavenport

This is not just highly recommended — it is mandatory.

I propose some clarifications like that:

In most cases, CalicoIPPool = clusterCIDR. Be careful when making this change.

For a zero-impact migration:
• you should temporarily extend the clusterCIDR in kube-proxy to cover both the old pool and the new pool;
• then, once the migration is complete, adjust the clusterCIDR to strictly match the new pool.

If downtime is acceptable, you can simply set the correct clusterCIDR value directly in kube-proxy at the end of the migration instead of extending it temporarily.

👉 It is in kube-proxy that this parameter must be modified, to ensure consistency between the cluster configuration and the Calico IP pools.

[caseydavenport]

In most cases, CalicoIPPool = clusterCIDR

I don't think this is necessarily true. Many users do not run in this configuration, instead using several IP pools within the cluster CIDR, or an IP pool that is a sub-set of the cluster CIDR (i.e., their cluster CIDR covers both their IP pool and their host IP range).

I think we could say something to the effect of "If you are using the new IP pool for Pod IP addresses and you have network policy in place, you must first update the cluster CIDR used by kube-proxy in order to prevent NAT that may impact your network policy", but I am pretty sure this is not unconditionally mandatory.

There are other uses for IP pools than pod IP allocation, users may not have network policy in place, or may not have policy that cares about the NAT that may occur, etc. (I know this sounds pedantic, but believe me I will receive clarifying questions in the opposite direction if we state this unconditionally!)

[jfpucheu]

i'm ok with that :

I think we could say something to the effect of "If you are using the new IP pool for Pod IP addresses and you have network policy in place, you must first update the cluster CIDR used by kube-proxy in order to prevent NAT that may impact your network policy", but I am pretty sure this is not unconditionally mandatory.

But it's better to change it even if it's not strictly required, so that it works in all cases.

[caseydavenport]

Closing due to tigera/docs#2255