Utilizar um principal do serviço com o Azure Kubernetes Service (AKS)

  • Artigo

Um cluster AKS requer uma entidade de serviço do Microsoft Entra ou uma identidade gerenciada para criar e gerenciar dinamicamente outros recursos do Azure, como um Balanceador de Carga do Azure ou um Registro de Contêiner do Azure (ACR).

Nota

Recomendamos usar identidades gerenciadas para autenticar com outros recursos no Azure, e elas são o método de autenticação padrão para seu cluster AKS. Para obter mais informações sobre como usar uma identidade gerenciada com seu cluster, consulte Usar uma identidade gerenciada atribuída ao sistema.

Este artigo mostra como criar e usar uma entidade de serviço para seus clusters AKS.

Antes de começar

Para criar uma entidade de serviço do Microsoft Entra, você deve ter permissões para registrar um aplicativo com seu locatário do Microsoft Entra e atribuir o aplicativo a uma função em sua assinatura. Se você não tiver as permissões necessárias, precisará pedir ao seu ID do Microsoft Entra ou administrador de assinatura para atribuir as permissões necessárias ou pré-criar uma entidade de serviço para você usar com seu cluster AKS.

Se você estiver usando uma entidade de serviço de um locatário diferente do Microsoft Entra, há outras considerações sobre as permissões disponíveis quando você implanta o cluster. Talvez você não tenha as permissões apropriadas para ler e gravar informações de diretório. Para obter mais informações, consulte Quais são as permissões de usuário padrão no Microsoft Entra ID?

Pré-requisitos

  • Se estiver usando a CLI do Azure, você precisará da CLI do Azure versão 2.0.59 ou posterior. Executar az --version para localizar a versão. Se precisar de instalar ou atualizar, veja Install Azure CLI (Instalar o Azure CLI).
  • Se estiver usando o Azure PowerShell, você precisará do Azure PowerShell versão 5.0.0 ou posterior. Executar Get-InstalledModule -Name Az para localizar a versão. Se você precisar instalar ou atualizar, consulte Instalar o módulo Azure Az PowerShell.

Criar um principal de serviço manualmente

  1. Crie uma entidade de serviço usando o az ad sp create-for-rbac comando.

    az ad sp create-for-rbac --name myAKSClusterServicePrincipal

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

    {
  "appId": "559513bd-0c19-4c1a-87cd-851a26afd5fc",
  "displayName": "myAKSClusterServicePrincipal",
  "name": "http://myAKSClusterServicePrincipal",
  "password": "e763725a-5eee-40e8-a466-dc88d980f415",
  "tenant": "72f988bf-86f1-41af-91ab-2d7cd011db48"
}

  2. Copie os valores de e password para appId a saída. Você os usa ao criar um cluster AKS na próxima seção.

Especificar um principal de serviço para um cluster do AKS

  • Use uma entidade de serviço existente para um novo cluster AKS usando o comando e use os --service-principal parâmetros e para especificar o appIdaz aks create e --client-secretpassword da saída que você recebeu na seção anterior.

    az aks create \
    --resource-group myResourceGroup \
    --name myAKSCluster \
    --service-principal <appId> \
    --client-secret <password>

    Nota

    Se estiver a utilizar uma entidade de serviço existente com segredo personalizado, certifique-se de que o segredo não tem mais de 190 bytes.

Delegar acesso a outros recursos do Azure

Você pode usar a entidade de serviço para o cluster AKS para acessar outros recursos. Por exemplo, se você quiser implantar seu cluster AKS em uma sub-rede de rede virtual existente do Azure ou conectar-se ao Azure Container Registry (ACR), precisará delegar o acesso a esses recursos à entidade de serviço. A permissão concedida a um cluster usando uma identidade gerenciada atribuída ao sistema pode levar até 60 minutos para ser preenchida.

  • Crie uma atribuição de função usando o az role assignment create comando. Atribua o appId a um escopo específico, como um grupo de recursos ou recurso de rede virtual. A função define quais permissões a entidade de serviço tem no recurso.

    Nota

    O --scope para um recurso precisa ser um ID de recurso completo, como /subscriptions/guid/resourceGroups/myResourceGroup ou /subscriptions/guid>>/resourceGroups/myResourceGroupVnet/providers/Microsoft.Network/virtualNetworks/<<myVnet.

    az role assignment create --assignee <appId> --scope <resourceScope> --role Contributor

