Partilhar via

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).

Para uma segurança e facilidade de utilização ideais, a Microsoft recomenda a utilização de identidades geridas em vez de entidades de serviço para autorizar o acesso de um cluster AKS a outros recursos no Azure. Uma identidade gerenciada é um tipo especial de entidade de serviço que pode ser usada para obter credenciais do Microsoft Entra sem a necessidade de gerenciar e proteger credenciais. Para obter mais informações sobre como usar uma identidade gerenciada com seu cluster, consulte Usar uma identidade gerenciada no AKS.

Este artigo mostra como criar e usar uma entidade de serviço com 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 uso 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

Crie uma entidade de serviço antes de criar o cluster.

  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": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "displayName": "myAKSClusterServicePrincipal",
  "name": "http://myAKSClusterServicePrincipal",
  "password": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "tenant": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}

  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 az aks create comando e use os --service-principal parâmetros e --client-secret para especificar o appId e password da saída que você recebeu na seção anterior.

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

    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, conectar-se ao Registro de Contêiner do Azure (ACR) ou acessar chaves ou segredos em um cofre de chaves do cluster, precisará delegar o acesso a esses recursos à entidade de serviço. Para delegar acesso, atribua uma função de controle de acesso baseado em função do Azure (Azure RBAC) à entidade de serviço.

Importante

As permissões concedidas a uma entidade de serviço associada a um cluster podem levar até 60 minutos para se propagar.

  • Crie uma atribuição de função usando o az role assignment create comando. Forneça o valor do appID da entidade de serviço para o appId parâmetro. Especifique o escopo para a atribuição de função, como um grupo de recursos ou recurso de rede virtual. A atribuição de função determina quais permissões a entidade de serviço tem no recurso e em que escopo.

    Por exemplo, para atribuir as permissões da entidade de serviço para acessar segredos em um cofre de chaves, você pode usar o seguinte comando:

    az role assignment create \
    --assignee <appId> \
    --scope "/subscriptions/<subscription-id>/resourceGroups/<resource-group>/providers/Microsoft.KeyVault/vaults/<vault-name>" \
    --role "Key Vault Secrets User"

    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.

As seções a seguir detalham as delegações comuns que talvez seja necessário atribuir a uma entidade de serviço.

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:

  • Crie uma função personalizada e defina as permissões de função Microsoft.Compute/disks/read e Microsoft.Compute/disks/write ou
  • Atribua a função interna de Colaborador de Máquina Virtual no grupo de recursos.

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 \
  --resource-group myResourceGroup \
  --name myAKSCluster \
  --query servicePrincipalProfile.clientId \
  --output 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ê poderá 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" \
    --output 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.