Summary: This wiki page explains how to use VS Code and Lens to connect to a private AKS cluster.
Date: 15 September 2025
Update: 8 February 2026: Added next steps for RDP to VMs.
Update: 2 June 2026: Refactored Lens and VS Code access. Added troubleshooting steps.

There are many ways to connect to a private AKS cluster. This page assumes you have a jumpbox VM in the same virtual network as the AKS cluster, and that you can connect to the jumpbox using Azure Bastion. Using ssh with port forwards is the easiesy way to connect to a private AKS cluster and allows for additional benefits.

See here the design of the network setup to connect to a private AKS cluster using a jumpbox through Azure Bastion. For simplicity, setup and requirements that are not relevant for this page, like private DNS, are left out:

Network overview of an private AKS cluster

Note: The Bastion must be Standard or Premium SKU and have native client support enabled under configuration settings

Make sure to have Azure CLI installed. The required module bastion will be automatically installed, but if needed it can be upgraded using az extension update --name bastion

• Optional: If applicable, activate the required Privileged Identity Management (PIM) groups to assign permissions for your account. You need at least 'Reader' permissions on the resource group where the bastion is located, and, depending on what you'll need to do, 'Reader' or 'Contributor' permissions on the resource group where the jumpbox and AKS cluster are located.
• Use the following Azure CLI commands to connect to Azure and set the subscription to the one with the bastion:

  # We need to use the azure cli as creating the tunnel to the jumpbox will only work with the azure cli
  az logout
  # Disable the subscription selector feature as well as sign in with WAM
  az config set core.login_experience_v2=off
  az config set core.enable_broker_on_windows=false
  az login --tenant 7e4an71d-a123-a123-a123-abcd12345678
  # Set the subscription to the bastion subscription
  az account set --subscription aa123456-a123-a123-a123-abcd12345678

• Now we can use the following command to setup the bastion connection and our required port forward(s) in one go:

  az network bastion ssh --name bas-001 --resource-group "rg-bastion" --target-resource-id /subscriptions/aa123456-a123-a123-a123-abcd12345678/resourceGroups/rg-cluster/providers/Microsoft.Compute/virtualMachines/vm-jumpbox --auth-type AAD -- -L 6443:aks-privatecluster-m8k6low2.privatelink.westeurope.azmk8s.io:443

Note: Although preferred, you don't have to use the AAD authentication type. For example, using a ssh-key will work just as well: --auth-type ssh-key --username azadmin --ssh-key C:/Users/<username>/.ssh/aks_cluster.pem

The az network bastion ssh command opens a shell on the jumpbox upon completion. Use the following commands to install required tooling and setup your authentication towards AKS. Note that this is usually only required once:

# Install the Azure CLI: https://learn.microsoft.com/en-us/cli/azure/install-azure-cli?view=azure-cli-latest
# Download and install the Microsoft signing key
sudo mkdir -p /etc/apt/keyrings
curl -sLS https://packages.microsoft.com/keys/microsoft.asc |
    gpg --dearmor |
    sudo tee /etc/apt/keyrings/microsoft.gpg > /dev/null
sudo chmod go+r /etc/apt/keyrings/microsoft.gpg
 
# Add the Azure CLI software repository
AZ_REPO=$(lsb_release -cs)
echo "deb [arch=`dpkg --print-architecture` signed-by=/etc/apt/keyrings/microsoft.gpg] https://packages.microsoft.com/repos/azure-cli/ $AZ_REPO main" |
    sudo tee /etc/apt/sources.list.d/azure-cli.list
 
# Update repository information and install the azure-cli package
sudo apt-get update
sudo apt-get install azure-cli
 
# Install kubectl and kubelogin: https://learn.microsoft.com/en-us/cli/azure/aks?view=azure-cli-latest#az-aks-install-cli
sudo az aks install-cli
 
