Use a static public IP address and DNS label with the Azure Kubernetes Service (AKS) load balancer

Article
02/27/2024

When you create a load balancer resource in an Azure Kubernetes Service (AKS) cluster, the public IP address assigned to it is only valid for the lifespan of that resource. If you delete the Kubernetes service, the associated load balancer and IP address are also deleted. If you want to assign a specific IP address or retain an IP address for redeployed Kubernetes services, you can create and use a static public IP address.

This article shows you how to create a static public IP address and assign it to your Kubernetes service.

Before you begin

You need the Azure CLI version 2.0.59 or later installed and configured. Run az --version to find the version. If you need to install or upgrade, see Install Azure CLI.
This article covers using a Standard SKU IP with a Standard SKU load balancer. For more information, see IP address types and allocation methods in Azure.

Create an AKS cluster

Create an Azure resource group using the az group create command.

az group create --name myNetworkResourceGroup --location eastus

Create an AKS cluster using the az aks create command.

az aks create --name myAKSCluster --resource-group myNetworkResourceGroup --generate-ssh-keys

Create a static IP address

Get the name of the node resource group using the az aks show command and query for the nodeResourceGroup property.
```
az aks show --name myAKSCluster --resource-group myNetworkResourceGroup --query nodeResourceGroup -o tsv
```
Create a static public IP address in the node resource group using the az network public ip create command.
```
az network public-ip create \
    --resource-group <node resource group name> \
    --name myAKSPublicIP \
    --sku Standard \
    --allocation-method static
```
Note

If you're using a Basic SKU load balancer in your AKS cluster, use Basic for the --sku parameter when defining a public IP. Only Basic SKU IPs work with the Basic SKU load balancer and only Standard SKU IPs work with Standard SKU load balancers.
Get the static public IP address using the az network public-ip list command. Specify the name of the node resource group and public IP address you created, and query for the ipAddress.
```
az network public-ip show --resource-group <node resource group name> --name myAKSPublicIP --query ipAddress --output tsv
```

Create a service using the static IP address

Ensure the cluster identity used by the AKS cluster has delegated permissions to the public IP's resource group using the az role assignment create command.

CLIENT_ID=$(az aks show --name myAKSCluster --resource-group myNetworkResourceGroup --query identity.principalId -o tsv)
RG_SCOPE=$(az group show --name <node resource group> --query id -o tsv)
az role assignment create \
    --assignee ${CLIENT_ID} \
    --role "Network Contributor" \
    --scope ${RG_SCOPE}

Important

If you customized your outbound IP, make sure your cluster identity has permissions to both the outbound public IP and the inbound public IP.

Create a file named load-balancer-service.yaml and copy in the contents of the following YAML file, providing your own public IP address created in the previous step and the node resource group name.

Important

Adding the loadBalancerIP property to the load balancer YAML manifest is deprecating following upstream Kubernetes. While current usage remains the same and existing services are expected to work without modification, we highly recommend setting service annotations instead. To set service annotations, you can either use service.beta.kubernetes.io/azure-pip-name for public IP name, or use service.beta.kubernetes.io/azure-load-balancer-ipv4 for an IPv4 address and service.beta.kubernetes.io/azure-load-balancer-ipv6 for an IPv6 address, as shown in the example YAML.
```
apiVersion: v1
kind: Service
metadata:
  annotations:
    service.beta.kubernetes.io/azure-load-balancer-resource-group: <node resource group name>
    service.beta.kubernetes.io/azure-pip-name: myAKSPublicIP
  name: azure-load-balancer
spec:
  type: LoadBalancer
  ports:
  - port: 80
  selector:
    app: azure-load-balancer
```
Note

Adding the service.beta.kubernetes.io/azure-pip-name annotation ensures the most efficient LoadBalancer creation and is highly recommended to avoid potential throttling.
Set a public-facing DNS label to the service using the service.beta.kubernetes.io/azure-dns-label-name service annotation. This publishes a fully qualified domain name (FQDN) for your service using Azure's public DNS servers and top-level domain. The annotation value must be unique within the Azure location, so we recommend you use a sufficiently qualified label. Azure automatically appends a default suffix in the location you selected, such as <location>.cloudapp.azure.com, to the name you provide, creating the FQDN.

Note

If you want to publish the service on your own domain, see Azure DNS and the external-dns project.
```
apiVersion: v1
kind: Service
metadata:
  annotations:
    service.beta.kubernetes.io/azure-load-balancer-resource-group: <node resource group name>
    service.beta.kubernetes.io/azure-pip-name: myAKSPublicIP
    service.beta.kubernetes.io/azure-dns-label-name: <unique-service-label>
  name: azure-load-balancer
spec:
  type: LoadBalancer
  ports:
  - port: 80
  selector:
    app: azure-load-balancer
```
Create the service and deployment using the kubectl apply command.
```
kubectl apply -f load-balancer-service.yaml
```

To see the DNS label for your load balancer, use the kubectl describe service command.

kubectl describe service azure-load-balancer

The DNS label will be listed under the Annotations, as shown in the following condensed example output:

Name:                    azure-load-balancer
Namespace:               default
Labels:                  <none>
Annotations:             service.beta.kuberenetes.io/azure-dns-label-name: <unique-service-label>

Troubleshoot

If the static IP address defined in the loadBalancerIP property of the Kubernetes service manifest doesn't exist or hasn't been created in the node resource group and there are no other delegations configured, the load balancer service creation fails. To troubleshoot, review the service creation events using the kubectl describe command. Provide the name of the service specified in the YAML manifest, as shown in the following example:

kubectl describe service azure-load-balancer

The output shows you information about the Kubernetes service resource. The following example output shows a Warning in the Events: "user supplied IP address was not found." In this scenario, make sure you created the static public IP address in the node resource group and that the IP address specified in the Kubernetes service manifest is correct.

Name:                     azure-load-balancer
Namespace:                default
Labels:                   <none>
Annotations:              <none>
Selector:                 app=azure-load-balancer
Type:                     LoadBalancer
IP:                       10.0.18.125
IP:                       40.121.183.52
Port:                     <unset>  80/TCP
TargetPort:               80/TCP
NodePort:                 <unset>  32582/TCP
Endpoints:                <none>
Session Affinity:         None
External Traffic Policy:  Cluster
Events:
  Type     Reason                      Age               From                Message
  ----     ------                      ----              ----                -------
  Normal   CreatingLoadBalancer        7s (x2 over 22s)  service-controller  Creating load balancer
  Warning  CreatingLoadBalancerFailed  6s (x2 over 12s)  service-controller  Error creating load balancer (will retry): Failed to create load balancer for service default/azure-load-balancer: user supplied IP Address 40.121.183.52 was not found

Next steps

For more control over the network traffic to your applications, use the application routing addon for AKS. For more information about the app routing addon, see Managed NGINX ingress with the application routing add-on.