Portal

Need

The Azure installation guide creates the AKS cluster with Azure CNI in node-subnet mode (--network-plugin azure). In this mode every pod takes an IP address from the AKS subnet, and each node reserves one address per pod it can run. With the guide's settings (up to 10 nodes, 30 pods per node), the AKS subnet needs about 340 usable addresses: a /23.

Many network teams cannot allocate that much routable address space without an approval process, and only offer a /26 or /27. This article explains how to install SDP on an AKS cluster that uses Azure CNI Overlay instead. With Overlay, only nodes use the subnet, so a /27 or /28 is enough. It also explains how to size the subnet with the attached calculator.

Summarized Solution

• Size the AKS subnet with the attached calculator. If Azure CNI needs more address space than you can get, use Azure CNI Overlay.
• Choose a private pod range (--pod-cidr, for example 10.244.0.0/16) and a service range that do not overlap your virtual network or any network connected to it.
• Create the AKS cluster with --network-plugin-mode overlay --pod-cidr …, without --network-policy azure and without --docker-bridge-address.
• Keep the network security group rules on the AKS subnet: pod traffic to PostgreSQL, Event Hubs and Elastic Cloud leaves with the node IP address.
• Install SDP as usual. No change to the Helm chart or to values.yaml is needed.

SDP 1.4.1 has been installed successfully on an AKS cluster with Azure CNI Overlay, following this procedure. Nothing in the Helm charts depends on how pods get their IP addresses, so the same chart and values work in both modes.

Detailed Solution

1. Understand the two networking modes

SDP works in both modes because all of its external traffic enters through the ingress controller's load balancer. The review of the 1.4.1 charts found:

• all Services are of type ClusterIP; no NodePort, hostPort or hostNetwork;
• no network policy with IP ranges, and no IP-based allow-lists for proxies;
• Data Management (Hazelcast) and Keycloak clustering use Kubernetes discovery inside the cluster;
• no hard-coded IP ranges, and the DNS precheck resolves names only.

2. Size the AKS subnet with the calculator

Open the attached AKS-Subnet-Calculator.xlsx in Excel. The shaded cells are inputs; the recommended subnet prefix updates automatically.

The calculator then shows:

• Total peak nodes: for each enabled pool, max-count + surge. Sizing always uses the peak, not the current node count, because the autoscaler and upgrades can reach it.
• Required usable IPs: peak nodes × (1 + max-pods) with Azure CNI; peak nodes with Overlay.
• Recommended AKS subnet: the smallest prefix whose usable addresses (2^{32 − prefix} − 5) cover the requirement, with the number of spare addresses.

Worked examples:

• The calculator recommends the smallest prefix that fits. Take one size larger when the spare figure is low, to allow a new node pool later: a subnet cannot be resized while it is in use.
• If the ingress controller uses an internal load balancer whose IP address comes from the AKS subnet, add one address.
• The calculator sizes the AKS subnet only. The private endpoint subnet (PostgreSQL, Event Hubs, Elastic Cloud) is separate; a /28 or /27 is enough.

Decision: if the Azure CNI result is larger than the address space you can obtain, use Overlay and continue with step 3. Otherwise, you can follow the standard installation guide.

3. Plan the address ranges

The pod and service ranges use no address space from your IP plan, but they must not overlap each other, the virtual network, or any peered, VPN or ExpressRoute network that pods need to reach. Use private (RFC 1918) address space. For a /26 allocation, a typical split is a /27 for the AKS subnet, a /28 for private endpoints and a spare /28.

4. Create the AKS cluster with Overlay

Follow Provision Azure resources, with these changes.

Add the pod range to the environment variables:

export AKS_POD_CIDR=10.244.0.0/16

AKS_SUBNET_ID=$(az network vnet subnet show \
  --vnet-name $VNET_NAME \
  --resource-group $AZURE_RESOURCE_GROUP \
  --name $AKS_SUBNET \
  --query id --output tsv)

AKS_CLUSTER_NAME=$AZURE_RESOURCE_GROUP-aks

az aks create \
  --resource-group $AZURE_RESOURCE_GROUP \
  --name $AKS_CLUSTER_NAME \
  --location $AZURE_LOCATION \
  --kubernetes-version 1.33 \
  --node-count 2 \
  --min-count 1 \
  --max-count 10 \
  --vm-set-type VirtualMachineScaleSets \
  --node-vm-size Standard_D8s_v3 \
  --vnet-subnet-id $AKS_SUBNET_ID \
  --enable-managed-identity \
  --network-plugin azure \
  --network-plugin-mode overlay \
  --pod-cidr $AKS_POD_CIDR \
  --service-cidr 10.100.0.0/16 \
  --dns-service-ip 10.100.0.10 \
  --enable-cluster-autoscaler

az aks show -g $AZURE_RESOURCE_GROUP -n $AKS_CLUSTER_NAME \
  --query "networkProfile.{plugin:networkPlugin, mode:networkPluginMode, podCidr:podCidr, serviceCidr:serviceCidr}" -o table

Expected: plugin azure, mode overlay, and your pod and service ranges.

5. Configure the network security groups

With Overlay, traffic from pods to PostgreSQL, Event Hubs and Elastic Cloud through their private endpoints uses the node IP address. The rules in the guide, which use the AKS subnet as the source, therefore still apply. Keep them unchanged.

If a network security group with deny rules is attached to the AKS subnet, it must also allow the following traffic, in addition to the AKS outbound requirements. Without these rules, pod-to-pod traffic and DNS resolution inside the cluster fail.

Two points to check on the private endpoint subnet, whatever the networking mode:

• A subnet holds only one network security group. Put the rules for PostgreSQL (port 5432) and Event Hubs (port 9093) in the same group: attaching a second group to the subnet replaces the first.
• Network security group rules apply to private endpoints only when network policies for private endpoints are enabled on the subnet (privateEndpointNetworkPolicies). Enable them if you rely on these rules to restrict access.

6. Install SDP

Continue with the installation guide from Configure Kubernetes. Nothing changes for Overlay: same Secrets, same starter values file, same helm upgrade --install command. Run the prechecks first, and install with --timeout 20m, without --wait or --atomic.

After the installation, the pods have addresses from the pod range, while the nodes have addresses from the AKS subnet:

kubectl get nodes -o wide          # INTERNAL-IP in the AKS subnet
kubectl get pods -n <NAMESPACE> -o wide   # IP in AKS_POD_CIDR

Then verify the platform as described in How to verify an SDP Self-Hosted installation.

7. Existing clusters

An existing AKS cluster can be moved from Azure CNI (node subnet) to Overlay without reinstalling SDP:

1. If the cluster uses Azure Network Policy Manager, remove it first: az aks update -g <RG> -n <CLUSTER> --network-policy none.
2. Update the IPAM mode as described in Update the IPAM mode to Azure CNI Overlay.
3. Update any network policy that uses ipBlock rules on pod addresses to use AKS_POD_CIDR.

The update cannot be reverted and reimages all node pools at the same time, so all SDP pods restart. Plan a maintenance window and take the usual backups before you start. No change to the SDP Helm values is needed.

Checklist

References

• Overview of Azure CNI Overlay networking in AKS (Microsoft)
• Configure Azure CNI Overlay networking in AKS (Microsoft)
• Provision Azure resources (SDP documentation)
• How to verify an SDP Self-Hosted installation