Share via

Usar uma e entidade de serviço com o AKS (Serviço de Kubernetes do Azure)

  • Artigo

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

Observação

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

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

Antes de começar

Para criar uma entidade de serviço do Microsoft Entra, você precisa ter permissões para registrar um aplicativo no seu locatário do Microsoft Entra e para atribuir ao aplicativo uma função na sua assinatura. Se não tiver as permissões necessárias, você precisará solicitar ao administrador do seu Microsoft Entra ID ou da sua assinatura para lhe atribuir as permissões necessárias ou criar previamente uma entidade de serviço para que você a use com seu cluster do AKS.

Se você estiver usando uma entidade de serviço de um locatário diferente do Microsoft Entra, haverá outras considerações em torno das permissões disponíveis ao implantar 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, confira Quais são as permissões de usuário padrão no Microsoft Entra ID?

Pré-requisitos

  • Se você estiver usando a CLI do Azure, precisará da CLI do Azure versão 2.0.59 ou posterior. Execute az --version para encontrar a versão. Se você precisa instalar ou atualizar, consulte Instalar a CLI do Azure.
  • Se estiver usando o Azure PowerShell, precisará do Azure PowerShell versão 5.0.0 ou posterior. Execute Get-InstalledModule -Name Az para encontrar a versão. Se você precisar instalá-lo ou atualizá-lo, confira Instalar o módulo do Azure Az PowerShell.

Criar uma entidade de serviço manualmente

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

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

    Sua saída deve ser semelhante à saída do 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 para appId e password da saída. Use-os ao criar um cluster do AKS na próxima seção.

Especificar uma entidade de serviço para um cluster do AKS

  • Use uma entidade de serviço existente para um novo cluster do AKS usando o comando az aks create e use os parâmetros --service-principal e --client-secret para especificar 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>

    Observação

    Se você estiver usando uma entidade de serviço existente com segredo personalizado, verifique se o segredo não excede 190 bytes.

Delegar acesso a outros recursos do Azure

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

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

    Observação

    O --scope de um recurso precisa ser uma ID de recurso completa, 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 as delegações comuns que talvez você precise fazer.

Registro de Contêiner do Azure

Se você usar o Registro de Contêiner do Azure (ACR) como seu repositório de imagens, precisará conceder permissões para a entidade de serviço do seu cluster do AKS ler e efetuar pull de imagens. Recomendamos usar o comando az aks create ou az aks update para integrá-lo a um registro e atribuir uma 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 de Kubernetes do Azure.

Rede

Você pode usar os recursos de rede quando rede e a sub-rede virtuais, ou endereços IP públicos, estiverem em outro grupo de recursos. Atribua a função interna 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, confira Permissões do 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:

Instâncias de Contêiner do Azure

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

Outras considerações

Ao usar o AKS e uma entidade de serviço do Microsoft Entra, leve em conta 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 girar as credenciais da entidade de serviço a qualquer momento.
  • Cada entidade de serviço é associada a um aplicativo do Microsoft Entra. Você pode associar a entidade de serviço de um cluster do Kubernetes a qualquer nome de aplicativo do Microsoft Entra válido (por exemplo: https://www.contoso.org/example). A URL para o aplicativo não precisa ser um ponto de extremidade real.
  • Ao especificar a ID do cliente da entidade de serviço, use o valor de appId.
  • Nas VMs do nó de agente no cluster do Kubernetes, as credenciais da entidade de serviço são armazenadas no arquivo /etc/kubernetes/azure.json.
  • Ao excluir um cluster do AKS que foi criado usando o comando az aks create, a entidade de serviço criada não será excluída automaticamente.

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

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

Solucionar problemas

A CLI do Azure armazena em cache as credenciais da entidade de serviço para clusters do AKS. Se essas credenciais expirarem, você encontrará erros durante a implantação do cluster do AKS. Se você executar o comando az aks create e receber uma mensagem de erro semelhante à seguinte, isso pode indicar um problema com as credenciais da entidade de serviço armazenadas 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 validade das credenciais da entidade de serviço usando o comando az ad app credential list com a consulta "[].endDateTime".

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

O tempo de expiração padrão para as credenciais da entidade 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 geral de problemas 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 comandos da CLI do Azure, confira Como usar a CLI do Azure com êxito.

Próximas etapas

Para obter mais informações sobre entidades de serviço do Microsoft Entra, confira Objetos de aplicativo e de entidade de 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.