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

  • Artigo

Os clusters do Serviço de Kubernetes do Azure (AKS) exigem uma identidade para acessar os recursos do Azure, como balanceadores de carga e discos gerenciados. A identidade pode ser uma identidade gerenciada ou uma entidade de serviço.

Este artigo fornece detalhes sobre como habilitar os seguintes tipos de identidade gerenciada em um cluster novo ou existente do AKS:

  • Identidade gerenciada atribuída pelo sistema
  • Traga sua própria identidade gerenciada atribuída pelo usuário
  • Identidade gerenciada do Kubelet criada previamente

Visão geral

Quando você implanta um cluster do AKS, uma identidade gerenciada atribuída pelo sistema é criada automaticamente e é gerenciada pela plataforma do Azure, portanto, ela não exige que você provisione ou gire segredos. Para saber mais, confira identidades gerenciadas para recursos do Azure.

O AKS não cria automaticamente uma entidade de serviço, então você precisa criar uma. Os clusters que usam uma entidade de serviço acabam expirando, e a entidade de serviço deve ser renovada para não afetar a autenticação do cluster com a identidade. O gerenciamento de entidades de serviço aumenta a complexidade, então é mais fácil usar identidades gerenciadas em vez disso. Os mesmos requisitos de permissão se aplicam a entidades de serviço e identidades gerenciadas. As identidades gerenciadas usam autenticação baseada em certificado. As credenciais de cada identidade gerenciada expiram em 90 dias e são transferidas após 45 dias.

O AKS usa os tipos de identidade gerenciada atribuídos pelo sistema e pelo usuário e essas identidades são imutáveis. Esses tipos de identidade não devem ser confundidos com um de identidade de carga de trabalho do Microsoft Entra, que se destina a ser usado por um aplicativo em execução em um pod.

Importante

A identidade gerenciada por pod do Microsoft Entra de software livre (versão prévia) no Serviço de Kubernetes do Azure foi preterida em 24/10/2022, e o projeto arquivado em setembro de 2023. Para obter mais informações, confira o aviso de preterimento. O complemento Gerenciado do AKS começa a ser preterido em setembro de 2024.

Recomendamos que você examine primeiro a visão geral da ID de Carga de Trabalho do Microsoft Entra. A autenticação de ID de Carga de Trabalho do Entra substitui a identidade gerenciada por pod do Microsoft Entra (versão prévia) e é o método recomendado para habilitar um aplicativo em execução em um pod para se autenticar em outros serviços do Azure que dão suporte a ele.

Antes de começar

Limitações

  • Não há suporte para locatários movendo ou migrando um cluster habilitado para identidade gerenciada.
  • Se o cluster tiver a identidade gerenciada por pod do Microsoft Entra (aad-pod-identity) habilitada, os pods da Identidade Gerenciada por Nó (NMI) modificarão os iptables dos nós para interceptar as chamadas no ponto de extremidade dos Metadados da Instância do Azure (IMDS). Essa configuração significa que qualquer solicitação feita ao ponto de extremidade de Metadados é interceptada pela NMI, mesmo que o POD não use aad-pod-identity. O CRD do AzurePodIdentityException pode ser configurado para informar que aad-pod-identity de quaisquer solicitações ao ponto de extremidade de Metadados originadas de um pod que corresponda aos rótulos definidos no CRD devem ser enviadas por proxy sem nenhum processamento no NMI. Os pods do sistema com o rótulo kubernetes.azure.com/managedby: aks no namespace kube-system devem ser excluídos em aad-pod-identity configurando o CRD AzurePodIdentityException.
  • O AKS não suporta o uso de uma identidade gerenciada atribuída pelo sistema quando estiver usando uma zona DNS privada personalizada.

Resumo das identidades gerenciadas

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

