Habilitar a autenticação de identidade do Microsoft Entra para o plano de controle do AKS

A integração do Microsoft Entra simplifica o processo de integração. 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 do AKS (Serviço de Kubernetes do Azure) gerencia os aplicativos 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.

Saiba mais sobre o fluxo de integração do Microsoft Entra na documentação do Microsoft Entra.

Limitações

A integração do Microsoft Entra não pode ser desabilitada depois de habilitada em um cluster.

Antes de começar

Para instalar o complemento do AKS, verifique se você tem os seguintes itens:

  • Você tem a CLI do Azure versão 2.29.0 ou posterior, instalada e configurada. Para localizar a versão, execute o comando az --version. Se precisar instalar ou atualizar, consulte Instalar Azure CLI.
  • Você precisa de kubectl com uma versão mínima de 1.18.1 ou kubelogin. 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 o az 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 e kubectl não deve ser superior a uma versão. Caso contrário, problemas de autenticação ocorrem na versão errada.
  • 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.

Habilitar a integração no cluster do AKS

Primeiro, defina variáveis de ambiente para o grupo de recursos, nome do cluster, IDs de objeto do grupo de administradores do Microsoft Entra e ID do locatário. Reutilize essas variáveis nos comandos a seguir.

export RESOURCE_GROUP="myResourceGroup"
export CLUSTER_NAME="myManagedCluster"
export AAD_ADMIN_GROUP_OBJECT_IDS="<group-object-id>"  # comma-separated for multiple groups
export AAD_TENANT_ID="<tenant-id>"
export LOCATION="centralus"

Criar um cluster

  1. Crie um grupo de recursos Azure usando o comando az group create.

    az group create --name $RESOURCE_GROUP --location $LOCATION

  2. 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 $RESOURCE_GROUP \
  --name $CLUSTER_NAME \
  --enable-aad \
  --aad-admin-group-object-ids $AAD_ADMIN_GROUP_OBJECT_IDS \
  --aad-tenant-id $AAD_TENANT_ID \
  --generate-ssh-keys

    Quando a criação de um cluster do Microsoft Entra ID é bem-sucedida, o corpo da resposta contém a seguinte seção.

    "AADProfile": {
  "adminGroupObjectIds": [
  "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb"
  ],
  "clientAppId": null,
  "managed": true,
  "serverAppId": null,
  "serverAppSecret": null,
  "tenantId": "aaaabbbb-0000-cccc-1111-dddd2222eeee"
}

Usar um cluster existente

Habilite a integração com o Microsoft Entra no seu cluster Kubernetes existente com RBAC habilitado usando o comando az aks update. Defina seu grupo de administradores para manter o acesso no cluster.

az aks update \
  --resource-group $RESOURCE_GROUP \
  --name $CLUSTER_NAME \
  --enable-aad \
  --aad-admin-group-object-ids $AAD_ADMIN_GROUP_OBJECT_IDS \
  --aad-tenant-id $AAD_TENANT_ID

Uma ativação bem-sucedida de um cluster do Microsoft Entra ID tem a seguinte seção no corpo da resposta:

"AADProfile": {
  "adminGroupObjectIds": [
      "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb"
  ],
  "clientAppId": null,
  "managed": true,
  "serverAppId": null,
  "serverAppSecret": null,
  "tenantId": "aaaabbbb-0000-cccc-1111-dddd2222eeee"
}

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 por meio do az aks update comando.

Aviso

Clusters da camada gratuita podem apresentar tempo de inatividade do servidor de API durante a atualização. É recomendável atualizar durante o horário que você não trabalha. Após a atualização, o kubeconfig conteúdo é alterado. Você precisa executar az aks get-credentials --resource-group <AKS resource group name> --name <AKS cluster name> para mesclar as novas credenciais no kubeconfig arquivo.

az aks update \
  --resource-group $RESOURCE_GROUP \
  --name $CLUSTER_NAME \
  --enable-aad \
  --aad-admin-group-object-ids $AAD_ADMIN_GROUP_OBJECT_IDS \
  --aad-tenant-id $AAD_TENANT_ID

Uma migração bem-sucedida de um cluster do Microsoft Entra ID tem a seguinte seção na resposta:

"AADProfile": {
  "adminGroupObjectIds": [
      "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb"
  ],
  "clientAppId": null,
  "managed": true,
  "serverAppId": null,
  "serverAppSecret": null,
  "tenantId": "aaaabbbb-0000-cccc-1111-dddd2222eeee"
}

Acessar o cluster habilitado

  1. Obtenha as credenciais de usuário para acessar o cluster usando o comando az aks get-credentials.

    az aks get-credentials --resource-group $RESOURCE_GROUP --name $CLUSTER_NAME

  2. Siga as instruções de entrada.

  3. Veja os nós no cluster com o comando kubectl get nodes.

    kubectl get nodes

Os clusters que executam o Kubernetes 1.24 ou posterior usam automaticamente o kubelogin formato exec-plug-in, portanto, nenhuma conversão manual kubeconfig é necessária para a entrada interativa da CLI do Azure. Para cenários não interativos, como pipelines de CI, ou para usar um método de autenticação diferente (entidade de serviço, identidade gerenciada, identidade de carga de trabalho ou código de dispositivo), consulte Usar o kubelogin para autenticar usuários no AKS.

Acesso de emergência

Na eventualidade de o login via Microsoft Entra ID no servidor da API do Kubernetes do seu cluster não funcionar — por exemplo, durante uma interrupção generalizada do serviço Microsoft Entra —, você pode recorrer à conta de administrador local do cluster para continuar operando o cluster até que o login baseado no Entra seja restaurado.

Note

Esse fallback só é necessário quando o login baseado em Entra não estiver disponível. Se o problema for um grupo de administradores configurado incorretamente (por exemplo, o grupo foi excluído ou a ID de objeto incorreta foi definida), você não precisa dele – atualize o grupo de administradores diretamente com az aks update --aad-admin-group-object-ids o uso de uma conta que tenha a Microsoft.ContainerService/managedClusters/write permissão.

Importante

Esse fluxo de trabalho ignora a autenticação do Microsoft Entra. Use-o apenas como uma alternativa temporária e desabilite as contas locais novamente quando o login do Microsoft Entra for restaurado.

Para usar o caminho de emergência, é necessário ter a função Colaborador do Serviço de Kubernetes do Azure no recurso do cluster. Essa função concede a permissão Microsoft.ContainerService/managedClusters/write necessária para reativar contas locais, além de acesso às credenciais locais de administrador do cluster. Ele é avaliado pelo Azure Resource Manager, portanto, ele funciona independentemente do caminho de entrada do Microsoft Entra para o servidor de API do Kubernetes.

  1. Se as contas locais estiverem desabilitadas no cluster, habilite-as novamente temporariamente.

    az aks update --resource-group $RESOURCE_GROUP --name $CLUSTER_NAME --enable-local-accounts

  2. Recupere a credencial de administrador do cluster local usando o comando az aks get-credentials com a flag --admin. Essa credencial é um kubeconfig baseado em certificado que dispensa o Microsoft Entra.

    az aks get-credentials --resource-group $RESOURCE_GROUP --name $CLUSTER_NAME --admin

  3. Use kubectl para operar o cluster enquanto o Microsoft Entra não estiver disponível. Depois que o login do Microsoft Entra estiver funcionando novamente, desabilite as contas locais para retornar o cluster ao padrão de segurança.

    az aks update --resource-group $RESOURCE_GROUP --name $CLUSTER_NAME --disable-local-accounts

Próximas Etapas 

  • Last updated on