# Using VS Code and Lens to connect to a private AKS cluster

**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.\\

{{tag>kubernetes vscode azure}}

There are many ways to [[https://learn.microsoft.com/en-us/azure/architecture/guide/security/access-azure-kubernetes-service-cluster-api-server#access-an-aks-private-cluster |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.

## Design

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:

[{{k8s-lens.drawio.png?800|Network overview of an private AKS cluster}}] \\

> Note: [[https://learn.microsoft.com/en-us/azure/bastion/bastion-connect-to-aks-private-cluster |The Bastion must be Standard or Premium SKU and have native client support enabled under configuration settings]]

## Connect to Bastion and Setup Tunnels

> 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: <code bash>
# 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
</code>
  * Now we can use the following command to setup the bastion connection and our required port forward(s) in one go: <code bash>
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
</code>

> 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`

### AKS - Commandline

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:

<code bash>
# 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
</code>

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

<code bash>
# 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"
</code>

> Note that a convenient way to setup AKS Permissions is to use my [[helmchartakspermissions |helm chart]]

#### Troubleshooting

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

<code bash>
# 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
</code>

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

### AKS - Tooling

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:

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

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:

<code yaml>
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
</code>

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

#### VS Code Kubernetes Extension

  * 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

  * [[https://k8slens.dev/ |Lens]] is a popular Kubernetes IDE that makes it easy to manage and monitor Kubernetes clusters. You can download it from [[https://k8slens.dev/download |here]] and [[https://docs.k8slens.dev/getting-started/install-lens/ |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.

## Alternative For VS Code

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: <code bash>
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
</code>
  * 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`): <code>
# 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
</code>
    * 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.

## Automate

> Note that some of the above steps can be automated using [[vscodetasks#examplestart_a_connection_to_a_azure_jumpbox_through_a_bastion |VS Code Tasks]].

## Troubleshooting - Using local accounts for AKS

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 [[https://learn.microsoft.com/en-us/azure/aks/entra-id-control-plane-authentication#break-glass-access |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:

<code bash>
# 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
</code>

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

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

<code yaml>
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
</code>

## Troubleshooting - Access AKS Nodes

In case you need to troubeshoot an AKS node, you can follow the MS documentation: [[https://learn.microsoft.com/en-us/azure/aks/node-access |Connect to Azure Kubernetes Service (AKS) cluster nodes for maintenance or troubleshooting]]

## More Automation - Use certificates to access the jumpbox

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): <code 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
</code>
  * Add the public key to the jumpbox: <code bash>
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
</code>

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

## Next steps

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

//This wiki has been made possible by://

<HTML>
<script async src="https://pagead2.googlesyndication.com/pagead/js/adsbygoogle.js?client=ca-pub-8613096447910897"
     crossorigin="anonymous"></script>
<!-- Wiki End of Page -->
<ins class="adsbygoogle"
     style="display:block"
     data-ad-client="ca-pub-8613096447910897"
     data-ad-slot="6221699236"
     data-ad-format="auto"
     data-full-width-responsive="true"></ins>
<script>
     (adsbygoogle = window.adsbygoogle || []).push({});
</script>
</HTML>