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

Artigo
08/02/2024

Um cluster do 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 Azure Load Balancer ou ACR (Registro de Contêiner do Azure).

Para obter a segurança ideal e a facilidade de uso, a Microsoft recomenda usar identidades gerenciadas em vez de entidades de serviço para autorizar o acesso de um cluster do 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, confira Usar uma identidade gerenciada no AKS.

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

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

CLI do Azure
Azure PowerShell

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

Copie os valores para appId e password da saída. Use-os ao criar um cluster do AKS na próxima seção.

Crie uma entidade de serviço usando o comando New-AzADServicePrincipal.

New-AzADServicePrincipal -DisplayName myAKSClusterServicePrincipal -OutVariable sp

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

Secret                : System.Security.SecureString
ServicePrincipalNames : {xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx, http://myAKSClusterServicePrincipal}
ApplicationId         : xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
ObjectType            : ServicePrincipal
DisplayName           : myAKSClusterServicePrincipal
Id                    : xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
Type                  :

Os valores são armazenados em uma variável que você usa quando cria um cluster do AKS na próxima seção.

Descriptografe o valor armazenado na cadeia de caracteres segura de segredo usando o seguinte comando.

$BSTR = [System.Runtime.InteropServices.Marshal]::SecureStringToBSTR($sp.Secret)
[System.Runtime.InteropServices.Marshal]::PtrToStringAuto($BSTR)

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

CLI do Azure
Azure PowerShell

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> \
    --generate-ssh-keys
```
Observação

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

Converta a entidade de serviço ApplicationId e Secret em um objeto PSCredential usando o comando a seguir.

$Cred = New-Object -TypeName System.Management.Automation.PSCredential ($sp.ApplicationId, $sp.Secret)

Use uma entidade de serviço existente para um novo cluster do AKS usando o comando New-AzAksCluster e especifique o parâmetro ServicePrincipalIdAndSecret com o objeto PSCredential criado anteriormente como seu valor.
```
New-AzAksCluster -ResourceGroupName myResourceGroup -Name myAKSCluster -ServicePrincipalIdAndSecret $Cred
```
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, conectar-se ao ACR (Registro de Contêiner do Azure) ou acessar chaves ou segredos em um cofre de chaves no seu cluster, precisará delegar acesso a esses recursos à entidade de serviço. Para delegar o acesso, atribua uma função do Azure RBAC (controle de acesso baseado em função do Azure) à 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 serem propagadas.

CLI do Azure
Azure PowerShell

Crie uma atribuição de função usando o comando az role assignment create. Forneça o valor da appID da entidade de serviço para o parâmetro appId. Especifique o escopo da atribuição de função, como um grupo de recursos ou um recurso de rede virtual. A atribuição de função determina quais permissões a entidade de serviço tem no recurso e em qual 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"
```
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.

Crie uma atribuição de função usando o comando New-AzRoleAssignment. Forneça o valor da appID da entidade de serviço para o parâmetro ApplicationId. Especifique o escopo da atribuição de função, como um grupo de recursos ou um recurso de rede virtual. A atribuição de função determina quais permissões a entidade de serviço tem no recurso e em qual 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:
```
New-AzRoleAssignment -ApplicationId <ApplicationId> `
    -Scope "/subscriptions/<subscription-id>/resourceGroups/<resource-group>/providers/Microsoft.KeyVault/vaults/<vault-name>" `
    -RoleDefinitionName "Key Vault Secrets User"
```
Observação

O Scope, pois um recurso precisa ser uma ID de recurso completa, 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 você precise atribuir a uma entidade de serviço.

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.

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 New-AzAksCluster ou Set-AzAksCluster 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:

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 Colaborador da Máquina virtual no grupo de recursos.

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

CLI do Azure
PowerShell do Azure

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 \
  --resource-group myResourceGroup \
  --name myAKSCluster \
  --query servicePrincipalProfile.clientId \
  --output tsv)
```

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 ApplicationId.
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 New-AzAksCluster, 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 Remove-AzADServicePrincipal. Substitua os valores do parâmetro -ResourceGroupName do nome do grupo de recursos e o parâmetro -Name do nome do cluster:
```
$ClientId = (Get-AzAksCluster -ResourceGroupName myResourceGroup -Name myAKSCluster ).ServicePrincipalProfile.ClientId
Remove-AzADServicePrincipal -ApplicationId $ClientId
```

Solucionar problemas

CLI do Azure
Azure PowerShell

A CLI do Azure armazena em cache as credenciais da entidade de serviço para clusters do AKS. Se essas credenciais expirarem, você poderá 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" \
    --output 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.

O Azure PowerShell 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 New-AzAksCluster 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 Get-AzADAppCredential. A saída mostra o StartDateTime de suas credenciais.

Get-AzADAppCredential -ApplicationId <ApplicationId>

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.

Compartilhar via