Identidade Nome Caso de uso Permissões padrão Traga sua própria identidade
Painel de controle Nome do cluster AKS Usado pelos componentes do plano de controle do AKS para gerenciar os recursos de cluster, incluindo balanceadores de carga de entrada e IPs públicos gerenciados pelo AKS, dimensionador automático de cluster; operações de dimensionamento automático de cluster, drivers da CSI de Disco, Blob e dos Arquivos do Azure. Função de colaborador para o grupo de recursos de nó Com suporte
Kubelet Nome do cluster do AKS – agentpool Autenticação com o Registro de Contêiner do Azure(ACR). N/D (para kubernetes v1.15+) Com suporte
Complemento AzureNPM Nenhuma identidade é necessária. N/D Não
Complemento Monitoramento de rede AzureCNI Nenhuma identidade é necessária. N/D Não
Complemento azure-policy (gatekeeper) Nenhuma identidade é necessária. N/D Não
Complemento azure-policy Nenhuma identidade é necessária. N/D Não
Complemento Calico Nenhuma identidade é necessária. N/D Não
Complemento Dashboard Nenhuma identidade é necessária. N/D Não
Complemento roteamento de aplicativo Gerencia certificados de DNS do Azure e do Azure Key Vault Função de usuário de Segredos do Key Vault para o Key Vault, função de colaborador de zona DNZ para zonas DNS, função de colaborador de zona DNS privada para zonas DNS privadas Não
Complemento HTTPApplicationRouting Gerencia os recursos de rede necessários. Função de leitor para o grupo de recursos de nó, função de colaborador para a zona DNS Não
Complemento Gateway de aplicativo de entrada Gerencia os recursos de rede necessários. Função de colaborador para o grupo de recursos de nó Não
Complemento omsagent Usado para enviar métricas do AKS para o Azure Monitor. Função de Publicador de Métricas de Monitoramento Não
Complemento Virtual-Node (ACIConnector) Gerencia os recursos de rede necessários para as Instâncias de Contêiner do Azure (ACI). Função de colaborador para o grupo de recursos de nó Não
Complemento Análise de custo Usado para coletar dados de alocação de custos
Identidade da carga de trabalho ID da carga do Microsoft Entra Permite aos aplicativos acessarem os recursos de nuvem com segurança com a ID da carga de trabalho do Microsoft Entra. N/D Não

Habilitar identidades gerenciadas em um novo cluster do AKS

Observação

O AKS cria uma identidade do kubelet atribuída pelo sistema no grupo de recursos do nó se você não especificar sua própria identidade gerenciada pelo kubelet.

Observação

Se o seu cluster já estiver usando a identidade gerenciada e a identidade tiver sido alterada, por exemplo, se você atualizar o tipo de identidade do cluster de atribuído pelo sistema para atribuído pelo utilizador, há um atraso para os componentes do painel de controle mudarem para a nova identidade. Os componentes do painel de controle continuam usando a identidade antiga até que seu token expire. Depois que o token for atualizado, ele mudará para a nova identidade. Esse processo pode levar várias horas.

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

    az group create --name myResourceGroup --location westus2

  2. Crie um cluster do AKS usando o comando az aks create.

    az aks create -g myResourceGroup -n myManagedCluster --enable-managed-identity

  3. Obtenha credenciais para acessar o cluster usando o comando az aks get-credentials.

    az aks get-credentials --resource-group myResourceGroup --name myManagedCluster

Habilitar as identidades gerenciadas em um cluster do AKS existente

Para atualizar o cluster AKS existente que está usando uma entidade de serviço para usar uma identidade gerenciada atribuída pelo sistema, execute o comando az aks update.

az aks update -g myResourceGroup -n myManagedCluster --enable-managed-identity

Depois de atualizar seu cluster, o plano de controle e os pods usam a identidade gerenciada. O Kubelet continuará usando uma entidade de serviço até que você atualize seu agentpool. Você pode usar o comando az aks nodepool upgrade --resource-group myResourceGroup --cluster-name myAKSCluster --name mynodepool --node-image-only em seus nós para atualizar para uma identidade gerenciada. Uma atualização do pool de nós causa tempo de inatividade para seu cluster do AKS, pois os nós nos pools de nós são isolados/drenados e reimaginados.