As seções a seguir detalham delegações comuns que você pode precisar atribuir.

Registo de Contentores do Azure

Se você usar o Azure Container Registry (ACR) como seu armazenamento de imagens de contêiner, precisará conceder permissões à entidade de serviço para que seu cluster AKS leia e extraia imagens. Recomendamos usar o az aks create comando or az aks update para integrar com um registro e atribuir a função apropriada para a entidade de serviço. Para obter etapas detalhadas, consulte Autenticar com o Registro de Contêiner do Azure do Serviço Kubernetes do Azure.

Rede

Você pode usar redes avançadas onde a rede virtual e a sub-rede ou endereços IP públicos estão em outro grupo de recursos. Atribua a função interna de Colaborador de Rede na sub-rede dentro da rede virtual. Como alternativa, você pode criar uma função personalizada com permissões para acessar os recursos de rede nesse grupo de recursos. Para obter mais informações, consulte Permissões de serviço AKS.

Armazenamento

Se você precisar acessar recursos de disco existentes em outro grupo de recursos, atribua um dos seguintes conjuntos de permissões de função:

Azure Container Instances

Se você usar o Kubelet Virtual para integrar com o AKS e optar por executar as Instâncias de Contêiner do Azure (ACI) no grupo de recursos separado do cluster AKS, a entidade de serviço do cluster AKS deverá receber permissões de Colaborador no grupo de recursos ACI.

Outras considerações

Ao usar o AKS e uma entidade de serviço do Microsoft Entra, considere o seguinte:

  • A entidade de serviço do Kubernetes faz parte da configuração do cluster, mas não use essa identidade para implantar o cluster.
  • Por padrão, as credenciais da entidade de serviço são válidas por um ano. Você pode atualizar ou alternar as credenciais da entidade de serviço a qualquer momento.
  • Cada entidade de serviço está associada a um aplicativo Microsoft Entra. Você pode associar a entidade de serviço de um cluster Kubernetes a qualquer nome de aplicativo Microsoft Entra válido (por exemplo: https://www.contoso.org/example). O URL para a aplicação não tem de ser um ponto final real.
  • Quando especificar o ID de Cliente do principal de serviço, utilize o valor de appId.
  • Nas VMs do nó do agente no cluster do Kubernetes, as credenciais da entidade de serviço são armazenadas no /etc/kubernetes/azure.json arquivo.
  • Quando você exclui um cluster AKS que foi criado usando o az aks create comando, a entidade de serviço criada não é excluída automaticamente.

    • Para excluir a entidade de serviço, consulte o servicePrincipalProfile.clientId do cluster e exclua-o usando o az ad sp delete comando. Substitua os valores do -g parâmetro para o nome do grupo de recursos e -n o parâmetro para o nome do cluster:

      az ad sp delete --id $(az aks show -g myResourceGroup -n myAKSCluster --query servicePrincipalProfile.clientId -o tsv)

Resolver problemas

A CLI do Azure armazena em cache as credenciais da entidade de serviço para clusters AKS. Se essas credenciais expirarem, você encontrará erros durante a implantação do cluster AKS. Se você executar o az aks create comando e receber uma mensagem de erro semelhante à seguinte, isso pode indicar um problema com as credenciais da entidade de serviço em cache:

Operation failed with status: 'Bad Request'.
Details: The credentials in ServicePrincipalProfile were invalid. Please see https://aka.ms/aks-sp-help for more details.
(Details: adal: Refresh request failed. Status Code = '401'.

Você pode verificar a data de expiração de suas credenciais da entidade de serviço usando o az ad app credential list comando com a "[].endDateTime" consulta.

az ad app credential list --id <app-id> --query "[].endDateTime" -o tsv

O prazo de expiração predefinido para as credenciais do principal de serviço é de um ano. Se suas credenciais tiverem mais de um ano, você poderá redefinir as credenciais existentes ou criar uma nova entidade de serviço.

Solução de problemas gerais da CLI do Azure

A CLI do Azure pode ser executada em vários ambientes de shell, mas com pequenas variações de formato. Se você tiver resultados inesperados com os comandos da CLI do Azure, consulte Como usar a CLI do Azure com êxito.

Próximos passos

Para obter mais informações sobre entidades de serviço do Microsoft Entra, consulte Objetos de entidade de aplicativo e serviço.

Para obter informações sobre como atualizar as credenciais, consulte Atualizar ou girar as credenciais de uma entidade de serviço no AKS.