# Remove any old kubeconfig you might have
rm .kube/config
# Make sure to start from a clean slate
az logout
# Login to your tenant
az login --tenant 7e4an71d-a123-a123-a123-abcd12345678
# Set your subscription to the one with the AKS cluster
az account set --subscription aa123456-a123-a123-a123-abcd12345678
# Get AKS credentials
az aks get-credentials --resource-group rg-cluster --name aks-privatecluster --overwrite-existing
# Use kubelogin plugin for authentication
kubelogin convert-kubeconfig -l azurecli

You can verify your account, group membership and access with:

# Verify your aks connection
kubectl cluster-info
# Verify your accounts and groups
kubectl auth whoami
# Verify your permissions
kubectl auth can-i "*" "*"
kubectl auth can-i "*" "pods"

Note that a convenient way to setup AKS Permissions is to use my helm chart

If something fails, but the connection was successful, use the following command to clean up and try again:

# Remove any old kubeconfig you might have
rm .kube/config
# Make sure to start from a clean slate
az logout
# Remove Kubelogin tokens
kubelogin remove-tokens

Also, make sure the azure cli is installed on the jumpbox: az aks install-cli

After setting up access through the commandline you can also use the kubeconfig you created to use with local tools:

• From the jumpbox, copy your .kube/config to your local machine and add it to your local .kube folder with the correct name, for example C:\Users\<username>\.kube\aks-privatecluster

Update the cluster settings inside the file like this:

clusters:
- cluster:
    certificate-authority-data: LS0XXX
    server: https://localhost:6443
  insecure-skip-tls-verify: true
  name: aks-privatecluster

Now that you have a local kubeconfig with the correct config, you can point your tools towards the local kubeconfig to use it.

As a reference, your local kuebconfig should look like this:

apiVersion: v1
clusters:
- cluster:
    certificate-authority-data: LS0XXX
    server: https://localhost:6443
  insecure-skip-tls-verify: true
  name: aks-privatecluster
contexts:
- context:
    cluster: aks-privatecluster
    namespace: shiftops
    user: clusterUser_rg-cluster_aks-privatecluster
  name: aks-privatecluster
current-context: aks-privatecluster
kind: Config
preferences: {}
users:
- name: clusterUser_rg-cluster_aks-privatecluster
  user:
    exec:
      apiVersion: client.authentication.k8s.io/v1beta1
      args:
      - get-token
      - --login
      - azurecli
      - --server-id
      - 6af89f29-940b-4706-b89f-b1ac3193ccdc
      command: kubelogin
      env: null
      installHint: |2
        kubelogin is not installed which is required to connect to AAD enabled cluster.
        To learn more, please go to https://aka.ms/aks/kubelogin

Note that the --server-id points to the Entra ID application that handles your kubernetes Entra ID authentication.

• Install the kubernetes extension in VS Code
• Open the extension in VS Code from the side panel
• Click on the three dots next to the clusters. Click on 'Set Kubeconfig' → Add new Kubeconfig and navigate to the kubeconfig you've just added.

• Lens is a popular Kubernetes IDE that makes it easy to manage and monitor Kubernetes clusters. You can download it from here and install it.
• From within Lens, right-click on Local Kubeconfigs and click on Add Kubeconfigs → From filesystem and navigate to the kubeconfig you've just added.

As an alternative to use VS Code to connect to a private AKS cluster, make sure you have the 'Remote Explorer' and 'Kubernetes' extensions installed. Then, follow these steps:

• Use the following Azure CLI command to create a ssh tunnel to the jumpbox through the bastion:

  az network bastion tunnel --name bas-001 --resource-group rg-bastion --target-resource-id /subscriptions/aa123456-a123-a123-a123-abcd12345678/resourceGroups/rg-cluster/providers/Microsoft.Compute/virtualMachines/vm-jumpbox --resource-port 22 --port 50022

• To use the 'Remote Explorer' extension, you need to add an entry to your ssh config file (usually located at C:\Users\<your-username>\.ssh\config):

  # Read more about SSH config files: https://linux.die.net/man/5/ssh_config
  Host vm-jumpbox
      HostName 127.0.0.1
      User azadmin
      Port 50022
      IdentityFile C:/Users/sjoer/.ssh/private_cluster.pem

  • Note that the IdentityFile must point to the private key that matches the public key configured on the jumpbox VM.
