Can I migrate my AKS cluster from Kubenet to Overlay network plugin without recreating the cluster?

Question

Can I migrate my AKS cluster from Kubenet to Overlay network plugin without recreating the cluster?

HarshadbhaiKothiyaMeetkumar-1376 0

I have an existing AKS cluster that uses Kubenet as the network plugin. I’m considering migrating to the Overlay network plugin for better IP management and scalability.

Is it possible to switch from Kubenet to Overlay without deleting and recreating the cluster?
If yes, what steps or considerations should I keep in mind during migration?
Are there any limitations, downtime, or risks involved?

Any official documentation links would be greatly appreciated!

Himanshu Shekhar 1,265 Reputation points Microsoft External Staff Moderator

2025-11-04T13:49:20.1366667+00:00
Harshadbhai, Kothiya Meetkumar Thank you for reaching Microsoft QnA platform.

No, it is not possible to migrate an existing AKS cluster from the Kubenet network plugin to the Azure CNI Overlay plugin without recreating the cluster.

The confusion often arises because AKS does support a specific, limited network migration:

You can update an existing cluster that already uses Azure CNI to switch from the standard (non-overlay) mode to Overlay mode, provided prerequisites are met (e.g., Kubernetes version 1.22+, no Calico network policies).

Migrating a cluster from the Kubenet plugin to the Azure CNI Overlay plugin is not supported. This is because Kubenet and Azure CNI have different architectures for pod networking.

The safe and supported method is by creating a new AKS cluster with the Azure CNI Overlay network plugin and migrate workloads to it.

please consider the suggested steps below :

Plan and build a new AKS cluster with Azure CNI Overlay enabled from the start.

The Overlay model require private Pod CIDR that does not overlap with your cluster's node subnets, any peered VNets, or on-premises networks. Careful IP address space planning is crucial.

You will need to migrate your applications and configurations (YAML files, Helm charts, etc.) to the new cluster.

This process will have downtime for your applications. You must plan a migration strategy with your application's availability requirements.

Please re-evaluate and reconfigure settings that are tied to the cluster's network, such as:

· Ingress controllers

· Network policies (if you were using a non-overlay solution)

· Firewall rules and IP restrictions

· Egress configuration

Configure Azure CNI Overlay networking in AKS : https://learn.microsoft.com/en-us/azure/aks/azure-cni-overlay?tabs=kubectl

Upgrade Azure CNI IPAM mode and dataplane technology for Azure Kubernetes Service (AKS) clusters: https://learn.microsoft.com/en-us/azure/aks/upgrade-azure-cni?tabs=azure-cni

Networking concepts for applications in Azure Kubernetes Service (AKS) : https://learn.microsoft.com/en-us/azure/aks/concepts-network

I’ve sent you a private message requesting some details related to your subscription to ensure your privacy is protected. Please check your messages and let me know if you have any questions or need further clarification.

Regards

Himanshu

1 answer

Your answer

Answer 1

Hello Harshadbhai, Kothiya Meetkumar,

Thank you for posting your query on the Microsoft Q&A platform. Unfortunately, if your cluster is currently using the kubenet networking plugin, there is no fully supported path to flip to Azure CNI Overlay via a simple CLI update (like az aks update) without recreating or migrating the cluster. The official document states that you can update an existing Azure CNI cluster to Overlay mode, given certain prerequisites (Kubernetes version 1.22+, no network policies enabled, etc). But the GitHub issue confirms that clusters using kubenet do not have a supported migration path to Overlay mode today: “Today you cannot migrate Kubenet to Azure CNI overlay. A new cluster is required.”

So, in your case the safe and supported recommendation is to create a new AKS cluster with Azure CNI Overlay mode and migrate workloads rather than expecting to update the existing one. But if you still want to proceed with the migration then first decide on the pod CIDR for your overlay cluster. The overlay model requires a private CIDR that does not overlap with your node subnets, VNet peerings, on-prem networks, review your ingress, egress, IP restrictions, node-pools, network policies and last but not least evaluate the downtime tolerances in your scenario.

However, since your cluster uses kubenet, the safe path is to build a new cluster with Azure CNI Overlay and migrate your workloads. Kindly checkout these documents for your ease.

https://learn.microsoft.com/en-us/azure/aks/azure-cni-overlay?tabs=kubectl
https://learn.microsoft.com/en-us/azure/aks/upgrade-azure-cni?tabs=azure-cni
https://learn.microsoft.com/en-us/azure/aks/concepts-network-legacy-cni

If you found this information helpful, please consider accepting the answer and upvoting it.

Share via

Can I migrate my AKS cluster from Kubenet to Overlay network plugin without recreating the cluster?

1 answer

Your answer