Usar uma identidade gerenciada no Serviço Kubernetes do Azure (AKS)

Os clusters do Serviço Kubernetes do Azure (AKS) exigem uma identidade do Microsoft Entra para acessar recursos do Azure, como balanceadores de carga e discos gerenciados. As identidades gerenciadas para recursos do Azure são a maneira recomendada de autorizar o acesso de um cluster AKS a outros serviços do Azure.

Você pode usar uma identidade gerenciada para autorizar o acesso de um cluster AKS a qualquer serviço que ofereça suporte à autorização do Microsoft Entra, sem precisar gerenciar credenciais ou incluí-las em seu código. Você atribui à identidade gerenciada uma função de controle de acesso baseado em função do Azure (Azure RBAC) para conceder-lhe permissões para um recurso específico no Azure. Por exemplo, você pode conceder permissões a uma identidade gerenciada para acessar segredos em um cofre de chaves do Azure para uso pelo cluster. Para obter mais informações sobre o RBAC do Azure, consulte O que é o controle de acesso baseado em função do Azure (Azure RBAC)?.

Este artigo mostra como habilitar os seguintes tipos de identidade gerenciada em um cluster AKS novo ou existente:

• Identidade gerenciada atribuída ao sistema. Uma identidade gerenciada atribuída ao sistema está associada a um único recurso do Azure, como um cluster AKS. Ele existe apenas para o ciclo de vida do cluster.
• Identidade gerenciada atribuída pelo usuário. Uma identidade gerenciada atribuída pelo usuário é um recurso autônomo do Azure que um cluster AKS pode usar para autorizar o acesso a outros serviços do Azure. Ele persiste separadamente do cluster AKS e pode ser usado por vários recursos do Azure.
• Identidade gerenciada kubelet pré-criada. Uma identidade gerenciada kubelet pré-criada é uma identidade opcional atribuída pelo usuário que o kubelet pode usar para acessar outros recursos no Azure. Se você não especificar uma identidade gerenciada atribuída pelo usuário para o kubelet, o AKS criará uma identidade kubelet atribuída pelo sistema no grupo de recursos do nó.

Para saber mais sobre identidades gerenciadas, consulte Identidades gerenciadas para recursos do Azure.

Descrição geral

Um cluster AKS usa uma identidade gerenciada para solicitar tokens do Microsoft Entra. Esses tokens são usados para autorizar o acesso a outros recursos em execução no Azure. Você pode atribuir uma função RBAC do Azure a uma identidade gerenciada para conceder permissões de cluster para acessar recursos específicos. Por exemplo, se o cluster precisar acessar segredos em um cofre de chaves do Azure, você poderá atribuir à identidade gerenciada do cluster uma função RBAC do Azure que conceda essas permissões.

Uma identidade gerenciada pode ser atribuída ao sistema ou ao usuário. Esses dois tipos de identidades gerenciadas são semelhantes, pois você pode usar qualquer tipo para autorizar o acesso aos recursos do Azure a partir do cluster AKS. A principal diferença entre eles é que uma identidade gerenciada atribuída ao sistema está associada a um único recurso do Azure, como um cluster AKS, enquanto uma identidade gerenciada atribuída pelo usuário é ela própria um recurso autônomo do Azure. Para obter mais detalhes sobre as diferenças entre tipos de identidades gerenciadas, consulte Tipos de identidade gerenciados em Identidades gerenciadas para recursos do Azure.

Ambos os tipos de identidades gerenciadas são gerenciados pela plataforma Azure, para que você possa autorizar o acesso de seus aplicativos sem precisar provisionar ou girar segredos. O Azure gerencia as credenciais da identidade para você.

Quando você implanta um cluster AKS, uma identidade gerenciada atribuída ao sistema é criada para você por padrão. Você também pode criar o cluster com uma identidade gerenciada atribuída pelo usuário.

Também é possível criar um cluster com uma entidade de serviço de aplicativo em vez de uma identidade gerenciada. As identidades gerenciadas são recomendadas em relação às entidades de serviço para segurança e facilidade de uso. Para obter mais informações sobre como criar um cluster com uma entidade de serviço, consulte Usar uma entidade de serviço com o Serviço Kubernetes do Azure (AKS).

