Habilitar a autenticação de identidade gerenciada do Azure para clusters Kubernetes com kubelogin
A integração do Microsoft Entra gerenciada pelo AKS simplifica o processo de integração do Microsoft Entra. Anteriormente, era necessário criar um aplicativo cliente e servidor, e o locatário do Microsoft Entra precisava atribuir permissões de função de Leitores de Diretório . Agora, o provedor de recursos AKS gerencia os aplicativos cliente e servidor para você.
Os administradores de cluster podem configurar o controle de acesso baseado em função do Kubernetes (Kubernetes RBAC) com base na identidade do usuário ou na associação ao grupo de diretórios. A autenticação do Microsoft Entra é fornecida para clusters AKS com OpenID Connect. OpenID Connect é uma camada de identidade construída sobre o protocolo OAuth 2.0. Para obter mais informações sobre o OpenID Connect, consulte a documentação do OpenID Connect.
Saiba mais sobre o fluxo de integração do Microsoft Entra na documentação do Microsoft Entra.
Este artigo fornece detalhes sobre como habilitar e usar identidades gerenciadas para recursos do Azure com seu cluster AKS.
Limitações
A seguir estão as restrições que integram a autenticação de identidade gerenciada do Azure no AKS.
- A integração não pode ser desativada depois de adicionada.
- Não há suporte para downgrades de um cluster integrado para os clusters de ID herdados do Microsoft Entra.
- Clusters sem suporte a RBAC do Kubernetes não conseguem adicionar a integração.
Antes de começar
Os seguintes requisitos precisam ser atendidos para instalar corretamente o addon AKS para identidade gerenciada.
- Você tem a CLI do Azure versão 2.29.0 ou posterior instalada e configurada. Executar
az --version
para localizar a versão. Se precisar de instalar ou atualizar, veja Install Azure CLI (Instalar o Azure CLI). - Você precisa
kubectl
com uma versão mínima de 1.18.1 oukubelogin
. Com a CLI do Azure e o módulo do Azure PowerShell, esses dois comandos são incluídos e gerenciados automaticamente. Ou seja, eles são atualizados por padrão e a execuçãoaz aks install-cli
não é necessária ou recomendada. Se você estiver usando um pipeline automatizado, precisará gerenciar atualizações para a versão correta ou mais recente. A diferença entre as versões secundárias do Kubernetes ekubectl
não deve ser mais de uma versão. Caso contrário, ocorrerão problemas de autenticação na versão errada. - Se você estiver usando helm, você precisa de uma versão mínima do helm 3.3.
- Essa configuração requer que você tenha um grupo do Microsoft Entra para seu cluster. Esse grupo é registrado como um grupo de administradores no cluster para conceder permissões de administrador. Se você não tiver um grupo existente do Microsoft Entra, poderá criar um usando o
az ad group create
comando.
Nota
Os clusters integrados do Microsoft Entra usando uma versão do Kubernetes mais recente que a versão 1.24 usam automaticamente o kubelogin
formato. A partir da versão 1.24 do Kubernetes, o formato padrão da credencial clusterUser para clusters de ID do Microsoft Entra é exec
, que requer kubelogin
binário no PATH de execução. Não há nenhuma alteração de comportamento para clusters que não sejam do Microsoft Entra ou clusters do Microsoft Entra ID que executam uma versão anterior à 1.24.
Os downloads kubeconfig
existentes continuam a funcionar. Um formato de parâmetro de consulta opcional é incluído ao obter a credencial clusterUser para substituir a alteração de comportamento padrão. Você pode especificar explicitamente o formato para azure se precisar manter o formato antigo kubeconfig
.
Habilite a integração em seu cluster AKS
Criar um novo cluster
Crie um grupo de recursos do Azure usando o
az group create
comando.az group create --name myResourceGroup --location centralus
Crie um cluster AKS e habilite o acesso de administração para seu grupo do Microsoft Entra usando o
az aks create
comando.az aks create \ --resource-group myResourceGroup \ --name myManagedCluster \ --enable-aad \ --aad-admin-group-object-ids <id> [--aad-tenant-id <id>] \ --generate-ssh-keys
Uma criação bem-sucedida de um cluster de ID do Microsoft Entra gerenciado pelo AKS tem a seguinte seção no corpo da resposta:
"AADProfile": { "adminGroupObjectIds": [ "5d24****-****-****-****-****afa27aed" ], "clientAppId": null, "managed": true, "serverAppId": null, "serverAppSecret": null, "tenantId": "72f9****-****-****-****-****d011db47" }
Usar um cluster existente
Habilite a integração do Microsoft Entra gerenciada pelo AKS em seu cluster existente habilitado para Kubernetes RBAC usando o az aks update
comando. Certifique-se de definir seu grupo de administradores para manter o acesso no cluster.
az aks update --resource-group MyResourceGroup --name myManagedCluster --enable-aad --aad-admin-group-object-ids <id-1>,<id-2> [--aad-tenant-id <id>]
Uma ativação bem-sucedida de um cluster de ID do Microsoft Entra gerenciado pelo AKS tem a seguinte seção no corpo da resposta:
"AADProfile": {
"adminGroupObjectIds": [
"5d24****-****-****-****-****afa27aed"
],
"clientAppId": null,
"managed": true,
"serverAppId": null,
"serverAppSecret": null,
"tenantId": "72f9****-****-****-****-****d011db47"
}
Migrar cluster herdado para integração
Se o cluster usa a integração herdada do Microsoft Entra, você pode atualizar para a integração do Microsoft Entra gerenciada pelo AKS por meio do az aks update
comando.
Aviso
Os clusters de camada livre podem enfrentar tempo de inatividade do servidor de API durante a atualização. Recomendamos atualizar fora do horário comercial.
Após a atualização, o conteúdo kubeconfig muda. Você precisa executar az aks get-credentials --resource-group <AKS resource group name> --name <AKS cluster name>
para mesclar as novas credenciais no arquivo kubeconfig.
az aks update --resource-group myResourceGroup --name myManagedCluster --enable-aad --aad-admin-group-object-ids <id> [--aad-tenant-id <id>]
Uma migração bem-sucedida de um cluster de ID do Microsoft Entra gerenciado pelo AKS tem a seguinte seção no corpo da resposta:
"AADProfile": {
"adminGroupObjectIds": [
"5d24****-****-****-****-****afa27aed"
],
"clientAppId": null,
"managed": true,
"serverAppId": null,
"serverAppSecret": null,
"tenantId": "72f9****-****-****-****-****d011db47"
}
Acessar o cluster habilitado
Obtenha as credenciais de usuário para acessar seu cluster usando o
az aks get-credentials
comando.az aks get-credentials --resource-group myResourceGroup --name myManagedCluster
Siga as suas instruções para iniciar sessão.
Defina
kubelogin
para usar a CLI do Azure.kubelogin convert-kubeconfig -l azurecli
Exiba os nós no cluster com o
kubectl get nodes
comando.kubectl get nodes
Login não interativo com kubelogin
Existem alguns cenários não interativos que não suportam kubectl
o . Nesses casos, use kubelogin
para se conectar ao cluster com uma credencial de entidade de serviço não interativa para executar pipelines de integração contínua.
Nota
Os clusters integrados do Microsoft Entra usando uma versão do Kubernetes mais recente que a versão 1.24 usam automaticamente o kubelogin
formato. A partir da versão 1.24 do Kubernetes, o formato padrão da credencial clusterUser para clusters de ID do Microsoft Entra é exec
, que requer kubelogin
binário no PATH de execução. Não há nenhuma alteração de comportamento para clusters que não sejam do Microsoft Entra ou clusters do Microsoft Entra ID que executam uma versão anterior à 1.24.
Os downloads kubeconfig
existentes continuam a funcionar. Um formato de parâmetro de consulta opcional é incluído ao obter a credencial clusterUser para substituir a alteração de comportamento padrão. Você pode especificar explicitamente o formato para azure se precisar manter o formato antigo kubeconfig
.
Ao obter a credencial clusterUser, você pode usar o
format
parâmetro query para substituir o comportamento padrão. Você pode definir o valor paraazure
usar o formato kubeconfig original:az aks get-credentials --format azure
Se o cluster integrado do Microsoft Entra usa o Kubernetes versão 1.24 ou inferior, você precisa converter manualmente o formato kubeconfig.
export KUBECONFIG=/path/to/kubeconfig kubelogin convert-kubeconfig
Nota
Se você receber a mensagem de erro: O plug-in de autenticação do Azure foi removido., você precisará executar o comando kubelogin convert-kubeconfig
para converter o formato kubeconfig manualmente.
Para obter mais informações, você pode consultar Problemas conhecidos do Kubelogin do Azure.
Resolver problemas de acesso
Importante
A etapa descrita nesta seção sugere um método de autenticação alternativo em comparação com a autenticação de grupo normal do Microsoft Entra. Utilize esta opção apenas em caso de emergência.
Se não tiver acesso administrativo a um grupo válido do Microsoft Entra, pode seguir esta solução alternativa. Entre com uma conta que seja membro da função Administrador do Cluster de Serviço do Kubernetes do Azure e conceda ao seu grupo ou credenciais de administrador de locatário para acessar seu cluster.
Próximos passos
- Saiba mais sobre a integração do Microsoft Entra com o Kubernetes RBAC.
- Saiba mais sobre os conceitos de identidade AKS e Kubernetes.
- Saiba como usar o kubelogin para todos os métodos de autenticação Microsoft Entra suportados no AKS.
- Use modelos do Azure Resource Manager (ARM) para criar clusters habilitados para Microsoft Entra ID gerenciados pelo AKS.
Azure Kubernetes Service