Observação

Lembre-se das seguintes informações ao atualizar seu cluster:

  • Uma atualização só funciona se houver uma atualização de VHD para consumir. Se você estiver executando o VHD mais recente, precisará esperar até que o próximo VHD esteja disponível para executar a atualização.

  • A CLI do Azure garante que a permissão do complemento seja definida corretamente após a migração. Se você não estiver usando a CLI do Azure para executar a operação de migração, precisará lidar com a permissão da identidade do complemento por conta própria. Para obter um exemplo usando um modelo do Azure Resource Manager (ARM), confira Atribuir funções do Azure usando modelos de ARM.

  • Se seu cluster estava usando --attach-acr para extrair imagens do Registro de Contêiner do Azure, é necessário executar o comando az aks update --resource-group myResourceGroup --name myAKSCluster --attach-acr <ACR resource ID> depois de atualizar seu cluster para permitir que o kubelet recém-criado usado para a identidade gerenciada obtenha a permissão para extrair do ACR. Caso contrário, você não conseguirá efetuar pull do ACR após a atualização.

Adicionar atribuição de função para identidade gerenciada

Quando você cria e usa sua própria VNet, anexa discos do Azure, endereço IP estático, tabela de rotas ou identidade de kubelet atribuída pelo usuário em que 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 do ARM ou outro método, precisará usar a ID Principal da identidade gerenciada do cluster para realizar uma atribuição de função.

Se você não estiver usando a CLI do Azure, mas estiver usando sua própria VNet, anexar discos do Azure, endereço IP estático, tabela de rotas ou identidade de kubelet atribuída pelo usuário que esteja fora do grupo de recursos do nó de trabalho, recomendamos usar a identidade gerenciada atribuída pelo usuário para o painel de controle. Para que o painel de controle use uma identidade gerenciada atribuída pelo sistema, não é possível obter a ID da identidade antes de criar o cluster, o que atrasa a efetivação da atribuição de função.

Obter a ID da entidade de segurança da identidade gerenciada

  • Obtenha a ID principal da identidade existente usando o comando az identity show.

    az identity show --ids <identity-resource-id>

    Sua saída deve ser parecida com o seguinte exemplo de saída:

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

Adicionar atribuição de função

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

  • Atribua a função Contributor no grupo de recursos personalizados usando o comando az role assignment create.

    az role assignment create --assignee <control-plane-identity-principal-id> --role "Contributor" --scope "<custom-resource-group-resource-id>"

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

  • Atribua a função Managed Identity Operator na identidade do kubelet usando o comando az role assignment create.

    az role assignment create --assignee  <control-plane-identity-principal-id> --role "Managed Identity Operator" --scope "<kubelet-identity-resource-id>"

Observação

Pode levar até 60 minutos para que as permissões concedidas à identidade gerenciada do seu cluster sejam preenchidas.

Traga sua própria identidade gerenciada

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

Uma identidade gerenciada atribuída pelo usuário para o painel de controle permite o acesso à identidade existente antes da criação do cluster. Esse recurso permite cenários como o uso de uma VNet personalizada ou outboundType de UDR com uma identidade gerenciada pré-criada.

Observação

Não há suporte para as regiões USDOD Central, USDOD East e USGov Iowa na nuvem do Azure US Government.

O AKS cria uma identidade do kubelet atribuída pelo sistema no grupo de recursos do nó se você não especificar sua própria identidade gerenciada pelo kubelet.

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

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

    Sua saída deve ser parecida com o seguinte exemplo de saída:

    {                                  
  "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"
}

Observação

Pode levar até 60 minutos para que as permissões concedidas à identidade gerenciada do seu cluster sejam preenchidas.

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

  • Criar um cluster com 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 \
    --enable-managed-identity \
    --assign-identity <identity-resource-id>

Atualizar a identidade gerenciada em um cluster existente

Observação