Você pode atualizar um cluster existente para usar uma identidade gerenciada de uma entidade de serviço de aplicativo. Você também pode atualizar um cluster existente para um tipo diferente de identidade gerenciada. Se o cluster já estiver usando uma identidade gerenciada e a identidade tiver sido alterada, por exemplo, se você atualizou o tipo de identidade do cluster de atribuído pelo sistema para atribuído pelo usuário, haverá um atraso enquanto os componentes do plano de controle mudam para a nova identidade. Os componentes do plano de controle continuam a usar a identidade antiga até que seu token expire. Depois que o token é atualizado, eles mudam para a nova identidade. Este processo pode demorar várias horas.

Os tipos de identidade atribuídos pelo sistema e pelo usuário diferem de uma identidade do Microsoft Entra Workload, que se destina ao uso por um aplicativo em execução em um pod.

Antes de começar

• Verifique se você tem a CLI do Azure versão 2.23.0 ou posterior instalada. Executar az --version para localizar a versão. Se precisar de instalar ou atualizar, veja Install Azure CLI (Instalar o Azure CLI).

• Para usar uma identidade gerenciada kubelet pré-criada, você precisa da CLI do Azure versão 2.26.0 ou posterior instalada.

• Para atualizar um cluster existente para usar uma identidade gerenciada atribuída pelo sistema ou uma identidade gerenciada atribuída pelo usuário, você precisa da CLI do Azure versão 2.49.0 ou posterior instalada.

Antes de executar os exemplos neste artigo, defina sua assinatura como a assinatura ativa atual chamando o comando az account set e passando sua ID de assinatura.

az account set --subscription <subscription-id>

Crie também um grupo de recursos do Azure se ainda não tiver um chamando o az group create comando.

az group create \
    --name myResourceGroup \
    --location westus2

Habilitar uma identidade gerenciada atribuída ao sistema

Uma identidade gerenciada atribuída ao sistema é uma identidade associada a um cluster AKS ou outro recurso do Azure. A identidade gerenciada atribuída ao sistema está vinculada ao ciclo de vida do cluster. Quando o cluster é excluído, a identidade gerenciada atribuída ao sistema também é excluída.

O cluster AKS pode usar a identidade gerenciada atribuída ao sistema para autorizar o acesso a outros recursos em execução no Azure. Você pode atribuir uma função RBAC do Azure à identidade gerenciada atribuída pelo sistema para conceder permissões de cluster para acessar recursos específicos. Por exemplo, se o cluster precisar acessar segredos em um cofre de chaves do Azure, você poderá atribuir à identidade gerenciada atribuída ao sistema uma função RBAC do Azure que conceda essas permissões.

Habilitar uma identidade gerenciada atribuída ao sistema em um novo cluster AKS

Para habilitar uma identidade gerenciada atribuída ao sistema em um novo cluster, chame o az aks createarquivo . Uma identidade gerenciada atribuída ao sistema é habilitada no novo cluster por padrão.

Crie um cluster AKS usando o az aks create comando.

az aks create \
    --resource-group myResourceGroup \
    --name myManagedCluster \
    --generate-ssh-keys

Para verificar se uma identidade gerenciada atribuída ao sistema está habilitada para o cluster depois de criado, consulte Determinar que tipo de identidade gerenciada um cluster está usando.

Atualizar um cluster AKS existente para usar uma identidade gerenciada atribuída ao sistema

Para atualizar um cluster AKS existente que esteja usando uma entidade de serviço para usar uma identidade gerenciada atribuída ao sistema, execute o az aks update comando com o --enable-managed-identity parâmetro.

az aks update \
    --resource-group myResourceGroup \
    --name myManagedCluster \
    --enable-managed-identity

Depois de atualizar o cluster para usar uma identidade gerenciada atribuída pelo sistema em vez de uma entidade de serviço, o plano de controle e os pods usam a identidade gerenciada atribuída pelo sistema para autorização ao acessar outros serviços no Azure. O Kubelet continua usando uma entidade de serviço até que você também atualize seu agentpool. Você pode usar o az aks nodepool upgrade --resource-group myResourceGroup --cluster-name myAKSCluster --name mynodepool --node-image-only comando em seus nós para atualizar para uma identidade gerenciada. Uma atualização do pool de nós causa tempo de inatividade para o cluster AKS à medida que os nós nos pools de nós são isolados, drenados e recriados.

