How to connect an AKS cluster

1. Bring AKS into your kubeconfig

az aks get-credentials writes the cluster, the user and the context into ~/.kube/config:

az login
az aks get-credentials --resource-group <group> --name <cluster>
kubectl get nodes

With --context <name>, the context gets the name you want. With --admin, you get the local accounts admin credential, when the cluster still has local accounts on.

2. AKS with Entra ID: kubelogin

On an AKS cluster with Entra ID (formerly Azure AD), the kubeconfig holds no token: it calls kubelogin, an exec plugin, which fetches the token on demand. Install kubelogin and convert the kubeconfig to use the Azure CLI sign-in:

az aks install-cli
kubelogin convert-kubeconfig -l azurecli
kubectl get nodes

The exec plugin runs on your machine, with your sign-in. That is why this kubeconfig works in kubectl and Kubepier Desktop, but cannot be pasted into a service that runs somewhere else.

Connect the AKS cluster to Kubepier Desktop

The desktop app reads the same ~/.kube/config, with kubelogin, just like kubectl. After az aks get-credentials, the cluster shows up in the catalog, under the client whose keyword matches its name.

Connect the AKS cluster to Kubepier Web: Azure account

The web connects from Kubepier’s server, where neither your sign-in nor kubelogin exist. That is why a context with an exec plugin is refused when you paste the kubeconfig, and the way in is the Cloud account tab, with a Service Principal. Kubepier scans the subscriptions, adds every AKS it finds and builds the access on each read: with Entra ID, the same token kubelogin would get; with local accounts, the listClusterUserCredential credential. Sync reads the account again.

The Service Principal needs Reader (to list the AKS clusters) and Azure Kubernetes Service Cluster User Role (for the address and the CA). To read a cluster with Entra ID, it also needs a role in it: Azure Kubernetes Service RBAC Reader, with Azure RBAC, or a ClusterRoleBinding for its objectId, with Kubernetes RBAC:

# Service Principal (the output has appId, password and tenant)
az ad sp create-for-rbac --name kubepier-leitura --role Reader --scopes /subscriptions/<subscription>

az role assignment create --assignee <appId> \
  --role "Azure Kubernetes Service Cluster User Role" --scope /subscriptions/<subscription>

# Cluster with Entra ID and Azure RBAC
az role assignment create --assignee <appId> \
  --role "Azure Kubernetes Service RBAC Reader" --scope /subscriptions/<subscription>

# Cluster with Entra ID and Kubernetes RBAC
kubectl create clusterrolebinding kubepier-leitura --clusterrole=view --user=<objectId>

In the form, fill in Tenant ID, App ID (client) and Client secret; subscriptions are optional. The app shows these commands already filled with the credential’s appId and objectId.

Or a read-only kubeconfig with a ServiceAccount

If you do not want to add the Azure account, create a ServiceAccount with the view role in the cluster and build a kubeconfig with its token. Run it in your terminal, with the AKS context active, and paste the generated file under Paste kubeconfig. The view role does not read Secrets, so the Secrets list and the Helm releases stay empty.

kubectl create namespace kubepier
kubectl -n kubepier create serviceaccount kubepier-leitura
kubectl create clusterrolebinding kubepier-leitura \
  --clusterrole=view --serviceaccount=kubepier:kubepier-leitura
kubectl -n kubepier apply -f - <<'EOF'
apiVersion: v1
kind: Secret
metadata:
  name: kubepier-leitura-token
  annotations:
    kubernetes.io/service-account.name: kubepier-leitura
type: kubernetes.io/service-account-token
EOF

TOKEN=$(kubectl -n kubepier get secret kubepier-leitura-token -o jsonpath='{.data.token}' | base64 -d)
SERVER=$(kubectl config view --minify -o jsonpath='{.clusters[0].cluster.server}')
CA=$(kubectl config view --minify --raw -o jsonpath='{.clusters[0].cluster.certificate-authority-data}')
NOME=$(kubectl config current-context)

cat > kubepier.kubeconfig <<EOF
apiVersion: v1
kind: Config
clusters:
- name: $NOME
  cluster: { server: $SERVER, certificate-authority-data: $CA }
users:
- name: kubepier-leitura
  user: { token: $TOKEN }
contexts:
- name: $NOME
  context: { cluster: $NOME, user: kubepier-leitura }
current-context: $NOME
EOF

3. AKS authorized IP ranges

If the cluster API only accepts some IPs, add Kubepier Web’s egress IPs (listed above and in Network and egress IPs) next to the ones already allowed. The command replaces the whole list:

az aks show -g <group> -n <cluster> --query apiServerAccessProfile.authorizedIpRanges
az aks update -g <group> -n <cluster> \
  --api-server-authorized-ip-ranges <ip-1>/32,<ip-2>/32,<already-allowed-ips>

The web cannot reach a private AKS cluster (no public endpoint). For it, use Kubepier Desktop through your VPN.

• Allow IPs in the AKS firewall
• Troubleshooting: kubelogin and private clusters

Common errors when connecting AKS

• "uses an exec plugin (kubelogin)" when pasting the kubeconfig on the web: use the Cloud account tab or the ServiceAccount kubeconfig.
• The Azure account finds no clusters: Reader or Azure Kubernetes Service Cluster User Role is missing on the subscription or resource group.
• The cluster shows up, but the lists return 403: with Entra ID, the role in the cluster is missing (RBAC Reader or the ClusterRoleBinding).
• Cluster unreachable: the API does not accept Kubepier’s egress IPs, or the cluster is private.

• Clusters and resources: what is accepted
• Connect an EKS cluster