A migração de uma identidade gerenciada para o painel de controle, de atribuída ao sistema para atribuída ao usuário, não causa nenhum tempo de inatividade para o painel de controle e os pools de agentes. Enquanto isso, os componentes do painel de controle continuarão usando a identidade antiga atribuída pelo sistema por várias horas até a próxima atualização do token.

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

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

    Sua saída deve ser parecida com o seguinte exemplo de saída:

    {                                  
  "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"
}

  • Depois de criar a identidade gerenciada atribuída pelo usuário personalizada para o painel de controle, adicione a atribuição de função para a identidade gerenciada usando o comando az role assignment create.

  • Atualize seu cluster com as identidades existentes usando o comando az aks update. Certifique-se de fornecer a ID do recurso da identidade gerenciada para o painel de controle, incluindo o argumento assign-identity.

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

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

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

Usar uma identidade gerenciada do kubelet criada previamente

Uma identidade kubelet permite o acesso à identidade existente antes da criação do cluster. Esse recurso habilita cenários como conexão com o ACR com uma identidade gerenciada pré-criada.

Limitações de identidade do kubelet pré- criadas

  • Funciona apenas com um cluster gerenciado atribuído pelo usuário.
  • Não há suporte para as regiões Norte e Leste da China no Microsoft Azure operado pela 21Vianet.

Criar identidades gerenciadas atribuídas pelo usuário

Identidade gerenciada do plano de controle

  • Se você não tiver uma identidade gerenciada para o painel de controle, crie uma usando az identity create.

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

    Sua saída deve ser parecida com o seguinte exemplo de saída:

    {                                  
  "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"
}

identidade gerenciada do kubelet

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

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

    Sua saída deve ser parecida com o seguinte exemplo de saída:

    {
  "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"
}

Criar um cluster usando uma identidade do kubelet atribuída pelo usuário

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

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

    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 \
    --enable-managed-identity \
    --assign-identity <identity-resource-id> \
    --assign-kubelet-identity <kubelet-identity-resource-id>

    Uma criação de cluster do AKS bem-sucedida usando sua própria identidade gerenciada do kubelet deve ser semelhante ao seguinte exemplo de saída:

      "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 com a identidade do kubelet

Aviso

A atualização da identidade gerenciada pelo kubelet atualiza os pools de nós, o que causa tempo de inatividade para seu cluster do AKS, pois os nós nos pools de nós serão isolados/drenados e recriados.

Observação

Se seu cluster estava usando --attach-acr para extrair imagens do Registro de Contêiner do Azure, é necessário executar o comando az aks update --resource-group myResourceGroup --name myAKSCluster --attach-acr <ACR Resource ID> depois de atualizar seu cluster para permitir que o kubelet recém-criado usado para a identidade gerenciada obtenha a permissão para extrair do ACR. Caso contrário, não será possível efetuar pull do ACR após a atualização.

Obtenha a identidade gerenciada do painel de controle atual para seu cluster do AKS

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

    az aks show -g <RGName> -n <ClusterName> --query "servicePrincipalProfile"

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

    {
  "clientId": "msi"
}

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

    az aks show -g <RGName> -n <ClusterName> --query "identity"

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

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

Atualize seu cluster com a identidade do kubelet

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

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

    Sua saída deve ser parecida com o seguinte exemplo de saída:

    {
  "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"
}

  2. Atualize seu cluster com as identidades existentes usando o comando az aks update. Certifique-se de fornecer a ID do recurso da identidade gerenciada para o painel de controle, incluindo o argumento assign-identity e a identidade gerenciada de kubelet para o argumento assign-kubelet-identity.

    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 bem-sucedida do cluster usando sua própria identidade gerenciada do kubelet deve ser semelhante à seguinte saída de exemplo:

      "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"
    }
  },

Próximas etapas

  • Use os modelos do Azure Resource Manager para criar um cluster habilitado para identidade gerenciada.
  • Saiba como usar [use kubelogin][kubelogin-authentication] para todos os métodos de autenticação do Microsoft Entra com suporte no AKS.