Adicionar uma atribuição de função para uma identidade gerenciada atribuída ao sistema

Você pode atribuir uma função RBAC do Azure à identidade gerenciada atribuída ao sistema para conceder as permissões de cluster em outro recurso do Azure. O RBAC do Azure dá suporte a definições de função internas e personalizadas que especificam níveis de permissões. Para obter mais informações sobre como atribuir funções RBAC do Azure, consulte Etapas para atribuir uma função do Azure.

Ao atribuir uma função RBAC do Azure a uma identidade gerenciada, você deve definir o escopo da função. Em geral, é uma prática recomendada limitar o escopo de uma função aos privilégios mínimos exigidos pela identidade gerenciada. Para obter mais informações sobre como definir o escopo das funções do RBAC do Azure, consulte Entender o escopo do RBAC do Azure.

Quando você cria e usa sua própria rede virtual, discos do Azure anexados, endereço IP estático, tabela de rotas ou identidade kubelet atribuída pelo usuário onde os recursos estão fora do grupo de recursos do nó de trabalho, a CLI do Azure adiciona a atribuição de função automaticamente. Se você estiver usando um modelo ARM ou outro método, use a ID principal da identidade gerenciada para executar uma atribuição de função.

Se você não estiver usando a CLI do Azure, mas estiver usando sua própria rede virtual, discos do Azure anexados, endereço IP estático, tabela de rotas ou identidade kubelet atribuída pelo usuário que esteja fora do grupo de recursos do nó de trabalho, recomendamos usar uma identidade gerenciada atribuída pelo usuário para o plano de controle. Quando o plano de controle usa uma identidade gerenciada atribuída ao sistema, a identidade é criada ao mesmo tempo que o cluster, portanto, a atribuição de função não pode ser executada até que o cluster tenha sido criado.

Obter a ID principal da identidade gerenciada atribuída ao sistema

Para atribuir uma função RBAC do Azure à identidade gerenciada atribuída ao sistema de um cluster, primeiro você precisa da ID principal da identidade gerenciada. Obtenha a ID principal para a identidade gerenciada atribuída ao sistema do cluster chamando o az aks show comando.

# Get the principal ID for a system-assigned managed identity.
CLIENT_ID=$(az aks show \
    --name myAKSCluster \
    --resource-group myResourceGroup \
    --query identity.principalId \
    --output tsv)

Atribuir uma função RBAC do Azure à identidade gerenciada atribuída ao sistema

Para conceder permissões de identidade gerenciada atribuídas pelo sistema a um recurso no Azure, chame o az role assignment create comando para atribuir uma função RBAC do Azure à identidade gerenciada.

Para uma rede virtual, disco do Azure anexado, endereço IP estático ou tabela de rotas fora do grupo de recursos do nó de trabalho padrão, você precisa atribuir a Network Contributor função no grupo de recursos personalizado.

Por exemplo, atribua a Network Contributor função no grupo de recursos personalizado usando o az role assignment create comando. Para o --scope parâmetro, forneça a ID do recurso para o grupo de recursos para o cluster.

az role assignment create \
    --assignee $CLIENT_ID \
    --role "Network Contributor" \
    --scope "<resource-group-id>"

Habilitar uma identidade gerenciada atribuída pelo usuário

Uma identidade gerenciada atribuída pelo usuário é um recurso autônomo do Azure. Quando você cria um cluster com uma identidade gerenciada atribuída pelo usuário para o plano de controle, o recurso de identidade gerenciada atribuído pelo usuário deve existir antes da criação do cluster. Esse recurso permite cenários como a criação do cluster com uma VNet personalizada ou com um tipo de saída de UDR (roteamento definido pelo usuário).

Criar uma identidade gerida atribuída pelo utilizador

Se você ainda não tiver um recurso de identidade gerenciado atribuído pelo usuário, crie um usando o az identity create comando.

az identity create \
    --name myIdentity \
    --resource-group myResourceGroup

Sua saída deve ser semelhante à saída de exemplo a seguir:

{                                  
  "clientId": "<client-id>",
  "clientSecretUrl": "<clientSecretUrl>",
  "id": "/subscriptions/<subscriptionid>/resourcegroups/myResourceGroup/providers/Microsoft.ManagedIdentity/userAssignedIdentities/myIdentity", 
  "location": "westus2",
  "name": "myIdentity",
  "principalId": "<principal-id>",
  "resourceGroup": "myResourceGroup",                       
  "tags": {},
  "tenantId": "<tenant-id>",
  "type": "Microsoft.ManagedIdentity/userAssignedIdentities"
}

Obter o ID principal da identidade gerenciada atribuída pelo usuário

Para obter o ID principal da identidade gerenciada atribuída pelo usuário, chame az identity show e consulte a principalId propriedade:

CLIENT_ID=$(az identity show \
    --name myIdentity \
    --resource-group myResourceGroup \
    --query principalId \
    --output tsv)

Obter o ID de recurso da identidade gerenciada atribuída pelo usuário

Para criar um cluster com uma identidade gerenciada atribuída pelo usuário, você precisará da ID do recurso para a nova identidade gerenciada. Para obter o ID de recurso da identidade gerenciada atribuída pelo usuário, chame az aks show e consulte a id propriedade:

RESOURCE_ID=$(az identity show \
    --name myIdentity \
    --resource-group myResourceGroup \
    --query id \
    --output tsv)

Atribuir uma função RBAC do Azure à identidade gerenciada atribuída pelo usuário

Antes de criar o cluster, adicione uma atribuição de função para a identidade gerenciada chamando o az role assignment create comando.

O exemplo a seguir atribui a função Usuário de Segredos do Cofre de Chaves à identidade gerenciada atribuída pelo usuário para conceder-lhe permissões para acessar segredos em um cofre de chaves. A atribuição de função tem como escopo o recurso do cofre de chaves:

az role assignment create \
    --assignee $CLIENT_ID \
    --role "Key Vault Secrets User" \
    --scope "<keyvault-resource-id>"

Criar um cluster com a identidade gerenciada atribuída pelo usuário

Para criar um cluster AKS com a identidade gerenciada atribuída pelo usuário, chame o az aks create comando. Inclua o --assign-identity parâmetro e passe o ID do recurso para a identidade gerenciada atribuída pelo usuário:

az aks create \
    --resource-group myResourceGroup \
    --name myManagedCluster \
    --network-plugin azure \
    --vnet-subnet-id <subnet-id> \
    --dns-service-ip 10.2.0.10 \
    --service-cidr 10.2.0.0/24 \
    --assign-identity $RESOURCE_ID \
    --generate-ssh-keys

Atualizar um cluster existente para usar uma identidade gerenciada atribuída pelo usuário

Para atualizar um cluster existente para usar uma identidade gerenciada atribuída pelo usuário, chame o az aks update comando. Inclua o --assign-identity parâmetro e passe o ID do recurso para a identidade gerenciada atribuída pelo usuário:

az aks update \
    --resource-group myResourceGroup \
    --name myManagedCluster \
    --enable-managed-identity \
    --assign-identity $RESOURCE_ID

A saída para uma atualização de cluster bem-sucedida para usar uma identidade gerenciada atribuída pelo usuário deve ser semelhante à saída de exemplo a seguir:

  "identity": {
    "principalId": null,
    "tenantId": null,
    "type": "UserAssigned",
    "userAssignedIdentities": {
      "/subscriptions/<subscriptionid>/resourcegroups/resourcegroups/providers/Microsoft.ManagedIdentity/userAssignedIdentities/myIdentity": {
        "clientId": "<client-id>",
        "principalId": "<principal-id>"
      }
    }
  },

Determinar que tipo de identidade gerenciada um cluster está usando

Para determinar que tipo de identidade gerenciada seu cluster AKS existente está usando, chame o comando az aks show e consulte a propriedade type da identidade.

az aks show \
    --name myAKSCluster \
    --resource-group myResourceGroup \
    --query identity.type \
    --output tsv       

Se o cluster estiver usando uma identidade gerenciada, o valor da propriedade type será SystemAssigned ou UserAssigned.

Se o cluster estiver usando uma entidade de serviço, o valor da propriedade type será null. Considere atualizar seu cluster para usar uma identidade gerenciada.

Use uma identidade gerenciada kubelet pré-criada

Uma identidade kubelet pré-criada é uma identidade gerenciada atribuída pelo usuário que existe antes da criação do cluster. Esse recurso habilita cenários como a conexão com o Registro de Contêiner do Azure (ACR) durante a criação do cluster.

Para uma identidade kubelet atribuída pelo usuário fora do grupo de recursos do nó de trabalho padrão, você precisa atribuir a função de Operador de Identidade Gerenciada na identidade kubelet para identidade gerenciada do plano de controle.

identidade gerenciada kubelet

Se você não tiver uma identidade gerenciada pelo kubelet, crie uma usando o az identity create comando.

az identity create \
    --name myKubeletIdentity \
    --resource-group myResourceGroup

Sua saída deve ser semelhante à saída de exemplo a seguir:

{
  "clientId": "<client-id>",
  "clientSecretUrl": "<clientSecretUrl>",
  "id": "/subscriptions/<subscriptionid>/resourcegroups/myResourceGroup/providers/Microsoft.ManagedIdentity/userAssignedIdentities/myKubeletIdentity", 
  "location": "westus2",
  "name": "myKubeletIdentity",
  "principalId": "<principal-id>",
  "resourceGroup": "myResourceGroup",                       
  "tags": {},
  "tenantId": "<tenant-id>",
  "type": "Microsoft.ManagedIdentity/userAssignedIdentities"
}

Atribuir uma função RBAC à identidade gerenciada pelo kubelet

Atribua a ACRPull função na identidade kubelet usando o az role assignment create comando. Forneça a ID principal da identidade kubelet para a variável $KUBELET_CLIENT_ID e forneça a ID do Registro ACR para a variável $ACR_REGISTRY_ID.

az role assignment create \
    --assignee $KUBELET_CLIENT_ID \
    --role "acrpull" \
    --scope "$ACR_REGISTRY_ID"

Criar um cluster para usar a identidade kubelet

Agora você pode criar seu cluster AKS com suas identidades existentes. Certifique-se de fornecer o ID de recurso da identidade gerenciada para o plano de controle incluindo o assign-identity argumento e a identidade gerenciada kubelet usando o assign-kubelet-identity argumento.

Crie um cluster AKS com suas identidades existentes usando o az aks create comando.

az aks create \
    --resource-group myResourceGroup \
    --name myManagedCluster \
    --network-plugin azure \
    --vnet-subnet-id <subnet-id> \
    --dns-service-ip 10.2.0.10 \
    --service-cidr 10.2.0.0/24 \
    --assign-identity <identity-resource-id> \
    --assign-kubelet-identity <kubelet-identity-resource-id> \
    --generate-ssh-keys

Uma criação bem-sucedida de cluster AKS usando uma identidade gerenciada kubelet deve resultar em uma saída semelhante à seguinte:

  "identity": {
    "principalId": null,
    "tenantId": null,
    "type": "UserAssigned",
    "userAssignedIdentities": {
      "/subscriptions/<subscriptionid>/resourcegroups/resourcegroups/providers/Microsoft.ManagedIdentity/userAssignedIdentities/myIdentity": {
        "clientId": "<client-id>",
        "principalId": "<principal-id>"
      }
    }
  },
  "identityProfile": {
    "kubeletidentity": {
      "clientId": "<client-id>",
      "objectId": "<object-id>",
      "resourceId": "/subscriptions/<subscriptionid>/resourcegroups/resourcegroups/providers/Microsoft.ManagedIdentity/userAssignedIdentities/myKubeletIdentity"
    }
  },

Atualizar um cluster existente para usar a identidade kubelet

Para atualizar um cluster existente para usar a identidade gerenciada kubelet, primeiro obtenha a identidade gerenciada do plano de controle atual para seu cluster AKS.

1. Confirme se o cluster AKS está usando a identidade gerenciada atribuída pelo usuário usando o az aks show comando.

   az aks show \
       --resource-group <RGName> \
       --name <ClusterName> \
       --query "servicePrincipalProfile"
   

   Se o cluster estiver usando uma identidade gerenciada, a saída será exibida clientId com um valor msi. Um cluster usando uma entidade de serviço mostra uma ID de objeto. Por exemplo:

   # The cluster is using a managed identity.
   {
     "clientId": "msi"
   }
   