• In VS Code, open the Remote Explorer extension from the activity bar → SSH Targets → Open 127.0.0.1 (linux) in a new window
  • This will open a new VS Code window connected to the jumpbox VM. You can now open a terminal in this window and run commands on the jumpbox VM.
  • Setup the jumpbox as explained above
• You can now use the 'Kubernetes' extension to view and manage the AKS cluster. Open the 'Kubernetes' extension from the activity bar → Click on the refresh button in the 'Clusters' section to load the clusters from your kubeconfig file. You should see your AKS cluster listed there. You can now expand the cluster to view its resources and perform various actions like viewing logs, executing commands in pods and more.

Note that some of the above steps can be automated using VS Code Tasks.

In case Entra ID is not available, but changes need to be done you could enable local accounts to access the cluster as an admin:

• In the Azure portal, go to the AKS cluster → Settings → Security configuration
• Under Authentication and Authorization is the option to enable 'Kubernetes local accounts'. Note that “Local accounts provide a legacy non auditable means of accessing an AKS cluster and are not recommended for use.”. Check the option and save.

Check the documentation on how to do this with Azure CLI.

• Once you've enabled the local accounts, you can use the following commands to switch to the admin user:

# Remove the current kubeconfig
rm .kube/config
# Make sure to start from a clean slate
az logout
# Login to your tenant
az login --tenant 7e4an71d-a123-a123-a123-abcd12345678
# Set your subscription to the one with the AKS cluster
az account set --subscription aa123456-a123-a123-a123-abcd12345678
# Get AKS credentials
az aks get-credentials --admin --resource-group rg-cluster --name aks-privatecluster --overwrite-existing
# Use kubelogin plugin for authentication
kubelogin convert-kubeconfig -l azurecli

Note the --admin option in the az aks get-credentials command

As a reference, your new admin enabled kubeconfig should look like this:

apiVersion: v1
clusters:
- cluster:
    certificate-authority-data: LS1QLSJBXXX
    server: aks-privatecluster-m8k6low2.privatelink.westeurope.azmk8s.io:443
  name: aks-privatecluster
contexts:
- context:
    cluster: aks-privatecluster
    namespace: shiftops
    user: clusterAdmin_rg-privatecluster_aks-privatecluster
  name: aks-privatecluster-admin
current-context: aks-privatecluster-admin
kind: Config
preferences: {}
users:
- name: clusterAdmin_rg-privatecluster_aks-privatecluster
  user:
    client-certificate-data: LS1QLSJBNMXXXLS0tCg==
    client-key-data: LS1QLSJBNMXXX
    token: xxx

In case you need to troubeshoot an AKS node, you can follow the MS documentation: Connect to Azure Kubernetes Service (AKS) cluster nodes for maintenance or troubleshooting

You can also use certificates to access the jumpbox. That way, only the first time you access the jumpbox you have to provide a username and password:

• Create a keypair and add it to the local SSH agent (note that you need an administrative powershell):

  # Create a ed25519 key pair
  ssh-keygen
  # Configure the ssh-agent service
  Get-Service ssh-agent | Set-Service -StartupType Automatic
  # Start the ssh-agent
  Start-Service ssh-agent
  # Add the private key you created to the SSH agent
  ssh-add .\.ssh\id_ed25519
  # List the added keys
  ssh-add -L
  # Delete all added keys
  ssh-add -D

• Add the public key to the jumpbox:

  mkdir .ssh
  cd .ssh
  vi authorized_keys
  # Make sure to copy the public key from your local machine
  # press i
  # press ctrl+v
  # press escape
  # press :wq

Now you can exit the jumpbox. The next time login will be automatic.

As a next step, you can extend the ssh tunnel to also RDP to VMs in Azure.

This wiki has been made possible by: