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

By default, the public IP address assigned to a load balancer resource created by an AKS cluster 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

This article assumes that you have an existing AKS cluster. If you need an AKS cluster, see the AKS quickstart using the Azure CLI or using the Azure portal.

You also 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 a static IP address

Create a static public IP address with the az network public ip create command. The following creates a static IP resource named myAKSPublicIP in the myResourceGroup resource group:

az network public-ip create \
    --resource-group myResourceGroup \
    --name myAKSPublicIP \
    --sku Standard \
    --allocation-method static

Note

If you are 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.

The IP address is displayed, as shown in the following condensed example output:

{
  "publicIp": {
    ...
    "ipAddress": "40.121.183.52",
    ...
  }
}

You can later get the 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 as shown in the following example:

$ az network public-ip show --resource-group myResourceGroup --name myAKSPublicIP --query ipAddress --output tsv

40.121.183.52

Create a service using the static IP address

Before creating a service, ensure the service principal used by the AKS cluster has delegated permissions to the other resource group. For example:

az role assignment create \
    --assignee <SP Client ID> \
    --role "Network Contributor" \
    --scope /subscriptions/<subscription id>/resourceGroups/<resource group name>

Alternatively, you can use the system assigned managed identity for permissions instead of the service principal. For more information, see Use managed identities.

Important

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

To create a LoadBalancer service with the static public IP address, add the loadBalancerIP property and the value of the static public IP address to the YAML manifest. Create a file named load-balancer-service.yaml and copy in the following YAML. Provide your own public IP address created in the previous step. The following example also sets the annotation to the resource group named myResourceGroup. Provide your own resource group name.

apiVersion: v1
kind: Service
metadata:
  annotations:
    service.beta.kubernetes.io/azure-load-balancer-resource-group: myResourceGroup
  name: azure-load-balancer
spec:
  loadBalancerIP: 40.121.183.52
  type: LoadBalancer
  ports:
  - port: 80
  selector:
    app: azure-load-balancer

Create the service and deployment with the kubectl apply command.

kubectl apply -f load-balancer-service.yaml

Apply a DNS label to the service

If your service is using a dynamic or static public IP address, you can use the service annotation service.beta.kubernetes.io/azure-dns-label-name to set a public-facing DNS label. This publishes a fully qualified domain name for your service using Azure's public DNS servers and top-level domain. The annotation value must be unique within the Azure location, so it's recommended to use a sufficiently qualified label.

Azure will then automatically append a default subnet, such as <location>.cloudapp.azure.com (where location is the region you selected), to the name you provide, to create the fully qualified DNS name. For example:

apiVersion: v1
kind: Service
metadata:
  annotations:
    service.beta.kubernetes.io/azure-dns-label-name: myserviceuniquelabel
  name: azure-load-balancer
spec:
  type: LoadBalancer
  ports:
  - port: 80
  selector:
    app: azure-load-balancer

Note

To publish the service on your own domain, see Azure DNS and the external-dns project.

Troubleshoot

If the static IP address defined in the loadBalancerIP property of the Kubernetes service manifest does not exist, or has not been created in the node resource group and no additional delegations configured, the load balancer service creation fails. To troubleshoot, review the service creation events with the kubectl describe command. Provide the name of the service as specified in the YAML manifest, as shown in the following example:

kubectl describe service azure-load-balancer

Information about the Kubernetes service resource is displayed. The Events at the end of the following example output indicate that the user supplied IP Address was not found. In these scenarios, verify that you have 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 additional control over the network traffic to your applications, you may want to instead create an ingress controller. You can also create an ingress controller with a static public IP address.