Habilitar a autenticação de identidade gerenciada do Azure para clusters do Kubernetes com kubelogin
A integração Microsoft Entra gerida por AKS simplifica o processo de integração Microsoft Entra. Anteriormente, você era obrigado a criar um aplicativo cliente e servidor, e o locatário do Microsoft Entra tinha que atribuir permissões de função Leitores de Diretório. Agora, o provedor de recursos AKS gerencia os aplicativos de cliente e servidor para você.
Os administradores do cluster podem configurar o RBAC (controle de acesso baseado em função) do Kubernetes com base na identidade de um usuário ou na associação dele a um grupo de diretórios. A autenticação do Microsoft Entra é fornecida aos clusters do AKS com OpenID Connect. O OpenID Connect é uma camada de identidade compilada sobre o protocolo OAuth 2.0. Para obter mais informações sobre o OpenID Connect, consulte a documentação do Open ID 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 o cluster do AKS.
Limitações
Veja a seguir restrições que integram a autenticação de identidade gerenciada do Azure no AKS.
- A integração não pode ser desabilitada depois de adicionada.
- Não há suporte para downgrades de um cluster integrado para os clusters herdados do Microsoft Entra ID.
- Clusters sem suporte do RBAC do Kubernetes não podem adicionar a integração.
Antes de começar
Os requisitos a seguir precisam ser atendidos para instalar corretamente o complemento do AKS para identidade gerenciada.
- Você tem a CLI do Azure versão 2.29.0 ou posterior, instalada e configurada. Execute
az --version
para encontrar a versão. Se você precisa instalar ou atualizar, consulte Instalar a CLI do Azure. - Você precisa de
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, são atualizados por padrão e executar oaz aks install-cli
não é necessário nem recomendado. Se estiver usando um pipeline automatizado, você precisará gerenciar as 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 superior a uma versão. Caso contrário, problemas de autenticação ocorrem na versão errada. - Se você estiver usando o helm, precisará de uma versão mínima do helm 3.3.
- Essa configuração exige que você tenha um grupo do Microsoft Entra para seu cluster. Este grupo é registrado como um grupo de administração no cluster para conceder permissões de administrador. Se você não tiver um grupo existente do Microsoft Entra, poderá criar um usando o comando
az ad group create
.
Observação
Os clusters integrados do Microsoft Entra usando uma versão do Kubernetes mais recente que a versão 1.24 usam automaticamente o formato kubelogin
. A partir do Kubernetes versão 1.24, o formato padrão da credencial do clusterUser para clusters do Microsoft Entra ID é exec
, o que requer o binário kubelogin
no CAMINHO de execução. Não há nenhuma alteração de comportamento para clusters não do Microsoft Entra ou clusters do Microsoft Entra ID executando uma versão anterior à versão 1.24.
O kubeconfig
baixado existente continuará a funcionar. Um formato de parâmetro de consulta opcional vem incluído quando você obtém a credencial de clusterUser para substituir a alteração de comportamento padrão. Você poderá especificar explicitamente o formato para o azure se precisar manter o formato do kubeconfig
antigo.
Habilitar a integração no cluster do AKS
Criar um cluster
Crie um grupo de recursos do Azure usando o comando
az group create
.az group create --name myResourceGroup --location centralus
Crie um cluster do AKS e habilite o acesso de administração para o seu grupo do Microsoft Entra usando o comando
az aks create
.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 do Microsoft Entra ID 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 no cluster habilitado para RBAC do Kubernetes existente usando o comando az aks update
. Defina 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 do Microsoft Entra ID 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 o cluster herdado para a integração
Se o cluster usar a integração herdada do Microsoft Entra, você poderá atualizar para a integração do Microsoft Entra gerenciada pelo AKS através do comando az aks update
.
Aviso
Os clusters de camada gratuita podem enfrentar um tempo de inatividade do servidor de API durante a atualização. É recomendável atualizar durante o horário que você não trabalha.
O conteúdo do kubeconfig é alterado após a atualização. 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 do Microsoft Entra ID 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 o cluster usando o comando
az aks get-credentials
.az aks get-credentials --resource-group myResourceGroup --name myManagedCluster
Siga suas instruções para entrar.
Defina
kubelogin
para usar a CLI do Azure.kubelogin convert-kubeconfig -l azurecli
Veja os nós no cluster com o comando
kubectl get nodes
.kubectl get nodes
Entrada não interativa com kubelogin
Há alguns cenários não interativos que não dão suporte a kubectl
. 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.
Observação
Os clusters integrados do Microsoft Entra usando uma versão do Kubernetes mais recente que a versão 1.24 usam automaticamente o formato kubelogin
. A partir do Kubernetes versão 1.24, o formato padrão da credencial do clusterUser para clusters do Microsoft Entra ID é exec
, o que requer o binário kubelogin
no CAMINHO de execução. Não há nenhuma alteração de comportamento para clusters não do Microsoft Entra ou clusters do Microsoft Entra ID executando uma versão anterior à versão 1.24.
O kubeconfig
baixado existente continuará a funcionar. Um formato de parâmetro de consulta opcional vem incluído quando você obtém a credencial de clusterUser para substituir a alteração de comportamento padrão. Você poderá especificar explicitamente o formato para o azure se precisar manter o formato do kubeconfig
antigo.
Ao obter a credencial clusterUser, você pode usar o parâmetro de consulta
format
para substituir o comportamento padrão. Você pode definir o valor paraazure
para usar o formato kubeconfig original:az aks get-credentials --format azure
Se o cluster integrado do Microsoft Entra usar o Kubernetes versão 1.24 ou inferior, você precisará converter manualmente o formato kubeconfig.
export KUBECONFIG=/path/to/kubeconfig kubelogin convert-kubeconfig
Observação
Se você receber o erro de mensagem: 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, consulte Problemas conhecidos do Kubelogin do Azure.
Solucionar 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. Use essa opção somente em uma emergência.
Se você não tiver acesso administrativo a um grupo válido do Microsoft Entra, poderá seguir essa solução alternativa. Entre com uma conta que seja membro da função de Administrador do Cluster do Serviço de Kubernetes do Azure e conceda credenciais de administrador de grupo ou locatário para acessar seu cluster.
Próximas etapas
- Saiba mais sobre a integração do Microsoft Entra com o RBAC do Kubernetes.
- Saiba mais sobre os conceitos de identidade do AKS e do Kubernetes.
- Saiba como usar kubelogin para todos os métodos de autenticação do Microsoft Entra com suporte no AKS.
- Use modelos do Azure Resource Manager (ARM) para criar clusters habilitados para o Microsoft Entra ID gerenciados pelo AKS.
Azure Kubernetes Service