Access an Azure Kubernetes Service (AKS) API server

This guide outlines options for connecting to the API server of your Azure Kubernetes Service (AKS) cluster. In a standard AKS cluster, the API server is exposed over the internet. In a private AKS cluster, you can only connect from a device with network access to the private cluster.

Planning API server access is a day-zero activity, and your access method depends on your deployment scenario.

AKS API server access

To manage an AKS cluster, you interact with its API server. It's essential to restrict API server access to only necessary users. Granular access can be provided by integrating the AKS cluster with Microsoft Entra ID. Administrators can use role-based access control (RBAC) to manage access, placing users and identities in Entra groups and assigning appropriate roles and permissions. Microsoft Entra authentication is enabled in AKS clusters via OpenID Connect. For more information, see these resources:

• AKS-managed Microsoft Entra integration
• Integrate Microsoft Entra ID for the cluster

Azure DDoS Protection, combined with application design best practices, offers enhanced mitigation features against DDoS attacks. You should enable Azure DDOS Protection on any perimeter virtual network.

Access AKS cluster over the internet

When you create a nonprivate cluster that resolves to the API server's fully qualified domain name (FQDN), it's assigned a public IP address by default. You can connect to your cluster using the Azure portal or a shell such as Azure CLI, PowerShell, or command prompt.

Azure Cloud Shell

Cloud Shell is a shell built into the Azure portal. You can manage and connect to Azure resources from Cloud Shell as you would from PowerShell or Azure CLI. For more information, see Overview of Azure Cloud Shell.

Access AKS private cluster

There are several ways to connect to an AKS private cluster. Planning access is a day-zero activity based on your scenario's needs and limitations. You can connect to your private cluster using the following components and services:

• Jump box deployed into a subnet as your operations workstation. This can be stand-alone, persistent virtual machines (VMs) in an availability set. You can also use Azure Virtual Machine Scale Sets.
• Azure Bastion.
• Virtual private network (VPN).
• Azure ExpressRoute.
• Azure CLI aks command invoke.
• Cloud Shell instance that's deployed into a subnet that's connected to the API server for the cluster.
• Azure Virtual Desktop. If your team connects remotely from various operating systems, you can use this service to provide access to Windows VMs that you use as jump boxes.
• Azure Container Instances and an OpenSSH-compatible Secure Shell (SSH) client.

Azure Bastion

Azure Bastion is a PaaS offering that enables secure RDP or SSH connections to a VM within your virtual network, without requiring a public IP address on the VM. When connecting to a private AKS cluster, you can use Azure Bastion to access a jump box in the hub virtual network, while the AKS cluster resides in a spoke network. A virtual network peering is used to connect the hub and spoke network. The jump box can resolve the AKS API server's FQDN using Azure Private Endpoint, a private DNS zone, and a DNS A record. This setup ensures that the API server's FQDN is only resolvable within the virtual network, providing a trusted connection to the private AKS cluster.

Download a Visio file of this architecture.

Dataflow

1. A user attempts to connect to a jump box by using Azure Bastion and an HTML5 browser with TLS encryption.
2. The user chooses from the portal whether to use RDP or SSH to connect to the jump box.
3. The user signs in to the jump box through Azure Bastion. The attempt to connect to the AKS private cluster is made from this jump box. The hub virtual network has a virtual network link to the AKS private DNS zone to resolve the FQDN of the private cluster.
4. The hub virtual network and the spoke virtual network communicate with each other by using a virtual network peering.
5. To reach the private AKS cluster, the traffic enters the Azure backbone. A private endpoint establishes a private, isolated connection to the private AKS cluster.
6. The traffic reaches the API server of the private AKS cluster. The user can then manage pods, nodes, and applications.

Troubleshoot connection problems

If you can't connect to your private cluster:

• Check the virtual network peering. This mechanism provides network-to-network connectivity between two virtual networks. For traffic to flow between those two networks, you need to establish the virtual network peering between them. When you establish a virtual network peering, a route is placed in the system route table of the virtual network. That route provides a path for reaching the destination address space. For more information about troubleshooting virtual network peerings, see Create, change, or delete a virtual network peering.

  Note

  You don't need a virtual network peering if your jump box is in the same virtual network as the private endpoint and your AKS private cluster.

• Check the virtual network link to the private DNS zone. Virtual network links provide a way for VMs that are inside virtual networks to connect to a private DNS zone and resolve the DNS records inside the zone. If you can't connect to your private AKS cluster or can't resolve the FQDN of the private cluster, check whether your virtual network has a virtual network link to your private DNS zone. The name of the private DNS zone should have the following format:

  privatelink.<region>.azmk8s.io

  For more information about troubleshooting virtual network links, see these resources:

  • Virtual network peering
  • What is a virtual network link?

  Note

  When you create a private AKS cluster, a private DNS zone is created that has a virtual network link to the virtual network that hosts the private AKS cluster.

Improve security

To further secure AKS workloads and your jump boxes, you can use just-in-time (JIT) access and a privileged access workstation (PAW).

To secure AKS workloads and your jump boxes, use just-in-time (JIT) access and a privileged access workstation (PAW). JIT access, part of Microsoft Defender for Cloud, reduces the threat landscape by blocking inbound traffic to your jump box and allowing access only for a specified time when needed. After the time expires, the access is automatically revoked. For more information about JIT access, see Understanding just-in-time (JIT) VM access.

PAWs are hardened devices that provide high security for operators by blocking common attack vectors like email and web browsing. It's difficult to compromise PAWs, because they block many common attack vectors such as email and web browsing. For more information about PAWs, see Securing devices as part of the privileged access story.

Virtual Private Network (VPN)