2. Depois de confirmar que o cluster está usando uma identidade gerenciada, localize o ID de recurso da identidade gerenciada usando o az aks show comando.

   az aks show --resource-group <RGName> \
       --name <ClusterName> \
       --query "identity"
   

   Para uma identidade gerenciada atribuída pelo usuário, sua saída deve ser semelhante à saída de exemplo a seguir:

   {
     "principalId": null,
     "tenantId": null,
     "type": "UserAssigned",
     "userAssignedIdentities": <identity-resource-id>
         "clientId": "<client-id>",
         "principalId": "<principal-id>"
   },
   

3. Atualize seu cluster com suas identidades existentes usando o az aks update comando. Forneça a ID de recurso da identidade gerenciada atribuída pelo usuário para o plano de controle para o assign-identity argumento. Forneça o ID do recurso da identidade gerenciada do kubelet para o assign-kubelet-identity argumento.

   az aks update \
       --resource-group myResourceGroup \
       --name myManagedCluster \
       --enable-managed-identity \
       --assign-identity <identity-resource-id> \
       --assign-kubelet-identity <kubelet-identity-resource-id>
   

Sua saída para uma atualização de cluster bem-sucedida usando sua própria identidade gerenciada kubelet deve ser semelhante à saída de exemplo a seguir:

  "identity": {
    "principalId": null,
    "tenantId": null,
    "type": "UserAssigned",
    "userAssignedIdentities": {
      "/subscriptions/<subscriptionid>/resourcegroups/resourcegroups/providers/Microsoft.ManagedIdentity/userAssignedIdentities/myIdentity": {
        "clientId": "<client-id>",
        "principalId": "<principal-id>"
      }
    }
  },
  "identityProfile": {
    "kubeletidentity": {
      "clientId": "<client-id>",
      "objectId": "<object-id>",
      "resourceId": "/subscriptions/<subscriptionid>/resourcegroups/resourcegroups/providers/Microsoft.ManagedIdentity/userAssignedIdentities/myKubeletIdentity"
    }
  },

Obter as propriedades da identidade kubelet

Para obter as propriedades da identidade kubelet, chame az aks show e consulte a identityProfile.kubeletidentity propriedade.

az aks show \
    --name myAKSCluster \
    --resource-group myResourceGroup \
    --query "identityProfile.kubeletidentity"

Limitações de identidade kubelet pré-criadas

Observe as seguintes limitações para a identidade kubelet pré-criada:

• Uma identidade kubelet pré-criada deve ser uma identidade gerenciada atribuída pelo usuário.
• As regiões Leste da China e Norte da China no Microsoft Azure operadas pela 21Vianet não são suportadas.

Resumo das identidades gerenciadas usadas pelo AKS

O AKS usa várias identidades gerenciadas para serviços e complementos integrados.

Limitações

• Não há suporte para mover ou migrar um cluster gerenciado habilitado para identidade para um locatário diferente.

• Se o cluster tiver a identidade gerenciada pelo pod do Microsoft Entra (aad-pod-identity) habilitada, os pods NMI (Node-Managed Identity) modificarão os iptables dos nós para intercetar chamadas para o ponto de extremidade IMDS (Instance Metadata) do Azure. Essa configuração significa que qualquer solicitação feita ao ponto de extremidade IMDS é intercetada pelo NMI, mesmo que um pod específico não use aad-pod-identity.

  A definição de recurso personalizada (CRD) AzurePodIdentityException pode ser configurada para especificar que as solicitações para o ponto de extremidade IMDS originadas de um rótulo de correspondência de pod definido no CRD devem ser intermediadas por proxy sem qualquer processamento no NMI. Exclua os pods do sistema com o kubernetes.azure.com/managedby: aks rótulo no namespace kube-system configurando aad-pod-identity o CRD AzurePodIdentityException. Para obter mais informações, consulte Usar identidades gerenciadas por pod do Microsoft Entra no Serviço Kubernetes do Azure.

  Para configurar uma exceção, instale o mic-exception YAML.

• O AKS não suporta o uso de uma identidade gerenciada atribuída ao sistema ao usar uma zona DNS privada personalizada.

Próximos passos

• Use os modelos do Azure Resource Manager para criar um cluster gerenciado habilitado para identidade.
• Saiba como usar o kubelogin para todos os métodos de autenticação Microsoft Entra suportados no AKS.