Como conectar um cluster AKS

1. Traga o AKS para o kubeconfig

O az aks get-credentials grava o cluster, o usuário e o contexto no ~/.kube/config:

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

Com --context <nome>, o contexto já sai com o nome que você quiser. Com --admin, vem a credencial de administrador das contas locais, quando o cluster ainda tem contas locais ligadas.

2. AKS com Entra ID: o kubelogin

Em cluster AKS com Entra ID (o antigo Azure AD), o kubeconfig não leva token: ele chama o kubelogin, um plugin exec, que pega o token na hora. Instale o kubelogin e converta o kubeconfig para usar o login do Azure CLI:

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

O plugin exec roda na sua máquina, com o seu login. Por isso esse kubeconfig funciona no kubectl e no Kubepier Desktop, mas não serve para colar num serviço que roda em outro lugar.

Conectar o cluster AKS no Kubepier Desktop

O desktop lê o mesmo ~/.kube/config, com o kubelogin, como o kubectl. Depois do az aks get-credentials, o cluster aparece no catálogo, no cliente cuja palavra-chave bate com o nome.

Conectar o cluster AKS no Kubepier Web: conta Azure

A web conecta do servidor do Kubepier, onde não existe o seu login nem o kubelogin. Por isso um contexto com plugin exec é recusado ao colar o kubeconfig, e o caminho é a aba Conta de nuvem, com um Service Principal. O Kubepier varre as assinaturas, cadastra cada AKS encontrado e gera o acesso a cada leitura: com Entra ID, o mesmo token que o kubelogin geraria; com contas locais, a credencial de listClusterUserCredential. Sincronizar relê a conta.

O Service Principal precisa de Reader (para listar os AKS) e de Azure Kubernetes Service Cluster User Role (para o endereço e a CA). Para ler o cluster com Entra ID, também de um papel nele: Azure Kubernetes Service RBAC Reader, com Azure RBAC, ou um ClusterRoleBinding para o objectId dele, com o RBAC do Kubernetes:

# Service Principal (a saída traz appId, password e tenant)
az ad sp create-for-rbac --name kubepier-leitura --role Reader --scopes /subscriptions/<assinatura>

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

# Cluster com Entra ID e Azure RBAC
az role assignment create --assignee <appId> \
  --role "Azure Kubernetes Service RBAC Reader" --scope /subscriptions/<assinatura>

# Cluster com Entra ID e RBAC do Kubernetes
kubectl create clusterrolebinding kubepier-leitura --clusterrole=view --user=<objectId>

No cadastro, informe Tenant ID, App ID (client) e Client secret; as assinaturas são opcionais. O app mostra esses comandos já com o appId e o objectId da credencial.

Ou um kubeconfig só leitura com ServiceAccount

Se você não quer cadastrar a conta Azure, crie no cluster uma ServiceAccount com o papel view e monte um kubeconfig com o token dela. Rode no seu terminal, com o contexto do AKS ativo, e cole o arquivo gerado em Colar kubeconfig. O papel view não lê Secrets, então a lista de Secrets e os releases do Helm ficam vazios.

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. Authorized IP ranges do AKS

Se a API do cluster aceita só alguns IPs, inclua os IPs de saída do Kubepier Web (listados acima e em Rede e IPs de saída) junto com os que já estão liberados. O comando substitui a lista inteira:

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

Cluster AKS privado (sem endpoint público) a web não alcança. Para ele, use o Kubepier Desktop pela sua VPN.

• Liberar IP no firewall do AKS
• Problemas comuns: kubelogin e cluster privado

Erros comuns ao conectar o AKS

• "usa plugin exec (kubelogin)" ao colar o kubeconfig na web: use a aba Conta de nuvem ou o kubeconfig com ServiceAccount.
• A conta Azure não acha os clusters: falta Reader ou Azure Kubernetes Service Cluster User Role na assinatura ou no resource group.
• O cluster aparece, mas as listas dão 403: com Entra ID, falta o papel no cluster (RBAC Reader ou o ClusterRoleBinding).
• Cluster inacessível: a API não aceita os IPs de saída do Kubepier, ou o cluster é privado.

• Clusters e recursos: o que é aceito
• Conectar cluster EKS