A VPN connection provides hybrid connectivity from your on-premises environment to Azure enabling access to a private AKS cluster. The API server of the private cluster isn't reachable outside your virtual networks. With a VPN, you can connect to your virtual network in Azure over an encrypted tunnel, then access your jump box and, from there, connect to the private cluster's API server.

Download a Visio file of this architecture.

Dataflow

1. A user initiates RDP or SSH traffic to the jump box from an on-premises workstation.
2. Jump box traffic leaves the customer edge routers and VPN appliance. The traffic uses an encrypted IPsec tunnel to traverse the internet.
3. Jump box traffic reaches the virtual network gateway in Azure, which is the ingress and egress point of the Azure virtual network infrastructure.
4. After traffic moves past the virtual network gateway, it reaches the jump box. The attempt to connect to the AKS private cluster is made from the jump box. The hub virtual network has a virtual network link to the AKS private DNS zone to resolve the FQDN of the private cluster.
5. The hub virtual network and the spoke virtual network communicate with each other by using a virtual network peering.
6. To reach the private AKS cluster, the traffic enters the Azure backbone. A private endpoint establishes a private, isolated connection to the private AKS cluster.
7. The traffic reaches the API server of the private AKS cluster. The user can then manage pods, nodes, and applications.

ExpressRoute

ExpressRoute provides connectivity to your AKS private cluster from an on-premises environment. ExpressRoute uses Border Gateway Protocol (BGP) to exchange routes between your on-premises network and Azure creating a path between IaaS resources and on-premises workstations. ExpressRoute offers a dedicated, isolated connection with consistent bandwidth and latency, making it ideal for enterprise environments.

Download a Visio file of this architecture.

Dataflow

1. A user initiates RDP or SSH traffic to the jump box from an on-premises workstation.
2. Jump box traffic leaves the customer edge routers and travels on a fiber connection to the meet-me location, where the ExpressRoute circuit resides. The traffic reaches the Microsoft Enterprise Edge (MSEE) devices there. Then it enters the Azure fabric.
3. Jump box traffic reaches the ExpressRoute gateway, which is the ingress and egress point of the Azure virtual network infrastructure.
4. The traffic reaches the jump box. The attempt to connect to the AKS private cluster is made from the jump box. The hub virtual network has a virtual network link to the AKS private DNS zone to resolve the FQDN of the private cluster.
5. The hub virtual network and the spoke virtual network communicate with each other by using a virtual network peering.
6. To reach the private AKS cluster, the traffic enters the Azure backbone. A private endpoint establishes a private, isolated connection to the private AKS cluster.
7. The traffic reaches the API server of the private AKS cluster. The user can then manage pods, nodes, and applications.

Run aks command invoke

With an AKS private cluster, you can connect from a VM that has access to the API server. Using the Azure CLI aks command invoke, you can run commands like kubectl or helm remotely via the Azure API. This creates a transient pod in the cluster, which lasts only during the command. The aks command invoke serves as an alternative connection method if you lack a VPN, ExpressRoute, or peered virtual network. Ensure your cluster and node pool have sufficient resources to create the transient pod.

For more information, see Use command invoke to access a private Azure Kubernetes Service (AKS) cluster.

Connect Cloud Shell to a subnet

When you deploy Cloud Shell into a virtual network you control, you can interact with resources inside that network. Deploying Cloud Shell into a subnet you manage enables connectivity to the API server of an AKS private cluster. This allows you to connect to the private cluster. For more information, see Deploy Cloud Shell into an Azure virtual network.

Use SSH and Visual Studio Code for testing

SSH securely manages and accesses files on a remote host using public-private key pairs. From your local machine, you can use SSH with the Visual Studio Code Remote - SSH extension to connect to a jump box in your virtual network. The encrypted SSH tunnel terminates at the public IP of the jump box, making it easy to modify Kubernetes manifest files.

To learn how to connect to your jump box via SSH, see Remote development over SSH.

If you can't connect to your VM over SSH to manage your private cluster:

• Check the inbound network security group rule for the VM subnet. The default network security group rule blocks all inbound traffic from outside Azure, so create a new rule allowing SSH traffic from your local machine's public IP.
• Check the certificate location. Check for correct placement of the certificates. The private key should be in the C:\Users\User\.ssh\id_rsa directory on your local machine. The public key should be placed in the ~/.ssh/id_rsa.pub file on the VM in Azure.

Conclusion

• You can access your AKS cluster's API server over the internet if the public FQDN is enabled.
• Cloud Shell is a built-in command-line shell in the Azure portal that you can use to connect to an AKS cluster.
• For more secure access, use Azure Bastion and a private endpoint.
• VPNs and ExpressRoute provide hybrid connectivity to your private AKS cluster.
• If no external connectivity solution is available, you can use aks command invoke remotely.
• Cloud Shell can also be deployed directly into a virtual network you manage to access the private cluster.
• Using Visual Studio Code with SSH on a jump box encrypts the connection and simplifies modifying manifest files, though it exposes a public IP address in your environment.

Contributors

This article is maintained by Microsoft. It was originally written by the following contributors.

Principal authors:

• Ayobami Ayodeji | Program Manager 2
• Ariel Ramirez | Senior Consultant
• Bahram Rushenas | Incubation Architect

Other contributors:

• Shubham Agnihotri | Consultant

To see nonpublic LinkedIn profiles, sign in to LinkedIn.

Next steps

• What is Azure Bastion?
• Get started with OpenSSH
• What is a private endpoint?
• What is Azure ExpressRoute?
• What is VPN Gateway?

Related resources

• Baseline architecture for an Azure Kubernetes Service (AKS) cluster
• Advanced Azure Kubernetes Service (AKS) microservices architecture
• Azure Kubernetes Service (AKS) architecture design